Data Sources Methods

Using the data sources methods of the Tableau Server REST API you can:

  • Publish, update metadata, delete, or refresh the extract of a data source of a site
  • Add and delete tags of a data source
  • Get a list of data sources and the details of each
  • Get and update the connection information for a data source
  • Get the revision history of a data source or remove specific revisions
  • Download the current data source or one of its past revisions
  • Incrementally update specified portions of data from a live-to-Hyper connection.

This functionality relates to the UI elements and concepts described at: Connect to Your Data(Link opens in a new window).



The Tableau Server Client library(Link opens in a new window), a Python wrapper for the REST API, offers the following related items: Data Sources(Link opens in a new window); and Populate connections for Data Sources(Link opens in a new window).

Add Tags to Data Source

Adds one or more tags to the specified data source.

URI

PUT /api/api-version/sites/site-id/datasources/datasource-id/tags

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to add tags to.

Request Body

<tsRequest>
  <tags>
    <tag label="tag" />
    ... additional tags ...
  </tags>
</tsRequest>
        

Attribute Values

datasource-id The data source to add the tag to. If the data source is already tagged with a tag that's included in the request body, those tags are ignored and the data source retains them. If the <tags> element is empty, no new tags are added to the data source.
tag The text of the tag.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read permissions for the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <tags>
    <tag label="tag"/>
        ... additional new tags ...
        ... existing tags ...
  </tags>
</tsResponse>

Version

Version 1.0 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 400075 Error adding tags There was a problem adding tags to the specified data source.
403 403004 Adding tags forbidden

A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if the <tags> element is empty.

404 404000 Site not found

The site ID in the URI is not for an existing site.

404 404004 Data source not found The data source ID in URI doesn't correspond to an existing data source.
404 404009 Data source ID mismatch The request body contains a data source ID (which is optional) and it doesn't match the ID in the URI.
404 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/tags" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-tags-to-datasource.xml

Content of add-tags-to-datasource.xml:

<tsRequest>
    <tags>
      <tag label="GDP" />
      <tag label="Health" />
    </tags>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <tags>
    <tag label="GDP"/>
    <tag label="Health"/>
    <tag label="Spending"/>
  </tags>
</tsResponse>

Delete Data Source

Deletes the specified data source from a site. When a data source is deleted, its associated data connection is also deleted. Workbooks that use the data source are not deleted, but they will no longer work properly.

URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to delete.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a data source for which they have Read (view) and Delete permissions (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Deletion forbidden A non-administrator user called this method but doesn't have Read (view) and Delete permission for the data source.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source in the site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Tag from Data Source

Deletes a tag from the specified data source.

URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id/tags/tag-name

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to remove the tag from.
tag-name The name of the tag to remove from the data source.

Request Body

None

Permissions

Tableau Server users who are not server administrators, site administrators, or data source owners can delete a tag from a data source only if they are project leaders or if they originally added the tag.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400077 Error deleting tag There was a problem deleting the tag from the specified data source.
403 403004 Deleting tags forbidden A non-administrator user called this method but doesn't have permission to delete a tag from the specified data source.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404007 Tag not found The tag in the URI doesn't exist for the specified data source.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Download Data Source

Downloads a data source in .tdsx format.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/content

GET /api/api-version/sites/site-id/datasources/datasource-id/content?includeExtract=extract-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to download.
extract-value (Optional) The extract-value is a Boolean value (False or True). When the data source specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the data source. You can use this parameter to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Users who are not server administrators or site administrators can download a data source only if they have ExportXml permission for the data source (either explicitly or implicitly).

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:datasources:download

Response Code

200

Response Body

The data source content in .tdsx format (Content-Type: application/octet-stream).

The response will have the following content disposition header:

Content-Disposition: name="tableau_datasource"; filename="datasource-filename"

Version

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

Errors

HTTP status error Code Condition Details
403 403028 Read forbidden A non-administrator user attempted to download a data source, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/content" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" > my-datasource.tdsx

The response is a file that contains the data source.

Download Data Source Revision

Downloads a specific version of a data source prior to the current one in .tdsx format. To down load the current version of a data source use the Download Data Source method.

Note: This method is available only if version history is enabled for the specified site. For more information, see Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number/content

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to download.
revision-number The revision number of the data source to download. To determine what versions are available, call Get Data Source Revisions.

Request Body

None

Permissions

Tableau Server users who are site administrators can download data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get data source revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified data source.
  • Save (write) permissions for the project that contains the data source.

Response Code

200

Response Body

The data source content in .tdsx format (Content-Type: application/octet-stream).

The response will have the following content disposition header:

Content-Disposition: name="tableau_datasource"; filename="datasource-filename"

Version

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

Errors

HTTP status error Code Condition Details
403 403028 Read forbidden A non-administrator user attempted to download a data source, but the caller doesn't have required permissions.
403 403053 Version history not enabled version history is not enabled for the specified site.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404024 Data source revision not found The revision number in the URI doesn't correspond to an existing data source revision.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Get Data Source Revisions

Returns a list of revision information (history) for the specified data source.

Note: This method is available only if version history is enabled for the specified site. For more information, see Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.

To get a specific version of the data source from revision history, use the Download Data Source Revision method.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source to get revisions for.
datasource-id The ID of the data source to get revisions for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are site administrators can get data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get data source revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified data source.
  • Save (write) permissions for the project that contains the data source.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
       totalAvailable="total-available" />
  <revisions>
    <revision createdAt="date" revisionNumber="1" isDeleted="false">
      <user id="user-id" name="user-name"/>
    </revision>
    <revision createdAt="date" revisionNumber="2" isDeleted="false">
    </revision>
    <revision createdAt="date" revisionNumber="3" isCurrent="true">
        <user id="user-id" name="user-name"/>
    </revision>
  </revisions>
</tsResponse>
        

If the revision element includes the attribute isDeleted="true", the data source has been deleted and cannot be downloaded using the Download Data Source Revision method.

If a user has been deleted from the site, no <user> element is included in the <revision> element.

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403054 A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Publish Data Source

Publishes a data source on the specified site, or appends data to an existing data source. To make other changes to a published data source, call Update Data Source or Update Data Source Connection.

Version: Available in API 2.0 and later. Version overview

License: Available for Tableau Server and Tableau Cloud.

Permissions: You can publish a data source if you have implicit or explicit Publish permissions for the data source, or are a Tableau administrator. Note: The queryTaggingEnabled attribute is returned only for administrator users. Permissions Overview

JWT Access Scope: tableau:datasources:create     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.

This method is used in two ways. You can call it to publish a data source in a single request. To do that, you include the content of the data source file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB. If you want to avoid having the publishing process time out, you can use the asJob parameter to make data source publication asynchronous.

Alternatively, you can publish a data source in multiple parts. To do that, you initiate a file upload by calling Initiate File Upload, send portions of the file to the server using Append to File Upload, and then commit the upload by calling Publish Data Source. In this case, Publish Data Source doesn't contain the file to publish.

Extracts with multiple table options
Starting in v2021.4, you can publish multi table Hyper extract files created using the Hyper API(Link opens in a new window). The data must include a single fact table(Link opens in a new window) containing the foreign keys that relate the tables to each other. The Hyper API infers the data object model, but does not perform any validation, such as referential integrity checking. If the Hyper API can’t infer the data object model of a Hyper extract, for instance, because there is more than one fact table, then attempting to publish the extract will fail. Prior to v2021.4, there was no way to append data to an extract with multiple tables using the REST API.

Data Sources stored locally
When you publish a data source from your local computer to the server, you must make sure that the server has all the components that are required in order for other users to see and interact with the data source. For example, if the data source is based on an Excel spreadsheet, you typically publish a packaged data source (.tdsx file) that contains all the components for that data source.

Working with Parquet files
- When publishing a Parquet file to a data source through a live-to-Hyper connection, the files are converted to Hyper files. You may want to publish a copy of your original Parquet file to retain that data in its native format.
- A data source with a live-to-Hyper connection to data in a Hyper file converted from Parquet can only have a single connection.
- When incrementally updating that data from that connection, using the Update Hyper in Data Source method, the Parquet file is not converted to Hyper.

For more information, see Publishing Resources.

URI

POST /api/api-version/sites/site-luid/datasources

POST /api/api-version/sites/site-luid/datasources?overwrite=overwrite-flag&asJob=asJob-value

POST /api/api-version/sites/site-luid/datasources?append=append-flag

POST /api/api-version/sites/site-luid/datasources?uploadSessionId=upload-session-id&datasourceType=datasource-file-type&overwrite=overwrite-flag&append=append-flag

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site to publish to.
overwrite-flag true to overwrite a data source that has the same name, or false to fail if the specified data source already exists. The default is false. If overwrite-flag is set to true but the data source doesn't already exist, the operation succeeds.

You can include both the overwrite and append parameters in a request, but they cannot both be true.

asJob-value A Boolean value that is used to publish data sources asynchronously. If you set this value to false (the default), the publishing process runs as a synchronous process. If a data source is very large, the process might time out before it finishes. If you set this value to true, the process runs asynchronously, and a job will start to perform the publishing process and return the job ID. You can check the status of the import job by calling Query Job.
append-flag true to append the data being published to an existing data source that has the same name. The default is false. If append-flag is set to true but the data source doesn't already exist, the operation fails.

In order to append data to a published data source on Tableau Server, both the source file and the published file must be an extract with the file extension .hyper or .tde. The schema of the source and the published extract must match.

If an extract was stored using the multiple tables option, you can't append data to it.

You can include both the overwrite and append parameters in a request, but they cannot both be true.

upload-session-luid If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session LUID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published.
datasource-file-type hyper, tds, tdsx, or tde the kind of file that you are uploading. This value is required if you are calling Publish Data Source in order to commit a file that was previously uploaded using Append to File Upload. The value is not used if you upload a file in the body of the request.

Request Body

The content type in the header of requests to publish a data source must use the mixed multipart content type with a boundary string definition, in the form of: Content-Type: multipart/mixed; boundary=boundary-string.

Publishing a file in the request body

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
	<datasource name="Sales"
	useRemoteQueryAgent="False"
	description="Sales Data Source">
		<connectionCredentials name="janedoe"
		  password="xxxxxx"
			embed="True" />
		<project id="ff2a8360-3c2b-4b05-a793-7607c602e1fb" />
  </datasource>
</tsRequest>
--boundary-string
Content-Disposition: name="tableau_datasource"; filename="Sales.TDSX"
Content-Type: application/octet-stream
	content-of-datasource-file
--boundary-string--
		

Committing a file previously uploaded

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
	<datasource name="Sales" >
		<connectionCredentials name="janedoe" password="xxxxxx"
			embed="False" oAuth="True" />
		<project id="ff2a8360-3c2b-4b05-a793-7607c602e1fb" />
  </datasource>
</tsRequest>
--boundary-string--
						

Publishing a file in the request body


Content-Length: 16301
Content-Type: multipart/form-data; boundary=----------------------my_boundary_string
----------------------my_boundary_string
Content-Disposition: form-data; name="part1.json"
Content-Type: application/json
{
  "the_JSON" : {
	"foo" :  "bar"
  }
}
----------------------my_boundary_string
Content-Disposition: form-data; name="datasource.tdsx"
Content-Type: application/pdf
  "datasource": {
	"name": "Sales",
	"useRemoteQueryAgent": "True",
	"description": "Sales Data Source",
	"connectionCredentials": {
	  "name": "janedoe",
	  "password": "xxxxxx",
	  "embed": "True"
	},
	"project": {
	  "id": "ff2a8360-3c2b-4b05-a793-7607c602e1fb"
	}
  }
}
----------------------my_boundary_string--

Committing a file previously uploaded


Content-Length: 16301
Content-Type: multipart/form-data; boundary=----------------------my_boundary_string
Content-Disposition: form-data; name="part1.json"
Content-Type: application/json
{
  "the_JSON" : {
	"foo" :  "bar"
  }
}
----------------------my_boundary_string
Content-Disposition: form-data; name="datasource.tdsx"
Content-Type: application/pdf
  "datasource": {
	"name": "Sales",
	"connectionCredentials": {
	  "name": "janedoe",
	  "password": "xxxxxx",
	  "embed": "True",
	  "oAuth": "True"
	},
	"project": {
	  "id": "ff2a8360-3c2b-4b05-a793-7607c602e1fb"
	}
  }
}
----------------------my_boundary_string--
						

