> 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/transpile-semantic-queries-to-native-warehouse-sql.md).

# Generate native warehouse SQL

Use transpile\_only=true to inspect the native warehouse SQL generated from a Semantic SQL or Semantic REST query, without executing it.

You want to see, check, or reuse the native warehouse query that a Semantic SQL or Semantic REST request turns into. This recipe sets the query parameter `transpile_only=true`, so the API translates the semantic query into the warehouse's native language and returns it directly, without running it. The journey is send the semantic query with `transpile_only=true` → review the generated SQL → use it where you need it.

**What this enables:**

* [ ] Inspect the native query before it runs
* [ ] Debug how a semantic query is translated for your warehouse
* [ ] Copy the generated query to test it in a warehouse client
* [ ] Compare the queries generated for different warehouses

{% 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).
{% endhint %}

## Steps

### 1. Send the query with `transpile_only=true`

Add `transpile_only=true` to the Semantic SQL endpoint:

{% code title="Transpile-only Semantic SQL request" %}

```bash
curl --location \
  'https://<DATAOS_FQDN>/vulcan/tenants/<DATAOS_TENANT_ID>/data-products/<DATAOS_TENANT_ID>-<resource-name>/api/v1/query/semantic/sql?transpile_only=true' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${DATAOS_TOKEN}" \
  --data '{
    "sql": "SELECT customer_profile.region_id, MEASURE(customer_profile.count) FROM customer_profile GROUP BY customer_profile.region_id LIMIT 10"
  }'
```

{% endcode %}

The same parameter works on the Semantic REST endpoint. Use the request body that the interface requires; only the query format changes.

| Interface     | Endpoint                                          |
| ------------- | ------------------------------------------------- |
| Semantic SQL  | `/api/v1/query/semantic/sql?transpile_only=true`  |
| Semantic REST | `/api/v1/query/semantic/rest?transpile_only=true` |

A transpile-only request returns directly. It works differently from a normal query execution:

| Standard query execution | Transpile-only request          |
| ------------------------ | ------------------------------- |
| Executes the query       | Does not execute the query      |
| Creates a statement ID   | Does not create a statement ID  |
| Requires status polling  | Returns directly                |
| Produces query results   | Produces native warehouse SQL   |
| May use cached results   | Only performs query translation |

### 2. Review the generated SQL

The API returns the query in the native language of the underlying warehouse. Depending on the warehouse, the generated query may use warehouse-specific:

* Table and column references
* Aggregation functions
* Quoting conventions
* Grouping logic
* Filters and limits

Review its filters, joins, aggregations, and grouping to validate how your semantic query was translated.

### 3. Use the generated SQL

Because the query was not executed, there is no statement to poll and no result to download. Copy the generated query to test it in a warehouse client, or compare it with the query generated for another warehouse. To run the semantic query and get results, send it again without `transpile_only=true`.

## Outcome

You can see exactly what a semantic query becomes in your warehouse's own SQL, so you can debug the translation or reuse the query without running it through DataOS.

## References

* [Query API reference](https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/query): `retry_on_recent_failure` and `transpile_only` on the Semantic REST/SQL endpoints
* [Retrieve large result sets with pagination](https://v2.dataos.info/consume/recipes/retrieve-large-result-sets-with-pagination.md): for queries you do intend to execute and page through


---

# 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/transpile-semantic-queries-to-native-warehouse-sql.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.
