Metadata Methods

Metadata methods are available in Tableau version 2019.3 and later.

Using the metadata methods of the Tableau Server Rest API, you can do the following tasks on metadata indexed by or surfaced through Tableau Catalog in Tableau Server and Tableau Online:

Database (external asset type)

  • Query a database or multiple databases
  • Update or remove a database
  • Add, query, or delete database permissions
  • Add, query, or delete default database permissions

Table (external asset type)

  • Query a table or multiple tables
  • Update or remove a table
  • Add, query, or delete table permissions

Column (external asset type)

  • Query a column or multiple columns that belong to a specific table
  • Update or remove a column that belongs to a specific table

Data quality warning (DQW) (communicates data quality information for databases, tables, published data sources, and flows)

  • Add, update, delete a data quality warning
  • Query data quality warnings

The above functionality relates to metadata concepts and Data Catalog UI elements described at: About Tableau Catalog.

For deeper and more comprehensive API functionality for querying metadata and schema information for Tableau content, see Tableau Metadata API Help.

Query Database

Get information about a database asset.

URI

GET api/api-version/sites/site-id/databases/database-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
database-id The unique ID of the database asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to query a database asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Online site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <database id="c495c67b-2a17-4706-991c-b3b14f881e20" name="dataengine_42020_789079537040lea.hyper" connectionType="hyper" isEmbedded="true" isCertified="true" certificationNote="Verified" type="File" filePath="dataengine_42020_789079537040lea.hyper" contentPermissions="ManagedByOwner">
	<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	<contact id="95656dcf-c669-46c0-81fb-8f278e4806b2" name="fsuzuki"/>
	<certifier id="2c5ea058-6408-46a6-9aa2-09f795a31237" name="snguyen"/>
  </database>
</tsResponse>

Note: This method returns connection information, including connection type. In some cases, the name of the connection type might not map directly to a name of a connection type that you're familiar with. In those cases, see Mapping ConnectionType Names for more information.

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409046 Unknown database query error An unknown error occurred and the database query could not complete.

Query Databases

Get information about all database assets for a site.

URI

GET api/api-version/sites/site-id/databases

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to query database assets:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Online site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <databases>
	<pagination pageNumber="1" pageSize="100" totalAvailable="496">
	<database id="b749a80e-43eb-4805-9e6d-44c615ee10e2" name="airlines" connectionType="sqlserver" isEmbedded="false" description="This is about airlines and other stuff but mainly airlines" isCertified="true" certificationNote="THIS IS ALSO FROM THE REST API" type="DatabaseServer" hostName="mssql.test.tsi.lan" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
		<contact id="95656dcf-c669-46c0-81fb-8f278e4806b2" name="jsmith"/>
		<certifier id="2c5ea058-6408-46a6-9aa2-09f795a31237" name="snguyen"/>
	</database>
	<database id="522f8295-5a07-4ba7-89be-cbbd9617928d" name="small.csv" connectionType="textscan" isEmbedded="true" isCertified="false" type="File" filePath="small.csv" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
		<contact id="95656dcf-c669-46c0-81fb-8f278e4806b2" name="fsuzuki"/>
	</database>
	<database id="fcd0f91e-8c8d-45c4-848a-0aa3b42990c6" name="ows.json" connectionType="semistructpassivestore-direct" isEmbedded="true" isCertified="false" type="File" filePath="ows.json" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</database>
	<database id="24010777-0e17-43ed-8624-577a85e8043b" name="/Users/awang/Dropbox (Tableau Software)/911_calls_short.csv" connectionType="textscan" isEmbedded="false" isCertified="false" type="File" filePath="/Users/jsmith/Dropbox (Tableau Software)/911_calls_short.csv" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</database>
	<database id="1d1879b2-789d-46c2-950f-f82a4d77e150" name="911_calls_short.csv" connectionType="textscan" isEmbedded="true" isCertified="false" type="File" filePath="911_calls_short.csv" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</database>
	<database id="bc872610-aa3e-4071-8a39-2c1a847cf39c" name="Prince.xlsx" connectionType="excel-direct" isEmbedded="true" isCertified="false" type="File" filePath="Prince.xlsx" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</database>
  </databases>