Request Attributes

boundary-string (Required) A string of characters that is guaranteed to be unique within the body of the request, and that is used to delimit sections of the request body. This value must be declared as a header that has this format:

Content-type: multipart/mixed; boundary=boundary-string

datasource name (Required) The name to assign to the data source when it is saved on the server.
datasource useRemoteQueryAgent (Optional) When true, this flag will allow your Tableau Cloud site to use Tableau Bridge clients(Link opens in a new window). Bridge allows you to maintain data sources with live connections to supported on-premises data sources.
datasource description (Optional) A description of the datasource.
connectionCredentials

The <connectionCredentials> element is required if the data source requires credentials. If the data source does not require credentials, Tableau will ignore this element if it is present. connectionCredentials attributes are:

username
(Required, depending on oAuth setting) The connection ceredentials username.

password
(Required, depending on oAuth setting) The connection credential password.

embed
(Optional) If true credentials are embedded in the datasource. Default is false.

oAuth
(Optional) If the data source connection is configured to use OAuth, set this to true to specify that the value of the name attribute in the connectionCredentials element is an OAuth username. In that case, no password is required and the value of the embed attribute specifies whether to embed the OAuth credential with the data source. For more information, see OAuth Connections(Link opens in a new window) in the Tableau Server documentation.

project The LUID of the project to assign the data source to. If the project is not specified, the data source will be published to the default project.
datasource-file-name The file name (including extension) of the data source file to upload. This attribute is used in the request body only if the request also includes the content of the data source file; it is not used if you are committing a file uploaded using previous requests.
content of datasource file The content of the data source file, if the request includes the file. The maximum size of a file that can be uploaded in one call is 64 MB.
askDataEnablement

This attribute is not available in API 3.12 and later (Tableau Cloud September 2021 / Server 2021.3).

cURL Example

curl "http://MY_SERVER/api/3.4/sites/ff2a8360-3c2b-4b05-a793-7607c602e1fb/datasources" -X POST -H "X-Tableau-Auth:6fSulU7ET8yjpHteQj56MQ|LrkEdTHcmPkWFcD8wOEy29hlVXm8iPo4" -H "Content-Type: multipart/mixed;" -F "request_payload=@publish-datasource.xml" -F "tableau_datasource=@data-source.tds"

Content of publish-datasource.xml:

<tsRequest>
  <datasource name="datasource1" description="This is a data source named datasource1." >
    <project id="522dc5c5-e1da-47b9-8e07-f02929ff5ceb" />
  </datasource>
</tsRequest>

Response Code

201

Response Body

<tsResponse>
  <datasource
	id="75b71d2f-e8d3-42af-b654-d953659326ee"
	name="Sales"
	contentUrl="mySite"
	description="Sales Data Source"
	useRemoteQueryAgent="True"
	webpageUrl="https://my_server/#/datasources/222"
	type="excel-direct"
	createdAt="2016-02-12T23:36:09Z"
	updatedAt="2020-12-16T15:33:03Z"
	isCertified="False"
	certificationNote="This is a certification note."
	encryptExtracts="True">
	  <project
		id="56c86f04-b834-4a08-a561-86497bb4b2df"
		name="Visualization"/>
	  <owner id="20148c74-7818-4eb8-b2a1-9f3f5f582613"/>
	  <tags/>
  </datasource>
</tsResponse>

{
  "datasource": {
	"id": "75b71d2f-e8d3-42af-b654-d953659326ee",
	"name": "Sales",
	"contentUrl": "mySite",
	"description": "Sales Data Source",
	"useRemoteQueryAgent": "True",
	"webpageUrl": "https://my_server/#/datasources/222",
	"type": "excel-direct",
	"createdAt": "2016-02-12T23:36:09Z",
	"updatedAt": "2020-12-16T15:33:03Z",
	"isCertified": "False",
	"certificationNote": "This is a certification note.",
	"encryptExtracts": "True",
	"project": {
	  "id": "56c86f04-b834-4a08-a561-86497bb4b2df",
	  "name": "Visualization"
	},
	"owner": {
	  "id": "20148c74-7818-4eb8-b2a1-9f3f5f582613"
	},
	"tags": []
  }
}

The createdAt and updatedAt attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Response Headers

Location: /api/3.22/sites/site-id/datasources/id-from-server

Errors

HTTP status error Code Condition Details
400 400000 Bad request The request message is missing or incomplete, or contains malformed XML. Make sure that the Content-Length value is set.
400 400000 Missing data source There is no attachment in the request for the data source.
400 400008 Invalid overwrite value The overwrite parameter must be set to true or false.
400 400008 Invalid append value The append parameter must be set to true or false.
400 400008 Invalid embed value The request body contains a <connectionCredentials> element and it has an embed attribute whose value is not true or false.
400 400010 Invalid data source filename The name of the data source file did not end with the suffix .hyper, .tds, .tdsx, or .tde.
400 400010 Missing or invalid file type The request included an uploadSessionId parameter but no file type, or the file type was something other than hyper, tds, tdsx, or tde.
400 400010 Unexpected attachments The message had both a uploadSessionId parameter and an attachment, or the message contained more than one attachment.
400 400011 Publishing error The data source could not be published for some other reason than those specified earlier.
400 400019 Malformed request body The request message is missing or incomplete, or contains malformed XML. Make sure that the Content-Length value is set.
400 400055 Incompatible overwrite and append values The overwrite and append parameter cannot both be set to true.
400 400129 Invalid Ask Data enablement The enablement setting in the request body is not valid for the current server configuration.
403 403007 Insufficient publishing permission A non-administrator user attempted to publish a data source, but the caller doesn't have sufficient project permissions.
403 403007 Unlicensed publishing forbidden A non-administrator user who is unlicensed attempted to publish a data source. This is disallowed for all projects (including the default project).
403 403007 Overwrite forbidden A data source with the specified name already exists and the overwrite parameter was not set to true.
403 403007 Problem connecting to data source There was a problem connecting to a data source. This can be due to missing or invalid connection credentials or because the referenced data source is not available on the server.
403 403008 Insufficient storage quota The data source could not be published because there is not enough storage remaining on the server to accommodate its size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The append parameter is true but the data source name specified in the request body does not correspond to an existing data source.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project on the site.
404 404015 File upload not found The file upload session ID in the request body doesn't correspond to an existing file upload on the site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Query Data Source

