Extracts(Link opens in a new window) are saved subsets of data that you can use to improve performance, or to take advantage of Tableau functionality not available or supported in your original data).
Using the extract methods of the Tableau Server REST API you can:
- Create an extract from a published data source (used by all workbooks in a site that consume the data source)
- Create extracts from the data sources of a published workbook (includes embedded data sources and embedding of published data sources for workbook-specific extract configuration).
- Delete the extract of a data source.
- Delete the extracts of a workbook.
- Delete the refresh task for an extract.
- Enable encryption and decryption of extracts on a site when you use Create Site or Update Site methods.
- Set the scope of encryption to be all extracts on a site, or allow the users to use: Publish Data Source, Publish Workbook, Update Data Source, or Update Workbook methods to enable or disable encryption for each workbook or data source on a site.
- Encrypt and decrypt extracts on a site
- Reencrypt extracts on a site with new security keys
This functionality relates to the UI elements and concepts described at: Extract Your Data(Link opens in a new window).
About Extract Encryption
Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).
The extract encryption mode is set at the site level. To set the mode, use the Create Site or Update Site methods with the extractEncryptionMode attribute. The extract encryption modes are:
- enforced: enforce encryption of all extracts on the site.
- enabled: allow users to specify to encrypt all extracts associated with specific published workbooks or data sources.
- disabled: disable extract encryption on the site.
To get the site extract encryption mode, use the Query Site method, which shows the extractEncryptionMode attribute in its response body.
When the site extract encryption mode is set to enforced, all content is encrypted. You can use the reencrypt-extracts method to reencrypt all extracts on a site.
When the site extract encryption mode is set to enabled, users can decide to encrypt or decrypt the extracts associated with specific published workbooks or data sources. To do this, use the Publish Data Source, Publish Workbook, Update Data Source, or Update Workbook methods with the encryptExtracts attribute. Set the encryptExtracts attribute to true to encrypt the extracts. The user must be the owner or administrator. To get the extract encryption status, use the Query Data Source or Get Workbook methods, which show the encryptExtracts attribute in the response body.
When the site extract encryption mode is set to enabled, the owner or administrator can encrypt, decrypt, and reencrypt all extracts associated with workbooks or data sources on a site.
When the site extract encryption mode is set to disabled, all encrypted extracts will be decrypted. Depending on the number and size of extracts, this operation may consume significant server resources.
Create Extracts for Embedded Data Sources in a Workbook
Create extracts for all embedded data sources of a workbook. Optionally, encrypt the extracts if the site and workbook using them are configured to allow it.
When you create an extract for a data source in a workbook, the extract is available only to the workbook and may have
configuration specific to the workbook, such as hiding of unused fields.
You can create workbook extracts for both embedded and published data sources used by the workbook. When you create a
workbook data source for a published data source, then refreshing the workbook extract will retrieve any changes to data
from the published datasource, or from the published data source's extract if it is using one.
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).
URI
POST /api/api-version/sites/site-id/workbooks/workbook-id/createExtract
POST /api/api-version/sites/site-id/workbooks/workbook-id/createExtract?encrypt=encryption-flag
Path Parameter Values
| api-version | The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions. |
| site-id | The LUID of the site. |
| workbook-id | The LUID of the workbook. |
| encryption-flag | If true, then Tableau will attempt to encrypt the created extracts.
If false, or no encrypt parameter is appended to the URI, then the extract won't
be encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned when
encrypt equals true and encryption is disabled in the site or workbook.
|
Request Body
<tsRequest>
<datasources includeAll="extract-all-datasources-flag">
<datasource id="datasource-id" />
</datasources>
</tsRequest>
Request Parameter Values
| datasource-id | LUID of the embedded data source to be extracted. |
| extract-all-datasources-flag | Boolean. If true, then all data sources in the workbook will have an extract created for them.
If false, then a data source must be supplied in the request.
|
Permissions
Extracts for data sources embedded in a workbook can be created by Tableau server or site administrators, and users who own the workbook, or are an owner or leader of the project where the workbook resides.
Response Code
200
Response Body
<tsResponse>
<job id="job-id" mode="Asynchronous" type="CreateExtract" createdAt="date-time">
<extractCreationJob>
<workbook id="workbook-id" name="workbook-name" />
</extractCreationJob>
</job>
</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. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 409 | 409070 | Invalid request method | The data source cannot be extracted because it is file based or in another unsupported form. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.19/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/createExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE" -d "@create-extracts-for-workbook.xml"
Content of create-extracts-for-workbook.xml
<tsResponse>
<datasources includeAll="false" />
<datasource id="6b4cf715-c90b-49d6-be85-920a47bae433" />
</datasources>
</tsRequest>Response body:
<tsResponse>
<job id="df410925-feae-481d-bf84-2f37bdf7ce69" mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z">
<extractCreationJob>
<workbook id="e35ec79d-9526-44f1-9a67-7a8b63d265df" name="MY_WORKBOOK_NAME"/>
<jobLuid>df410925-feae-481d-bf84-2f37bdf7ce69</jobLuid>
</extractCreationJob>
</job>
</tsResponse>Create an Extract for a Data Source
Create an extract for a data source in a site. Optionally, encrypt the extract if the site and workbooks using it are configured to allow it.
URI
POST /api/api-version/sites/site-id/datasources/datasource-id/createExtract
POST /api/api-version/sites/site-id/datasources/datasource-id/createExtract?encrypt=encryption-flag
Parameter Values
| api-version | The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions. |
| site-id | The LUID of the site. |
| datasource-id | The LUID of the datasource. |
| encryption-flag | If true, then Tableau will attempt to encrypt the created extracts.
If false, or no encrypt parameter is appended to the URI, then the extract won't
be encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned when
encrypt equals true and encryption is disabled in the site or workbook.
|
Request Body
None
Permissions
Extracts for data sources can be created by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.
Response Code
200
Response Body
<tsResponse>
<job id="job-id" mode="Asynchronous" type="CreateExtract" createdAt="date-time">
<extractCreationJob>
<datasource id="datasource-id" name="datasource-name" />
</extractCreationJob>
</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. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 409 | 409070 | Invalid request method | The data source cannot be extracted because it is file based or in another unsupported form. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.19/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/createExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE"
Response body:
<tsResponse>
<job id="df410925-feae-481d-bf84-2f37bdf7ce69" mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z">
<extractCreationJob>
<datasource id="e35ec79d-9526-44f1-9a67-7a8b63d265df" name="MY_DATASOURCE_NAME"/>
<jobLuid>df410925-feae-481d-bf84-2f37bdf7ce69</jobLuid>
</extractCreationJob>
</job>
</tsResponse> Decrypt Extracts in a Site
Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).
Decrypts all extracts on a site.
Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.
URI
POST /api/api-version/sites/site-id/decrypt-extracts
Parameter Values
| api-version | The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site. |
Request Body
None
Permissions
Tableau Server administrators can call this method.
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 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
For more information, see Handling Errors.
Delete Extracts of Embedded Data Sources from a Workbook
Delete all extracts of embedded data sources in a workbook.
Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.
URI
POST /api/api-version/sites/site-id/workbookss/workbook-id/deleteExtract
Path Parameter Values
| api-version | The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions. |
| site-id | The LUID of the site. |
| datasource-id | The LUID of the workbook containing the extract to be deleted. |
Permissions
Extracts for data sources can be deleted by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.
Request Body
<tsRequest>
<datasources includeAll="true"/>
</tsRequest>
Request Parameter Values
None.
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 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 409 | 409070 | Invalid request method | The data source cannot be extracted because it is file based or in another unsupported form. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.19/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/deleteExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE" -d "@delete-extracts-for-workbook.xml"
Content of create-extracts-for-workbook.xml
<tsResponse>
<datasources includeAll="true" />
</tsRequest>Response body:
None. Response code is 200.
Delete the Extract from a Data Source
Delete the extract of a data source in a site.
URI
POST /api/api-version/sites/site-id/datasources/datasource-id/deleteExtract
Parameter Values
| api-version | The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions. |
| site-id | The LUID of the site. |
| datasource-id | The LUID of the datasource whose extract is to be deleted. |
Permissions
Extracts for data sources can be deleted by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.
Response Code
204 No Content
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. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 409 | 409070 | Invalid request method | The data source cannot be extracted because it is file based or in another unsupported form. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.19/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/deleteExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE"
Response body:
None.
Delete Extract Refresh Task
Deletes an extract refresh task.
URI
DELETE /api/api-version/sites/site-id/tasks/extractRefreshes/task-id
Parameter Values
| api-version | The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the extract refresh task. |
| task-id | The ID of the extract refresh task to remove. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can delete an extract refresh task for which they have Read (view) and Delete permissions (either explicitly or implicitly).
Response Code
204
Response Body
None
Version
Version 3.6 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404026 | Task not found | The task id in the URI doesn't correspond to an existing extract refresh task. |
| 405 | 405000 | Invalid request method | Request type was not DELETE. |
For more information, see Handling Errors.
Encrypt Extracts in a Site
Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).
Encrypts all extracts on a site.
Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.
URI
POST /api/api-version/sites/site-id/encrypt-extracts
Parameter Values
| api-version | The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site. |
Request Body
None
Permissions
Tableau Server administrators can call this method.
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 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
For more information, see Handling Errors.
Reencrypt Extracts in a Site
Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).
Reencrypt all extracts on a site with new encryption keys. If no site is specified, extracts on the default site will be reencrypted.
Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.
URI
POST /api/api-version/sites/site-id/reencrypt-extracts
Parameter Values
| api-version | The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site. |
Request Body
None
Permissions
Tableau Server administrators can call this method.
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 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
For more information, see Handling Errors.