| Name | vizql-data-service-py JSON |
| Version |
1.1.2
JSON |
| download |
| home_page | None |
| Summary | A Python client library for interacting with the VizQL Data Service API |
| upload_time | 2025-07-31 23:15:33 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
vizqldataservice
tableau
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# VizQL Data Service Python SDK
[](https://www.tableau.com/support-levels-it-and-developer-tools)
[](https://raw.githubusercontent.com/tableau/VizQL-Data-Service/refs/heads/main/python_sdk/LICENSE.txt)
[](https://github.com/tableau/VizQL-Data-Service/actions/workflows/push.yml)
[](https://pypi.org/project/vizql-data-service-py/)
[](https://www.python.org/downloads/)
[](https://raw.githubusercontent.com/tableau/VizQL-Data-Service/refs/heads/main/VizQLDataServiceOpenAPISchema.json)
[](https://pypi.org/project/vizql-data-service-py/)
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](https://help.tableau.com/current/api/vizql-data-service/en-us/index.html)
- [VizQL Data Service API Reference](https://help.tableau.com/current/api/vizql-data-service/en-us/reference/index.html)
- [VizQL Data Service Postman collection](https://www.postman.com/salesforce-developers/salesforce-developers/folder/jdy4gr3/vizql-data-service-queries)
- [VizQL Data Service OpenAPI Schema](https://github.com/tableau/VizQL-Data-Service/blob/main/VizQLDataServiceOpenAPISchema.json)
## Version Support
The VizQL Data Service Python SDK supports different versions of the VizQLDataServiceOpenAPISchema. Past versions of the schema corresponding to past releases of Tableau can be found in the release branches with name `release-[year].[quarter]`. As an example, `release-20251.0` contains the VizQLDataServiceOpenAPISchema corresponding to 20251.0 (as a special note, the 20251.0 release uniquely does not have Python SDK support). `release-20252.0` contains the schema corresponding to 20252.0 and the Python SDK that supports 20252.0. The main branch will always contain the most recent version of the VizQLDataServiceOpenAPISchema as well as the Python SDK that supports it.
### Schema Versions
[20251.0](https://github.com/tableau/VizQL-Data-Service/blob/release-20251.0/VizQLDataServiceOpenAPISchema.json)
[20252.0](https://github.com/tableau/VizQL-Data-Service/blob/main/VizQLDataServiceOpenAPISchema.json)
### Python SDK Versions
None for 20251.0
[20252.0](https://github.com/tableau/VizQL-Data-Service/tree/main/python_sdk)
## 🔧 Installation
```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
```
## 🚀 Quick Start
### Importing Required Modules
```python
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](https://tableau.github.io/server-client-python/docs/sign-in-out). For JWT authentication setup, see the [Configure Connected Apps with Direct Trust](https://help.tableau.com/current/online/en-us/connected_apps_direct.htm) 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
```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>"
)
]
)
```
### Sign in, Read Metadata and Query Data Sources
```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}")
```
### SSL Configuration
If you encounter SSL certificate verification errors (common in corporate environments with VPNs or custom certificates), you can configure SSL verification:
**Options:**
- `verify_ssl=True` (default): Use system's default CA bundle for SSL verification
- `verify_ssl=False`: Disable SSL verification entirely
- `verify_ssl="/path/to/ca-bundle.pem"`: Use custom CA bundle file
- `verify_ssl=ssl_context`: Use custom SSL context for advanced configurations
```python
# Disable SSL verification (for development/testing only)
client = VizQLDataServiceClient(server_url, server, tableau_auth, verify_ssl=False)
# Use custom CA bundle
client = VizQLDataServiceClient(server_url, server, tableau_auth, verify_ssl="/path/to/ca-bundle.pem")
# Use custom SSL context
import ssl
ssl_context = ssl.create_default_context()
# Load a custom CA bundle (e.g., for self-signed certificates)
ssl_context.load_verify_locations(cafile="/path/to/ca-bundle.pem")
# Or load client certificates for mutual TLS authentication
# ssl_context.load_cert_chain(certfile="path/to/your/client.pem", keyfile="path/to/your/client.key")
client = VizQLDataServiceClient(server_url, server, tableau_auth, verify_ssl=ssl_context)
```
> **Security Note**: Only disable SSL verification (`verify_ssl=False`) in development or testing environments. For production, use proper SSL certificates or custom CA bundles.
### API Methods
The SDK provides two ways to make API calls:
```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)
```
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](https://github.com/tableau/VizQL-Data-Service/blob/main/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](https://github.com/tableau/VizQL-Data-Service/tree/main/python_sdk/src/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](https://github.com/tableau/VizQL-Data-Service/blob/main/python_sdk/CONTRIBUTING.md) Guide. A list of all our contributors to date is in [CONTRIBUTORS.md](https://github.com/tableau/VizQL-Data-Service/blob/main/python_sdk/CONTRIBUTORS.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "vizql-data-service-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Tableau <github@tableau.com>",
"keywords": "vizqldataservice, tableau",
"author": null,
"author_email": "Tableau <github@tableau.com>",
"download_url": "https://files.pythonhosted.org/packages/cc/e5/24a643fed5d9292be59d38c957e64a85de9d3d4283709cd0524464d41eae/vizql_data_service_py-1.1.2.tar.gz",
"platform": null,
"description": "# VizQL Data Service Python SDK \n\n[](https://www.tableau.com/support-levels-it-and-developer-tools)\n[](https://raw.githubusercontent.com/tableau/VizQL-Data-Service/refs/heads/main/python_sdk/LICENSE.txt)\n[](https://github.com/tableau/VizQL-Data-Service/actions/workflows/push.yml)\n[](https://pypi.org/project/vizql-data-service-py/)\n[](https://www.python.org/downloads/)\n[](https://raw.githubusercontent.com/tableau/VizQL-Data-Service/refs/heads/main/VizQLDataServiceOpenAPISchema.json)\n[](https://pypi.org/project/vizql-data-service-py/)\n\nThe 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.\n\nConsider reading VizQL Data Service in the following order:\n- [VizQL Data Service help documentation](https://help.tableau.com/current/api/vizql-data-service/en-us/index.html)\n- [VizQL Data Service API Reference](https://help.tableau.com/current/api/vizql-data-service/en-us/reference/index.html)\n- [VizQL Data Service Postman collection](https://www.postman.com/salesforce-developers/salesforce-developers/folder/jdy4gr3/vizql-data-service-queries)\n- [VizQL Data Service OpenAPI Schema](https://github.com/tableau/VizQL-Data-Service/blob/main/VizQLDataServiceOpenAPISchema.json)\n\n## Version Support\nThe VizQL Data Service Python SDK supports different versions of the VizQLDataServiceOpenAPISchema. Past versions of the schema corresponding to past releases of Tableau can be found in the release branches with name `release-[year].[quarter]`. As an example, `release-20251.0` contains the VizQLDataServiceOpenAPISchema corresponding to 20251.0 (as a special note, the 20251.0 release uniquely does not have Python SDK support). `release-20252.0` contains the schema corresponding to 20252.0 and the Python SDK that supports 20252.0. The main branch will always contain the most recent version of the VizQLDataServiceOpenAPISchema as well as the Python SDK that supports it.\n\n### Schema Versions\n[20251.0](https://github.com/tableau/VizQL-Data-Service/blob/release-20251.0/VizQLDataServiceOpenAPISchema.json)\n\n[20252.0](https://github.com/tableau/VizQL-Data-Service/blob/main/VizQLDataServiceOpenAPISchema.json)\n\n### Python SDK Versions\nNone for 20251.0\n\n[20252.0](https://github.com/tableau/VizQL-Data-Service/tree/main/python_sdk)\n\n## \ud83d\udd27 Installation\n```bash\npython -m venv --system-site-packages venv # Optional command: set up a python virtual environment before installing the vizql_data_service_py package\nsource venv/bin/activate # A continuation of the first command for Unix/MacOS users. This activates the virtual environment for Unix/MacOS\nvenv\\Scripts\\activate # A continuation of the first command for Windows users. This activates the virtual environment for Windows\n\npip install vizql-data-service-py\n```\n\n## \ud83d\ude80 Quick Start\n\n### Importing Required Modules\n```python\nfrom vizql_data_service_py import (\n ReadMetadataRequest,\n QueryRequest,\n Datasource,\n Connection,\n VizQLDataServiceClient,\n read_metadata,\n query_datasource,\n DimensionField,\n MeasureField,\n Function,\n Query\n)\n```\n\n### Setting Up Server Connection\nTo create Server and Auth instances, please refer to the [Tableau Server Client (Python) Authentication Guide](https://tableau.github.io/server-client-python/docs/sign-in-out). For JWT authentication setup, see the [Configure Connected Apps with Direct Trust](https://help.tableau.com/current/online/en-us/connected_apps_direct.htm) documentation.\n\n> **Note**: Authentication methods vary between Tableau Cloud and On-premises deployments:\n> - Tableau Cloud: Supports JWT and Personal Access Token (PAT) authentication\n> - Tableau On-premises: Supports JWT, PAT, and username/password authentication\n\n### Configuring Data Source\n```python\n# Create a data source instance with optional connection parameters\ndatasource = Datasource(\n datasourceLuid=\"<datasource-luid>\",\n # Optional: Configure connections for external data sources\n connections=[\n Connection(\n connectionUsername=\"<connection-username>\",\n connectionPassword=\"<connection-password>\"\n )\n ]\n)\n```\n\n### Sign in, Read Metadata and Query Data Sources\n```python\nimport tableauserverclient as TSC\n\n# Choose one of these auth mechanisms\ntableau_auth = TSC.PersonalAccessTokenAuth('TOKEN_NAME', 'TOKEN_VALUE', 'SITENAME')\n# tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', 'SITENAME')\n# tableau_auth = TSC.JWTAuth('JWT', 'SITENAME')\n\nserver_url = 'https://SERVER_URL'\nserver = TSC.Server(server_url)\n\nwith server.auth.sign_in(tableau_auth):\n client = VizQLDataServiceClient(server_url, server, tableau_auth)\n # Define your query fields\n query = Query(\n # Example: sample Superstore data source\n # Aggregate SUM(Sales) by Category\n fields=[\n DimensionField(fieldCaption=\"Category\"),\n MeasureField(fieldCaption=\"Sales\", function=Function.SUM),\n ]\n )\n # Step 1: Read metadata\n read_metadata_request = ReadMetadataRequest(\n datasource=datasource\n )\n read_metadata_response = read_metadata.sync(\n client=client, body=read_metadata_request\n )\n print(f\"Read Metadata Response: {read_metadata_response}\")\n\n # Step 2: Execute query\n query_request = QueryRequest(\n query=query, datasource=datasource\n )\n query_response = query_datasource.sync(\n client=client, body=query_request\n )\n print(f\"Query Datasource Response: {query_response}\")\n```\n\n### SSL Configuration\n\nIf you encounter SSL certificate verification errors (common in corporate environments with VPNs or custom certificates), you can configure SSL verification:\n\n**Options:**\n- `verify_ssl=True` (default): Use system's default CA bundle for SSL verification\n- `verify_ssl=False`: Disable SSL verification entirely \n- `verify_ssl=\"/path/to/ca-bundle.pem\"`: Use custom CA bundle file\n- `verify_ssl=ssl_context`: Use custom SSL context for advanced configurations\n\n```python\n# Disable SSL verification (for development/testing only)\nclient = VizQLDataServiceClient(server_url, server, tableau_auth, verify_ssl=False)\n\n# Use custom CA bundle\nclient = VizQLDataServiceClient(server_url, server, tableau_auth, verify_ssl=\"/path/to/ca-bundle.pem\")\n\n# Use custom SSL context\nimport ssl\nssl_context = ssl.create_default_context() \n# Load a custom CA bundle (e.g., for self-signed certificates)\nssl_context.load_verify_locations(cafile=\"/path/to/ca-bundle.pem\")\n# Or load client certificates for mutual TLS authentication\n# ssl_context.load_cert_chain(certfile=\"path/to/your/client.pem\", keyfile=\"path/to/your/client.key\")\nclient = VizQLDataServiceClient(server_url, server, tableau_auth, verify_ssl=ssl_context)\n```\n\n> **Security Note**: Only disable SSL verification (`verify_ssl=False`) in development or testing environments. For production, use proper SSL certificates or custom CA bundles.\n\n### API Methods\nThe SDK provides two ways to make API calls:\n\n```python\n# Simple way - just get the response data\nresponse = read_metadata.sync(client=client, body=read_metadata_request)\n\n# Detailed way - get response data, status code and headers\nresponse, status, headers = read_metadata.sync_detailed(client=client, body=read_metadata_request)\n```\n\nBoth methods work for `read_metadata` and `query_datasource`. Use `sync_detailed()` when you need HTTP response details like status code and headers.\n\nThis 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](https://github.com/tableau/VizQL-Data-Service/blob/main/VizQLDataServiceOpenAPISchema.json) file. \n\n> **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:\n> - Type safety and validation at compile time\n> - Better IDE support with autocompletion\n> - Consistent request structure\n> - Easier maintenance and debugging\n\nFor comprehensive examples demonstrating various query patterns and filter combinations, please check the [examples](https://github.com/tableau/VizQL-Data-Service/tree/main/python_sdk/src/examples) directory.\n\n## \ud83d\udcd8 Supported Features\n- \u2705 Read metadata of Tableau published datasources\n- \u2705 Query published datasources with selectable fields and queries supports various filters\n- \u2705 Synchronous and Asynchronous Python client support\n- \u2705 Authentication using Tableau username/password, JWT or PAT\n- \u2705 Works with both Tableau Cloud and Tableau Server (on-prem)\n- \u2705 OpenAPI schema generated Python Pydantic v2 models for type-safe API interactions\n\n## \ud83d\udee0\ufe0f Requirements\n- Python 3.9+\n- pip 20.0+\n- Tableau Server 2025.1+ or Tableau Cloud\n\n## \ud83e\udd1d Contributing\nTo contribute, see our [CONTRIBUTING.md](https://github.com/tableau/VizQL-Data-Service/blob/main/python_sdk/CONTRIBUTING.md) Guide. A list of all our contributors to date is in [CONTRIBUTORS.md](https://github.com/tableau/VizQL-Data-Service/blob/main/python_sdk/CONTRIBUTORS.md).\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python client library for interacting with the VizQL Data Service API",
"version": "1.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/tableau/VizQL-Data-Service/issues",
"Homepage": "https://github.com/tableau/VizQL-Data-Service/python_sdk",
"Source Code": "https://github.com/tableau/VizQL-Data-Service/python_sdk"
},
"split_keywords": [
"vizqldataservice",
" tableau"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a700b49ca6d6923400d63d1a9032b8aa906121b3aa83879d93e4a78e3dfdfef7",
"md5": "9e155c545e2a42e52d4c4a17376979e3",
"sha256": "b2c0fe2dc54abf0dd43088fdb366fbd254a76a8815cec02f87e760f3eecc77a4"
},
"downloads": -1,
"filename": "vizql_data_service_py-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e155c545e2a42e52d4c4a17376979e3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 28186,
"upload_time": "2025-07-31T23:15:32",
"upload_time_iso_8601": "2025-07-31T23:15:32.107063Z",
"url": "https://files.pythonhosted.org/packages/a7/00/b49ca6d6923400d63d1a9032b8aa906121b3aa83879d93e4a78e3dfdfef7/vizql_data_service_py-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cce524a643fed5d9292be59d38c957e64a85de9d3d4283709cd0524464d41eae",
"md5": "e15c5b1a9c38dc9c39185e733ff60573",
"sha256": "5ea31cb084044c7499adbfe20fa00792230661e0751adbf080acddde5894468b"
},
"downloads": -1,
"filename": "vizql_data_service_py-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "e15c5b1a9c38dc9c39185e733ff60573",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 25658,
"upload_time": "2025-07-31T23:15:33",
"upload_time_iso_8601": "2025-07-31T23:15:33.536138Z",
"url": "https://files.pythonhosted.org/packages/cc/e5/24a643fed5d9292be59d38c957e64a85de9d3d4283709cd0524464d41eae/vizql_data_service_py-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 23:15:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tableau",
"github_project": "VizQL-Data-Service",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "vizql-data-service-py"
}