</tsResponse>

Note: This method returns connection information, including connection type. In some cases, the name of the connection type might not map directly to a name of a connection type that you're familiar with. In those cases, see Mapping ConnectionType Names for more information.

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested databases could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409046 Unknown database query error An unknown error occurred and the database query could not complete.

Update Database

Update the database description, certify a database, or assign a contact (must be a Tableau Server or Tableau Online user) to the database asset.

URI

PUT api/api-version/sites/site-id/databases/database-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
database-id The unique ID of the database asset.

Request Body

<tsRequest>
  <database isCertified="certification-status" certificationNote="certification-note"description="new-description-value">
	<contact id="new-contact-id">
  </database>
</tsRequest>

Attribute Values

Any combination of attributes inside the <database> element is valid. Only the attributes and child elements that are included result in updates to the database asset. If no attributes or nested elements are included, no update is made.

certification-status

(Optional) Certify or remove certification by using the following:

  • True
  • False
certification-note (Optional) Custom text to accompany the certification status.
new-description-value (Optional) Custom text to describe the database asset.
new-contact-id (Optional) The ID (not name) of the Tableau Server or Tableau Online user to associated with the database asset.

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to update the database asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <database id="31d6ab16-3821-489b-8197-39453ce94a49" name="coffee" connectionType="sqlserver" isEmbedded="false" description="Contact Susan Nguyen (database admin) for changes." isCertified="true" certificationNote="Removed certification via REST" type="DatabaseServer" hostName="mssql.test.tsi.lan" contentPermissions="LockedToDatabase">
	<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	<contact id="2a80c15e-87c8-4b07-a5f4-e49f95e9fb0b" name="fsuzuki"/>
	<certifier id="26183d16-82f7-4fcf-b163-0e607bf292bc" name="admin"/>
  </database>
</tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409050 Database update error An unknown error occurred and the database asset could not be updated.
409 409051 Database update forbidden A user without "write" permissions to the database asset attempted an update.

Remove Database

Permanently remove the database asset.

URI

DELETE api/api-version/sites/site-id/databases/database-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
database-id The unique ID of the database asset.

Request Body

None

Permissions

Server or site administrators only.

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to remove the database asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409047 Database delete error An unknown error occurred and the database asset could not be deleted.

Add Database Permissions

Add permissions to a database asset. To add permissions, the database asset must be associated with a published data source.

URI

PUT api/api-version/sites/site-id/databases/database-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
database-id The unique ID of the database asset.

Request Body

<tsRequest>
  <permissions>
    <database id="database-id" />
    <granteeCapabilities>
     	<user id="user-id" />
     	<capabilities>
     	 <capability name="capability-name" mode="capability-mode" />
      	... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
       <capability name="capability-name" mode="capability-mode" />
       ... additional capabilities ...
       </capabilities>
     </granteeCapabilities>
     <contentPermisions="new-content-permissions" />
  </permissions>
</tsRequest>

Attribute Values

database-id The ID (not name) for the database asset you want to add permissions to.
user-id The ID (not name) of the user to add permissions for.
capability-name

The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a database are:

  • Read (view)
  • Write (edit)
  • ProjectLeader (set permissions)

These values are case sensitive.

capability-mode

Use one of the following capabilities: 

  • Allow
  • Deny

These values are case sensitive.

group-id The ID (not name) of the group to add permissions for.
new-content-permissions

(Optional) The new permissions setting for the database. You can specify one of the following:

  • LockedToDatabase to lock permissions so that users cannot overwrite the default permissions set for the database asset.
  • ManagedByOwner to allow users to manage permissions for the database asset used by the content that they own.