Returns information about the specified data source.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The site that contains the data source.
datasource-id The ID of the data source to get.

Request Body

None

Permissions

Users who are not server administrators or site administrators can view a data source only if they have Connect permission for the data source (either explicitly or implicitly).

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:content:read

Response Code

200

Response Body

<tsResponse>
  <datasource id="datasource-id"
	certificationNote="certification-note"
	name="datasource-name"
	description="data-source-description"
	type="datasource-type"
    contentUrl="datasource-content-url"
    createdAt="datetime-created"
    updatedAt="datetime-updated"
    encryptExtracts="encryptExtracts"
	hasExtracts="has-extracts-flag"
 	isCertified="is-certified-flag"
	useRemoteQueryAgent="use-remote-query-agent-flag"
	webpageUrl="web-page-url" >
      <project id="project-id" name="project-name" />
      <owner id="datasource-owner-id"  />
      <tags>
        <tag label="tag"/>
        ... additional tags ...
      </tags>
      <askData enablement="enablement-setting"/>
  </datasource>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A non-administrator user attempted to query a data source, but the caller doesn't have Connect permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" name="Activity rates and healthy living"
    certificationNote="This is a note about the datasource certification."
	contentUrl="activity-dates-and-healthy-living"
	encryptExtracts="true"
	description="The Activity and Health data source."
	isCertified="true"
	type="excel-direct"
	createdAt="2011-03-30T22:32:35Z"
	updatedAt="2016-01-13T01:00:02Z">
	useRemoteQueryAgent="false"
	webpageUrl="https://MYSERVER/#/datasources/4414"
      <project id="1f2f3e4e5-d6d7-c8c9-b0b1-a2a3f4f5e6e" name="default"/>
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
      <tags>
      </tags>
	  <askData enablement="Enabled"/>
  </datasource>
</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.

Query Data Sources

Returns a list of published data sources on the specified site, with optional parameters for specifying the paging of large results. To get a list of data sources embedded in a workbook, use the Query Workbook Connections method.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

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

GET /api/api-version/sites/site-id/datasources?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/datasources?filter=filter-expression

GET /api/api-version/sites/site-id/datasources?sort=sort-expression

