vizql-data-service-py 1.1.0

A Python client library for interacting with the VizQL Data Service API

VizQL Data Service Python SDK

The VizQL Data Service Python SDK is a lightweight client library that enables interaction with Tableau's VizQL Data Service APIs. It supports both cloud and on-premises deployments, offering both synchronous and asynchronous methods for querying the VizQL Data Service APIs.

Consider reading VizQL Data Service in the following order:

• VizQL Data Service help documentation
• VizQL Data Service API Reference
• VizQL Data Service Postman collection
• VizQL Data Service OpenAPI Schema

🔧 Installation

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

🚀 Quick Start

Importing Required Modules

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

Setting Up Server Connection

To create Server and Auth instances, please refer to the Tableau Server Client (Python) Authentication Guide. For JWT authentication setup, see the Configure Connected Apps with Direct Trust documentation.

Note: Authentication methods vary between Tableau Cloud and On-premises deployments:

• Tableau Cloud: Supports JWT and Personal Access Token (PAT) authentication
• Tableau On-premises: Supports JWT, PAT, and username/password authentication

Configuring Data Source

# 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>"
        )
    ]
)

Sign in, Read Metadata and Query Data Sources

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}")

API Methods

The SDK provides two ways to make API calls:

# 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)

Both methods work for read_metadata and query_datasource. Use sync_detailed() when you need HTTP response details like status code and headers.

This SDK is built using datamodel-codegen to generate all VizQL Data Service models based on Pydantic v2. For detailed API documentation and model specifications, please refer to the VizQLDataServiceOpenAPISchema.json file.

Note: While raw JSON requests are supported, we strongly recommend using the provided Python pydantic v2 objects to construct requests. This approach offers several advantages:

• Type safety and validation at compile time
• Better IDE support with autocompletion
• Consistent request structure
• Easier maintenance and debugging

For comprehensive examples demonstrating various query patterns and filter combinations, please check the examples directory.

📘 Supported Features

• ✅ Read metadata of Tableau published datasources
• ✅ Query published datasources with selectable fields and queries supports various filters
• ✅ Synchronous and Asynchronous Python client support
• ✅ Authentication using Tableau username/password, JWT or PAT
• ✅ Works with both Tableau Cloud and Tableau Server (on-prem)
• ✅ OpenAPI schema generated Python Pydantic v2 models for type-safe API interactions

🛠️ Requirements

• Python 3.9+
• pip 20.0+
• Tableau Server 2025.1+ or Tableau Cloud

🤝 Contributing

To contribute, see our CONTRIBUTING.md Guide. A list of all our contributors to date is in CONTRIBUTORS.md.