Interface Worksheet

since

1.10.0 and Tableau 2022.4

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');

since

1.10.0 and Tableau 2022.3

since

1.10.0 Errors will now be thrown for invalid fields or values.

since

version 1.9.0 and Tableau 2022.2

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,
   }
 );

   worksheet.clearSelectedMarksAsync().then(function () {
       console.log('Your marks selection has been cleared!');
   })

since

1.10.0 and Tableau 2022.4

The following example shows how you might call this method.

   let annotations = await worksheet.getAnnotationsAsync();
   console.log(annotations);

worksheet.getDataSourcesAsync().then(datasources => {
  dataSource = datasources.find(datasource => datasource.name === "Sample - Superstore");
  return dataSource.getUnderlyingDataAsync();
}).then(dataTable => {
// process the dataTable...
});

// Call to get the selected marks for the worksheet
worksheet.getSelectedMarksAsync().then(function (marks) {
  // Get the first DataTable for our selected marks (usually there is just one)
  const worksheetData = marks.data[0];

  // Map the data into a format for display, etc.

});

since

1.5.0

deprecated

since 1.10.0 Use getSummaryDataReaderAsync to avoid failures with many rows of data.

---

Note: The getSummaryDataAsync and getSummaryDataReaderAsync methods return the data that is currently in the viz, with parameters, calculated fields, and sorting applied. To access full data, that is the underlying data without the additional fields and processing you have added in Tableau, use the Worksheet.getUnderlyingTableDataAsync and Worksheet.getUnderlyingTableDataReaderAsync methods.

---

The following example shows how to replace unsafe usage of getSummaryDataAsync with getSummaryDataReaderAsync and getAllPagesAsync, assuming you have less than 4,000,000 rows of data.

const dataTableReader = await worksheet.getSummaryDataReaderAsync();
const dataTable = await dataTableReader.getAllPagesAsync();
await dataTableReader.releaseAsync();
// ... process data table ...

The following example shows how to replace unsafe usage of getSummaryDataAsync with getSummaryDataReaderAsync and getPageAsync and work with individual pages.

const dataTableReader = await worksheet.getSummaryDataReaderAsync();
for (let currentPage = 0; currentPage < dataTableReader.pageCount; currentPage++) {
  const dataTablePage = await dataTableReader.getPageAsync(currentPage);
  // ... process current page ....
}
await dataTableReader.releaseAsync();

---

Note: The getSummaryDataAsync and getSummaryDataReaderAsync methods return the data that is currently in the viz, with parameters, calculated fields, and sorting applied. To access full data, that is the underlying data without the additional fields and processing you have added in Tableau, use the Worksheet.getUnderlyingTableDataAsync and Worksheet.getUnderlyingTableDataReaderAsync methods.

---

const dataTableReader = await worksheet.getSummaryDataReaderAsync();
for (let currentPage = 0; currentPage < dataTableReader.pageCount; currentPage++) {
  let dataTablePage = await dataTableReader.getPageAsync(currentPage);
  // ... process current page ....
}
await dataTableReader.releaseAsync();

deprecated

Use Worksheet.getUnderlyingTableDataReaderAsync or Worksheet.getUnderlyingTableDataAsync.

since

1.4.0

---

Note: Use the getUnderlyingTableDataAsync method to access the full data, that is the underlying data without the parameters, calculated fields, and processing you might have added in Tableau. To access just the data that is currently in the viz, with parameters, calculated fields, and sorting applied, use the Worksheet.getSummaryDataAsync and Worksheet.getSummaryDataReaderAsync methods.

---

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.

since

1.5.0 You can use the GetUnderlyingDataOptions.includeDataValuesOption property to optimize performance by restricting the properties included in the returned DataValues.

see

getUnderlyingTableDataReaderAsync to read more than 10,000 rows.

const logicalTables = await worksheet.getUnderlyingTablesAsync();
const dataTable = await worksheet.getUnderlyingTableDataAsync(logicalTables[0].id)
// process the dataTable...

---

Note: Use the getUnderlyingTableDataReaderAsync method to access the full data, that is the underlying data without the parameters, calculated fields, and processing you might have added in Tableau. To access just the data that is currently in the viz, with parameters, calculated fields, and sorting applied use the Worksheet.getSummaryDataAsync and Worksheet.getSummaryDataReaderAsync methods.

---

The getUnderlyingTableDataReaderAsync method 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.

// Call to get the underlying logical tables used by the worksheet
const underlyingTablesData = await worksheet.getUnderlyingTablesAsync();
const logicalTableId = underlyingTablesData[0].id;
// Use the above logicalTableId to get the underlying data reader on the active sheet
const dataTableReader = await worksheet.getUnderlyingTableDataReaderAsync(logicalTableId);
const page = await dataTableReader.getPageAsync(0);
// ... process first page of data table ...
await dataTableReader.releaseAsync();

