> 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/typescript-sdk.md).

# TypeScript SDK

A fully typed TypeScript client for integrating applications with Data Product APIs.

Connect once, then pull data, save views, and check on pipeline health using plain TypeScript (or JavaScript). No manual `fetch` calls, no hand-rolled JSON parsing. Every method returns a typed object, so your editor knows the shape of the response before you've even run the code.

Zero runtime dependencies. Uses the native `fetch` API (Node 18+).

<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)
* [Cancelling requests](#cancelling-requests)
* [Handling errors](#handling-errors)
* [Full method reference](#full-method-reference)
* [Cheat sheet](#cheat-sheet)

</details>

### Install

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

```bash
# From a local .tgz
npm install vulcan-sdk-0.228.1.32.tgz

# Or from registry (once published)
npm install vulcan-sdk
```

Requires Node 18+ (the SDK uses the native `fetch` API and has zero runtime dependencies).

### Connect

```typescript
import { VulcanClient } from "vulcan-sdk";

const client = new VulcanClient({
  fqdn: "example.dataos.io", // your DataOS instance
  dpName: "clothing_retail", // the data product you're connecting to
  accessToken: "<your-dataos-api-token>",
  tenant: "public",
});
```

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

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

Every request is sent with `Accept: application/json`, so responses always come back as JSON, even for endpoints where the REST API defaults to something else.

Once you have a client, every resource is a property on it: `client.metadata`, `client.query`, `client.perspectives`, `client.followers`, `client.notifications`, `client.dq`, `client.activity`.

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

```typescript
const schema = await client.metadata.getSemantic();
for (const model of schema.models) {
  console.log(model["name"], model["columns"]);
}
```

`models` is typed loosely (`Record<string, unknown>[]`), since its shape depends on what the data product defines, so you'll want a small cast or a runtime check if you plan to do more than log it.

Need the full catalog instead (product info, gateway, status)? 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:**

```typescript
const stmt = await client.query.submitSemanticRest({
  query: {
    measures: ["orders.total_revenue"],
    dimensions: ["orders.ORDERSTATUS"],
    limit: 10,
  },
});
```

**Or just write SQL:**

```typescript
const stmt = await client.query.submitSemanticSQL({
  sql: "SELECT ORDERKEY, ORDERSTATUS FROM orders LIMIT 10",
});
```

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:

```typescript
const TERMINAL = new Set(["SUCCESS", "SUCCEEDED", "FAILED", "CANCELLED"]);

let current = stmt;
while (!TERMINAL.has(current.status.toUpperCase())) {
  await new Promise((r) => setTimeout(r, 2000));
  current = await client.query.getStatement(stmt.id);
}

const result = await client.query.getStatementResult(stmt.id);
console.log(result.cols);
for (const row of result.rows ?? []) {
  console.log(row);
}
```

If you'd rather write GraphQL, you can pass that in too:

```typescript
const stmt = await client.query.submitSemanticRest({
  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:

```typescript
const data = await client.query.getMetric("CUSTOMER_GROWTH", {
  granularity: "month",
  limit: 100,
});
```

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

```typescript
const stmt = await client.query.postMetric("CUSTOMER_GROWTH", {
  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:

```typescript
const newView = await client.perspectives.create({
  name: "Top Customers",
  statement_id: stmt.id,
  is_public: true,
});
```

Want to pick your own slug instead of letting the server derive one from the name? Just include it in the same object:

```typescript
const newView = await client.perspectives.create({
  name: "Top Customers",
  statement_id: stmt.id,
  slug: "top-customers",
  is_public: true,
});
```

Check whether a slug is free before you commit to it:

```typescript
const available = await client.perspectives.checkAvailability("top-customers");
```

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

```typescript
const result = await client.perspectives.getResult("top-customers");
```

To see what's already been saved:

```typescript
const listing = await client.perspectives.list();
for (const p of listing.items) {
  console.log(p.slug, p.name, p.owner);
}
```

And if you need to change or remove one later:

```typescript
await client.perspectives.update("top-customers", { description: "Q3 view" });
await 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:

```typescript
import { writeFileSync } from "fs";

writeFileSync("powerbi.zip", await client.metadata.downloadPowerBI());
writeFileSync("connection.tds", await client.metadata.downloadTableau());
```

{% 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

```typescript
const summary = await client.dq.getSummary();
console.log(summary.pass_rate, summary.dimensions);
```

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

```typescript
const rules = await client.dq.listRules({ model: "orders" });
for (const r of rules.rules) {
  console.log(r.name, r.dimension, r.column);
}
```

One thing to watch for: use `rule.identity` to look a rule up later, not `rule.id`; the field is called `identity`.

{% 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`](#clientquality-data-quality-legacy) below.
{% endhint %}

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

```typescript
const runs = await client.activity.listRuns({ limit: 10 });
for (const r of runs.runs) {
  console.log(r.run_id, r.success, r.start_ts);
}

const plans = await client.activity.listPlans({ limit: 10 });
for (const p of plans.plans) {
  console.log(p.plan_id, p.git_commit_sha);
}
```

### Stay in the loop

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

```typescript
await client.followers.follow();
```

And check what's happened recently:

```typescript
const notifs = await client.notifications.list({ limit: 20 });
for (const n of notifs.notifications) {
  console.log(n.event, n.created_ts);
}
```

### Cancelling requests

Every method takes an optional `opts.signal`, so any call can be wired up to an `AbortController` if you need to cancel it. This is useful in a UI where the user navigates away mid-request:

```typescript
const controller = new AbortController();
const promise = client.activity.listRuns({
  limit: 10,
  signal: controller.signal,
});

// later, if you need to bail out
controller.abort();
```

### Handling errors

Every failed call throws the same error class:

```typescript
import { VulcanAPIError } from "vulcan-sdk";

try {
  await client.activity.getPlan("does-not-exist");
} catch (e) {
  if (e instanceof VulcanAPIError) {
    console.log(e.statusCode); // e.g. 404
    console.log(e.detail); // what actually went wrong
  } else {
    throw e;
  }
}
```

The `instanceof` check matters in TypeScript specifically: with strict settings, whatever you catch is typed `unknown`, not `Error`, so you can't reach `.statusCode` until you've narrowed it.

### Full method reference

Everything above covers the common cases. If you need something more specific, here's every method on every client. All of them accept an optional trailing `opts` for `{ signal }` (see [Cancelling requests](#cancelling-requests)), omitted below for brevity.

#### `client.metadata`

| Method              | What it does                                               | Returns            |
| ------------------- | ---------------------------------------------------------- | ------------------ |
| `get()`             | Core metadata: name, env, tenant, product, gateway, status | `MetadataResponse` |
| `getSemantic()`     | The semantic schema: models, dimensions, measures          | `SemanticSchema`   |
| `downloadPowerBI()` | Power BI connection file as raw bytes                      | `Uint8Array`       |
| `downloadTableau()` | Tableau connector file as raw bytes                        | `Uint8Array`       |

#### `client.query`

| Method                            | What it does                                                             | Returns                   |
| --------------------------------- | ------------------------------------------------------------------------ | ------------------------- |
| `submitSemanticRest(req)`         | Run a query using measures/dimensions, or GraphQL via `req.graphql_body` | `StatementAccepted`       |
| `submitSemanticSQL(req)`          | Run a query written as SQL (`req.sql`)                                   | `StatementAccepted`       |
| `submitStatement(req)`            | Run raw SQL directly against physical tables (`req.sql`)                 | `StatementAccepted`       |
| `getStatement(statementId)`       | Check the status of a submitted query                                    | `StatementDetail`         |
| `getStatementResult(statementId)` | Get the rows back for a completed query                                  | `StatementResult`         |
| `getMetric(metricName, params?)`  | Quick lookup of a named metric via query params                          | `Record<string, unknown>` |
| `postMetric(metricName, body)`    | Named metric query with filters/grouping in the body                     | `StatementAccepted`       |
| `getUsageMetrics()`               | 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(opts?)`             | List saved perspectives (`opts.limit`, `opts.offset`, `opts.owner`, `opts.is_public`) | `PerspectivesListResponse` |
| `get(slug)`               | Fetch one perspective's details                                                       | `PerspectiveDetail`        |
| `getResult(slug, opts?)`  | Run the perspective's query and get the rows (`opts.force_refresh`)                   | `StatementResult`          |
| `create(req)`             | Save a completed query as a new perspective                                           | `PerspectiveDetail`        |
| `update(slug, req)`       | Change a perspective's name, description, visibility, etc.                            | `PerspectiveDetail`        |
| `delete(slug)`            | Delete a perspective                                                                  | `Record<string, unknown>`  |
| `checkAvailability(slug)` | Check whether a slug is already taken                                                 | `boolean`                  |

`req` is a plain object matching `PerspectiveCreateRequest` / `PerspectiveUpdateRequest`, no class to construct.

#### `client.followers`

| Method                | What it does                                                           | Returns                 |
| --------------------- | ---------------------------------------------------------------------- | ----------------------- |
| `follow(req?)`        | Follow this data product, `req` is optional metadata                   | `Follower`              |
| `unfollow()`          | Stop following this data product                                       | `Follower`              |
| `getFollowStatus()`   | Whether you're currently following this data product                   | `FollowStatus`          |
| `getAnalytics(opts?)` | Follower counts, optionally broken down over time (`opts.granularity`) | `FollowerAnalytics`     |
| `list(opts?)`         | List everyone following this data product                              | `FollowersListResponse` |

#### `client.notifications`

| Method        | What it does                                                                   | Returns                     |
| ------------- | ------------------------------------------------------------------------------ | --------------------------- |
| `list(opts?)` | List notifications, filterable by `run_id`, `plan_id`, `events`, or time range | `NotificationsListResponse` |

#### `client.dq`

| Method                                  | What it does                                                                 | Returns              |
| --------------------------------------- | ---------------------------------------------------------------------------- | -------------------- |
| `getSummary()`                          | Product-level data quality roll-up                                           | `DQSummary`          |
| `listRules(opts?)`                      | List configured data quality rules and recent outcomes                       | `RulesResponse`      |
| `getRuleByName(model, dimension, name)` | Look up a rule by model, dimension, and check name (result is under `.rule`) | `RuleDetailResponse` |
| `getRule(identity)`                     | Look up a rule by its identity UUID (result is under `.rule`)                | `RuleDetailResponse` |

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

Prefer `client.dq` for new code.

```typescript
const checks = await client.quality.listChecks({ model: "orders" });
for (const c of checks.checks) {
  console.log(c.check_identity, c.check_name, c.model_name);
}

const check = await client.quality.getCheckByName(
  "test_db.project.customer", "completeness", "custkey_not_null"
);
const check2 = await client.quality.getCheck("dfabde6e");
```

#### `client.activity`

| Method                           | What it does                                                  | Returns               |
| -------------------------------- | ------------------------------------------------------------- | --------------------- |
| `listPlans(opts?)`               | List deployment plans                                         | `PlansListResponse`   |
| `getPlan(planId)`                | Fetch one plan's details                                      | `Plan`                |
| `getPlanGitDiff(planId)`         | Git diff behind a plan                                        | `PlanGitDiffResponse` |
| `listRuns(opts?)`                | List pipeline runs                                            | `RunsListResponse`    |
| `getRun(runId)`                  | Fetch one run's details                                       | `Run`                 |
| `getModelRuns(modelName, opts?)` | Runs that touched a specific model                            | `RunsListResponse`    |
| `listModels(opts?)`              | Every model tracked in this data product, with its latest run | `ModelsListResponse`  |

### Cheat sheet

| I want to...                         | Call this                                                                                                                  |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Connect                              | `new VulcanClient({ fqdn, dpName, accessToken, tenant })`                                                                  |
| See available models and columns     | `client.metadata.getSemantic()`                                                                                            |
| Run a query (measures/dimensions)    | `client.query.submitSemanticRest({ query: {...} })`                                                                        |
| Run a query (SQL)                    | `client.query.submitSemanticSQL({ sql: "SELECT ..." })`                                                                    |
| Run raw SQL (physical tables)        | `client.query.submitStatement({ sql: "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.getStatement(id)`                                                                                            |
| Get query results                    | `client.query.getStatementResult(id)`                                                                                      |
| Query a named metric                 | `client.query.getMetric(name, params)`                                                                                     |
| Query a metric with filters          | `client.query.postMetric(name, body)`                                                                                      |
| Save a query for reuse               | `client.perspectives.create({ name, statement_id, ... })`                                                                  |
| Check if a slug is free              | `client.perspectives.checkAvailability(slug)`                                                                              |
| Fetch a saved view                   | `client.perspectives.getResult(slug)`                                                                                      |
| Download Power BI / Tableau files    | `client.metadata.downloadPowerBI()` / `downloadTableau()`                                                                  |
| Check data quality                   | `client.dq.getSummary()`                                                                                                   |
| See recent pipeline runs             | `client.activity.listRuns()`                                                                                               |
| Follow a data product                | `client.followers.follow()`                                                                                                |
| See notifications                    | `client.notifications.list()`                                                                                              |
| Cancel an in-flight request          | pass `{ signal: controller.signal }` as the last argument                                                                  |

### Constructor Options

| Option        | Type     | Required | Description                                 |
| ------------- | -------- | -------- | ------------------------------------------- |
| `fqdn`        | `string` | Yes      | DataOS FQDN, e.g. `"example.dataos.io"`     |
| `dpName`      | `string` | Yes      | Data product name, e.g. `"clothing_retail"` |
| `accessToken` | `string` | Yes      | DataOS API token                            |
| `tenant`      | `string` | Yes      | Tenant name, e.g. `"public"`                |

### Types

All methods are fully typed. Import types directly from the package:

```typescript
import type {
  Plan, PlansListResponse,
  Run, RunsListResponse,
  StatementAccepted, StatementDetail, StatementResult,
  PerspectiveDetail, PerspectivesListResponse,
  MetadataResponse, SemanticSchema,
  DQSummary, RulesResponse,
} from "vulcan-sdk";
```

| Client          | Key Types                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| `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`                                                  |

#### Requirements

* **Node.js** >= 18 (native `fetch` required)
* TypeScript >= 5.0 (for TypeScript projects)


---

# 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/typescript-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.
