Data Labels in the REST API


Data labels are metadata that you attach to assets, like the certification of a published data source or a data quality warning on a table. Using the REST API, you can manage both the labels as they relate to assets, and – starting with Tableau Cloud 2023.2 – the names and descriptions of the labels as they appear to users in dialogs.

  • The labels methods: Use the labels methods to manage data labels on assets (including earlier features like data quality warnings and certifications) in a unified way. The labels methods were introduced with Tableau Server 2022.3 and Tableau Cloud June 2022.
  • The labelValues methods: Use the labelValues methods to manage the labels available on the server (including those that users see in places like label selection dropdowns). The labelValues methods were introduced starting with Tableau Cloud 2023.2. (The labelValues methods are not currently available for Tableau Server.)

All label operations except those related to the certification of data sources require Catalog to be enabled. Catalog requires a Data Management license.

You can attach labels to the following Tableau content or external assets:

  • Databases
  • Tables
  • Columns - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • Data sources
  • Flows
  • Virtual connections
  • Virtual connection tables

Data label properties

Each data label on an asset has a number of properties, like message, owner, active, and elevated. One of these properties – value – has its own properties: name, category, and description.

Value

The label property called label value has itself three other properties: name, category, and description.

  • name: The label value name can be thought of as the name of the label. The label value name is seen in places like label selection dropdowns in dialog boxes.
  • category: The label value category determines where and how the label appears, whether it appears on assets that are downstream from the one it's attached to, and which parts are customizable, among other things.
  • description: The label value description typically indicates what the label is used for, and may appear in dialog boxes that allow the user to select a label.

Note: The terms label, label value, and label value name are sometimes used interchangeably.

The label value names and label value categories built into Tableau are:

Label value name Label value category
certified certification
warning
deprecated
stale
maintenance
sensitive_data*
extract_refresh_failure
flow_run_failure 		warning
sensitive_data* sensitivity*

* Starting in Tableau Cloud June 2023, the sensitive_data label value is associated with a new category, sensitivity, instead of the warning category. In current versions of Tableau Server, the sensitive_data label value remains associated with the warning category.

The certification category

The certification category is associated with one label value name: certified. It corresponds to certification as described at "Use Certification to Help Users Find Trusted Data" in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) Help, and in the certification methods listed in Metadata Methods.

Starting in Tableau Cloud June 2023, administrators can customize the built-in certification label value description using the labelValues methods. The description can't be changed in current versions of Tableau Server.

The warning category

The label value names associated with the warning category correspond to the warnings mentioned in "Set a Data Quality Warning" in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) Help, and in the data quality warnings methods listed in Metadata Methods.

Five of the label value names correspond to data quality warnings:

  • warning : Warning
  • deprecated : Deprecated
  • stale : Stale data
  • maintenance : Under maintenance
  • sensitive_data : Sensitive data

Note: The sensitive data warning is associated with the Sensitivity category starting in Tableau Cloud June 2023. It remains associated with the warning category in current versions of Tableau Server.

Two of the label value names correspond to monitoring quality warnings:

  • extract_refresh_failure : Extract Refresh Monitoring
  • flow_run_failure : Flow Run Monitoring

Once a monitoring quality warning has been triggered and the warning is attached to an asset, the warning can be seen using the labels methods. However, you can’t create, update, or delete the monitoring quality warnings using the labels methods. (You can’t create, update, or delete monitoring quality warnings using older dataQualityWarning methods either.) See also "How to set a monitoring quality warning" in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) Help and the quality warning trigger methods in Metadata Methods.

Starting in Tableau Cloud 2023.3, administrators can customize the built-in warning label value names and descriptions using the labelValues methods, or add new label values entirely. Label values can't be customized or added in current versions of Tableau Server.

The sensitivity category

The sensitivity category is associated with one built-in label value name: sensitive_data. It corresponds to sensitivity labels described at "Sensitivity Labels" in the Tableau Cloud(Link opens in a new window) Help. This category was released with Tableau Cloud June 2023, and does not currently exist in Tableau Server.

Active

Data labels can be active or inactive.

An active data label can affect the treatment or display of the asset it’s attached to. For example, in the web interface, a database might show a certified icon, or a datasource might show a data quality warning indicating the data is stale.

An inactive data label does not affect the treatment or display of the asset it’s attached to. No special icons or indicators will be attached to the asset. The attributes of an inactive label are not removed, but they also do not affect the asset while the data label is inactive.

Elevated

Data labels can be elevated. An elevated data label may be displayed differently in the Tableau Server or Tableau Cloud web interface. For example, in the web interface, an elevated warning will be seen as a high visibility data quality warning.

Note: Data labels with a category other than warning can also be elevated or not elevated, but this has no effect on the treatment or display of them, and there is no method to change the elevated status of them in the web interface.

Owner

The user who created or last updated the data label is its owner.

Permissions

Permissions required to view, add, update, and delete labels on assets are listed below:

  • To view a data label, you must have read permissions on the associated asset.
  • To add, update, or delete a data label other than a certification label, you must have write permission on the associated asset.
  • To add, update, or delete a certification label, you must be an administrator, or else you must be a project leader or product owner for the project the asset is in.
  • To add, update, or delete a certification label for an external asset not in a project, you must have the change permissions permission on the associated asset.

Webhooks

You can create webhooks that trigger when a data label is created, updated, or deleted. For information, see "Label Events" in Webhook Events and Payloads(Link opens in a new window).


Back to top
Thanks for your feedback!