VizQL Data Service

https://github.com/tableau/vizql-data-service
Admin
VizQL Data Service is Tableau's RESTful API service with OpenAPI schema documentation and a Python...
Tokens:53,512
Snippets:358
Trust Score:9.4
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Quick Start Example

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/README.md

Example usage of the SDK to authenticate, create a client, read metadata, and query a datasource.

```APIDOC
## Quick Start

```python
import tableauserverclient as TSC
from vizql_data_service_py import (
    VizQLDataServiceClient,
    QueryRequest,
    ReadMetadataRequest,
    Datasource,
    Connection,
    Query,
    DimensionField,
    MeasureField,
    Function,
    read_metadata,
    query_datasource,
)

tableau_auth = TSC.PersonalAccessTokenAuth("TOKEN_NAME", "TOKEN_VALUE", "SITENAME")
server = TSC.Server("https://SERVER_URL")

with server.auth.sign_in(tableau_auth):
    client = VizQLDataServiceClient(server.url, server, tableau_auth)

    datasource = Datasource(datasourceLuid="<datasource-luid>")

    metadata = read_metadata.sync(
        client=client, body=ReadMetadataRequest(datasource=datasource)
    )
    print(metadata)

    query = Query(
        fields=[
            DimensionField(fieldCaption="Category"),
            MeasureField(fieldCaption="Sales", function=Function.SUM),
        ]
    )
    result = query_datasource.sync(
        client=client, body=QueryRequest(query=query, datasource=datasource)
    )
    print(result)
```
```

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

### Install vizql-data-service-py with pip

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/README.md

Install the package using pip. This is the first step in the quick start.

```bash
pip install vizql-data-service-py
```

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

### Install vizql-data-service-py with virtual environment setup

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/README.md

Commands to create and activate a Python virtual environment (optional) and install the vizql-data-service-py package. Includes commands for Unix/MacOS and Windows activation.

```bash
python -m venv --system-site-packages venv # Optional command: set up a python virtual environment before installing the vizql_data_service_py package
source venv/bin/activate    # A continuation of the first command for Unix/MacOS users. This activates the virtual environment for Unix/MacOS
venv\Scripts\activate       # A continuation of the first command for Windows users. This activates the virtual environment for Windows

pip install vizql-data-service-py
```

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

### Set up virtual environment and install dependencies

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/CONTRIBUTING.md

Create a virtual environment, activate it, upgrade pip, and install required (or optional dev) dependencies.

```bash
cd VizQL-Data-Service/python_sdk
python -m venv --system-site-packages venv
source venv/bin/activate    # On Unix/MacOS
venv\Scripts\activate       # On Windows

python -m pip install --upgrade pip # Upgrade pip
pip install -e .            # Required dependencies
# pip install -e .[dev]     # Required and optional dependencies
```

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

### Run examples.py with help and authentication options

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/CONTRIBUTING.md

Shows how to run examples.py from the src/examples directory. Use --help to see options. Authentication can be done with username/password, PAT (--pat-name, --pat-secret), or JWT (--jwt-token). The --async flag runs asynchronous examples; otherwise synchronous examples run by default. The --site argument is optional and defaults to a site your token works for.

```bash
cd src/examples

python examples.py --help

# Running the published + static workbook datasource examples
# If `site` argument is left out, this will run against a default site that your token works for
# If `async` argument is left out, the default examples run synchronously

# Auth using username and password and run synchronous examples
python examples.py --user "<username>" --password "<password>" --server "<server>"

# Auth using personal access token (PAT) and run asynchronous examples
python examples.py --pat-name "<pat-name>" --pat-secret "<pat-secret>" --server "<server>" --site "<site-id>" --async

# Auth using JWT and run async examples
python examples.py --jwt-token "<jwt-token>" --server "<server>" --site "<site-id>" --async
```

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

### Installation

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/README.md

Install the vizql-data-service-py package using pip.

```APIDOC
## Installation

```bash
pip install vizql-data-service-py
```
```

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

### Run live workbook examples with all three workbook flags

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/CONTRIBUTING.md

Runs the synchronous published, static workbook datasource, and live workbook examples. Requires all three workbook flags: --workbook-datasource-id, --global-session-header, and --x-session-id. If any flag is missing, the live workbook flow is skipped.

```bash
# Runs the synchronous published, static workbook datasource, and live workbook examples
python examples.py \
  --pat-name "<pat-name>" --pat-secret "<pat-secret>" \
  --server "<server>" --site "<site-id>" \
  --workbook-datasource-id "<workbook-datasource-id>" \
  --global-session-header "<global-session-header>" \
  --x-session-id "<x-session-id>"
```

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

### Install dev dependencies and run tests

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/CONTRIBUTING.md

Install the package with development dependencies and run the test suite with pytest.

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

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

### Usage examples for format_server_url

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/utils.md

Shows how to import and call format_server_url with various inputs: a full URL with subdomain, a Tableau Online host (forced to https), a bare host (gets http), and an empty string raising ValueError.

```python
from vizql_data_service_py.api.utils import format_server_url

# From the client's perspective:
base = format_server_url("https://your-server.example.com", "/api/v1/vizql-data-service")
# -> "https://your-server.example.com/api/v1/vizql-data-service"

# Tableau Online is forced to https
print(format_server_url("10ax.online.tableau.com"))
# -> "https://10ax.online.tableau.com"

# Bare host gets http://
print(format_server_url("localhost:8080"))
# -> "http://localhost:8080"

try:
    format_server_url("")
except ValueError as e:
    print(e)  # "URL cannot be empty"
```

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