The default permissions setting is ManagedByOwner. These values are case sensitive.

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following authorized users have permissions to add database asset permissions:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Response Body

Example response

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.tsi.lan:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400120 Bad request Permissions could not be added because support for explicit permissions is available for database assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
405 405000 Invalid request method Request type was not PUT.
409 409045 Database error An unknown database asset error occurred.
409 409050 Database update error An unknown error occurred and the database asset could not be updated.
409 409051 Database update forbidden A user without "write" permissions to the database asset attempted an update.

Query Database Permissions

Get information about the permissions on a database asset.

URI

GET api/api-version/sites/site-id/databases/database-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
database-id The unique ID of the database asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following authorized users have permissions to query the permissions on the database asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Response Body

Example response with explicit permissions set on a database asset:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.tsi.lan:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>

Example response without explicit permissions set on a database asset:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<database id="0f206b0e-da69-4746-bb95-87695f522b4d" name="stage"/>
  </permissions>
</tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400120 Bad request Permissions could not be returned because support for explicit permissions is available for database assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
400 400120 Bad request Support for explicit permissions is available for database assets associated with published data sources only.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.

Add Default Database Permissions

Applying default permissions to a database functions as a permissions template for the database's children table assets. How default permissions are enforced depends on whether the database is locked or unlocked.

  • Locked to the database: If the permissions on a database are locked or Locked to the database, existing child table assets and new child table assets that get indexed by Catalog will inherit the default permissions applied to the parent database asset. Note: If the database is locked, explicit permissions cannot be made for individual tables.

  • Managed by the owner: If the permissions on a database are unlocked or Managed by the owner, only new child table assets that get indexed by Catalog will inherit the default permissions applied to the parent database asset. Note: If the database is unlocked, explicit permissions for the table can be made in a separate request.

URI

PUT /api/api-version/sites/site-id/databases/database-id/default-permissions/tables

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
database-id The unique ID of the database asset to set default permissions for.

Request Body

<tsRequest>
  <permissions>
	<granteeCapabilities>
	  <user id="user-id" />
      <capabilities>
	    <capability name="capability-name" mode="capability-mode" />
	    < !-- ... additional capabilities ... -->
	  </capabilities>
	</granteeCapabilities>
	<granteeCapabilities>
      <group id="group-id" />
	  <capabilities>
		<capability name="capability-name" mode="capability-mode" />
		< !-- ...  additional capabilities ... -->
	  </capabilities>
	</granteeCapabilities>
    < !-- ... additional grantee capability sets ...  -->
  </permissions>
</tsRequest>

Attribute Values

user-id The ID (not name) of the user to add default permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name

The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a databases are the following:

  • Read (view)
  • Write (edit)
  • ChangePermissions (manage permissions)

These values are case sensitive.

capability-mode

Use one of the following capabilities:

  • Allow
  • Deny

These values are case sensitive.

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following authorized users set default permissions for the database asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Response Body

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.tsi.lan:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to add permissions on the project.
403 403114 Permissions setting forbidden Default permissions cannot be added because the database asset is locked.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404003 Resource not found The database ID in the URI doesn't correspond to a database asset on the site.
404 404002 User not found A user ID in the request body as the grantee doesn't correspond to an existing user.
404 404012 Group not found A group ID in the request body doesn't correspond to an existing group.
404 404013 Capability not found The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

Query Default Database Permissions

Get the default permissions applied to the database asset and its children tables.

URI

GET /api/api-version/sites/site-id/databases/database-id/default-permissions/tables

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
database-id The unique ID of the database asset to set default permissions for.

Request Body

None

Attribute Values

user-id The ID (not name) of the user to add default permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name

The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a databases are the following:

  • Read (view)
  • Write (edit)
  • ChangePermissions (manage permissions)

These values are case sensitive.

capability-mode

