Tableau Document API

https://github.com/tableau/document-api-python
Admin
Tableau Document API is a Python SDK that enables programmatic updates to Tableau workbooks and data...
Tokens:7,765
Snippets:94
Trust Score:9.4
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Tableau Document API (Development Version)

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/index.md

Installs the development version of the Tableau Document API directly from GitHub.

```shell
pip install git+https://github.com/tableau/document-api-python.git@development
```

--------------------------------

### Install Tableau Document API (From Source)

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/index.md

Installs the Tableau Document API from a local source directory after downloading the zip file.

```shell
pip install -e <directory containing setup.py>
```

--------------------------------

### Install Tableau Document API (Stable)

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/index.md

Installs the latest stable version of the Tableau Document API using pip.

```shell
pip install tableaudocumentapi
```

--------------------------------

### Checkout Development Branch

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/dev-guide.md

Switch to the development branch to start working on new features or fixes.

```shell
git checkout development
```

--------------------------------

### Update Workbook Data Source Connections (Multiple Connections)

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/index.md

Updates connection details for multiple connections within the first data source of a Tableau workbook. This example demonstrates accessing and modifying the second connection (index 1) in addition to the first.

```python
from tableaudocumentapi import Workbook

sourceWB = Workbook('WorkbookToUpdate.twb')

sourceWB.datasources[0].connections[0].server = "MY-NEW-SERVER"
sourceWB.datasources[0].connections[0].dbname = "NEW-DATABASE"
sourceWB.datasources[0].connections[0].username = "benl"

sourceWB.datasources[0].connections[1].server = "MY-NEW-SERVER"
sourceWB.datasources[0].connections[1].dbname = "NEW-DATABASE"
sourceWB.datasources[0].connections[1].username = "benl"


sourceWB.save()
```

--------------------------------

### Uninstall Tableau Document API

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/index.md

Uninstalls the currently installed version of the Tableau Document API. This is often needed before switching between stable and development versions.

```shell
pip uninstall tableaudocumentapi
```

--------------------------------

### Run Tests

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/dev-guide.md

Execute tests using the setup.py script to ensure code integrity.

```shell
python setup.py test
```

--------------------------------

### Clone Repository

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/dev-guide.md

Clone your forked repository to your local machine.

```shell
git clone http://github.com/<your_username>/document-api-python
```

--------------------------------

### Handle Workbooks with Multiple Connections

Source: https://context7.com/tableau/document-api-python/llms.txt

Demonstrates how to load a workbook that contains multiple connections per datasource, a feature introduced in Tableau 10 with Data Integration.

```python
from tableaudocumentapi import Workbook

workbook = Workbook('MultiSource-Dashboard.twb')
```

--------------------------------

### Access Connection Properties

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Retrieve details about a data connection, including server address, database name, username, database class, port, query band, and initial SQL.

```python
self.server:
```

```python
self.dbname:
```

```python
self.username:
```

```python
self.dbclass:
```

```python
self.port:
```

```python
self.query_band:
```

```python
self.initial_sql:
```

--------------------------------

### Access Datasource Properties

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Retrieve the name, version, caption, connections, fields, and calculations associated with a datasource.

```python
self.name
```

```python
self.version
```

```python
self.caption
```

```python
self.connections
```

```python
self.fields
```

```python
self.calculations
```

--------------------------------

### Create Feature Branch

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/dev-guide.md

Create a new branch for your feature or fix, following the recommended naming convention.

```shell
git checkout -b 13-feature-new-stuff
```

--------------------------------

### Add and Remove Fields from Datasource

Source: https://context7.com/tableau/document-api-python/llms.txt

Programmatically add new basic fields or calculated fields to a datasource. Also demonstrates how to remove an existing field. Remember to save the datasource after modifications.

