> 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/recipes/query-semantic-model-with-graphql.md).

# Build applications with Semantic GraphQL

Query specific measures and dimensions through the Semantic GraphQL endpoint and get a structured response back in one request.

You are building an application that needs specific measures and dimensions from a Data Product, in a structured response, without polling for results. This recipe uses the Semantic GraphQL endpoint, where the client defines the exact fields it needs and receives the result in a single response. Use it when your application already uses GraphQL, needs only selected fields, and wants JSON results immediately. The journey is send a GraphQL query → read the response → validate it → make it reusable with variables.

**What this enables:**

* [ ] Request only the measures and dimensions your application needs
* [ ] Get the query result and its execution metadata in one response, with no polling
* [ ] Validate each response before your application processes the records
* [ ] Reuse one query with different runtime values through GraphQL variables

{% hint style="info" %}
**Prerequisites:** a DataOS API token and the Data Product's API base URL. See [Authentication](https://v2.dataos.info/references/interfaces/apis/data-product-apis/getting-started/authentication). Keep the token outside your application's source code.
{% endhint %}

{% hint style="info" %}
Unlike the asynchronous Semantic SQL and REST flow, the GraphQL endpoint returns the query result and execution metadata in the same response. A `statement_id` is still created and returned under `extensions`, but no additional polling is required when the returned status is `SUCCESS`.
{% endhint %}

## Steps

### 1. Send a GraphQL query

{% code title="Semantic GraphQL request" %}

```bash
curl --location \
  'https://<DATAOS_FQDN>/vulcan/tenants/<DATAOS_TENANT_ID>/data-products/<DATAOS_TENANT_ID>-<resource-name>/api/v1/query/semantic/graphql' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${DATAOS_TOKEN}" \
  --data '{
    "query": "query {\n  table(limit: 10) {\n    customer_profile {\n      count\n      region_id\n    }\n  }\n}",
    "variables": {}
  }'
```

{% endcode %}

The query requests:

* `customer_profile.count` as a measure.
* `customer_profile.region_id` as a dimension.
* A maximum of 10 records.

Request only the fields your application uses, and keep a bounded `limit`. For result sets too large for one response, see [Retrieve large result sets with pagination](https://v2.dataos.info/consume/recipes/retrieve-large-result-sets-with-pagination.md).

### 2. Read the response

```json
{
  "data": {
    "table": [
      {
        "customer_profile": {
          "count": 1.0,
          "region_id": 1.0
        }
      },
      {
        "customer_profile": {
          "count": 1.0,
          "region_id": 3.0
        }
      }
    ]
  },
  "extensions": {
    "statement_id": "01KYPE8HDFCDFAMCJ76D5CVS9K",
    "strategy": "EXECUTE",
    "status": "SUCCESS",
    "fingerprint": "06458a7a04494abd34cbebbd8a8be25ec022dcf04bea497fb3e7496bfbea25ef",
    "is_stale": false,
    "_links": {
      "self": {
        "href": "/api/v1/query/statement/01KYPE8HDFCDFAMCJ76D5CVS9K"
      },
      "result": {
        "href": "/api/v1/query/statement/01KYPE8HDFCDFAMCJ76D5CVS9K/result"
      }
    }
  }
}
```

The response has two parts:

* **`data`** holds the records. Its structure follows the fields you selected in the request:

  ```
  table
   └── customer_profile
         ├── count
         └── region_id
  ```
* **`extensions`** holds the execution metadata:

  | Field           | What to check                                          |
  | --------------- | ------------------------------------------------------ |
  | `statement_id`  | Unique identifier created for the query execution.     |
  | `status`        | Confirm that the query completed with `SUCCESS`.       |
  | `strategy`      | Indicates whether the query was executed or reused.    |
  | `fingerprint`   | Identifies the normalized query for matching or reuse. |
  | `is_stale`      | Check whether the returned result is marked as stale.  |
  | `_links.self`   | Statement endpoint associated with the query.          |
  | `_links.result` | Result endpoint associated with the statement.         |

### 3. Validate the response

Check both the GraphQL payload and the execution metadata before processing records. Check for GraphQL errors even when the HTTP request succeeds.

At minimum, confirm that:

* The response does not contain a top-level `errors` array.
* The expected object exists under `data`.
* `extensions.status` is `SUCCESS`.
* `extensions.is_stale` has the expected value, when result freshness matters.
* The requested fields are present in every returned record.

### 4. Pass dynamic values with variables

When filter values or limits come from your application at runtime, pass them as GraphQL variables instead of building the query string yourself.

{% code title="GraphQL request with variables" %}

```bash
curl --location \
  'https://<DATAOS_FQDN>/vulcan/tenants/<DATAOS_TENANT_ID>/data-products/<DATAOS_TENANT_ID>-<resource-name>/api/v1/query/semantic/graphql' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${DATAOS_TOKEN}" \
  --data '{
    "query": "query CustomerProfile($limit: Int!) {\n  table(limit: $limit) {\n    customer_profile {\n      count\n      region_id\n    }\n  }\n}",
    "variables": {
      "limit": 10
    }
  }'
```

{% endcode %}

Variables keep the query reusable and separate its structure from runtime values.

## Outcome

Your application requests exactly the measures and dimensions it needs, gets the result and its execution metadata in one response, and validates both before rendering or processing the records.

## References

* [GraphQL API reference](https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/graphql): full endpoint details and error behavior
* [Retrieve large result sets with pagination](https://v2.dataos.info/consume/recipes/retrieve-large-result-sets-with-pagination.md): for Semantic REST/SQL queries returning more than 50,000 records
* [Generate native warehouse SQL](https://v2.dataos.info/consume/recipes/transpile-semantic-queries-to-native-warehouse-sql.md): inspect the SQL a semantic query would run, without executing it


---

# 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/consume/recipes/query-semantic-model-with-graphql.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.