### Quick start: authenticate and query a datasource with VizQLDataServiceClient

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/README.md

Shows how to import the SDK, authenticate with Tableau Server using a personal access token, create a client, read metadata, and run a query. Requires a valid datasource LUID and Tableau Server URL.

```python
import tableauserverclient as TSC
from vizql_data_service_py import (
    VizQLDataServiceClient,
    QueryRequest,
    ReadMetadataRequest,
    Datasource,
    Connection,
    Query,
    DimensionField,
    MeasureField,
    Function,
    read_metadata,
    query_datasource,
)

tableau_auth = TSC.PersonalAccessTokenAuth("TOKEN_NAME", "TOKEN_VALUE", "SITENAME")
server = TSC.Server("https://SERVER_URL")

with server.auth.sign_in(tableau_auth):
    client = VizQLDataServiceClient(server.url, server, tableau_auth)

    datasource = Datasource(datasourceLuid="<datasource-luid>")

    metadata = read_metadata.sync(
        client=client, body=ReadMetadataRequest(datasource=datasource)
    )
    print(metadata)

    query = Query(
        fields=[
            DimensionField(fieldCaption="Category"),
            MeasureField(fieldCaption="Sales", function=Function.SUM),
        ]
    )
    result = query_datasource.sync(
        client=client, body=QueryRequest(query=query, datasource=datasource)
    )
    print(result)
```

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

### Quick import cheat sheet for VizQL Data Service SDK

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/README.md

Shows how to import the main client, endpoint modules, request/response models, and field types. Includes a comment distinguishing detailed vs. simple variants and example calls for sync and sync_detailed.

```python
from vizql_data_service_py import (
    VizQLDataServiceClient,       # class
    read_metadata,                # module with sync/sync_detailed/asyncio/asyncio_detailed
    query_datasource,
    get_datasource_model,
    Datasource, Connection,       # request models
    ReadMetadataRequest,
    Query, QueryRequest, QueryDatasourceOptions, QueryOptions,
    GetDatasourceModelRequest,
    QueryOutput, MetadataOutput, DatasourceModelOutput,
    DimensionField, MeasureField, CalculatedField, BinField, TableCalcField,
    Function, FilterType, SortDirection,
)

# Detailed vs. simple variants:
data = read_metadata.sync(client=client, body=request)          # Optional[MetadataOutput]
resp, status, headers = read_metadata.sync_detailed(client=client, body=request)  # Response
```

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

### Catch UnexpectedStatus exception

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/errors.md

Example showing how to opt in to raising UnexpectedStatus and catch it, printing the status code and raw response body.

```python
from vizql_data_service_py import query_datasource
from vizql_data_service_py.api.errors import UnexpectedStatus

client.raise_on_unexpected_status = True  # opt in

try:
    result = query_datasource.sync(client=client, body=request)
except UnexpectedStatus as e:
    print(f"HTTP {e.status_code}")
    print(e.content.decode(errors="ignore"))  # raw body
```

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

### SDK constants for sample names and session headers

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/constants.md

Defines constant values for sample names and session header names used across the SDK and examples runner.

```python
SAMPLE_DATASOURCE = "Superstore Datasource"
SAMPLE_WORKBOOK = "Superstore"
SAMPLE_STATIC_WORKBOOK_DATASOURCE = "Sample - Superstore"
GLOBAL_SESSION_HEADER_NAME = "Global-Session-Header"
X_SESSION_ID_HEADER_NAME = "X-Session-Id"
```

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

### get_async_httpx_client

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Gets the underlying httpx.AsyncClient, constructing a new one if not previously set. The new client is configured with the base URL, cookies, headers, timeout, SSL verification, and follow redirects settings.

```APIDOC
## get_async_httpx_client

### Description
Gets the underlying httpx.AsyncClient, constructing a new one if not previously set. The new client is configured with the base URL, cookies, headers, timeout, SSL verification, and follow redirects settings.

### Method
get_async_httpx_client

### Signature
```python
def get_async_httpx_client(self) -> httpx.AsyncClient:
```

### Returns
- **httpx.AsyncClient** - The underlying async client.

```

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

### POST /get-datasource-model

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/endpoints.md

Gets the datasource model. Requires X-Tableau-Auth authentication and returns a DatasourceModelOutput object.

```APIDOC
## POST /get-datasource-model

### Description
Gets the datasource model.

### Method
POST

### Endpoint
/get-datasource-model

### Parameters
#### Headers
- **X-Tableau-Auth** (string) - Required - Authentication token.

### Request Example
No request body documented.

### Response
#### Success Response (200)
- **DatasourceModelOutput** (object) - The datasource model output.

#### Response Example
{}

```

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

### Basic synchronous query with query_datasource.sync

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/query_datasource.md

Shows how to create a client, datasource, and query, then execute it synchronously using query_datasource.sync. The result's data is printed if the result is not None.

