Extensions v1.5.0

The theme of 1.5.0 is flexibility leading to improved performance. All of the added options and functions allow you as developers to request the data you need, and not spend time requesting data that you do not need. In the DataSourceUnderlyingDataOptions, and GetSummaryDataOptions, you can specify exactly what you want returned. This will reduce both the compute time and transfer size of the data. In addition, internally the payload for all the Get...DataAsync calls changed to reduce the size of the data. Please note that while all these options and functions work with previous versions of Tableau, to recognize the speed improvements, Tableau 2021.2 or newer will be needed.

All of the Get...DataAsync calls return a DataTable with rows of DataValue objects. Notice that DataValue provides both a nativeValue, and a formattedValue property.

export interface DataValue {
  /* tslint:disable:no-any */
  /**
   * @since 1.2.0 Fixes the type to be the raw native value rather than a string.
   * @returns  Contains the raw native value as a JavaScript type, which is
   *           one of string, number, boolean, or Date (as a string). Please note that special
   *           values, regardless of type, are always returned as a String surrounded by
   *           percent signs, such as '%null%', or '%no-access%'.
   */
  readonly value: any;
  /**
   * @since 1.4.0
   * @returns The raw native value as a JavaScript type, which is
   *          one of string, number, boolean, or Date object. Please note that special
   *          values are returned as null. The actual special value can be found
   *          in formattedValue, which would be something like 'Null', or 'No-Access'.
   *          Using nativeValue can greatly simplify your error checking since all values
   *          will be their native type value or null.
   */
  readonly nativeValue: any;
  /* tslint:enable:no-any */
  /**
   * @returns  The value formatted according to the locale and the
   *           formatting applied to the field or parameter.
   */
  readonly formattedValue?: string;
}

It turns out that many developers ignore one of these properties when processing results. The changes in 1.5.0 provide for requesting only the data that you need.

DataSourceUnderlyingDataOptions

DataSourceUnderlyingDataOptions has two new options: columnsToIncludeById, and includeDataValuesOption. Sometimes it is more convenient to work with field ids rather than names. The option columnsToIncludeById supports working with field ids. The option includeDataValuesOption supports requesting only native values or formatted values.

export interface DataSourceUnderlyingDataOptions {
  /**
   * Do not use aliases specified in the data source in Tableau. Default is false.
   */
  ignoreAliases?: boolean;
  /**
   * The columns to return specified by field name, returns all by default.
   */
  columnsToInclude?: Array<string>;
  /**
   * The columns to return specified by field id, returns all by default.
   * Since 1.5.0, fieldId is a property of the Column object.
   * @since 1.5.0
   */
  columnsToIncludeById?: Array<string>;
  /**
   * The maximum number of rows to return. 10,000 by default (this goes away once pagination is implemented)
   */
  maxRows?: number;
  /**
     * Specify which properties to return in DataValues. The default is 
     * `IncludeDataValuesOption.AllValues`.
     * This is a performance optimization only, and will be ignored in 
     * Tableau versions prior to 2021.2.
     *
     * @since 1.5.0
     */
  includeDataValuesOption?: IncludeDataValuesOption;
}

Here is an example call requesting only the native values. When OnlyNativeValues is requested, any DataValue.formattedValue will be undefined.

    let datasources = await this.worksheet.getDataSourcesAsync();
    let tables = await datasources[0].getLogicalTablesAsync();
    let dataTable = await datasources[0].getLogicalTableDataAsync(tables[0].id, {
      includeDataValuesOption: tableau.IncludeDataValuesOption.OnlyNativeValues,
    });

GetSummaryDataOptions & GetUnderlyingDataOptions

The property maxRows, was moved from GetUnderlyingDataOptions to GetSummaryDataOptions so that it is available to both. In addition, GetSummaryDataOptions now include the properties: columnsToIncludeById, and includeDataValuesOption. The option columnsToIncludeById can be used to request just a specified set of columns from either summary or underlying data. The option includeDataValuesOption supports requesting only native values or formatted values from summary or underlying data.

