Tableau Data Extract Command-Line Utility

Applies to: Tableau Desktop

You can automate extract refresh tasks using the Tableau Data Extract Command-Line Utility. This is a command-line utility that comes with Tableau Desktop, through which you can refresh published extract data sources or append data to them from a file.

Requirements for using the Tableau Data Extract Command-Line Utility include the following:

  • It is available with Tableau Desktop on Windows and can run only on a Windows system.

  • It is not available with the trial version of Tableau Desktop.

  • You can use it for extract data sources that don't use OAuth.

  • You can use it to refresh single-connection data sources only. It does not work for multi-connection data sources.

Deprecated October 2022: This utility isn't available in later releases due to the multi-factor authentication(Link opens in a new window) requirement in Tableau Cloud. To refresh data sources or virtual connections data that Tableau Cloud can't reach directly, use Tableau Bridge instead. For more information, see Set Up a Bridge Refresh Schedule(Link opens in a new window).

To initiate refresh jobs using a script, use tabcmd refreshextracts(Link opens in a new window) or REST API Run Extract Refresh Task(Link opens in a new window).

Run the utility

  1. Open the Command Prompt as an administrator and change to the Tableau Desktop bin directory. For example:

    cd C:\Program Files\Tableau\Tableau 2022.4\bin

  2. Use either of the following commands, adding parameters described in the tables below.

    • tableau refreshextract

    • tableau addfiletoextract

Note: When using the utility, always specify tableau on the command line or in scripts, never tableau.exe.

Note: To troubleshoot, check the logs in the tableaucom.txt file in the \My Tableau Repository\Logs folder.

Note: In a multiple-site environment, specify the site to which the command applies.

Syntax and parameters for the tableau refreshextract command

Use tableau refreshextract to refresh an extract on Tableau Server or Tableau Cloud. Refreshing an extract updates an existing extract with any modifications that have been made to the data source since the last refresh.

To see help for this command, at the Windows command prompt, type the following command:

tableau help refreshextract

Using parameters

  • All options have a full form that you use with a double hyphen (for example, --server).

  • Some options also have a short form that you use with a single hyphen (for example, -s).

  • If the value for an option contains spaces, enclose it in quotation marks.

  • The source being refreshed must be the original data source, not an extract (.hyper).

tableau refreshextract command options

Short Form Full Form Description
  --source-username <user name>

A valid user name for the data source connection.

Use this option with --source-password, or use

--original-file instead of the user name and password options.

Note: You must provide the user name and password when refreshing a published extract, even if the data source was originally published with embedded credentials.
  --source-password "<password>"

The password for the data source user.
 

--original-file <path and file name>

or

--original-file <path and folder name>

Path and file name for the data source to be refreshed on the server. For example: --original-file c:\folder\file.csv

To refresh a multi-file data source, pass the path to a folder that contains the data files. For example: --original-file c:\folder.

If the file is on a network share, use the UNC format for the path: \\server\path\filename.csv
  --force-full-refresh

If the data source is set up for incremental refreshes, use this option to force a full extract refresh. If this option is not included, an incremental refresh is performed. Not all data sources support incremental refresh.
-s <server http address> --server <URL>

The URL for the Tableau server on which the data is published.

For Tableau Cloud, specify https://online.tableau.com.
-t <site id> --site <siteid>

In a multiple-site environment, specifies the site to which the command applies. For Tableau Cloud, use this argument if your user name is associated with more than one site. For Tableau Server, if you do not specify a site, the default site is assumed.

The site id is independent of the site name, and it is indicated in the URL when you view the site in a browser. For example, if the URL for the page you see after signing in to Tableau Cloud is

https://online.tableau.com/t/vernazza/views

the site id is vernazza.

  --datasource <datasource>

The name of the data source, as published to Tableau Server or Tableau Cloud.

  --project <projectname>

The project to which the data source belongs. If this option is not included, the default project is assumed.

If the project you want to specify is a child project nested within a project hierarchy, you must use this parameter along with the --parent-project-path parameter.
  --parent-project-path path/to/project