```python
from vizql_data_service_py import (
    VizQLDataServiceClient,
    Datasource,
    Query,
    QueryRequest,
    DimensionField,
    MeasureField,
    Function,
    query_datasource,
)

client = VizQLDataServiceClient(server_url, server, auth)
datasource = Datasource(datasourceLuid="<datasource-luid>")

query = Query(
    fields=[
        DimensionField(fieldCaption="Category"),
        MeasureField(fieldCaption="Sales", function=Function.SUM),
    ]
)
result = query_datasource.sync(
    client=client, body=QueryRequest(query=query, datasource=datasource)
)
print(result.data if result else None)
```

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

### Basic initialization and synchronous call

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Demonstrates how to initialize the VizQLDataServiceClient with Tableau authentication and make a synchronous read_metadata call.

```APIDOC
## VizQLDataServiceClient Initialization and read_metadata.sync_detailed

### Description
Initializes the VizQLDataServiceClient with a Tableau Server connection and personal access token authentication, then performs a synchronous read_metadata request.

### Method
POST (implied by sync_detailed)

### Endpoint
Not explicitly specified in source.

### Parameters
#### Constructor Parameters
- **server.url** (string) - Required - The base URL of the Tableau Server.
- **server** (TSC.Server) - Required - The Tableau Server client instance.
- **tableau_auth** (TSC.PersonalAccessTokenAuth) - Required - Authentication object with token name, token value, and site name.

#### read_metadata.sync_detailed Parameters
- **client** (VizQLDataServiceClient) - Required - The initialized client.
- **body** (ReadMetadataRequest) - Required - Request body containing a Datasource with a datasourceLuid.

### Request Example
```python
ReadMetadataRequest(datasource=Datasource(datasourceLuid="<luid>"))
```

### Response
#### Success Response
- **response.parsed** - Parsed response object.
- **status** (int) - HTTP status code.
- **headers** (dict) - Response headers.

#### Response Example
```python
response, status, headers = read_metadata.sync_detailed(client=client, body=...)
```
```

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

### Basic synchronous call to get_datasource_model

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/get_datasource_model.md

Shows how to create a client, define a datasource, and call get_datasource_model.sync. It prints logical table IDs and captions, and relationship mappings.

```python
from vizql_data_service_py import (
    VizQLDataServiceClient,
    Datasource,
    GetDatasourceModelRequest,
    get_datasource_model,
)

client = VizQLDataServiceClient(server_url, server, auth)
datasource = Datasource(datasourceLuid="<datasource-luid>")

model = get_datasource_model.sync(
    client=client, body=GetDatasourceModelRequest(datasource=datasource)
)
if model:
    for table in model.logicalTables:
        print(table.logicalTableId, table.caption)
    for rel in model.logicalTableRelationships:
        print(rel.fromLogicalTable.logicalTableId, "->", rel.toLogicalTable.logicalTableId)
```

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

### GET /simple-request

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/endpoints.md

Sends a request that can be used for testing or doing a health check. This endpoint requires no authentication and returns a plain string body.

```APIDOC
## GET /simple-request

### Description
Sends a request that can be used for testing or doing a health check.

### Method
GET

### Endpoint
/simple-request

### Parameters
No parameters.

### Request Example
No request body.

### Response
#### Success Response (200)
- **body** (string) - A plain string body.

#### Response Example
"string"

```

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

### Configure a Datasource with optional connections

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/README.md

Creates a Datasource instance with a datasource LUID and optional connection credentials for external data sources.

```python
# Create a data source instance with optional connection parameters
datasource = Datasource(
    datasourceLuid="<datasource-luid>",
    # Optional: Configure connections for external data sources
    connections=[
        Connection(
            connectionUsername="<connection-username>",
            connectionPassword="<connection-password>"
        )
    ]
)
```

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

### XTableauAuth API key security scheme

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/endpoints.md

Defines the global API key security scheme used for authentication. All requests must include the X-Tableau-Auth header except GET /simple-request.

```json
{ "XTableauAuth": { "type": "apiKey", "in": "header", "name": "X-Tableau-Auth" } }
```

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

### VizQLDataServiceClient constructor

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Initializes the client with the server URL, TSC server and auth objects, SSL verification settings, and optional session headers. Session headers are only applied when both are provided. Sets raise_on_unexpected_status to False and prints the server URL to stdout.

```python
def __init__(
    self,
    url: str,
    server: TSC.Server,
    auth: Union[TSC.JWTAuth, TSC.PersonalAccessTokenAuth, TSC.TableauAuth],
    verify_ssl: Union[str, bool, ssl.SSLContext] = True,
    global_session_header: Optional[str] = None,
    x_session_id: Optional[str] = None,
):
```

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

### VizQLDataServiceClient.__init__

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Constructs a new VizQLDataServiceClient instance with the given server URL, TSC server and auth objects, SSL settings, and optional session headers.

```APIDOC
## VizQLDataServiceClient.__init__

### Description
Initializes a new VizQLDataServiceClient instance.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    url: str,
    server: TSC.Server,
    auth: Union[TSC.JWTAuth, TSC.PersonalAccessTokenAuth, TSC.TableauAuth],
    verify_ssl: Union[str, bool, ssl.SSLContext] = True,
    global_session_header: Optional[str] = None,
    x_session_id: Optional[str] = None,
):
```