GET /api/api-version/sites/site-id/datasources?fields=field-expression

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data sources.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression (Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such as name and updatedAt. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
field-expression (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the data sources or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the Rest API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&).

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can view a data source only if they have Connect permission for the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
    totalAvailable="total-available" />
  <datasources>
    <datasource id="datasource1-id"
      description="data-source-description"
      name="datasource-name"
      size="datasource-size"
      type="datasource-type"
      contentUrl="datasource-content-url"
      createdAt="datetime-created"
      updatedAt="datetime-updated"
      encryptExtracts="encrypt-extracts-flag"
      hasExtracts="has-extracts-flag"
      isCertified="is-certified-flag"
      useRemoteQueryAgent="use-remote-query-agent-flag"
      webpageUrl="datasource-webpage-url"  >
	    <project id="project-id" name="project-name" />
        <owner id="datasource-owner-id" />
        <tags>
          <tag label="tag"/>
          ... additional tags ...
        </tags>
    </datasource>
    ... additional data sources ...
  </datasources>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <datasources>
    <datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b"
      name="Sample - Coffee Chain (Access)"
	  contentUrl="coffee-chain"
	  description="The Sample - Coffee Chain data source."
	  type="msaccess"
	  createdAt="2011-03-30T22:32:35Z"
	  updatedAt="2016-01-13T01:00:02Z"
	  encryptExtracts="false"
	  isCertified="false"
      useRemoteQueryAgent="false"
      webpageUrl="https://my-server.com/#/site/my-site/datasources/1275708" >
        <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Default"/>
        <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
        <tags>
	  	  <tag label="test"/>
        </tags>
    </datasource>
  </datasources>
</tsResponse>

Query Data Source Connections

Returns a list of data connections for the specified data source.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/connections

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to return connection information about.

Request Body

None

Permissions

Users who are not server administrators or site administrators can query a data source only if they have Read (view) permission for the data source (either explicitly or implicitly). queryTaggingEnabled is returned only for administrator users.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:content:read

Response Code

200

Response Body

<tsResponse>
  <connections>
    <connection id="connection-id" type="connection-type"
      serverAddress="server-address" serverPort="port"
	  userName="connection-user-name"
	  queryTaggingEnabled="query-tagging-enabled" />
	< ... additional connections ... >
  </connections>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
403 403021 Read forbidden A user who is not a server administrator user attempted to query the data source connections, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404011 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <connections>
    <connection id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" type="dataengine" />
    <connection id="374371c0-ffe9-4e16-b48e-6b868e3026ca" type="dataengine" />
    <connection id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" type="dataengine" />
  </connections>
</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.

Remove Data Source Revision

Removes a specific version of a data source from the specified site.

The content is removed, and the specified revision can no longer be downloaded using Download Data Source Revision. If you call Get Data Source Revisions, the revision that's been removed is listed with the attribute IsDeleted="true".

Note: Calling this method permanently removes the specified data source revision.

URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
datasource-id The ID of the data source to remove the revision for.
revision-number The revision number of the data source to remove. To determine what versions are available, call Get Data Source Revisions.

Request Body

None

Permissions

Tableau Server users who are site administrators can remove data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can remove data source revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified data source.
  • Save (write) permissions for the project that contains the data source.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Deletion forbidden A non-administrator user attempted to remove a data source revision, but the caller doesn't have required permissions.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403055 Cannot delete head revision The head (first) version cannot be deleted. To remove the data source, call Delete Data Source.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404024 Data source revision not found The revision number in the URI doesn't correspond to an existing data source revision.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Update Data in Hyper Connection

Incrementally updates data (insert, update, upsert, replace and delete) in a published data source from a live-to-Hyper connection, where the data source has multiple connections.

A live-to-Hyper connection has a Hyper or Parquet formatted file/database as the origin of its data.

For all connections to Parquet files, and for any data sources with a single connection generally, you can use the Update Data in Hyper Data Source method without specifying the connection-id.

A request for this method must include an upload-session-id for a Hyper file payload containing an upload of the most current data from the data source for your published live-to-Hyper data. Use Initiate File Upload(Link opens in a new window) and Append to File Upload(Link opens in a new window) methods to form the payload and acquire upload-session-id.

For details and examples, see Update Data in Published Live-to-Hyper Data Sources.

Note: While Hyper Update REST API methods make incremental changes much more efficient, multiple simultaneous update requests and large changes in large datasets can overwhelm Tableau server background processes. To mitigate this issue, Hyper Update requests are limited by the server configuration setting api.server.update_uploaded_file.max_size_in_mb. Starting in Tableau Server 2022.1 / Tableau Cloud March 2022, the default for this setting is 100MB. In previous versions, the limit was set to 10MB. Where heavy incremental update traffic is expected, we recommend you use a chunking strategy to limit the size of each update, and fine tune max_size_in_mb value to optimize performance for your exact conditions.

URI

PATCH /api/api-version/sites/site-id/datasources/datasource-id/connections/connection-iddata?uploadSessionId=upload-session-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to update.
connection-id The ID of the connection. To determine what connections are available for a data source, call Query Data Source Connections.
upload-session-id The upload session ID. A user-generated identifier that is unique to a request. If the server receives more than one request with the same ID within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests.

Request Body

This method supports only JSON content-type for the request body.

{"actions": [
	{"action": action-type",
		"source-schema": "source-schema-name",
		"source-table": "source-table-name",
		"target-schema": "target-schema-name",
		"target-table": "target-table-name",
		"condition": {conditional-declaration"}
		. . . more action definition . . .}
	}
	{. . . more actions . . .}
]} 

Attribute Values

actions-type (Required) The definition of the operation(s) to perform on the data in the target hyper file.
source-schema-name (Optional) The name of the source database schema for the data to be updated. A value is not required unless there are multiple schemas in the database.
source-table-name (Required) The name of the source database table containing the data to be updated.
target-schema-name (Optional) The name of the target hyper file schema of the data to be updated from the source database. A value is not required unless there are multiple schemas in the database.
target-table-name (Required) The name of the table containing the data to be updated in the target hyper file.
condition (Required for insert, upsert, and delete)A declaration that defines a comparison operation between source and target data or between source or target data and a user provided constant. For details and examples, see Update Data in Published Live-to-Hyper Data Sources.

An action is an operation to be performed on specified target data. Multiple different actions can be defined as a batch in a request. The supported actions are:

  • insert - Inserts rows from a named source-table in your data source into a named target-table in your published Hyper. A simplified example is:

    {"action": "insert", "source-table": "added_users", "target-table": "current_users"}

  • update – Updates existing tuples from a named source-table in your data source into a named target-table in your published Hyper. The tuples to be updated are defined in a condition declaration. A simplified example is:

    {"action": "update",
    	"target-table": "my_data",
    	"source-table": "uploaded_table",
    	"condition": {"op": "eq", "target-col": "row_id",
    	"source-col": "update_row_id"}
    }

  • upsert - Updates a tuple inside the target-table, if such a tuple exists. If no such tuple exists, a new tuple will be inserted. The tuples to be updated are defined in a condition declaration. A simplified example is:

    {"action": "upsert",
    	"target-table": "my_data",
    	"source-table": "uploaded_table",
    	"condition": {"op": "gt", "target-col": "row_id",
    	"source-col": "update_row_id"}
    }

  • replace – Deletes all tuples from a target-table and inserts all data from a source-table with a matching schema. A simplified example is:

    {"action": "replace", "source-table": "added_users",
    "target-table": "current_users"}

  • delete – Deletes tuples from a target-table. The tuples to be deleted are defined in a condition declaration. A simplified example is:

    {"action": "delete",
    	"target-table": "my_extract_table",
    	"source-table": "deleted_row_id_table",
    	"condition": {"op": "gt", "target-col": "id",
    	"source-col": "deleted_id"}
    }

For more information, see Update Data in Published Live-to-Hyper Data Sources.

Permissions

This method requires server or site administrator permissions.

Request Header

In addition to the typical authentication token, the following fields must be specified as part of the request header:

  • content-type: application/json - This endpoint accepts JSON only.
  • RequestID - A user-generated identifier that uniquely identifies a request. If the server receives more than one request with the same id within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests, which prevents executing the same job more than once could be caused by network anomalies or client crashes.

Response Code

200

Response Body

The response body returns the job-id, which specifies the ID of the async job that will carry out the data operations described in the action batch. This returned "job-id" can be used to query the status of the update job(Link opens in a new window) or to cancel a scheduled job(Link opens in a new window).

(job-id: "scheduled-job-luid"}

Version

Version 2o21.2 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 JSON.
400 400008 Invalid parameter value A parameter in the request body is missing or invalid.
403 403062 Update data source multiple connections forbidden A connection ID is required because the data source has multiple connections. Consider using Update Data in Hyper Connection to specify the connection. (This error does not apply to that Connection method)
403 403032 Update forbidden A non-administrator user tried to update a data source, but the caller doesn't have Write permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source LUID in the request body doesn't correspond to an existing data source.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404008 Operation not supported The operation requested is not supported, the source data for the connection must be a Hyper file/database.
404 404020 Connection not found No resource was found for the specified connection and data source. (This error does not apply to Update Data in Hyper Data Source)
405 405000 Invalid request method Request type was not PATCH.
409 409015 Data source name conflict The data source name in the request already belongs to the specified site. For the purpose of uniqueness checks, data source names are case-insensitive.
409 409094 Data update job already exists A data update job for the datasource is already queued or in progress.

For more information, see Handling Errors.

Update Data in Hyper Data Source

Incrementally updates data (insert, update, upsert, replace and delete) in a published data source from a live-to-Hyper connection, where the data source has a single connection.

A live-to-Hyper connection has a Hyper or Parquet formatted file/database as the origin of its data.

For data sources with multiple connections, you can specify which to update using the Update Data in Hyper Data Source method.

A request for this method must include an upload-session-id for a Hyper file payload containing an upload of the most current data from the data source for your published live-to-Hyper data. Use Initiate File Upload(Link opens in a new window) and Append to File Upload(Link opens in a new window) methods to form the payload and acquire upload-session-id.

For details and examples, see Update Data in Published Live-to-Hyper Data Sources.

Note: While Hyper Update REST API methods make incremental changes much more efficient, multiple simultaneous update requests and large changes in large datasets can overwhelm Tableau server background processes. To mitigate this issue, Hyper Update requests are limited by the server configuration setting api.server.update_uploaded_file.max_size_in_mb. Starting in Tableau Server 2022.1 / Tableau Cloud March 2022, the default for this setting is 100MB. In previous versions, the limit was set to 10MB. Where heavy incremental update traffic is expected, we recommend you use a chunking strategy to limit the size of each update, and fine tune max_size_in_mb value to optimize performance for your exact conditions.

Working with Parquet files
- When publishing a Parquet file to a data source through a live-to-Hyper connection, the files are converted to Hyper files. You may want to publish a copy of your original Parquet file to retain that data in its native format.
- A data source with a live-to-Hyper connection to data in a Hyper file converted from Parquet can only have a single connection.
- When incrementally updating that data from that connection, using the Update Hyper in Data Source method, the Parquet file is not converted to Hyper.

URI

PATCH /api/api-version/sites/site-id/datasources/datasource-id/data?uploadSessionId=upload-session-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to update.
upload-session-id The upload session ID. A user-generated identifier that is unique to a request. If the server receives more than one request with the same ID within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests.

Request Body

This method supports only JSON content-type for the request body.

{"actions": [
	{"action": action-type",
		"source-schema": "source-schema-name",
		"source-table": "source-table-name",
		"target-schema": "target-schema-name",
		"target-table": "target-table-name",
		"condition": {conditional-declaration"}
		. . . more action definition . . .}
	}
	{. . . more actions . . .}
]} 

Attribute Values

actions-type (Required) The definition of the operation(s) to perform on the data in the target hyper file.
source-schema-name (Optional) The name of the source database schema for the data to be updated. A value is not required unless there are multiple schemas in the database.
source-table-name (Required) The name of the source database table containing the data to be updated.
target-schema-name (Optional) The name of the target hyper file schema of the data to be updated from the source database. A value is not required unless there are multiple schemas in the database.
target-table-name (Required) The name of the table containing the data to be updated in the target hyper file.
condition (Required for insert, upsert, and delete)A declaration that defines a comparison operation between source and target data or between source or target data and a user provided constant. For details and examples, see Update Data in Published Live-to-Hyper Data Sources.

An action is an operation to be performed on specified target data. Multiple different actions can be defined as a batch in a request. The supported actions are:

  • insert - Inserts rows from a named source-table in your data source into a named target-table in your published Hyper. A simplified example is:

    {"action": "insert", "source-table": "added_users", "target-table": "current_users"}

  • update – Updates existing tuples from a named source-table in your data source into a named target-table in your published Hyper. The tuples to be updated are defined in a condition declaration. A simplified example is:

    {"action": "update",
    	"target-table": "my_data",
    	"source-table": "uploaded_table",
    	"condition": {"op": "eq", "target-col": "row_id",
    	"source-col": "update_row_id"}
    }

  • upsert - Updates a tuple inside the target-table, if such a tuple exists. If no such tuple exists, a new tuple will be inserted. The tuples to be updated are defined in a condition declaration. A simplified example is:

    {"action": "upsert",
    	"target-table": "my_data",
    	"source-table": "uploaded_table",
    	"condition": {"op": "gt", "target-col": "row_id",
    	"source-col": "update_row_id"}
    }

  • replace – Deletes all tuples from a target-table and inserts all data from a source-table with a matching schema. A simplified example is:

    {"action": "replace", "source-table": "added_users",
    "target-table": "current_users"}

  • delete – Deletes tuples from a target-table. The tuples to be deleted are defined in a condition declaration. A simplified example is:

    {"action": "delete",
    	"target-table": "my_extract_table",
    	"source-table": "deleted_row_id_table",
    	"condition": {"op": "gt", "target-col": "id",
    	"source-col": "deleted_id"}
    }

For more information, see Update Data in Published Live-to-Hyper Data Sources.

Permissions

This method requires server or site administrator permissions.

Request Header

In addition to the typical authentication token, the following fields must be specified as part of the request header:

  • content-type: application/json - This endpoint accepts JSON only.
  • RequestID - A user-generated identifier that uniquely identifies a request. If the server receives more than one request with the same id within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests, which prevents executing the same job more than once could be caused by network anomalies or client crashes.

Response Code

200

Response Body

The response body returns the job-id, which specifies the ID of the async job that will carry out the data operations described in the action batch. This returned "job-id" can be used to query the status of the update job(Link opens in a new window) or to cancel a scheduled job(Link opens in a new window).

(job-id: "scheduled-job-luid"}

Version

Version 2o21.2 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 JSON.
400 400008 Invalid parameter value A parameter in the request body is missing or invalid.
403 403062 Update data source multiple connections forbidden A connection ID is required because the data source has multiple connections. Consider using Update Data in Hyper Connection to specify the connection. (This error does not apply to that Connection method)
403 403032 Update forbidden A non-administrator user tried to update a data source, but the caller doesn't have Write permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source LUID in the request body doesn't correspond to an existing data source.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404008 Operation not supported The operation requested is not supported, the source data for the connection must be a Hyper file/database.
404 404020 Connection not found No resource was found for the specified connection and data source. (This error does not apply to Update Data in Hyper Data Source)
405 405000 Invalid request method Request type was not PATCH.
409 409015 Data source name conflict The data source name in the request already belongs to the specified site. For the purpose of uniqueness checks, data source names are case-insensitive.
409 409094 Data update job already exists A data update job for the datasource is already queued or in progress.

For more information, see Handling Errors.

Update Data Source

Updates the owner, project or certification status of the specified data source.

Version: Available in API Version 2.0 and later. Version Overview

License:No additional license required.

Permissions: You can update data source details if you are a Tableau administrator. Specific properties can be updated by other users depending on the type of update action and the permissions granted to the user . . . learn more  | Permissions Overview

JWT Access Scope: tableau:datasources:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.

URI

PUT /api/api-version/sites/site-id/datasources/datasource-id

Starting in 2021.2, you can also modify (insert, update, upsert, replace and delete) data in a published data source that is a live-to-Hyper connection. To do this, use the Update Data in Hyper Data Source method, or for data sources with multiple connections, use the Update Data in Hyper Connection method. For more information, see UpdateData in Published Live-to-Hyper Data Sources.

Path Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the data source.
datasource-luid The LUID of the data source to update.

Request Body

<tsRequest>
  <datasource name="Sales"
    isCertified="true"
    certificationNote="This is a certification note."
    encryptExtracts="false">
      <project id="56c86f04-b834-4a08-a561-86497bb4b2df"/>
      <owner id="20148c74-7818-4eb8-b2a1-9f3f5f582613"/>
      <askData enablement="true [REMOVED IN API 3.12]"/>
  </datasource>
</tsRequest>

{
  "datasource": {
    "name": "Sales",
    "isCertified": "true",
    "certificationNote": "This is a certification note.",
    "encryptExtracts": "false",
    "project": {
    "id": "56c86f04-b834-4a08-a561-86497bb4b2df"
    },
	"owner": {
      "id": "20148c74-7818-4eb8-b2a1-9f3f5f582613"
	  },
	 "askData": {
	   "enablement": "true [REMOVED IN API 3.12]"
	 }
  }
}

Request Attributes

datasource name (Optional) The new name of a the data source.
project (Optional) The LUID of a project to add the data source to.
owner (Optional) The LUID of a user to assign the data source to as owner.
datasource certification-status (Optional) A Boolean value that indicates whether the data source is certified. To learn more about data source certification, see Use Certified and Recommended Data Sources and Tables.
datasource certification-note (Optional) A note that provides more information on the certification of the data source, if applicable.
datasource encryptExtracts (Optional) true to encrypt the extracts or false to not encrypt extracts. For more information, see Extract and Encryption Methods.
askDataEnablement

This attribute is removed in API 3.12 and later (Tableau Cloud September 2021 / Server 2021.3).

(Optional) Determines if a data source allows use of Ask Data. The value can be Enabled, Disabled, or SiteDefault.

If enablement is not specified, Ask Data availability for the data source is unchanged during this update. If the askData element is included, it must contain an enablement attribute. Setting the value of enablement to SiteDefault for a data source will cause its enablement to follow the site's settings for Availability of Ask Data. A value of Enabled or Disabled will override a site's settings for the data source unless the setting Always disable Ask Data is selected. In that case, Ask Data will not be available for the data source regardless of the value of enablement.

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

If the <project> element is included, the id attribute must be included, and any other attributes of the <project> element are ignored.

If the <owner> element is included, the id attribute must be included, and any other attributes of the owner are ignored.

Permissions Details

Users who are server administrators or site administrators can change the owner for a data source.

Users who are not server administrators can move a data source from one project to another if they own the data source or the current (source) project, or are a project leader for the current project, and they have Write permission for the destination project.

Users can change certification status and the certification note if they are server administrators, site administrators, or project leaders for the current project.

Users can modify the name of the data source if: they have server or site administrator permissions, or the site role of Creator or higher and access to the data source with the overwrite capability.

cURL Example

curl --location --request GET "https://MY_SERVER/api/3.16/sites/a946d998-2ead-4894-bb50-1054a91dcab3/datasources" \ --header "X-Tableau-Auth: b09KVmT7QxuLVLv1En7iMg"oxKwSGTYT0WKRes5xk3dgI4gIkG3TM8W"a946d998-2ead-4894-bb50-1054a91dcvv8" \ --header "Content-Type: application/xml" \ --data-raw "<tsRequest/> <datasource name='Sales'/> >datasource/> >tsRequest/>"

Response Code

200

Response Body

<tsResponse>
  <datasource name="Sales" id="75b71d2f-e8d3-42af-b654-d953659326ee"
    contentUrl="mySite" type="excel-direct"
    createdAt="2016-02-12T23:36:09Z" updatedAt="2020-12-16T15:33:03Z"
    isCertified="false"
    certificationNote="This is a certification note."
    encryptExtracts="false">
      <project id="56c86f04-b834-4a08-a561-86497bb4b2df" />
      <owner id="20148c74-7818-4eb8-b2a1-9f3f5f582613" />
      <job id="65348c74-7818-4eb8-b2a1-9f3f5f588870" />
      <askData enablement="true [REMOVED IN API 3.12]" />
  </datasource>
</tsResponse>

{
  "datasource": {
    "name": "Sales",
    "id": "75b71d2f-e8d3-42af-b654-d953659326ee",
    "contentUrl": "mySite",
	"type": "excel-direct",
	"createdAt": "2016-02-12T23:36:09Z",
	"updatedAt": "2020-12-16T15:33:03Z",
	"isCertified": "false",
	"certificationNote": "This is a certification note.",
	"encryptExtracts": "false",
	"project": {
	"id": "56c86f04-b834-4a08-a561-86497bb4b2df"
    },
    "owner": {
      "id": "20148c74-7818-4eb8-b2a1-9f3f5f582613"
    },
    "job": {
      "id": "65348c74-7818-4eb8-b2a1-9f3f5f588870"
    },
    "askData": {
	  "enablement": "true [REMOVED IN API 3.12]"
    }
  }
}

The createdAt and updatedAt attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

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 400008 Invalid parameter value A user attempted to rename a datasource to a name containing only spaces, or to a name with more 255 characters.
400 400129 Invalid Ask Data enablement The requested enablement setting in the request body does not correspond to the site configuration.
403 403027 Owner update forbidden A non-administrator user tried to change the owner for the data source.
403 403030 Project update forbidden A non-administrator user tried to change the project for the data source, but the caller doesn't have Write permission for the project.
403 403032 Update forbidden A non-administrator user tried to update a data source, but the caller doesn't have Write permission.
403 403141 Update forbidden A user attempted to update a data source that they do not have permissions to update.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 Owner not found The owner ID in the request body doesn't correspond to an existing owner.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not PUT or PATCH.
409 409015 Data source name conflict The data source name in the request already belongs to the specified site. For the purpose of uniqueness checks, data source names are case-insensitive.

For more information, see Handling Errors.

Update Data Source Connection

Updates the server address, port, username, or password for the specified data source connection.

Version: Available in API Version 2.3 . . . learn more | Version Overview

License: Available for Tableau Server and Tableau Cloud.

Permissions: Users who are server administrators or site administrators can change the connection for a data source or enable query tagging(Link opens in a new window). Users who are not server administrators can update a data source only. . . learn more |  Permissions overview

JWT Access Scope:     tableau:datasources:update access scope details

URI

PUT /api/api-version/sites/site-id/datasources/datasource-id/connections/connection-id

Path Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the data source.
datasource-luid The LUID of the data source to update.
connection-luid The LUID of the connection to update. To determine what connections are available for a data source, call Query Data Source Connections.

Request Body

<tsRequest>
  <connection
	serverAddress="newAddress"
	serverPort="newPort"
	userName="Jane Doe"
	password="xxxxxx"
	embedPassword="false"
	queryTaggingEnabled="false" />
</tsRequest>

{
  "connection": {
	"serverAddress": "newAddress",
	"serverPort": "newPort",
	"userName": "Jane Doe",
	"password": "xxxxxx",
	"embedPassword": "false",
	"queryTaggingEnabled": "false"
  }
}

Request Attributes

connection serverAddress (Required) The new server for the connection.
connection serverPort (Required) The new port for the connection
connection userName (Required) The new username for the connection.
connection password (Required) The new password for the connection.
embedPassword True to embed the password; otherwise, False.
queryTaggingEnabled

In API 3.23 (Tableau Cloud June 2024 / Server 2024.2) and later: using queryTaggingEnabeld to enable query tagging for individual connections is deprecated, will no longer be supported, and may be retired in future releases. Instead:

- For Tableau Cloud, query tagging will be enabled for all content on a site by default.

- For Tableau Server 2023.3 and later, you can use TSM to enable query tagging for all content on a server by setting native_api.UserInfoInGeneratedSQLEnabled(Link opens in a new window) to true.

For API 3.22 or earlier: true to enable query tagging that associates a specific server log query event with the Tableau resource that made the query. False, which disables query tagging, is the default.

Any combination of the attributes inside the <connection> element is valid. If no attributes are included, no update is made.

Permissions Details

Users who are server administrators or site administrators can change the connection for a data source or enable query tagging(Link opens in a new window). Users who are not server administrators can update a data source only. If they have Write (save) permission for the data source and if they have write permission for the project.

Version Details

Version 2.3 and later. (A different version of this method was available in earlier versions of the REST API. For details, see Update Data Source Connection(Link opens in a new window) in the REST API version 9.3 documentation.) For more information, see REST API and Resource Versions.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:datasources:update

Response Code

200

Response Body

<tsResponse>
  <connection id="90365b4d-978f-425b-bb53-66a984bab34v"
	serverAddress="newAddress"
	serverPort="newPort"
	userName="Jane Doe"
	queryTaggingEnabled="false" />
</tsResponse>

{
  "connection": {
	"id": "90365b4d-978f-425b-bb53-66a984bab34v",
	"serverAddress": "newAddress",
	"serverPort": "newPort",
	"userName": "Jane Doe",
	"queryTaggingEnabled": "false"
  }
}

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 403023 Update forbidden A non-administrator user tried to update a data source, but the caller doesn't have Write permission.
403 403027 Owner update forbidden A non-administrator user tried to change connection information, but the caller doesn't have Write permission.
403 403062 Unsupported operation The data source contains multiple connections, but the URI did not include /connections/connection-id to indicate which connection should be updated.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl --location --request PUT "https://MY_SERVER/api/3.16/sites/a946d998-2ead-4894-bb50-1054a91dcab3/datasources/75b71d2f-e8d3-42af-b654-d953659326ee/connections/90365b4d-978f-425b-bb53-66a984bab10c" \ --header "X-Tableau-Auth: TimrTnJ3QqSzqA7bg65WMQ"3F3Gfr186RJTCovRpYyyw5KuNU3saxuu"a946d998-2ead-4894-bb50-1054a91dcab3" \ --header "Content-Type: application/xml" \ --data-raw "<tsRequest> <connection queryTaggingEnabled='true' /> </tsRequest>"

Update Data Source Now

Runs an extract refresh on the specified data source.

Note: This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).