If a project to which the data source is published is not at the top level of a project hierarchy, use this parameter along with the --project parameter to specify the path to a nested project.

Use the forward slash character (/) to delimit project levels in the hierarchy. Use the backward slash (\), to escape instances of forward or backward slash characters in project names.

For example, for a project named Sandbox, in project Social, under top-level Marketing:

--project Sandbox --parent-project-path Marketing/Social

-u <user name> --username <username>

Valid Tableau Server or Tableau Cloud user.
-p "<password>" --password "<password>"

The password for the specified Tableau Server or Tableau Cloud user.
  --proxy-username <username>

The user name for a proxy server.
  --proxy-password "<password>"

The password for a proxy server.
-c "<path and file name>" --config-file "<path and file name>"

Path and file name information for a file containing configuration options for the command. Always enclose the path in double quotation marks. For more information, see Using a config file below.

Sample tableau refreshextract command

The following command refreshes an extract named CurrentYrOverYrStats that has been published to Tableau Server on-premises. This command specifies the following:

  • The name of your Tableau Server.
  • Server user name and password.
  • Project name.
  • The name of the data source to refresh, along with the data source username and password.

C:\Program Files\Tableau\Tableau 2022.4\bin>tableau refreshextract --server https://our_server_name --username OurServerSignIn --password "OurServerPwd" --project "New Animations" --datasource "CurrentYrOverYrStats" --source-username OurDatabaseSignIn --source-password "OurDatabasePassword"

The following command refreshes an extract named CurrentYrOverYrStats that has been published to Tableau Cloud. This command specifies the following:

  • Tableau Cloud user and password.
  • Tableau Cloud site and project names.
  • The data source, which in this case is hosted by a cloud-based data source provider (for example, Salesforce.com), and the username and password to sign in to the hosted data source.

C:\Program Files\Tableau\Tableau 2022.4\bin>tableau refreshextract --server https://online.tableau.com --username email@domain.com --password "OurServerPwd" --site vernazza --project "New Animations" --datasource "CurrentYrOverYrStats" --source-username database_user@hosted_datasource_provider.com --source-password "db_password"

To refresh an extract of file-based data source, provide the path to the original file from which you created the extract. If the file is on a network share, use the UNC format instead of a mapped drive.

C:\Program Files\Tableau\Tableau 2022.4\bin>tableau refreshextract --server https://online.tableau.com --username email@domain.com --password "OurServerPwd" --site vernazza --project "New Animations" --datasource "CurrentYrOverYrStats" --original-file "\\server\path\filename.csv"

Syntax for tableau addfiletoextract

Use tableau addfiletoextract to append file content to an extract that has been published to Tableau Server or Tableau Cloud. This command combines the two files.

If you want simply to update an existing extract with the latest changes, use the refreshextract command instead. Using addfiletoextract to update an existing extract will duplicate data instead.

To see help for this command, at the Windows command prompt, type the following command:

tableau help addfiletoextract

All options have a full form that you use with a double hyphen (for example, --server). Some options also have a short form that you use with a single hyphen (for example, -s). If the value for an option contains spaces, enclose it in quotation marks.

tableau addfiletoextract command options

Short Form Full Form Description
  --file <path and file name>

Path and file name information for the data file containing data to append. The file can be from Excel, Access, a Tableau data extract, or a delimited text file. It cannot be password protected. Use UNC format if the file is on a network share. For example, \\server\path\filename.csv
-s <server http address> --server <URL>

The URL for the Tableau server on which the data is published.

For Tableau Cloud, specify https://online.tableau.com.
-t <site id> --site <site id>

In a multiple-site environment, specifies the site to which the command applies. For Tableau Cloud, you must include this argument if your user name is associated with more than one site. For Tableau Server, if you do not specify a site, the default site is assumed.
  --datasource <datasource>

The name of the data source, as published to Tableau Server or Tableau Cloud.
  --project <projectname>

The project to which the data source belongs. If this option is not included, the default project is assumed.

