> 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/semantic-sql.md).

# Semantic SQL

The Semantic SQL editor lets you write SQL against a Data Product's semantic models. Use it when field selection is already clear, or when you want to validate filters, joins, and result shape in SQL before consuming the data downstream.

## Open Semantic SQL

From the Data Product page, select **Explore → Semantic SQL**.

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

## Interface overview

The Semantic SQL editor opens with two panels:

* **Left panel** — lists the semantic models available in the Data Product (for example, `customer_profile`, `daily_sales`, `product_profile`, `rfm`, `sales_funnel`, `weekly_sales`). Select a model name to copy it into the editor.
* **Editor** — the SQL input area where you write your query.

<figure><img src="/files/bdvDdkDvL0PYQM8PXmqs" alt="Semantic SQL editor showing the model list on the left and a SELECT query in the editor"><figcaption><p>Semantic SQL editor with the model list and query editor</p></figcaption></figure>

## Write SQL against semantic models

The editor queries the semantic layer, not raw warehouse tables. Write SQL against the semantic model names listed in the left panel.

**Explore models before querying**

Use these commands to understand the available models and their fields:

| Command            | What it returns                                                                 |
| ------------------ | ------------------------------------------------------------------------------- |
| `SHOW TABLES`      | Lists all semantic models exposed by the Data Product.                          |
| `DESCRIBE <model>` | Lists the dimensions and measures available in a model, along with their types. |

**Query a model**

Select fields from one or more models using standard SQL syntax:

```sql
SELECT * FROM customer_profile
```

```sql
SELECT
  customer_profile.customer_id,
  customer_profile.region_name,
  customer_profile.total_revenue
FROM customer_profile
WHERE customer_profile.is_active_customer = true
LIMIT 100
```

## Run the query and review results

Select **Run** to execute the query. Results appear in the **Results** tab with a row and column count.

Use the **Source SQL** tab to see the underlying SQL that the semantic layer generates from your query.

Use the **REST API** tab to see how the same query can be submitted programmatically. It lists the steps, the base URL, and the endpoints to submit a query, check its status, and retrieve the result. All APIs require a Bearer token in the Authorization header.

## What Semantic SQL queries

Semantic SQL still goes through the semantic layer — you query model names and their logical fields, not the physical column names in the warehouse. The engine translates your SQL into optimized warehouse SQL, applying joins, aggregations, and access controls defined in the semantic model.

This means:

* You cannot reference raw table names or warehouse-specific syntax.
* The fields you select must match dimensions or measures defined in the model.
* Filters, limits, and ordering behave the same as in the Visual Builder.

## After validating in Semantic SQL

When the query returns the right result, you can:

* Save it as a [Perspective](/consume/understand/overview/perspectives.md) for reuse and sharing.
* Continue to [DB clients](/consume/activate/mysql-clients.md) if you need client-specific execution using the same SQL patterns.
* Use the REST API tab to copy the endpoints for programmatic consumption.

For deeper reference on Semantic SQL syntax, supported clauses, and how it translates to warehouse SQL, see:

* [Semantic SQL querying reference](/concepts/foundations/activation/apis/getting-started/querying-data-products/semantic-sql.md)
* [Source SQL](/concepts/foundations/activation/apis/getting-started/querying-data-products/source-sql.md) — understanding the physical SQL generated underneath
* [Measure and dimension behavior](/concepts/foundations/activation/apis/getting-started/querying-data-products/measure-and-dimension-behavior.md)  — how aggregations, filters, and joins behave
* [Cross-model queries](/concepts/foundations/activation/apis/getting-started/querying-data-products/cross-model-queries.md) — querying across multiple semantic models in one statement


---

# 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/semantic-sql.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.