### Parameters
- **url** (str) - Required - The base URL of the server
- **server** (TSC.Server) - Required - The signed-in Tableau Server instance; `server.auth_token` is used as the auth token
- **auth** (Union[TSC.JWTAuth, TSC.PersonalAccessTokenAuth, TSC.TableauAuth]) - Required - The TSC authentication object (JWT, PAT, or username/password)
- **verify_ssl** (Union[str, bool, ssl.SSLContext]) - Optional - Default: `True` - SSL verification: `True` (system CA bundle), `False` (disable), a path to a CA bundle, or an `ssl.SSLContext`
- **global_session_header** (Optional[str]) - Optional - Default: `None` - Value for the `Global-Session-Header` request header, used for workbook-datasource-id queries
- **x_session_id** (Optional[str]) - Optional - Default: `None` - Value for the `X-Session-Id` request header, used for workbook-datasource-id queries

### Behavior
Session headers are only applied when **both** `global_session_header` and `x_session_id` are provided (non-empty).

During construction:
1. `self._client = self._create_client()` builds the `AuthenticatedClient`.
2. If both session headers are present, they are merged via `AuthenticatedClient.with_headers(...)`.
3. `self.raise_on_unexpected_status = False` is set.

**Side effect:** `_create_client()` prints `Server URL: <base_url>` to stdout on construction.
```

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

### AuthenticatedClient.get_httpx_client

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Gets the underlying httpx.Client, constructing a new one if not previously set. The new client is configured with the client's base URL, cookies, headers, timeout, SSL verification, redirect settings, and additional httpx arguments, and includes the Authorization header.

```APIDOC
## get_httpx_client

### Description
Gets the underlying httpx.Client, constructing a new one if not previously set. The new client is configured with the client's base URL, cookies, headers, timeout, SSL verification, redirect settings, and additional httpx arguments, and includes the Authorization header.

### Method
get_httpx_client

### Signature
```python
def get_httpx_client(self) -> httpx.Client:
```

### Returns
- **httpx.Client** - The underlying httpx.Client.

### Example
```python
client = client.get_httpx_client()
```
```

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

### Sign in, read metadata, and query data sources

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/README.md

Complete workflow: sign in with Tableau Server Client, create a VizQLDataServiceClient, define a query with dimensions and measures, read metadata, and execute a query. Includes commented alternatives for authentication methods.

```python
import tableauserverclient as TSC

# Choose one of these auth mechanisms
tableau_auth = TSC.PersonalAccessTokenAuth('TOKEN_NAME', 'TOKEN_VALUE', 'SITENAME')
# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', 'SITENAME')
# tableau_auth = TSC.JWTAuth('JWT', 'SITENAME')

server_url = 'https://SERVER_URL'
server = TSC.Server(server_url)

with server.auth.sign_in(tableau_auth):
    client = VizQLDataServiceClient(server_url, server, tableau_auth)
    # Define your query fields
    query = Query(
        # Example: sample Superstore data source
        # Aggregate SUM(Sales) by Category
        fields=[
            DimensionField(fieldCaption="Category"),
            MeasureField(fieldCaption="Sales", function=Function.SUM),
        ]
    )
    # Step 1: Read metadata
    read_metadata_request = ReadMetadataRequest(
        datasource=datasource
    )
    read_metadata_response = read_metadata.sync(
        client=client, body=read_metadata_request
    )
    print(f"Read Metadata Response: {read_metadata_response}")

    # Step 2: Execute query
    query_request = QueryRequest(
        query=query, datasource=datasource
    )
    query_response = query_datasource.sync(
        client=client, body=query_request
    )
    print(f"Query Datasource Response: {query_response}")
```

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

### __enter__

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Enters a context manager for the internal httpx.Client, returning the AuthenticatedClient instance. Cannot be entered twice.

```APIDOC
## __enter__

### Description
Enters a context manager for the internal httpx.Client, returning the AuthenticatedClient instance. Cannot be entered twice.

### Method
__enter__

### Signature
```python
def __enter__(self) -> "AuthenticatedClient":
```

### Returns
- **AuthenticatedClient** - The client instance for use within the context manager.

```

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

### Basic initialization and synchronous call

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Initializes the client with a personal access token and performs a synchronous read_metadata call. Requires a valid Tableau server URL and datasource LUID.

```python
import tableauserverclient as TSC
from vizql_data_service_py import VizQLDataServiceClient, ReadMetadataRequest, Datasource, read_metadata

tableau_auth = TSC.PersonalAccessTokenAuth("TOKEN_NAME", "TOKEN_VALUE", "SITENAME")
server = TSC.Server("https://your-server.example.com")

with server.auth.sign_in(tableau_auth):
    client = VizQLDataServiceClient(server.url, server, tableau_auth)

    response, status, headers = read_metadata.sync_detailed(
        client=client,
        body=ReadMetadataRequest(datasource=Datasource(datasourceLuid="<luid>")),
    )
    print(status, headers, response.parsed)
```

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

### SSL and workbook session-header configuration

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Shows how to configure a custom SSL context, set session headers for workbook datasource queries, and access the underlying httpx client.

```python
import ssl
from vizql_data_service_py import VizQLDataServiceClient

# Custom CA bundle / SSL context
ctx = ssl.create_default_context()
ctx.load_verify_locations(cafile="/path/to/ca-bundle.pem")
client = VizQLDataServiceClient(server.url, server, auth, verify_ssl=ctx)