Use one of the following capabilities:

  • Allow
  • Deny

These values are case sensitive.

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following authorized users set default permissions for the database asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Response Body

Example response

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.tsi.lan:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
		

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400120 Bad request Permissions could not be returned because support for explicit permissions is available for database assets associated with published data sources only.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to see the database asset.
403 403115 Permissions setting forbidden Default permissions cannot be queried because the user is not a Tableau Server admin, Tableau Online site admin, or have explicit Set Permissions on the database asset.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404003 Resource not found The database ID in the URI doesn't correspond to a database asset on the site.
404 404002 User not found A user ID in the request body as the grantee doesn't correspond to an existing user.
404 404012 Group not found A group ID in the request body doesn't correspond to an existing group.
404 404013 Capability not found The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

Delete Database Permissions

Permanently remove the permissions applied to a database asset.

URI

DELETE api/api-version/sites/site-id/databases/database-id/permissions/users/user-id/capability-name/capability-mode

DELETE api/api-version/sites/site-id/databases/database-id/permissions/groups/group-id/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site.
database-id The unique ID of the database asset.
user-id The unique ID of the user to remove the permissions for.
group-id The unique ID of the group to remove the permissions for.
capability-name The explicit permissions capability to remove. Capabilities that can be removed are Read, Write, or ChangePermissions.
capability-mode The permissions mode to remove. Modes that can be removed are Allow or Deny.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following authorized users have permissions to delete the permissions on the database asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400120 Bad request Permissions could not be deleted because support for explicit permissions is available for database assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
403 403117 Database locked Permissions for the database asset cannot be deleted because the database asset is locked.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409051 Database update forbidden A user without "write" permissions to the database asset attempted an update.

Delete Default Database Permissions

Permanently remove the default permissions on a database asset. Removing the default permissions from the database asset means that any new child table assets that are indexed by Catalog won't have any default permissions set.

URI

DELETE api/api-version/sites/site-id/databases/database-id/default-permissions/tables/users/user-id/capability-mode

DELETE api/api-version/sites/site-id/databases/database-id/default-permissions/tables/groups/group-id/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
database-id The unique ID of the database asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following authorized users have permissions to delete the permissions on the database asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400120 Bad request Permissions could not be deleted because support for explicit permissions is available for database assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
403 403117 Database locked Default permissions cannot be deleted because the database asset is locked.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409051 Database update forbidden A user without "write" permissions to the database asset attempted an update.

Query Table

Get information about a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to query the table asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Online site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <table id="917b1438-7000-4a9e-a949-13b90a0237dd" name="[Orders$]" isEmbedded="true" isCertified="false">
	<site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
  </tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table could not be found.
409 409052 Unknown table error An unknown table asset error occurred.
409 409053 Unknown table query error An unknown error occurred and the table query could not complete.

Query Tables

Get information about all table assets for a site.

URI

GET api/api-version/sites/site-id/tables

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to query table assets:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Online site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <tables>
	<table id="6a9b6058-671d-44bc-ad6d-c58b225f5d4c" name="Culture" isEmbedded="false" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
 	</table>
	<table id="917b1438-7000-4a9e-a949-13b90a0237dd" name="[Orders$]" isEmbedded="true" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
	</table>
	<table id="58d94f3f-1339-4721-8674-e53dc9dfe02e" name="Batters" isEmbedded="false" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
	</table>
	<table id="5e8ca1e3-9752-430c-abae-11104084b469" name="[911_calls_short#csv]" isEmbedded="false" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
	</table>
  </tables>
</tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested tables could not be found.
409 409052 Unknown table error An unknown table asset error occurred.
409 409053 Unknown table query error An unknown error occurred and the table query could not complete.

Update Table

Update the table description, certify a table, or a assign a user contact to the table asset.

URI

PUT api/api-version/sites/site-id/tables/table-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