```python
from tableaudocumentapi import Datasource

datasource = Datasource.from_file('metrics.tds')

# Add a basic field
new_field = datasource.add_field(
    name='[Custom Metric]',
    datatype='integer',
    role='measure',
    field_type='quantitative',
    caption='Custom Metric',
    hidden='false'
)
print(f"Added field: {new_field.name}")

# Add a calculated field
calc_field = datasource.add_calculation(
    caption='Profit Margin',
    formula='[Profit] / [Sales]',
    datatype='real',
    role='measure',
    type='quantitative',
    hidden='false'
)
print(f"Added calculation: {calc_field.caption}")
print(f"Formula: {calc_field.calculation}")

# Modify the calculation formula
calc_field.calculation = '([Sales] - [Cost]) / [Sales]'

# Remove a field
field_to_remove = datasource.fields['[Obsolete Field]']
datasource.remove_field(field_to_remove)

datasource.save()
```

--------------------------------

### Open and Inspect Standalone Datasource

Source: https://context7.com/tableau/document-api-python/llms.txt

Load a standalone Tableau data source file (.tds) to inspect its properties, fields, and calculations. Captions can be updated, and the datasource can be saved.

```python
from tableaudocumentapi import Datasource

# Open a standalone datasource file
datasource = Datasource.from_file('sales-data.tds')

# Access datasource properties
print(f"Name: {datasource.name}")
print(f"Version: {datasource.version}")
print(f"Caption: {datasource.caption}")
print(f"Total fields: {len(datasource.fields)}")
print(f"Connections: {len(datasource.connections)}")

# Iterate through fields
for field_id, field in datasource.fields.items():
    print(f"  {field.name}: {field.datatype} ({field.role})")

# Get calculated fields only
for calc_name, calc_field in datasource.calculations.items():
    print(f"  {calc_field.caption}: {calc_field.calculation}")

# Update caption and save
datasource.caption = "Updated Sales Data"
datasource.save()
datasource.save_as('sales-data-updated.tds')
```

--------------------------------

### Manage Datasource Fields and Calculations

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Methods for adding and removing fields, and adding calculated fields to a datasource. Ensure correct data types and roles are provided when adding fields.

```python
Datasource.add_field(self, name, datatype, role, field_type, caption)
```

```python
Datasource.remove_field(self, field)
```

```python
Datasource.add_calculation(self, caption, formula, datatype, role, type)
```

--------------------------------

### Create Datasource from Connections

Source: https://context7.com/tableau/document-api-python/llms.txt

Construct a new Tableau datasource (.tds) by defining connections programmatically. Supports federated datasources with multiple connections.

```python
from tableaudocumentapi import Datasource, Connection

# Create connections
postgres_conn = Connection.from_attributes(
    server="analytics.company.com",
    dbname="reporting",
    username="analyst",
    dbclass="postgres",
    port="5432"
)

mysql_conn = Connection.from_attributes(
    server="crm.company.com",
    dbname="customer_data",
    username="crm_reader",
    dbclass="mysql",
    port="3306"
)

# Create federated datasource with multiple connections
datasource = Datasource.from_connections(
    caption="Combined Analytics Source",
    connections=[postgres_conn, mysql_conn]
)

# Save the new datasource
datasource.save_as('combined-analytics.tds')
```

--------------------------------

### Read and Update Workbook Connections

Source: https://context7.com/tableau/document-api-python/llms.txt

Access and modify connection details for datasources within a workbook. This includes server, database, username, port, and authentication settings. A new connection can also be instantiated.