# Workbook datasource queries require both session headers
client = VizQLDataServiceClient(
    server.url,
    server,
    auth,
    global_session_header="<global-session-value>",
    x_session_id="<session-id>",
)

# Direct access to the underlying httpx client (e.g. for custom middleware)
httpx_client = client.get_httpx_client()
```

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

### Generate OpenAPI client on Windows

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/CONTRIBUTING.md

Run the stub generation script on Windows.

```bash
scripts\generate_stub.bat
```

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

### _create_client method

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Builds the AuthenticatedClient with the formatted server URL, the server's auth token, and the X-Tableau-Auth header. The prefix is empty so the token is used without a 'Bearer ' prefix. Requires the server to be signed in or the token set, otherwise the header will be empty.

```python
def _create_client(self) -> AuthenticatedClient:
    base_url = format_server_url(self.url, API_SUBDOMAIN)
    print(f"Server URL: {base_url}")

    return AuthenticatedClient(
        base_url=base_url,
        token=self.server.auth_token,
        prefix="",
        auth_header_name=X_TABLEAU_AUTH,
        verify_ssl=self.verify_ssl,
    )
```

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

### SSL and workbook session-header configuration

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Shows how to configure the client with a custom SSL context, workbook session headers, and access to the underlying httpx client.

```APIDOC
## VizQLDataServiceClient Configuration Options

### Description
Configures the VizQLDataServiceClient with custom SSL verification, global session header, and X-Session-ID for workbook datasource queries. Also provides direct access to the underlying httpx client.

### Method
N/A (configuration)

### Endpoint
N/A

### Parameters
#### Constructor Parameters
- **server.url** (string) - Required - The base URL of the Tableau Server.
- **server** (TSC.Server) - Required - The Tableau Server client instance.
- **auth** (TSC.PersonalAccessTokenAuth) - Required - Authentication object.
- **verify_ssl** (ssl.SSLContext) - Optional - Custom SSL context for certificate verification.
- **global_session_header** (string) - Optional - Global session header value for workbook datasource queries.
- **x_session_id** (string) - Optional - X-Session-ID header value for workbook datasource queries.

#### get_httpx_client Method
- Returns the underlying httpx.Client instance for custom middleware.

### Request Example
```python
client = VizQLDataServiceClient(server.url, server, auth, verify_ssl=ctx)
client = VizQLDataServiceClient(server.url, server, auth, global_session_header="<global-session-value>", x_session_id="<session-id>")
httpx_client = client.get_httpx_client()
```

### Response
No direct response; configuration only.
```

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

### Basic synchronous call

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/read_metadata.md

Shows how to create a client, build a ReadMetadataRequest with a Datasource, and call read_metadata.sync. Iterates over the returned metadata fields and prints field properties.

```python
from vizql_data_service_py import (
    VizQLDataServiceClient,
    Datasource,
    ReadMetadataRequest,
    read_metadata,
)

client = VizQLDataServiceClient(server_url, server, auth)
datasource = Datasource(datasourceLuid="<datasource-luid>")

metadata = read_metadata.sync(client=client, body=ReadMetadataRequest(datasource=datasource))
if metadata is not None:
    for field in metadata.data:
        print(field.fieldName, field.fieldCaption, field.dataType, field.fieldRole)

```

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

### Run all code quality checks

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/CONTRIBUTING.md

Run Black, isort, flake8, and mypy to ensure code formatting and type correctness.

```bash
black .
isort .
flake8 .
mypy .
```

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

### Direct usage of session header constants

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/constants.md

Shows direct import and usage of the session header constants, demonstrating that they exactly match the argument values passed to the client.

```python
from vizql_data_service_py.api.constants import (
    GLOBAL_SESSION_HEADER_NAME,
    X_SESSION_ID_HEADER_NAME,
)

# Equivalent to passing global_session_header=... and x_session_id=... to the client
client = VizQLDataServiceClient(
    url, server, auth,
    global_session_header="<global-session-value>",
    x_session_id="<session-id>",
)
assert GLOBAL_SESSION_HEADER_NAME == "Global-Session-Header"
assert X_SESSION_ID_HEADER_NAME == "X-Session-Id"
```

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

### Clone the repository

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/CONTRIBUTING.md

Clone the VizQL-Data-Service repository from GitHub.

```bash
git clone https://github.com/tableau/VizQL-Data-Service.git
```

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

### Query with filters, parameters, and error handling

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/query_datasource.md

Demonstrates a query with a SetFilter and a Parameter, using QueryDatasourceOptions to set return format and row limit. It enables raise_on_unexpected_status and catches UnexpectedStatus and httpx.TimeoutException.

```python
from vizql_data_service_py import (
    Query,
    QueryRequest,
    QueryDatasourceOptions,
    ReturnFormat,
    SetFilter,
    DimensionFilterField,
    FilterType,
    Parameter,
    query_datasource,
)
from vizql_data_service_py.api.errors import UnexpectedStatus
import httpx

query = Query(
    fields=[
        DimensionField(fieldCaption="Ship Mode"),
        MeasureField(fieldCaption="Sales", function=Function.SUM),
    ],
    filters=[
        SetFilter(
            field=DimensionFilterField(fieldCaption="Ship Mode"),
            filterType=FilterType.SET,
            values=["First Class", "Standard Class"],
        )
    ],
    parameters=[Parameter(parameterCaption="Profit Bin Size", value=50)],
)
request = QueryRequest(
    query=query,
    datasource=datasource,
    options=QueryDatasourceOptions(returnFormat=ReturnFormat.ARRAYS, rowLimit=100),
)
client.raise_on_unexpected_status = True
try:
    response, status, headers = query_datasource.sync_detailed(client=client, body=request)
    print(status, headers, response.parsed)