export interface GetSummaryDataOptions {
  /**
   * Do not use aliases specified in the data source in Tableau. Default is false.
   */
  ignoreAliases?: boolean;
  /**
   * Only return data for the currently selected marks. Default is false.
   */
  ignoreSelection?: boolean;
  /**
   * The columns to return specified by field id, returns all by default.
   * Since 1.5.0, fieldId is a property of the Column object.
   * @since 1.5.0
   */
  columnsToIncludeById?: Array<string>;
  /**
   * The number of rows of data that you want to return. A value of `0` will 
   * attempt to return all rows. `0` is the default if maxRows is not specified.
   * `getUnderlyingTableDataAsync' - maximum number of rows returned is 
   * capped at 10,000 regardless of maxRows.
   * `getSummaryDataAsync` - maximum number of rows returned is not capped, 
   * but performance may suffer for large row counts.
   *
   * @since 1.5.0 maxRows is now supported in both `GetSummaryDataOptions` 
   * and `GetUnderlyingDataOptions`.
   */
  maxRows?: number;
  /**
   * Specify which properties to return in DataValues. The default is 
   * `IncludeDataValuesOption.AllValues`.
   * This is a performance optimization only, and will be ignored in 
   * Tableau versions prior to 2021.2.
   *
   * @since 1.5.0
   */
  includeDataValuesOption?: IncludeDataValuesOption;
}

The following example shows requesting 10 rows, formatted data only, of one column of summary data.

    let dataTable = await this.worksheet.getSummaryDataAsync({
      maxRows: 10,
      includeDataValuesOption: tableau.IncludeDataValuesOption.OnlyNativeValues,
      columnsToIncludeById: [desiredFieldId],
    });

Column object

The Column object has an additional property fieldId. This fieldId can be used the columnsToIncludeById option.

export interface Column {
  /**
   * @returns  The name of the field in the column. In summary data, this includes 
   * the aggregation.
   * The summary data field name is not stable across languages.
   * For example, in an English version of Tableau, the field name might be 
   * SUM(Sales). In French, this would be SOMME(Sales).
   */
  readonly fieldName: string;
  /**
   * @since 1.5.0
   * @returns  The fieldId of the field in the column. In summary data, this 
   * includes the aggregation.
   * The fieldId is not stable across replacing data sources.
   * For example after replacing the data source 
   * [Clipboard_20210305T164000].[sum:Sales:qk] could become
   * [federated.12usuoq1171o1b1ebdyh60fjnev1].[sum:Sales:qk].
   */
  readonly fieldId: string;
  /**
   * @returns The data type of the column. Possible values are
   *           float, integer, string, boolean, date, and datetime.
   */
  readonly dataType: DataType;
  /**
   * @returns  Whether the column data is referenced in the visualization.
   */
  readonly isReferenced: boolean;
  /**
   * @returns  The number of rows in the returned data.
   */
  readonly index: number;
}

GetSummaryColumnsInfoAsync

There are times when you might be interested in column information, but not the data. Up until now, the only way to get the columns was to use getSummaryDataAsync. If the user has lots of data in their viz, this could be expensive. Use GetSummaryColumnsInfoAsync to quickly get the column information. Note that in Tableau versions prior to 2021.2, this will not be any faster than getSummaryDataAsync. To see a dramatic speedup, ensure the user is on version 2021.2+.

  /**
  * Gets the columns that are returned with `getSummaryDataAsync`.
  *
  * @returns The array of columns that describe the data in the worksheet.
  * @since 1.5.0
  */
  getSummaryColumnsInfoAsync(): Promise<Array<Column>>;

Other 1.5 improvements

• setZoneVisibilityAsync can now be used on any zone in the dashboard rather than just on floating zones.
• Filter.getFieldAsync has been fixed to properly return the field. This requires Tableau 2019.2+.