> 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/consume/understand/overview/graphql.md).

# GraphQL

The GraphQL editor lets you write queries against a Data Product's semantic models using the GraphQL query language. Use it when you need full control over the query structure, want to mirror the exact shape a downstream application will use, or when you are validating a query before embedding it in code.

## Open GraphQL

From the Data Product page, select **Explore → GraphQL**.

<figure><img src="/files/KvLfZcGBVfQh1gOjhjoh" alt="Explore dropdown showing Visual builder, GraphQL, and Semantic SQL options"><figcaption><p>Select GraphQL from the Explore menu</p></figcaption></figure>

## Interface overview

The GraphQL editor opens with:

* **Query editor** — where you write or paste a GraphQL query.
* **Variables panel** — where you pass variable values for parameterized queries.
* **Headers panel** — where you set the Authorization header and any custom headers.
* **Docs panel** — a browsable schema reference. Open it to explore the available types, fields, and arguments without leaving the editor.

<figure><img src="/files/5SyB7jtuI3pErPqDA5S6" alt="GraphQL editor with a query and the Docs panel open"><figcaption><p>GraphQL editor with the Docs panel open</p></figcaption></figure>

## Browse the schema with the Docs panel

The **Docs** panel is how you learn the query structure without guessing. Open **Query** to see the root `table` field and its arguments. Use the search shortcut to find a type or field quickly.

![GraphQL Docs panel showing the Query table field and its arguments](/files/6qZ7MONVTrtVbMmIRDtF)

## The `table` query and its arguments

The `table` query is the main entry point. It accepts the arguments below, which mirror the controls in the Visual Builder so you can reproduce the same filtering, paging, sorting, and time zone behavior in code.

<table><thead><tr><th width="220">Argument</th><th>When to use it</th></tr></thead><tbody><tr><td><code>where: RootWhereInput</code></td><td>Scope the result to a business segment, date range, or condition.</td></tr><tr><td><code>limit: Int</code></td><td>Cap the number of rows so responses stay fast and payloads stay small.</td></tr><tr><td><code>offset: Int</code></td><td>Page through a large result set across multiple calls.</td></tr><tr><td><code>timezone: String</code></td><td>Return time fields in the time zone your application expects.</td></tr><tr><td><code>renewQuery: Boolean</code></td><td>Force fresh data when you cannot rely on a cached result.</td></tr><tr><td><code>ungrouped: Boolean</code></td><td>Get raw rows instead of aggregated values when you need row-level detail.</td></tr><tr><td><code>orderBy: RootOrderByInput</code></td><td>Sort results so the most relevant rows come first.</td></tr></tbody></table>

## Write a query

A basic query selects fields from a semantic model:

```graphql
{
  table(
    limit: 100
    timezone: "UTC"
  ) {
    customer_profile {
      customer_id
      region_name
      total_revenue
    }
  }
}
```

To filter results, pass a `where` argument:

```graphql
{
  table(
    limit: 100
    timezone: "UTC"
    where: {
      customer_profile: {
        is_active_customer: { equals: true }
      }
    }
  ) {
    customer_profile {
      customer_id
      region_name
      total_revenue
    }
  }
}
```

## Run the query and review results

Select **Run** (or press the play button) to execute the query. Results appear in the response panel below the editor.

## Authentication

All GraphQL API calls require a Bearer token in the Authorization header. Set it in the **Headers** panel before running the query. To create an API token, use the link shown in the editor.

## After validating in GraphQL

When the query returns the right result, you can:

* Copy the query directly into your application code — the same query syntax works against the Data Product's API endpoint.
* Save it as a [Perspective](/consume/understand/overview/perspectives.md) for reuse and sharing.

For deeper reference on GraphQL query structure, variables, filtering syntax, and schema types, see:

* [GraphQL querying reference](/concepts/foundations/activation/apis/getting-started/querying-data-products/graphql.md)
* [GraphQL vs REST](/concepts/foundations/activation/apis/getting-started/querying-data-products/graphql-vs-rest.md) — when to use each approach
* [Statement lifecycle](/concepts/foundations/activation/apis/getting-started/querying-data-products/statement-lifecycle.md) — how async query execution works
* [Measure and dimension behavior](/concepts/foundations/activation/apis/getting-started/querying-data-products/measure-and-dimension-behavior.md) — how aggregations and filters behave in results


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/consume/understand/overview/graphql.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.