except UnexpectedStatus as e:
    print(f"Unexpected status {e.status_code}: {e.content.decode(errors='ignore')}")
except httpx.TimeoutException:
    print("Timed out")
```

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

### Generate OpenAPI client on Linux

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/CONTRIBUTING.md

Run the stub generation script on a Linux-based OS.

```bash
bash scripts/generate_stub.sh
```

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

### __aenter__

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Enters an async context manager for the underlying httpx.AsyncClient, returning the AuthenticatedClient instance. Cannot be entered twice.

```APIDOC
## __aenter__

### Description
Enters an async context manager for the underlying httpx.AsyncClient, returning the AuthenticatedClient instance. Cannot be entered twice.

### Method
__aenter__

### Signature
```python
async def __aenter__(self) -> "AuthenticatedClient":
```

### Returns
- **AuthenticatedClient** - The client instance for use within the async context manager.

```

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

### __str__ method

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Returns a string representation of the client, showing the auth object.

```python
def __str__(self) -> str:
    return f"Client for {self.auth}"
```

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

### Configure verify_ssl for VizQLDataServiceClient

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/configuration.md

Shows three ways to configure SSL verification for the VizQLDataServiceClient: disabling it, using a custom CA bundle path, or providing an ssl.SSLContext for mutual TLS. The default is True (system CA bundle); False is for development/testing only.

```python
import ssl
from vizql_data_service_py import VizQLDataServiceClient

client = VizQLDataServiceClient(url, server, auth, verify_ssl=False)
client = VizQLDataServiceClient(url, server, auth, verify_ssl="/path/to/ca-bundle.pem")

ctx = ssl.create_default_context()
ctx.load_verify_locations(cafile="/path/to/ca-bundle.pem")
client = VizQLDataServiceClient(url, server, auth, verify_ssl=ctx)
```

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

### Context manager __enter__ and __exit__ for AuthenticatedClient

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Defines synchronous context manager methods that delegate to the internal httpx.Client. Cannot enter twice per httpx docs.

```python
def __enter__(self) -> "AuthenticatedClient":
    """Enter a context manager for self.client—you cannot enter twice (see httpx docs)"""
    self.get_httpx_client().__enter__()
    return self

def __exit__(self, *args: Any, **kwargs: Any) -> None:
    """Exit a context manager for internal httpx.Client (see httpx docs)"""
    self.get_httpx_client().__exit__(*args, **kwargs)
```

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

### VizQLDataServiceClient.__str__

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Returns a string representation of the client.

```APIDOC
## VizQLDataServiceClient.__str__

### Description
Returns a string representation of the client.

### Method
Method

### Signature
```python
def __str__(self) -> str:
```

### Returns
- **str** - A string representation of the client.
```

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

### Architecture diagram: VizQLDataServiceClient and endpoint flow

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/README.md

Shows the structure of the public facade and how endpoint functions use the client. The diagram lists the client's attributes and the flow for sync and async requests.

```text
VizQLDataServiceClient            (public facade; src/api/client.py)
 ├─ url, server, auth             (TSC objects; X-Tableau-Auth token from server.auth_token)
 ├─ verify_ssl, global_session_header, x_session_id
 └─ .client → AuthenticatedClient (attrs; lazily owns httpx.Client + httpx.AsyncClient)
       └─ base_url = format_server_url(url, "/api/v1/vizql-data-service")

read_metadata / query_datasource / get_datasource_model
 ├─ _get_kwargs(body)             → POST <path>, json=model_dump(exclude_none=True)
 ├─ client.client.get_httpx_client().request(**kwargs)     [sync / sync_detailed]
 ├─ client.client.get_async_httpx_client().request(**kwargs) [asyncio / asyncio_detailed]
 ├─ _build_response(...)          → Response[T]   (src/api/types.py)
 └─ _parse_response(...)          → parsed model on 200 | None | UnexpectedStatus
```

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

### Async context manager __aenter__ and __aexit__

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Defines asynchronous context manager methods that delegate to the underlying httpx.AsyncClient. Cannot enter twice per httpx docs.

```python
async def __aenter__(self) -> "AuthenticatedClient":
    """Enter a context manager for underlying httpx.AsyncClient—you cannot enter twice (see httpx docs)"""
    await self.get_async_httpx_client().__aenter__()
    return self

async def __aexit__(self, *args: Any, **kwargs: Any) -> None:
    """Exit a context manager for underlying httpx.AsyncClient (see httpx docs)"""
    await self.get_async_httpx_client().__aexit__(*args, **kwargs)