```python
from tableaudocumentapi import Workbook, Connection

# Access connections through a workbook
workbook = Workbook('Analytics.twb')
datasource = workbook.datasources[0]

# Read connection properties
for conn in datasource.connections:
    print(f"Server: {conn.server}")
    print(f"Database: {conn.dbname}")
    print(f"Username: {conn.username}")
    print(f"DB Class: {conn.dbclass}")
    print(f"Port: {conn.port}")
    print(f"Schema: {conn.schema}")
    print(f"Authentication: {conn.authentication}")
    print(f"Query Band: {conn.query_band}")
    print(f"Initial SQL: {conn.initial_sql}")

# Update connection settings
conn = datasource.connections[0]
conn.server = "prod-db.company.com"
conn.dbname = "analytics_prod"
conn.username = "report_user"
conn.port = "5432"

# Create a new connection from scratch
new_conn = Connection.from_attributes(
    server="warehouse.company.com",
    dbname="data_warehouse",
    username="etl_user",
    dbclass="postgres",
    port="5432",
    schema="public",
    authentication=""
)

workbook.save()
```

--------------------------------

### Batch Update Workbooks from CSV

Source: https://context7.com/tableau/document-api-python/llms.txt

Update connection details for a workbook based on configurations in a CSV file and save it as a new workbook for each environment. This is useful for templating workbooks for different database instances.

```python
import csv
from tableaudocumentapi import Workbook

# databases.csv contents:
# Server,Database,User,DBFriendlyName
# prod-server.com,prod_db,prod_user,Production
# staging-server.com,staging_db,stage_user,Staging
# dev-server.com,dev_db,dev_user,Development

source_workbook = Workbook('template-workbook.twb')

with open('databases.csv') as csvfile:
    databases = csv.DictReader(csvfile)
    for row in databases:
        # Update connection details
        source_workbook.datasources[0].connections[0].server = row['Server']
        source_workbook.datasources[0].connections[0].dbname = row['Database']
        source_workbook.datasources[0].connections[0].username = row['User']

        # Save as new workbook with environment-specific name
        new_filename = f"{row['DBFriendlyName']} - Dashboard.twb"
        source_workbook.save_as(new_filename)
        print(f"Created: {new_filename}")
```

--------------------------------

### Save Workbook Changes

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Saves any modifications made to the workbook. Use `save()` to update the existing file or `save_as()` to save to a new file.

```python
Workbook.save(self):
```

```python
Workbook.save_as(self, new_filename):
```

--------------------------------

### Open and Modify Workbook

Source: https://context7.com/tableau/document-api-python/llms.txt

Open a Tableau workbook (.twb or .twbx) to access and modify its properties, including datasources, worksheets, and dashboards. Connections can be updated, and the workbook can be saved to the existing file or a new one.

```python
from tableaudocumentapi import Workbook

# Open a workbook (TWB or TWBX)
workbook = Workbook('Sales-Dashboard.twbx')

# Access workbook properties
print(f"Filename: {workbook.filename}")
print(f"Datasources: {len(workbook.datasources)}")
print(f"Worksheets: {workbook.worksheets}")
print(f"Dashboards: {workbook.dashboards}")
print(f"Shapes: {workbook.shapes}")

# Modify connection and save
workbook.datasources[0].connections[0].server = "new-server.example.com"
workbook.datasources[0].connections[0].dbname = "production_db"
workbook.datasources[0].connections[0].username = "tableau_user"

# Save to existing file
workbook.save()

# Or save to a new file
workbook.save_as('Sales-Dashboard-Production.twbx')
```

--------------------------------

### Access Datasource Fields

Source: https://context7.com/tableau/document-api-python/llms.txt

Load a Tableau data source file (.tds) to access information about its fields, including name, datatype, role, and aggregation.

```python
from tableaudocumentapi import Datasource

datasource = Datasource.from_file('orders.tds')
```

--------------------------------

### Manage Field Aliases

Source: https://context7.com/tableau/document-api-python/llms.txt

Add or retrieve display aliases for specific field values within a datasource. Aliases map raw data values to more user-friendly display names. Save the datasource to persist changes.

```python
from tableaudocumentapi import Datasource

datasource = Datasource.from_file('categories.tds')

field = datasource.fields['[Status Code]']

# Add aliases to map data values to display values
field.add_alias('1', 'Active')
field.add_alias('2', 'Pending')
field.add_alias('3', 'Inactive')
field.add_alias('0', 'Unknown')

# Get all aliases for a field
all_aliases = field.aliases
print(f"Aliases: {all_aliases}")
# Output: {'1': 'Active', '2': 'Pending', '3': 'Inactive', '0': 'Unknown'}

datasource.save()
```