If the project you want to specify is a child project nested within a project hierarchy, you must use this parameter along with the --parent-project-path parameter.
  --parent-project-path path/to/project

If a project to which the data source is published is not at the top level of a project hierarchy, use this parameter along with the --project parameter to specify the path to a nested project.

Use the forward slash character (/) to delimit project levels in the hierarchy. Use the backward slash (\), to escape instances of forward or backward slash characters in project names.

For example, for a project named Sandbox, in project Social, under top-level Marketing:

--project Sandbox --parent-project-path Marketing/Social

-u <username> --username <username>

Valid Tableau Server or Tableau Cloud user.
-p "<password>" --password "<password>"

The password for the specified Tableau Server or Tableau Cloud user.
  --proxy-username <username>

The user name for a proxy server.
  --proxy-password "<password>"

The password for a proxy server.
-c "<path and filename>" --config-file "<path and filename>"

Path and file name information for a file containing configuration options for the command. Always enclose the path in double quotation marks. For more information, see Using a config file below.

Sample tableau addfiletoextract command

C:\Program Files\Tableau\Tableau 2022.4\bin>tableau addfiletoextract --server https://our_server_name --username OurServerSignIn --password "OurServerPwd" --project "New Animations" --datasource "CurrentYrOverYrStats" --file "C:\Users\user1\Documents\DataUploadFiles\AprMay.csv"

C:\Program Files\Tableau\Tableau 2022.4\bin>tableau addfiletoextract --server https://online.tableau.com --username email@domain.com --password "OurServerPwd" --site vernazza --project "New Animations" --datasource "CurrentYrOverYrStats" --file "C:\Users\user2\Documents\DataUploadFiles\AprMay.csv"

Using a config file

You can use a plain text editor, such as Notepad or Text Edit, to create a config (configuration) file that you can use with tableau refreshextract or tableau addfiletoextract. A config file can be useful if you expect to update the same data source regularly over time. Instead of having to type the same options each time you run a command, you specify the config file. A config file also has the advantage of not exposing user names and passwords on the command line.

Create the config file

For example, say you created a file called config.txt and saved it to your Documents folder. And in the file, you included the parameter information shown below.

For an extract published to Tableau Server:

server=https://our_server_name
username=OurServerSignIn
password=OurServerPwd
project=New Animations
datasource=CurrentYrOverYrStats

For an extract from a hosted data source, published to Tableau Cloud, where server is https://online.tableau.com:

server=https://online.tableau.com
site=vernazza
username=email@domain.com
password=OurPassword
project=New Animations
datasource=CurrentYrOverYrStats
source-username=database_user@hosted_datasource_provider.com
source-password=db_password

Reference the Config File from the Command Line

After you create the config file, you run the tableau refreshextract or tableau addfiletoextract command, pointing to the config file as the only option you use on the command line, and enclosing the config file’s path in double quotation marks. The syntax is as follows:

tableau refreshextract --config-file "<path>"

For example, to refresh the extract specified in the sample in the Create the config file section, you would run the following command (making sure that you are working in the bin directory for your version of Tableau Desktop):

C:\Program Files\Tableau\Tableau 2022.4\bin>tableau refreshextract --config-file "C:\Users\user1\Documents\config.txt"

Syntax Differences for Config Files

The syntax for specifying options inside a config file differs from the syntax you use on the command line in the following ways:

  • Option names do not begin with dashes or hyphens.
  • You use an equals sign (with no spaces) to separate option names from option values.
  • Quotation marks are not necessary (or allowed) around values, even when they include spaces (as for the project option in the example shown earlier).

Use Windows Task Scheduler to Refresh Extracts

You can use Windows Task Scheduler, in combination with the Tableau Data Extract Command-Line Utility, to automate regular updates to Tableau Desktop data sources from within your corporate firewall. You can configure a task to occur once per day, week, or month, or after a specific system event. For example, run the task when the computer starts.

To learn more, see the Task Scheduler How To...(Link opens in a new window) page in the Microsoft TechNet library.

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