<tsRequest>
  <table isCertified="certification-status" certificationNote="certification-note" description="new-descrption-value">
	<contact id="new-contact-id">
	</contact>
  </table>
</tsRequest>

Attribute Values

Any combination of attributes inside the <table> element is valid. Only the attributes and child elements that are included result in updates to the table. If no attributes or nested elements are included, no update is made.

certification-status

(Optional) Use one of the following values:

  • true
  • false

These values are case sensitive.

certification-note (Optional) Custom text to accompany the certification status.
new-description-value (Optional) Custom text to describe the table asset.
new-contact-id (Optional) The ID (not name) of the certification owner.

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to update the table asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <table id="b86632d7-b82e-4d4c-88e5-11957cdadd95" name="Zoning.shp" description="Contact Susan Nguyen (database admin) for changes." isEmbedded="true" isCertified="false">
	<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
  </table>
</tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409052 Table error An unknown table asset error occurred.
409 409057 Table update error An unknown error occurred and the table asset could not be updated.
409 409058 Table update forbidden A user without "write" permissions to the table asset attempted an update.

Remove Table

Permanently remove the table asset.

URI

DELETE api/api-version/sites/site-id/tables/table-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to remove the table asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409052 Table error An unknown table asset error occurred.
409 409054 Unknown table delete error An unknown error occurred and the table could not be deleted.

Add Table Permissions

Add permissions to a table asset.

URI

PUT api/api-version/sites/site-id/tables/table-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

<tsRequest>
  <permissions>
    <table id="table-id" />
    <granteeCapabilities>
     <user id="user-id" />
     <capabilities>
      <capability name="capability-name" mode="capability-mode" />
      ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
     <group id="group-id" />
      <capabilities>
       <capability name="capability-name" mode="capability-mode" />
       ... additional capabilities ...
       </capabilities>
     </granteeCapabilities>
       ... additional grantee capability sets ...
     <contentPermissions="new-content-permissions" />
  </permissions>
</tsRequest>

Attribute Values

table-id The ID (not name) for the table asset you want to add permissions to.
user-id The ID (not name) of the user to add permissions for.
capability-name

The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a database are:

  • Read (view)
  • Write (edit)
  • ProjectLeader (set permissions)

These values are case sensitive.

capability-mode

Use one of the following capabilities:

  • Allow
  • Deny

These values are case sensitive.

group-id The ID (not name) of the group to add permissions for.

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to add table asset permissions:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<table id="d0fe66ae-1407-4338-8520-9489d7ce959c" name="_WarehouseConfig"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400120 Bad request Permissions could not be added because support for explicit permissions is available for table assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
403 403117 Database locked Permissions for the table asset cannot be deleted because the database asset is locked.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409052 Table error An unknown table asset error occurred.
409 409057 Table update error An unknown error occurred and the table asset could not be updated.
409 409058 Table update forbidden A user without "write" permissions to the table asset attempted an update.

Query Table Permissions

Get information about the permissions on a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following authorized users have permissions to query the permissions on the table asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Response Body

Example response with explicit permissions set:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<table id="d0fe66ae-1407-4338-8520-9489d7ce959c" name="_WarehouseConfig"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>

Example response without explicit permissions set:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<parent id="95ac9b30-5b2c-48ed-af56-cab9b0d4b064" type="Database"/>
	  <table id="4ef842be-5c90-4878-a048-99a896b59996" name="BigMachines"/>
  </permissions>
</tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400120 Bad request Permissions could not be returned because support for explicit permissions is available for table assets associated with published data sources (not embedded data sources) only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409052 Table error An unknown table asset error occurred.
409 409053 Unknown table query error An unknown error occurred and the table query could not complete.

Delete Table Permissions

Permanently remove the permissions applied to a table asset.

URI