--------------------------------

### Access Field Properties

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Retrieve various properties of a field, including its name, ID, caption, alias, data type, role (Dimension/Measure), type (quantitative/ordinal/nominal), calculation formula, default aggregation, description, and associated worksheets.

```python
self.name
```

```python
self.id
```

```python
self.xml
```

```python
self.caption
```

```python
self.alias
```

```python
self.datatype
```

```python
self.role
```

```python
self.type
```

```python
self.aliases
```

```python
self.is_quantitative
```

```python
self.is_ordinal
```

```python
self.is_nominal
```

```python
self.calculation
```

```python
self.default_aggregation
```

```python
self.description
```

```python
self.worksheets
```

--------------------------------

### Update Workbook Datasource Connections

Source: https://context7.com/tableau/document-api-python/llms.txt

Modify connection details for datasources within a workbook. Ensure the workbook is saved after making changes.

```python
datasource = workbook.datasources[0]

# Update primary connection
datasource.connections[0].server = "primary-db.company.com"
datasource.connections[0].dbname = "main_database"
datasource.connections[0].username = "primary_user"

# Update secondary connection (federated data source)
if len(datasource.connections) > 1:
    datasource.connections[1].server = "secondary-db.company.com"
    datasource.connections[1].dbname = "lookup_database"
    datasource.connections[1].username = "secondary_user"

workbook.save()
```

--------------------------------

### Create Field XML

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Generates the XML representation for a field object. This method is useful for creating new fields or inspecting existing ones.

```python
Field.create_field_xml()
```

--------------------------------

### Connection Class

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Represents a Tableau data connection, applicable to various database types.

```APIDOC
## Connection Class

### Description
The Connection class represents a tableau data connection. It can be from any type of connection found in `dbclass.py` via `is_valid_dbclass`.

### Properties
- **self.server**: Returns a string containing the server.
- **self.dbname**: Returns a string containing the database name.
- **self.username**: Returns a string containing the username.
- **self.dbclass**: Returns a string containing the database class.
- **self.port**: Returns a string containing the port.
- **self.query_band**: Returns a string containing the query band.
- **self.initial_sql**: Returns a string containing the initial sql.
```

--------------------------------

### Workbook Class

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Represents a Tableau workbook (TWB or TWBX) and provides methods for saving and accessing its components.

```APIDOC
## Workbook Class

### Description
The Workbook class represents a tableau workbook. It may be either a TWB or TWBX, and the library will handle packaging and unpackaging automatically.

### Parameters
- **filename** (string) - The path to the workbook file.

### Raises
- `TableauVersionNotSupportedException` - If the workbook is not a supported version.
- `TableauInvalidFileException` - If the file is not a valid tableau workbook file.

### Methods
- **save()**: Saves any changes to the workbook to the existing file.
- **save_as(new_filename)**: Saves any changes to the workbook to a new file specified by the `new_file` parameter.

### Properties
- **self.worksheets**: Returns a list of worksheets found in the workbook.
- **self.datasources**: Returns a list of Datasource objects found in the workbook.
- **self.filename**: Returns the filename of the workbook.
- **self.shapes**: Returns a list of strings with the names of shapes found in the workbook.
- **self.dashboards**: Returns a list of strings with the names of the dashboards found in the workbook.
```

--------------------------------

### Update Workbook Data Source Connection (Single Connection)

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/index.md

Updates the server, database name, and username for the first data source and its first connection in a Tableau workbook. Ensure the Workbook object is imported from the tableaudocumentapi module.