```

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

### get_async_httpx_client method

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Returns the underlying httpx.AsyncClient, constructing a new one if not previously set. Uses current headers, cookies, timeout, SSL verification, and follow_redirects settings.

```python
def get_async_httpx_client(self) -> httpx.AsyncClient:
    """Get the underlying httpx.AsyncClient, constructing a new one if not previously set"""
    if self._async_client is None:
        self._headers[self.auth_header_name] = (
            f"{self.prefix} {self.token}" if self.prefix else self.token
        )
        self._update_user_agent()
        self._async_client = httpx.AsyncClient(
            base_url=self._base_url,
            cookies=self._cookies,
            headers=self._headers,
            timeout=self._timeout,
            verify=self._verify_ssl,
            follow_redirects=self._follow_redirects,
            **self._httpx_args,
        )
    return self._async_client
```

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

### Module __all__ for query_datasource

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/query_datasource.md

Defines the public API of the module, listing the exported functions: sync, sync_detailed, asyncio, and asyncio_detailed.

```python
__all__ = [
    "sync",
    "sync_detailed",
    "asyncio",
    "asyncio_detailed",
]
```

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

### get_httpx_client method

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Returns the underlying httpx.Client, creating it on first call if it does not exist.

```python
def get_httpx_client(self) -> httpx.Client:
    """Get the underlying httpx.Client."""
    return self.client.get_httpx_client()
```

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

### Asynchronous call to get_datasource_model

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/get_datasource_model.md

Shows how to use the asyncio wrapper with asyncio.run. It calls get_datasource_model.asyncio with a client and request.

```python
import asyncio

async def main():
    return await get_datasource_model.asyncio(
        client=client, body=GetDatasourceModelRequest(datasource=datasource)
    )

model = asyncio.run(main())
```

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

### POST /list-supported-functions

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/endpoints.md

Lists supported functions. Requires X-Tableau-Auth authentication and returns an array of SupportedFunction objects.

```APIDOC
## POST /list-supported-functions

### Description
Lists supported functions.

### Method
POST

### Endpoint
/list-supported-functions

### Parameters
#### Headers
- **X-Tableau-Auth** (string) - Required - Authentication token.

### Request Example
No request body documented.

### Response
#### Success Response (200)
- **SupportedFunction[]** (array) - Array of supported functions.

#### Response Example
[]

```

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

### get_httpx_client method

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Returns the underlying httpx.Client, constructing a new one if not previously set. The new client is configured with the base URL, cookies, headers, timeout, SSL verification, redirects, and additional httpx args, and includes the Authorization header.

```python
def get_httpx_client(self) -> httpx.Client:
    """Get the underlying httpx.Client, constructing a new one if not previously set"""
    if self._client is None:
        self._headers[self.auth_header_name] = (
            f"{self.prefix} {self.token}" if self.prefix else self.token
        )
        self._update_user_agent()
        self._client = httpx.Client(
            base_url=self._base_url,
            cookies=self._cookies,
            headers=self._headers,
            timeout=self._timeout,
            verify=self._verify_ssl,
            follow_redirects=self._follow_redirects,
            **self._httpx_args,
        )
    return self._client
```

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

### Asynchronous query with asyncio_detailed

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/query_datasource.md

Shows how to run an asynchronous query using query_datasource.asyncio_detailed within an asyncio event loop. The response's parsed data is returned.

```python
import asyncio

async def main():
    response = await query_datasource.asyncio_detailed(client=client, body=request)
    return response.parsed

data = asyncio.run(main())
```

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

### get_async_httpx_client method

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Returns the underlying httpx.AsyncClient.

```python
def get_async_httpx_client(self) -> httpx.AsyncClient:
    """Get the underlying httpx.AsyncClient."""
    return self.client.get_async_httpx_client()
```

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

### VizQLDataServiceClient.client

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Property that returns the authenticated client instance.

```APIDOC
## VizQLDataServiceClient.client

### Description
Get the authenticated client.

### Method
Property getter

### Signature
```python
@property
def client(self) -> AuthenticatedClient:
```

### Returns
- **AuthenticatedClient** - The authenticated client instance.

### Raises
- **RuntimeError** - If not signed in.
```

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

### Detailed response with options and error handling

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/get_datasource_model.md

Demonstrates sync_detailed with QueryOptions(bypassMetadataCache=True) and error handling for UnexpectedStatus and httpx.TimeoutException. It sets client.raise_on_unexpected_status = True.

```python
from vizql_data_service_py import GetDatasourceModelRequest, QueryOptions, get_datasource_model
from vizql_data_service_py.api.errors import UnexpectedStatus
import httpx

request = GetDatasourceModelRequest(
    datasource=Datasource(datasourceLuid="<luid>"),
    options=QueryOptions(bypassMetadataCache=True),
)
client.raise_on_unexpected_status = True
try:
    response, status, headers = get_datasource_model.sync_detailed(client=client, body=request)
    print(status, headers, response.parsed)
except UnexpectedStatus as e:
    print(f"Unexpected status {e.status_code}: {e.content.decode(errors='ignore')}")
except httpx.TimeoutException:
    print("Timed out")
```

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

### query_datasource.asyncio_detailed

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/README.md

Asynchronously calls the POST /query-datasource endpoint and returns a Response object with status and headers.

```APIDOC
## POST /query-datasource

### Description
Asynchronously calls the POST /query-datasource endpoint and returns a Response object with status and headers.

### Method
POST

### Endpoint
/query-datasource

### Parameters
#### Request Body
- **body** (QueryRequest) - Required - The request model for querying a datasource.

### Request Example
```python
from vizql_data_service_py import query_datasource, QueryRequest

# resp, status, headers = await query_datasource.asyncio_detailed(client=client, body=request)
```