This method runs an extract refresh for the specified data source, with no need to associate that extract refresh with a scheduled task. This method is the equivalent of selecting a data source using the Tableau Server UI, and then selecting Refresh Extracts from the menu (also known as a "manual refresh"), however, the REST method always runs a full refresh even if the refresh type is set to incremental. Similar to a manual refresh, if the extract is a .tde file, it will be converted to a .hyper file as a result of the refresh. To learn more about extract upgrades to the .hyper file format, see Extract Upgrade to .hyper Format.

URI

POST /api/api-version/sites/site-id/datasources/datasource-id/refresh

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to refresh.

Request Body

<tsRequest>
</tsRequest>        

Permissions

Users who are not server administrators or site administrators can only refresh extracts for data sources if they own the data source, or if they are the project leader for the project.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:tasks:run

Response Code

202

Response Body

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="RefreshExtract" createdAt="date-time">
    <extractRefreshJob>
      <datasource id="datasource-id" name="datasource-name" />
    </extractRefreshJob>
</tsResponse>

        

Version

Version 2.8 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 The authentication token provided in the request header was invalid or has expired.
403 403032 Update Forbidden A non-administrator user attempted to update a data source, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI is unknown.
404 404004 Data source not found The data source ID in the URI is unknown.
405 405000 Invalid request method Request type was not POST.
409 409093 Operation already in Queue The extract refresh job is already in the queue.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/datasources/89a82d78-664f-45a1-8256-d4d2961a070b/refresh" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @empty-tsrequest.xml"

Content of empty-tsrequest.xml:

<tsRequest>
</tsRequest>

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-2.8.xsd">
  <job id="20cf4ddc-6d73-4733-89ec-8d336669bd56" mode="Asynchronous" type="RefreshExtract" createdAt="2017-12-06T22:58:52Z">
    <extractRefreshJob>
      <datasource id="89a82d78-664f-45a1-8256-d4d2961a070b" name="World Indicators Extract" />
    </extractRefreshJob>
  </job>
</tsResponse>


Thanks for your feedback!Your feedback has been successfully submitted. Thank you!