```python
from tableaudocumentapi import Workbook

sourceWB = Workbook('WorkbookToUpdate.twb')

sourceWB.datasources[0].connections[0].server = "MY-NEW-SERVER"
sourceWB.datasources[0].connections[0].dbname = "NEW-DATABASE"
sourceWB.datasources[0].connections[0].username = "benl"

sourceWB.save()
```

--------------------------------

### Access Workbook Properties

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Retrieve lists of worksheets, datasources, dashboards, and shape names within a workbook. Also provides access to the workbook's filename.

```python
self.worksheets:
```

```python
self.datasources:
```

```python
self.filename:
```

```python
self.shapes
```

```python
self.dashboards:
```

--------------------------------

### Iterate and Modify Datasource Fields

Source: https://context7.com/tableau/document-api-python/llms.txt

Iterate through all fields in a datasource to print their properties. Modify properties like caption, datatype, role, type, and hidden status for a specific field. Ensure to save changes to the datasource.

```python
for field_id, field in datasource.fields.items():
    print(f"ID: {field.id}")
    print(f"Name: {field.name}")
    print(f"Caption: {field.caption}")
    print(f"Alias: {field.alias}")
    print(f"Datatype: {field.datatype}")
    print(f"Role: {field.role}")  # 'dimension' or 'measure'
    print(f"Type: {field.type}")  # 'quantitative', 'ordinal', 'nominal'
    print(f"Default Aggregation: {field.default_aggregation}")
    print(f"Hidden: {field.hidden}")
    print(f"Description: {field.description}")
    print(f"Used in worksheets: {field.worksheets}")

    # Type checks
    print(f"Is Quantitative: {field.is_quantitative}")
    print(f"Is Ordinal: {field.is_ordinal}")
    print(f"Is Nominal: {field.is_nominal}")

    # If calculated field
    if field.calculation:
        print(f"Calculation: {field.calculation}")

    print("---")

# Modify field properties
field = datasource.fields['[Sales]']
field.caption = "Total Sales"
field.datatype = "integer"  # 'string', 'integer', 'date', 'boolean'
field.role = "measure"  # 'dimension', 'measure'
field.type = "quantitative"  # 'quantitative', 'ordinal', 'nominal'
field.hidden = "false"  # 'true', 'false'

datasource.save()
```

--------------------------------

### Validate Database Classes

Source: https://context7.com/tableau/document-api-python/llms.txt

Check if a specified database class is supported by the Tableau Document API. Lists common supported database classes.

```python
from tableaudocumentapi.dbclass import is_valid_dbclass, KNOWN_DB_CLASSES

# Check if a database class is valid
print(is_valid_dbclass('postgres'))  # True
print(is_valid_dbclass('mysql'))     # True
print(is_valid_dbclass('invalid'))   # False

# Common supported database classes:
# 'postgres', 'mysql', 'sqlserver', 'oracle', 'redshift', 'snowflake',
# 'bigquery', 'teradata', 'db2', 'saphana', 'vertica', 'spark',
# 'excel', 'csv', 'textscan', 'google-sheets', 'salesforce'
```

--------------------------------

### Datasource Class

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Represents a Tableau Data Source, either embedded in workbook files or as standalone TDS files.

```APIDOC
## Datasource Class

### Description
A class representing Tableau Data Sources, embedded in workbook files or in TDS files.

### Methods
- **save()**: Saves any changes to the datasource to the existing file.
- **save_as()**: Saves any changes to the datasource to a new file specified by the `new_file` parameter.
- **add_field(name, datatype, role, field_type, caption)**: Adds a base field object with the given values.
- **remove_field(field)**: Remove a given field.
- **add_calculation(caption, formula, datatype, role, type)**: Adds a calculated field with the given values.

### Properties
- **self.name**: Returns string with the name of datasource.
- **self.version**: Returns string of datasource's version.
- **self.caption**: Returns string of user defined name of datasource if exists.
- **self.connections**: Returns list of connections used in workbook.
- **self.fields**: Returns key-value result of field name and their attributes.
- **self.calculations**: Returns calculated field of the workbook.
```