DELETE api/api-version/sites/site-id/table/table-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to delete the permissions on a table asset:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400120 Bad request Permissions could not be deleted because support for explicit permissions is available for table assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
403 403117 Database locked Permissions for the table asset cannot be deleted because the database asset is locked.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
409 409051 Database update forbidden A user without "write" permissions to the database asset attempted an update.

Query Column in a Table

Get information about a column in a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id/columns/column-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to query a column asset in a table:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Online site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
	<column id="0b589fc9-1523-4aae-b711-62d48672ac6a" name="StateProvinceID" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
	  <site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</column>
</tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
409 409059 Unknown column error An unknown column asset error occurred.
409 409060 Unknown column query error An unknown error occurred and the column query could not complete.
409 409066 Column not found The requested column asset could not be found.

Query Columns in a Table

Get information about the columns in a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id/columns

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to query column assets in a table:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Online site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <columns>
	<column id="38cb9944-4b81-4107-8946-5adf9e047d23" name="AddressID" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</column>
	<column id="c6dcdb0e-9b2a-4224-bf3b-58662fe72b09" name="AddressLine1" remoteType="WSTR" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</column>
  </columns>
</tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
409 409059 Unknown column error An unknown column asset error occurred.
409 409060 Unknown column query error An unknown error occurred and the column query could not complete.
409 409066 Column not found The requested column assets could not be found.

Update Column

Update the description of the column.

URI

PUT api/api-version/sites/site-id/tables/table-id/columns/column-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.

Request Body

<tsRequest>
  <column description="new-description-value">
  </column>
</tsRequest>

Attribute Values

Any combination of attributes inside the <column> element is valid. Only the attributes and child elements that are included result in updates to the table. If no attributes or nested elements are included, no update is made.

new-description-value (Optional) Custom text to describe the column.

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to update the column:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <column id="0b589fc9-1523-4aae-b711-62d48672ac6a" name="StateProvinceID" description="Validated against maps" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
	<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
  </column>
</tsResponse>

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409052 Column error An unknown table asset error occurred.
409 409057 Column update error An unknown error occurred and the table asset could not be updated.
409 409058 Column update forbidden A user without "write" permissions to the table asset attempted an update.
409 409066 Column not found The requested column asset could not be found.

Remove Column

Permanently remove the column from a table asset.

URI

DELETE api/api-version/sites/site-id/tables/table-id/columns/column-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to remove the column:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409059 Column error An unknown column asset error occurred.
409 409061 Unknown column delete error An unknown error occurred and the column could not be deleted.
409 409066 Column not found The requested column asset could not be found.

Add Data Quality Warning

Create and apply a data quality warning to a database, table, published data source, or flow.

Only one data quality warning can be applied to the asset. Adding a data quality warning to the asset that already has one causes an error.

URI

POST api/api-version/sites/site-id/dataQualityWarnings/content-type/content-luid

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type The type of asset that the data quality warning is being attached to. To specify the type, use:
  • database
  • table
  • datasource
  • flow

Types are not case sensitive.

content-luid The unique ID of the asset (database, table, published data source, or flow). This is the same as the content ID.

Request Body

<tsRequest>
  <dataQualityWarning type="type" isActive="status" message="message" isSevere="true"/>
</tsRequest>

Attribute Values

Any combination of attributes inside the <dataQualityWarning> element is valid, but the data quality warning type is required. If the data quality warning type is not included, an error is thrown.

type

Type of data quality warning to apply to the asset. To specify the type, use one of the following values:

  • Deprecated
  • Warning
  • Stale data
  • Under maintenance
status (Optional) Status of the data quality warning. Values can be "true" or "false".
message (Optional) A custom message to accompany the data quality warning.
isSevere (Optional) Enables high visibility for the data quality warning. Values can be "true" or "false". For more information, see "Set high visibility for data quality warning" in the Server Help or Online Help.

 

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to add the data quality warning:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

201

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400109 Bad request The request body is missing the data quality warning type.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The requested asset could not be found.

Query Data Quality Warning by ID

