Add an annotation to the specified mark. This is intended to be passed a MarkInfo object received from a DataTable. MarkInfo can be found in the DataTable returned from getSelectedMarksAsync.
The mark to annotate.
The text to display in the annotation.
Empty promise that resolves when the annotation is complete.
The following example shows how you might call this method using a MarkInfo object.
const markCollection = await worksheet.getSelectedMarksAsync();
const markToAnnotate = marksCollection.data[0].marksInfo[0];
await worksheet.annotateMarkAsync(markToAnnotate, 'Manufacturing line #2 shutdown triggered');Adds external context menu item into location defined by targetMenu input parameter.
Calling this function does not have immediate affect, it just registers new menu item. When the corresponding context menu is later shown, the new menu item is also rendered there.
The return value of this function is the unique identifier for the newly inserted context menu item.
When the user clicks the new context menu item, a TableauEvent is raised. Each targetMenu parameter will have a different event type. The unique identifier could be used to distinguish different menu items that have the same event type.
Defines where to insert the new external menu item.
Provides configuration information for new external menu item.
Unique identifier for newly inserted context menu item.
Applies the list of provided categorical filter values.
The name of the field to filter on.
The list of values to filter on.
The update type of this filter (add, all, remove, replace).
Advanced filter options (isExcludeMode).
The field name that the filter is applied on.
Applies the list of provided hierarchial filter values.
The name of the field to filter on.
The list of values or levels to filter on.
The update type of this filter (add, all, remove, replace).
The field name that the filter is applied on.
Applies a range filter to a quantitative or date field.
The name of the field to filter on
Filter Options: min, max, nullOption. Atleast one of of min and max is required. For applying date filters, UTC Date objects are expected. (i.e., var min = new Date(Date.UTC(1999, 0, 1)))
The field name that the filter is applied on.
Applies a relative date filter.
The name of the field to filter on.
The relative date filter options (anchorDate, periodType, rangeType, rangeN). When the rangeType is LASTN or NEXTN, the rangeN is required.
The field name that the filter is applied on.
The following example shows how to apply a relative date filter from a worksheet.
worksheet.applyRelativeDateFilterAsync(
'Order Date',
{
anchorDate: new Date(Date.UTC(2022, 4, 13)),
periodType: PeriodType.Years,
rangeType: DateRangeType.LastN,
rangeN: 1,
}
);Resets existing filters on the given field. Categorical filters are reset to "All," and range filters are reset to the full range. Relative date filters can not be reset, consider using the applyRelativeDateFilterAsync API.
The name of the field to clear filter on.
The field to clear filter on.
Clears selected marks in the current worksheet.
Empty promise that resolves when the selection has been cleared.
The following example assumes that you have some marks already selected in the worksheet. After it has run,
you should have no marks selected, and you should see the console message.
Use await only inside an Async function
let vizActiveSheet = viz.workbook.activeSheet;
if (vizActiveSheet.sheetType === "worksheet") {
// clear selected marks
await vizActiveSheet.clearSelectedMarksAsync();
console.log('Your marks selection has been cleared!');
}Executes the external context menu item inserted by the appendContextMenuAsync method.
The parameter menuItemId specifies the menu item to execute and is the return value from the appendContextMenuAsync method.
Once this function is called, menu item identified by menuItemId will be executed.
Defines where to execute new external menu item.
Unique identifier of external context menu item that user wants to execute.
Retrieves a list of the annotations in the worksheet.
A list annotations in the worksheet.
The following example shows how you might call this method.
let annotations = await worksheet.getAnnotationsAsync();
console.log(annotations);Gets the data sources for this worksheet. Note that calling this method might negatively impact performance and responsiveness of the viz that you are embedding. The method is partly asynchronous but includes some serial operations.
The primary data source and all of the secondary data sources for this worksheet. By convention the first data source in the array is the primary.
The following example shows how you might find a specific data source of a worksheet,
using the getDataSourcesAsync() method. You could then call the getLogicalTablesAsync() method
to get the logical tables in the data source, and then use the either the DataSource or the
Worksheet to get the underlying table data.
Use await only inside an Async function
let vizActiveSheet = viz.workbook.activeSheet;
if (vizActiveSheet.sheetType === "worksheet") {
let dataSources = await vizActiveSheet.getDataSourcesAsync();
console.log(dataSources[0].name);
let dataSource = dataSources.find(datasource => datasource.name === "Sample - Superstore");
// process the dataSource
}Gets the list of filters on a worksheet. Hierarchical filters are not yet supported
A promise that resolves to the collection of filters used in this worksheet.
Gets the data for the marks which are currently selected on the worksheet. If there are no marks currently selected, an empty model is returned.
The marks that are selected.
Use await only inside an Async function
let vizActiveSheet = viz.workbook.activeSheet;
if (vizActiveSheet.sheetType === "worksheet") {
// Call to get the selected marks for the worksheet
let selectedMarks = await vizActiveSheet.getSelectedMarksAsync();
// Get the first DataTable for our selected marks (usually there is just one)
const dataTableName = selectedMarks.data[0];
// Map the data into a format for display, etc.
}Gets the columns that are returned with getSummaryDataAsync.
The array of columns that describe the data in the worksheet.
Gets the summary data table for a worksheet. Warning: getSummaryDataAsync can fail with a worksheet with many rows of data and is now deprecated.
Collection of options to change the behavior of the call.
A data table containing the summary data for the worksheet.
Gets a summary data table reader for this worksheet. Only one active DataTableReader for summary data is supported.
The number of rows per page. The default and maximum is 10,000 rows.
Collection of options to change the behavior of the reader.
A data table reader to access the summary data for the worksheet.
Example showing the methods to get and use the summary data reader for all rows in a worksheet.
Use await only inside an Async function
let vizActiveSheet = viz.workbook.activeSheet;
if (vizActiveSheet.sheetType === "worksheet") {
const dataTableReader = await vizActiveSheet.getSummaryDataReaderAsync();
for (let currentPage = 0; currentPage < dataTableReader.pageCount; currentPage++) {
const dataTablePage = await dataTableReader.getPageAsync(currentPage);
// ... process current page ....
}
await dataTableReader.releaseAsync();
}Gets the underlying data table for this worksheet.
Collection of options to change the behavior of the call.
A data table containing the underlying data for the worksheet.
You can use the GetUnderlyingDataOptions.maxRows property to request the number of rows of data to return.
If unspecified (maxRows == '0'), the call to getUnderlyingDataAsync requests all rows in the data source.
Note that the maximum number of rows returned from the getUnderlyingDataAsync() method is limited
to 10,000 rows. You can use the DataTable property, isTotalRowCountLimited, to test whether there is
more data. A value of true indicates that the calling function requested more rows than the limit (10,000) and the
underlying data source contains more rows than can be returned.
In the following example, the getUnderlyingDataAsync() method is used to get the underlying data for
a specific column in a workbook.
Use await only inside an Async function
let vizActiveSheet = viz.workbook.activeSheet;
if (vizActiveSheet.sheetType === "worksheet") {
let dataTable = await vizActiveSheet.getUnderlyingDataAsync();
let field = dataTable.columns.find(column => column.fieldName === "Sales");
let list = [];
for (let row of dataTable.data) {
list.push(row[field.index].value);
}
let values = list.filter((el, i, arr) => arr.indexOf(el) === i);
console.log(values);
}
Gets the underlying data table for the given logical table id.
Use the getUnderlyingTablesAsync method to identify the logical tables.
logical table id.
Collection of options to change the behavior of the call.
A data table containing the underlying data for the given logical table id
You can use the getUnderlyingDataOptions.maxRows property to request the number of rows of data to return.
If unspecified (maxRows == '0'), the call to getUnderlyingTableDataAsync requests all rows in the logical table.
Note that the maximum number of rows returned from the getUnderlyingTableDataAsync() method is limited
to 10,000 rows. You can use the DataTable property, isTotalRowCountLimited, to test whether there is
more data. A value of true indicates that the calling function requested more rows than the limit (10,000) and the
underlying data source contains more rows than can be returned.
Gets a underlying data table reader for the given logical table id.
Use the getUnderlyingTablesAsync method to identify the logical tables.
Only one active DataTableReader per logical table id is supported.
getUnderlyingTableDataReaderAsync attempts to prepare all the rows of the underlying table to be read as pages.
However, there is a limit to the number of rows that can be prepared. The default limit is 1 million rows of data.
You can change the default limit with the Tableau Server (Cloud) or Tableau Desktop option: ExtensionsAndEmbeddingReaderRowLimit.
If the underlying table has many columns, getUnderlyingTableDataReaderAsync can be sped up by only requesting
native data values in the GetUnderlyingDataOptions.
logical table id.
The number of rows per page. The default and maximum is 10,000 rows.
Collection of options to change the behavior of the reader.
A data table reader to access the underlying data for the given logical table id.
The following example shows getting the first page of underlying data.
Use await only inside an Async function
let vizActiveSheet = viz.workbook.activeSheet;
if (vizActiveSheet.sheetType === "worksheet") {
// Call to get the underlying logical tables used by the worksheet
const underlyingTablesData = await vizActiveSheet.getUnderlyingTablesAsync();
const logicalTableId = underlyingTablesData[0].id;
// Use the above logicalTableId to get the underlying data reader on the active sheet
const dataTableReader = await vizActiveSheet.getUnderlyingTableDataReaderAsync(logicalTableId);
const page = await dataTableReader.getPageAsync(0);
// ... process first page ....
await dataTableReader.releaseAsync();
}Gets the underlying logical tables used by the worksheet. The resulting logical tables are determined by the measures in the worksheet. If a worksheet's data source contains multiple logical tables and the worksheet contains only measures from one logical table, this API will return one logical table.
An array of logical tables corresponding to the measures referenced by the worksheet.
Use await only inside an Async function
let vizActiveSheet = viz.workbook.activeSheet;
if (vizActiveSheet.sheetType === "worksheet") {
// Call to get the underlying logical tables used by the worksheet
let underlyingTablesData = await vizActiveSheet.getUnderlyingTablesAsync();
let logicalTableId = underlyingTablesData[0].id;
// Use the above logicalTableId to get the underlying data on the active sheet
// by calling worksheet.getUnderlyingTableDataAsync(logicalTableId)
let underlyingTableDataForId = await vizActiveSheet.getUnderlyingTableDataAsync(logicalTableId);
}Returns the visual specification for the worksheet, which can be used to get the mappings from fields to encodings backing the visual within the worksheet
Promise containing the VisualSpecification
Removes the corresponding annotation from the worksheet it belongs to. This is intended to be passed an Annotation object received from getAnnotationsAsync.
The annotation to remove.
Empty promise that resolves when the annotation is removed.
The following example shows how you might call this method using an annotation object.
for (const annotation of annotations) {
await worksheet.removeAnnotationAsync(annotation);
}Removes the external context menu item inserted by the appendContextMenuAsync method.
The parameter menuItemId specifies the menu item to remove and is the return value from the appendContextMenuAsync method.
Once this function is called, menu item identified by menuItemId won't be rendered to the user in corresponding context menu.
Defines where to remove new external menu item.
Unique identifier of external context menu item that user wants to remove.
Sets the displayed header for the external context menu.
The parameter menuHeader specifies the header to be displayed.
Once this function is called, menuHeader will be rendered to the user as the header for corresponding context menu. If not called, a default header will be displayed.
Specifies the location of the external context menu.
Defines a header string to be displayed for the menu.
Defines a description of the menu to be displayed in a tooltip
Selects the marks by value, using the SelectionCriteria interface. This is intended for manual construction of the desired selections.
A list of criteria for which marks to select.
The type of selection to make: add, remove, or replace.
Empty promise that resolves when the selection is complete.
The following example shows how you might call this method using state names as the SelectionCriteria.
The SelectionUpdateType is replace (SelectionUpdateType.Replace), so these values replace
the marks that are currently selected.
worksheet.selectMarksByValueAsync([{
fieldName: 'State',
value: ['Texas', 'Washington', 'California']
}], SelectionUpdateType.Replace );
The index of the sheet within the published tabs. Note that hidden tabs are still counted in the ordering, as long as they are published.