since

1.4.0

// Call to get the underlying logical tables used by the worksheet
worksheet.getUnderlyingTablesAsync().then(function (logicalTables) {
  // Get the first logical table's id
  const logicalTableId = logicalTables[0].id;

  // Use the above logicalTableId to then get worksheet's underlying data
  // by calling worksheet.getUnderlyingTableDataAsync(logicalTableId)

});

since

1.11.0 and Tableau 2024.1

since

1.10.0 and Tableau 2022.4

The following example shows how you might call this method using an annotation.

   for (const annotation of annotations) {
     await worksheet.removeAnnotationAsync(annotation);
   }

since

1.10.0 Errors will now be thrown for invalid fields or values.

The following example shows how you might call this method using state names as the SelectionCriteria. The SelectionUpdateType is replace (tableau.SelectionUpdateType.Replace), so these values replace the marks that are currently selected.

   worksheet.selectMarksByValueAsync([{
        fieldName: 'State',
        value: ['Texas', 'Washington', 'California']
    }], tableau.SelectionUpdateType.Replace );

You can find the tuple id for a row of data by subtracting the index of the row from the total number of rows. For example, if you have 10 rows, and want to know the tuple id associated with the third row, it will be 7 (10 - 3 = 7). The last row of data will always have the tuple id of 1.

Passing in an invalid tuple id will not throw.

let navigatedTuple = -1;
let updateScreenReaderElement = (screenReadertext) => {
  // updates an element to be read out by screen readers
};

let updateNavigatedTuple = (keyboardEvent) => {
  switch (keyboardEvent.key) {
    case 'ArrowLeft':
      navigatedTuple = navigatedTuple - 1;
      break;
    case 'ArrowRight':
      navigatedTuple = navigatedTuple + 1;
      break;
    default:
      break;
  }
  // do any work to show visual indication of a mark being navigated to
};

svg.on('keydown', (keyboardEvent) => {
  updateNavigatedTuple(keyboardEvent);
  tableau.extensions.worksheetContent.worksheet
    .getTooltipTextAsync(navigatedTuple)
    .then((response) => {
      console.log(response.result);
      updateScreenReaderElement(response.result);
    })
    .catch((error) => console.log('Failed to get tooltip text because of: ', error));
});

since

1.12.0 and Tableau 2024.2

The hoveredTuple parameter is a tuple id. You can find the tuple id for a row of data by subtracting the index of the row from the total number of rows. For example, if you have 10 rows, and want to know the tuple id associated with the third row, it will be 7 (10 - 3 = 7). The last row of data will always have the tuple id of 1.

Passing in an invalid tuple id will not throw and will clear the tooltip.

svg.on('mousemove', (mouseEvent) => {
 const myHoveredTuple = 10;
 tableau.extensions.worksheetContent.worksheet.hoverTupleAsync(myHoveredTuple, { tooltipAnchorPoint: { x: mouseEvent.pageX, y: mouseEvent.pageY } })
   .then(() => console.log('Done'))
   .catch((error) => console.log('Failed to hover because of: ', error));
 });

since

1.12.0 and Tableau 2024.2

svg.on('keyup', (keyboardEvent) => {
  if (keyboardEvent.key == "Escape") {
    tableau.extensions.worksheetContent.worksheet
      .leaveMarkNavigationAsync()
      .then(() => console.log('Done'))
      .catch((error) => console.log('Failed to leave mark-level keyboard navigation because of: ', error));
  }
});

since

1.12.0 and Tableau 2024.2

The selectedTuples parameter is an array of tuple ids. You can find the tuple id for a row of data by subtracting the index of the row from the total number of rows. For example, if you have 10 rows, and want to know the tuple id associated with the third row, it will be 7 (10 - 3 = 7). The last row of data will always have the tuple id of 1.

Passing in an invalid tuple id will not throw and will clear the tooltip.

svg.on('click', (mouseEvent) => {
const myClickedTuples = [10];
const ctrlKeyPressed = !!mouseEvent.ctrlKey;
const selectOption = ctrlKeyPressed ? tableau.SelectOptions.Toggle : tableau.SelectOptions.Simple;

tableau.extensions.worksheetContent.worksheet.selectTuplesAsync(myClickedTuples, selectOption, { tooltipAnchorPoint: { x: mouseEvent.pageX, y: mouseEvent.pageY } })
   .then(() => console.log('Done'))
   .catch((error) => console.log('Failed to select because of: ', error));
});

since

1.12.0 and Tableau 2024.2