Get information about a specific data quality warning.

URI

GET api/api-version/sites/site-id/dataQualityWarnings/dataqualitywarning-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
dataqualitywarning-id The unique ID of the data quality warning attached to the asset (database, table, published data source, or flow).

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to query the data quality warning:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Online site admins.

Response Code

200

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400103 Unknown data quality warning query error An unknown error occurred and the data quality warning query could not complete.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404030 Data quality warning not found The data quality warning for the requested asset could not be found.

Query Data Quality Warning by Content

Get information about the data quality warning for the database, table, published data source, or flow.

URI

GET api/api-version/sites/site-id/dataQualityWarnings/content-type/content-luid

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type The type of asset that the data quality warning is being attached to. To specify the type, use one of the following values:
  • database
  • table
  • datasource
  • flow

Types are not case sensitive.

content-luid The unique ID of the content type (database, table, published data source, or flow). This is the same as the content ID.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to query the data quality warning:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Online site admins.

Response Code

200

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400104 Unknown data quality warning query error An unknown error occurred and the data quality warning query could not complete.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The requested asset could not be found.
404 404030 Data quality warning not found The data quality warning for the requested asset could not be found.

Update Data Quality Warning

Update the warning type, status, and message of a data quality warning.

URI

PUT api/api-version/sites/site-id/dataQualityWarnings/dataqualitywarning-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
dataqualitywarning-id The unique ID of the data quality warning attached to the asset (database, table, published data source, or flow).

Request Body

<tsRequest>
  <dataQualityWarning type="type" isActive="status" message="message" isSevere="true"/>
</tsRequest>

Attribute Values

Any combination of attributes inside the <dataQualityWarning> element is valid, but the request body can't be empty.

type Type of data quality warning to apply to the asset. The following types are allowed:
  • Deprecated
  • Warning
  • Stale data
  • Under maintenance
status Status of the data quality warning. Values can be "true" or "false".
message (Optional) Custom text to accompany the data quality warning.
isSevere (Optional) Enables high visibility for the data quality warning. Values can be "true" or "false". For more information, see "Set high visibility for data quality warning" in the Server Help or Online Help.

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to update the data quality warning:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

200

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400109 Bad request The request body can't be empty.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The requested asset could not be found.
404 404030 Data quality warning not found The data quality warning for the requested asset could not be found.

Delete Data Quality Warning by ID

Permanently remove a data quality warning.

URI

DELETE api/api-version/sites/site-id/dataQualityWarnings/dataqualitywarning-id

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
dataqualitywarning-id

The unique ID of the data quality warning attached to the asset (database, table, published data source, or flow).

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions delete the data quality warning:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400105 Data quality warning delete error An unknown error occurred and the data quality warning could not be deleted.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The requested asset could not be found.
404 404030 Data quality warning not found The data quality warning for the requested asset could not be found.

Delete Data Quality Warning by Content

Permanently remove the data quality warning from the database, table, published data source, or flow.

URI

DELETE api/api-version/sites/site-id/dataQualityWarnings/content-type/content-luid

Parameter Values

api-version The version of the API to use, such as 3.8. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type

The type of asset that the data quality warning is being attached to. To specify the type, use:

  • database
  • table
  • datasource
  • flow

Types are not case sensitive.

content-luid The unique ID of the content type(database, table, published data source, or flow). This is the same as the content ID.

Request Body

None

Permissions

If Tableau Server or Tableau Online is licensed through the Data Management Add-on, the following users have permissions to delete the data quality warning:

  • Tableau Server admins or Tableau Online site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Otherwise, Tableau Server admins or Tableau Online site admins only.

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
409 400106 Data quality warning delete error An unknown error occurred and the data quality warning could not be deleted.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The requested asset could not be found.
404 404030 Data quality warning not found The data quality warning for the requested asset could not be found.

Thanks for your feedback! There was an error submitting your feedback. Please try again.