--------------------------------

### Represent a Tableau Data Connection

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

The Connection class represents a Tableau data connection. It provides properties to access connection details like server, database name, username, and port.

```python
class Connection(connxml)
```

--------------------------------

### Represent a Tableau Workbook

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

The Workbook class represents a Tableau workbook (TWB or TWBX). It handles packaging and unpackaging automatically. Use this class to interact with workbook properties and methods.

```python
class Workbook(filename):
```

--------------------------------

### Find Fields Used by Specific Worksheets

Source: https://context7.com/tableau/document-api-python/llms.txt

Retrieve fields from a datasource that are utilized by one or more specified worksheets. This is useful for understanding data dependencies within a workbook.

```python
from tableaudocumentapi import Workbook

workbook = Workbook('Dashboard.twbx')

# List all worksheets
print(f"Worksheets: {workbook.worksheets}")

# For each datasource, find fields used by specific worksheets
for datasource in workbook.datasources:
    print(f"\nDatasource: {datasource.name}")

    # Get fields used by a single worksheet
    fields_in_sheet = datasource.fields.used_by_sheet('Sales Overview')
    for field in fields_in_sheet:
        print(f"  {field.name} ({field.datatype})")

    # Get fields used by multiple worksheets
    multi_sheet_fields = datasource.fields.used_by_sheet(['Sales Overview', 'Regional Analysis'])
    print(f"Fields shared across sheets: {len(multi_sheet_fields)}")
```

--------------------------------

### Represent a Tableau Datasource

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

The Datasource class represents Tableau Data Sources, whether embedded in workbooks or in separate TDS files. Use its methods to manage fields and calculations.

```python
class Datasource(dsxml, filename=None)
```

--------------------------------

### Manage Field Aliases

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Add aliases to a field to control its display value in Tableau. Use `add_alias()` to map a key to a display value.

```python
Field.add_alias(self, key, value)
```

--------------------------------

### Field Class

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

Represents a field within a Tableau datasource, providing access to its properties and metadata.

```APIDOC
## Field Class

### Description
Represents a field in a datasource.

### Methods
- **create_field_xml()**: Create field from scratch.
- **add_alias(key, value)**: Add an alias for a given display value.

### Properties
- **self.name**: Returns a string providing a nice name for the field which is derived from the alias, caption, or the id.
- **self.id**: Returns a string with name of the field as specified in the file, usually surrounded by [ ].
- **self.xml**: Returns a ElementTree object which represents an XML of the field.
- **self.caption**: Returns a string with the name of the field as displayed in Tableau unless an aliases is defined.
- **self.alias**: Returns a string with the name of the field as displayed in Tableau if the default name isn't wanted.
- **self.datatype**: Returns a string with the type of the field within Tableau (string, integer, etc).
- **self.role**: Returns a string which identify field as a Dimension or Measure.
- **self.type**: Returns a string with type of field (quantitative, ordinal, nominal).
- **self.aliases**: Returns Key-value mappings of all aliases that are registered under this field.
- **self.is_quantitative**: Returns a boolean if field is quantitative.
- **self.is_ordinal**: Returns a boolean if field is categorical that has a specific order.
- **self.is_nominal**: Returns a boolean if field is categorical that does not have a specific order.
- **self.calculation**: Returns a string with the formula if this field is a calculated field.
- **self.default_aggregation**: Returns a string with he default type of aggregation on the field (e.g Sum, Avg).
- **self.description**: Returns a string with contents of the <desc> tag on a field.
- **self.worksheets**: Returns a list of strings with the worksheet's names uses this field.
```

--------------------------------

### Represent a Field in a Datasource

Source: https://github.com/tableau/document-api-python/blob/master/docs/docs/api-ref.md

The Field class represents a field within a Tableau datasource. It allows manipulation of field properties, aliases, and creation of XML representations.

```python
class Field(column_xml=None, metadata_xml=None)
```
Tokens:
Raw