> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/interfaces/apis/data-product-apis/sdks/python-sdk.md).

# Python SDK

A typed Python client for integrating applications with Data Product APIs.

Connect once, then pull data, save views, and check on pipeline health using plain Python. No HTTP requests, no manual JSON parsing. You get back real Python objects with autocomplete, not raw dicts you have to guess the shape of.

Built on [uplink](https://uplink.readthedocs.io/) and [Pydantic v2](https://docs.pydantic.dev/).

<details>

<summary>On this page</summary>

* [Install](#install)
* [Connect](#connect)
* [See what's inside a data product](#see-whats-inside-a-data-product)
* [Run a query and get your data](#run-a-query-and-get-your-data)
* [Save a query so you don't have to rewrite it](#save-a-query-so-you-dont-have-to-rewrite-it)
* [Connect from Power BI or Tableau](#connect-from-power-bi-or-tableau)
* [Know whether you can trust the data](#know-whether-you-can-trust-the-data)
* [See what's been running behind the scenes](#see-whats-been-running-behind-the-scenes)
* [Stay in the loop](#stay-in-the-loop)
* [Handling errors](#handling-errors)
* [Full method reference](#full-method-reference)
* [Cheat sheet](#cheat-sheet)

</details>

### Install

{% file src="/files/vlvFYSSrXPe5Kgs0CCwV" %}

```bash
pip install vulcan_sdk-0.228.1.32-py3-none-any.whl
```

Requires Python 3.9+. Dependencies (`pydantic`, `requests`, `uplink`) are installed automatically with the SDK.

### Connect

```python
from vulcan_sdk import VulcanClient

client = VulcanClient(
    fqdn="example.dataos.io",       # your DataOS instance
    dp_name="clothing_retail",      # the data product you're connecting to
    access_token="<your-dataos-api-token>",
    tenant="public",
)
```

That's it. Every example below just reuses this `client`. The SDK builds the base URL for you:

```
https://{fqdn}/vulcan/tenants/{tenant}/data-products/{tenant}-{dp_name}/api/v1
```

`Accept: application/json` is set on every request so the server always returns JSON (not Parquet).

### See what's inside a data product

Before you query anything, it helps to know what models, columns, and metrics you actually have to work with:

```python
schema = client.metadata.get_semantic()
for model in schema.models:
    print(model["name"], [c["name"] for c in model.get("columns", [])])
```

Need the full catalog instead (product info, lineage graph, gateway config, per-model freshness)? Use `client.metadata.get()`.

### Run a query and get your data

There are two ways to ask for data. Use whichever one feels natural to you.

**Measures and dimensions, if you think in those terms:**

```python
stmt = client.query.submit_semantic_rest(
    query={
        "measures": ["orders.total_revenue"],
        "dimensions": ["orders.ORDERSTATUS"],
        "limit": 10,
    }
)
```

**Or just write SQL:**

```python
stmt = client.query.submit_semantic_sql(
    "SELECT ORDERKEY, ORDERSTATUS FROM orders LIMIT 10"
)
```

Need raw SQL against physical tables instead of the semantic layer? Use `client.query.submit_statement(sql)`.

Either way, you get a response back immediately with a job id. The query itself runs in the background, so you need to wait for it to finish before you can grab the results:

```python
import time

while stmt.status.upper() not in {"SUCCESS", "SUCCEEDED", "FAILED", "CANCELLED"}:
    time.sleep(2)
    stmt = client.query.get_statement(stmt.id)

result = client.query.get_statement_result(stmt.id)
print(result.cols)
for row in result.rows:
    print(row)
```

Tip: if you'd rather work with a DataFrame, this takes one line:

```python
import pandas as pd
df = pd.DataFrame(result.rows, columns=result.cols)
```

If you'd rather write GraphQL, `submit_semantic_rest` takes it directly via `graphql_body`:

```python
stmt = client.query.submit_semantic_rest(
    query={},
    graphql_body="query { table(limit: 10) { orders { ORDERKEY ORDERSTATUS } } }",
)
```

Need the generated warehouse SQL instead of executing the query? See the [transpile-only recipe](https://v2.dataos.info/consume/recipes/transpile-semantic-queries-to-native-warehouse-sql). Need to page through more than 50,000 rows? See the [pagination recipe](https://v2.dataos.info/consume/recipes/retrieve-large-result-sets-with-pagination).

#### Querying a named metric

If the data product has metrics already defined, you can just ask for one by name:

```python
data = client.query.get_metric("CUSTOMER_GROWTH", granularity="month", limit=100)
```

If you need filters on top of that, use `post_metric` instead and poll for the result the same way you would for any other query:

```python
stmt = client.query.post_metric(
    "CUSTOMER_GROWTH",
    body={"dimensions": ["ts"], "granularity": "month", "filters": []},
)
```

### Save a query so you don't have to rewrite it

Once a query has finished running, you can save it as a **perspective**: basically a named, shareable view that lives at its own slug:

```python
from vulcan_sdk import PerspectiveCreateRequest

new_view = client.perspectives.create(
    "top-customers",
    PerspectiveCreateRequest(name="Top Customers", statement_id=stmt.id, is_public=True),
)
```

`request` must be an actual `PerspectiveCreateRequest` / `PerspectiveUpdateRequest` instance (import both from `vulcan_sdk`); a plain dict raises `AttributeError`.

From then on you can just fetch it whenever you need it, no need to resubmit the query:

```python
result = client.perspectives.get_result("top-customers")
```

To see what's already been saved:

```python
listing = client.perspectives.list()
for p in listing.items:
    print(p.slug, p.name, p.owner)
```

```python
from vulcan_sdk import PerspectiveUpdateRequest

client.perspectives.update("top-customers", PerspectiveUpdateRequest(description="Q3 view"))
client.perspectives.delete("top-customers")
```

### Connect from Power BI or Tableau

If you'd rather work in a BI tool, you can grab the connection files and open them there instead:

```python
with open("powerbi.zip", "wb") as f:
    f.write(client.metadata.download_powerbi())

with open("connection.tds", "wb") as f:
    f.write(client.metadata.download_tableau())
```

{% hint style="info" %}
These are only populated for production deployments, so don't expect much from a dev or staging environment.
{% endhint %}

### Know whether you can trust the data

```python
summary = client.dq.get_summary()
print(summary.checks_count, summary.summary)
```

If something looks off, you can dig into the specific rule behind it:

```python
rules = client.dq.list_rules(model="orders")
for r in rules.rules:
    print(r.name, r.dimension, r.column)
```

{% hint style="info" %}
Older code may still use `client.quality`; it is kept for backward compatibility, but prefer `client.dq` for anything new. See [`client.quality`](#client.quality-data-quality-legacy) below.
{% endhint %}

### See what's been running behind the scenes

```python
runs = client.activity.list_runs(limit=10)
for r in runs.runs:
    print(r.run_id, r.success, r.start_ts)

plans = client.activity.list_plans(limit=10)
for p in plans.plans:
    print(p.plan_id, p.git_commit_sha)
```

### Stay in the loop

Follow a data product if you want to keep tabs on it:

```python
client.followers.follow()
```

And check what's happened recently:

```python
notifs = client.notifications.list(limit=20)
for n in notifs.notifications:
    print(n.event, n.created_ts)
```

### Handling errors

Every failed call raises the same exception, so you really only need one `except` block anywhere you use the SDK:

```python
from vulcan_sdk import VulcanClient, VulcanError

try:
    client.activity.get_plan("does-not-exist")
except VulcanError as e:
    print(e.status_code)   # e.g. 404
    print(e.detail)        # what actually went wrong
```

### Full method reference

Everything above covers the common cases. If you need something more specific, here's every method on every client.

#### `client.metadata`

| Method               | What it does                                                                                | Returns            |
| -------------------- | ------------------------------------------------------------------------------------------- | ------------------ |
| `get()`              | Full catalog for the data product: name, version, fingerprint, product info, gateway config | `MetadataResponse` |
| `get_semantic()`     | The semantic schema: models, dimensions, measures                                           | `SemanticSchema`   |
| `download_powerbi()` | Power BI connection file as raw bytes                                                       | `bytes`            |
| `download_tableau()` | Tableau connector file as raw bytes                                                         | `bytes`            |

#### `client.query`

| Method                                                         | What it does                                                                                | Returns             |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------- |
| `submit_semantic_rest(query, *, graphql_body=None, meta=None)` | Run a query using measures/dimensions, or GraphQL via `graphql_body`                        | `StatementAccepted` |
| `submit_semantic_sql(sql, *, meta=None)`                       | Run a query written as SQL                                                                  | `StatementAccepted` |
| `submit_statement(sql, *, meta=None)`                          | Run raw SQL directly against physical tables, bypassing the semantic layer                  | `StatementAccepted` |
| `get_statement(statement_id)`                                  | Check the status of a submitted query                                                       | `StatementDetail`   |
| `get_statement_result(statement_id)`                           | Get the rows back for a completed query                                                     | `StatementResult`   |
| `get_metric(metric_name, **params)`                            | Quick lookup of a named metric (dimensions, granularity, timezone, limit, offset as kwargs) | `dict`              |
| `post_metric(metric_name, body)`                               | Named metric query with filters/grouping in the body                                        | `StatementAccepted` |
| `get_usage_metrics()`                                          | Query usage stats for this data product                                                     | `UsageMetrics`      |

Query syntax references: [REST query format](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/rest.md) · [SQL reference](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/semantic-sql.md) · [GraphQL reference](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/graphql.md)

#### `client.perspectives`

| Method                                                    | What it does                                               | Returns                    |
| --------------------------------------------------------- | ---------------------------------------------------------- | -------------------------- |
| `list(*, limit=20, offset=0, owner=None, is_public=None)` | List saved perspectives                                    | `PerspectivesListResponse` |
| `get(slug)`                                               | Fetch one perspective's details                            | `PerspectiveDetail`        |
| `get_result(slug, *, force_refresh=None)`                 | Run the perspective's query and get the rows               | `StatementResult`          |
| `create(slug, request: PerspectiveCreateRequest)`         | Save a completed query as a new perspective                | `PerspectiveDetail`        |
| `update(slug, request: PerspectiveUpdateRequest)`         | Change a perspective's name, description, visibility, etc. | `PerspectiveDetail`        |
| `delete(slug)`                                            | Delete a perspective                                       | `dict`                     |

`request` must be an actual `PerspectiveCreateRequest` / `PerspectiveUpdateRequest` instance (import both from `vulcan_sdk`). A plain dict raises `AttributeError`.

#### `client.followers`

| Method                                                           | What it does                                         | Returns                 |
| ---------------------------------------------------------------- | ---------------------------------------------------- | ----------------------- |
| `get_follow_status()`                                            | Whether you're currently following this data product | `FollowStatus`          |
| `follow(*, metadata=None)`                                       | Follow this data product                             | `Follower`              |
| `unfollow()`                                                     | Stop following this data product                     | `Follower`              |
| `get_analytics(*, granularity=None, start_ts=None, end_ts=None)` | Follower counts, optionally broken down over time    | `FollowerAnalytics`     |
| `list(*, limit=50, offset=0)`                                    | List everyone following this data product            | `FollowersListResponse` |

#### `client.notifications`

| Method                                                                                            | What it does                                                                    | Returns                     |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------- |
| `list(*, run_id=None, plan_id=None, events=None, start_ts=None, end_ts=None, limit=50, offset=0)` | List notifications, optionally filtered by run, plan, event type, or time range | `NotificationsListResponse` |

#### `client.dq`

| Method                                                          | What it does                                                                 | Returns              |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------- |
| `get_summary()`                                                 | Product-level data quality roll-up                                           | `DQSummary`          |
| `list_rules(*, model=None, dimension=None, limit=50, offset=0)` | List configured data quality rules and recent outcomes                       | `RulesResponse`      |
| `get_rule_by_name(model, dimension, name)`                      | Look up a rule by model, dimension, and check name (result is under `.rule`) | `RuleDetailResponse` |
| `get_rule(identity)`                                            | Look up a rule by its identity hash (result is under `.rule`)                | `RuleDetailResponse` |

**`client.quality` (Data Quality, legacy)**

Prefer `client.dq` for new code.

```python
checks = client.quality.list_checks(model="orders")
for c in checks.checks:
    print(c.check_identity, c.check_name, c.model_name)

check = client.quality.get_check_by_name(
    "test_db.project.customer", "completeness", "custkey_not_null"
)
check = client.quality.get_check("dfabde6e")
```

#### `client.activity`

| Method                                                                                          | What it does                                                  | Returns               |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------------------- |
| `list_plans(*, model_names=None, limit=20, offset=0, start_ts=None, end_ts=None, success=None)` | List deployment plans                                         | `PlansListResponse`   |
| `get_plan(plan_id)`                                                                             | Fetch one plan's details                                      | `Plan`                |
| `get_plan_git_diff(plan_id)`                                                                    | Git diff behind a plan                                        | `PlanGitDiffResponse` |
| `list_runs(*, model_names=None, success=None, limit=20, offset=0, start_ts=None, end_ts=None)`  | List pipeline runs                                            | `RunsListResponse`    |
| `get_run(run_id)`                                                                               | Fetch one run's details                                       | `Run`                 |
| `get_model_runs(model_name, *, limit=20, offset=0)`                                             | Runs that touched a specific model                            | `RunsListResponse`    |
| `list_models(*, limit=20, offset=0)`                                                            | Every model tracked in this data product, with its latest run | `ModelsListResponse`  |

### Cheat sheet

| I want to...                         | Call this                                                                                                                  |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Connect                              | `VulcanClient(fqdn=..., dp_name=..., access_token=..., tenant=...)`                                                        |
| See available models and columns     | `client.metadata.get_semantic()`                                                                                           |
| Run a query (measures/dimensions)    | `client.query.submit_semantic_rest(query={...})`                                                                           |
| Run a query (SQL)                    | `client.query.submit_semantic_sql("SELECT ...")`                                                                           |
| Run raw SQL (physical tables)        | `client.query.submit_statement("SELECT ...")`                                                                              |
| Get the generated warehouse SQL only | See the [transpile-only recipe](https://v2.dataos.info/consume/recipes/transpile-semantic-queries-to-native-warehouse-sql) |
| Check if a query is done             | `client.query.get_statement(id)`                                                                                           |
| Get query results                    | `client.query.get_statement_result(id)`                                                                                    |
| Query a named metric                 | `client.query.get_metric(name, **filters)`                                                                                 |
| Query a metric with filters          | `client.query.post_metric(name, body={...})`                                                                               |
| Save a query for reuse               | `client.perspectives.create(slug, PerspectiveCreateRequest(...))`                                                          |
| Fetch a saved view                   | `client.perspectives.get_result(slug)`                                                                                     |
| Download Power BI / Tableau files    | `client.metadata.download_powerbi()` / `download_tableau()`                                                                |
| Check data quality                   | `client.dq.get_summary()`                                                                                                  |
| See recent pipeline runs             | `client.activity.list_runs()`                                                                                              |
| Follow a data product                | `client.followers.follow()`                                                                                                |
| See notifications                    | `client.notifications.list()`                                                                                              |

### Constructor Options

| Parameter      | Type    | Required | Description                                 |
| -------------- | ------- | -------- | ------------------------------------------- |
| `fqdn`         | `str`   | Yes      | DataOS FQDN, e.g. `"example.dataos.io"`     |
| `dp_name`      | `str`   | Yes      | Data product name, e.g. `"clothing_retail"` |
| `access_token` | `str`   | Yes      | DataOS API token                            |
| `tenant`       | `str`   | Yes      | Tenant name, e.g. `"public"`                |
| `timeout`      | `float` | No       | Request timeout in seconds (default `30.0`) |
| `verify_ssl`   | `bool`  | No       | Verify TLS certificates (default `True`)    |

### Response Models

All methods return typed Pydantic v2 models with full IDE autocomplete. Extra fields from the API are preserved via `extra="allow"`.

| Client          | Key Models                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| `metadata`      | `MetadataResponse`, `SemanticSchema`                                                                          |
| `activity`      | `Plan` (key: `plan_id`), `PlansListResponse`, `Run` (key: `run_id`), `RunsListResponse`, `ModelsListResponse` |
| `dq`            | `DQSummary`, `RulesResponse`, `RuleDetailResponse`                                                            |
| `quality`       | `ChecksListResponse`, `CheckDetailResponse`                                                                   |
| `query`         | `StatementAccepted` (key: `id`), `StatementDetail`, `StatementResult`, `UsageMetrics`                         |
| `perspectives`  | `PerspectiveDetail`, `PerspectivesListResponse` (items via `.items`)                                          |
| `notifications` | `NotificationsListResponse`, `Notification`                                                                   |
| `followers`     | `FollowStatus`, `FollowersListResponse`, `FollowerAnalytics`                                                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/interfaces/apis/data-product-apis/sdks/python-sdk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