### Response
#### Success Response (200)
- **Response** - A Response object containing the parsed model, status code, and headers.

#### Response Example
```python
# resp, status, headers = await query_datasource.asyncio_detailed(client=client, body=request)
```
```

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

### VizQLDataServiceClient.get_httpx_client

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Returns the underlying httpx.Client used by the authenticated client.

```APIDOC
## VizQLDataServiceClient.get_httpx_client

### Description
Get the underlying httpx.Client.

### Method
Method

### Signature
```python
def get_httpx_client(self) -> httpx.Client:
```

### Returns
- **httpx.Client** - The underlying httpx.Client instance.
```

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

### Import required modules from vizql_data_service_py

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/README.md

Imports the necessary classes and functions for using the VizQL Data Service Python SDK.

```python
from vizql_data_service_py import (
    ReadMetadataRequest,
    QueryRequest,
    Datasource,
    Connection,
    VizQLDataServiceClient,
    read_metadata,
    query_datasource,
    DimensionField,
    MeasureField,
    Function,
    Query
)
```

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

### asyncio_detailed

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/query_datasource.md

Asynchronously queries a datasource and returns a full Response object, awaiting the underlying HTTP client request.

```APIDOC
## asyncio_detailed

### Description
Asynchronously queries a datasource and returns a full Response object, awaiting the underlying HTTP client request.

### Method
asyncio_detailed

### Endpoint
src/api/query_datasource.py:118

### Parameters
- **client** (VizQLDataServiceClient) - Required - Signed-in client
- **body** (QueryRequest) - Required - The query request parameters (`datasource`, `query`, optional `options`)

### Returns
- **Response[QueryOutput]** - Response object carrying `status_code: HTTPStatus`, `content: bytes`, `headers`, and `parsed: Optional[QueryOutput]`

### Throws
- **errors.UnexpectedStatus** - Undocumented status code and `Client.raise_on_unexpected_status` is `True`
- **httpx.TimeoutException** - Request takes longer than `Client.timeout`
```

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

### __aexit__

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/client.md

Exits the async context manager for the underlying httpx.AsyncClient, cleaning up resources.

```APIDOC
## __aexit__

### Description
Exits the async context manager for the underlying httpx.AsyncClient, cleaning up resources.

### Method
__aexit__

### Signature
```python
async def __aexit__(self, *args: Any, **kwargs: Any) -> None:
```

### Parameters
- **args** (Any) - Optional - Positional arguments passed to the underlying client's exit method.
- **kwargs** (Any) - Optional - Keyword arguments passed to the underlying client's exit method.

### Returns
- **None**

```

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

### Call API with sync and sync_detailed methods

Source: https://github.com/tableau/vizql-data-service/blob/main/python_sdk/README.md

Shows two ways to call read_metadata: the simple sync method returns only response data, while sync_detailed returns a tuple of response data, status code, and headers. Both methods work for read_metadata and query_datasource.

```python
# Simple way - just get the response data
response = read_metadata.sync(client=client, body=read_metadata_request)

# Detailed way - get response data, status code and headers
response, status, headers = read_metadata.sync_detailed(client=client, body=read_metadata_request)
```

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

### asyncio

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/query_datasource.md

Convenience async wrapper around asyncio_detailed that returns the parsed QueryOutput directly.

```APIDOC
## asyncio

### Description
Convenience async wrapper around `asyncio_detailed(...).parsed`; returns `Optional[QueryOutput]`.

### Method
asyncio

### Endpoint
src/api/query_datasource.py:151

### Parameters
- **client** (VizQLDataServiceClient) - Required - Signed-in client
- **body** (QueryRequest) - Required - The query request parameters (`datasource`, `query`, optional `options`)

### Returns
- **Optional[QueryOutput]** - Parsed query output, or `None` if not available.
```

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

### query_datasource.asyncio

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/README.md

Asynchronously calls the POST /query-datasource endpoint with a QueryRequest body and returns an optional QueryOutput.

```APIDOC
## POST /query-datasource

### Description
Asynchronously calls the POST /query-datasource endpoint with a QueryRequest body and returns an optional QueryOutput.

### Method
POST

### Endpoint
/query-datasource

### Parameters
#### Request Body
- **body** (QueryRequest) - Required - The request model for querying a datasource.

### Request Example
```python
from vizql_data_service_py import query_datasource, QueryRequest

# await query_datasource.asyncio(client=client, body=request)
```

### Response
#### Success Response (200)
- **QueryOutput** - The parsed query output model.

#### Response Example
```python
# data is Optional[QueryOutput]
```
```

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

### get_datasource_model.asyncio function signature

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/get_datasource_model.md

Defines the async wrapper for get_datasource_model. It returns Optional[DatasourceModelOutput] and is a convenience wrapper around asyncio_detailed(...).parsed.

```python
async def asyncio(
    *,
    client: VizQLDataServiceClient,
    body: GetDatasourceModelRequest,
) -> Optional[DatasourceModelOutput]:
```

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

### to_tuple method signature

Source: https://github.com/tableau/vizql-data-service/blob/main/_autodocs/api-reference/types.md

Returns the `(file_name, payload, mime_type)` tuple for `httpx` multipart/form-data requests.

```python
def to_tuple(self) -> FileJsonType:
```
Tokens:
Raw