> 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/visual-builder.md).

# Visual builder

The Visual Builder is a point-and-click query interface for exploring a Data Product's semantic models. Use it when you want to validate fields, filters, and result shape without writing SQL or GraphQL.

## Open Visual Builder

From the Data Product page, select **Explore → Visual builder**.

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

## Left panel — models and fields

The left panel lists the Data Product's semantic models. Switch between **All fields** and **Selected** tabs to see all available fields or only the ones you have added to the current query. Use the search box to find a specific model or field by name.

Select the info (**i**) icon next to a model to see its description, joins, owner, tags, and status before adding its fields.

![Semantic model info popover in the Visual Builder](/files/tukZqb2kssRysfZRO8EE)

Expand a model and select dimensions and measures to add them to the query.

![Selected dimensions in the Visual Builder](/files/9dMRnRWpLy5hdk5xYfno)

## Query tabs

Tabs let you explore a Data Product from several angles at once — for example, comparing customer and sales views side by side, or testing a variation without losing a query that already works.

* Select **+** to open a new query tab.
* Right-click a tab to **Rename** it for clarity, **Duplicate** it as a starting point for a variation, or **Close** it when you are done.

![Query tab menu showing Rename, Duplicate, and Close options](/files/Q4TR03bBnvcRCcmCbHen)

## Apply filters

Select **Filters** to add conditions that scope the result to a specific segment. Filters are grouped by **Dimensions** and **Measures**. Within each group, add individual filter rules or use **+ Group** to combine conditions with AND/OR logic.

Each filter rule specifies a field, an operator (for example `==`, `>`, `contains`), and a value.

<figure><img src="/files/NGuBNnxeuX61MoFqMvKE" alt="Filters panel showing a Dimension filter on customer_id and a Measure filter on activation_rate"><figcaption><p>Dimension and Measure filters applied before running the query</p></figcaption></figure>

## Query settings

The query settings panel shapes the preview so it reflects what you intend to consume, and keeps the result fast and readable while you validate. Open it from the toolbar before running the query.

<figure><img src="/files/GOtglXQlo5eu9434TcE2" alt="Query settings panel showing Sort By, Limit, Offset, and Zone controls"><figcaption><p>Query settings: Sort By, Limit, Offset, and Zone</p></figcaption></figure>

<table><thead><tr><th width="150">Setting</th><th>Why you would use it</th></tr></thead><tbody><tr><td>Sort By</td><td>Bring the rows you care about to the top (for example, highest revenue first) so you can spot-check results quickly. Add multiple fields for tie-breaking. Choose <strong>ASC</strong> or <strong>DESC</strong> for each field.</td></tr><tr><td>Limit</td><td>Keep the preview responsive and avoid pulling more rows than you need while validating. Options include 100, 500, 1K, 5K, and 10K.</td></tr><tr><td>Offset</td><td>Page through a large result to inspect rows beyond the first batch.</td></tr><tr><td>Zone</td><td>Align time-based fields to the time zone your analysis or report uses so dates and times match what your audience expects.</td></tr></tbody></table>

**Limit options**

<figure><img src="/files/hkTslSrqNCGgoyC38cMR" alt="Limit dropdown showing 100, 500, 1K, 5K selected, and 10K"><figcaption><p>Choose how many rows to return in the preview</p></figcaption></figure>

**Zone options**

Pick a time zone from the **Zone** dropdown so timestamps are interpreted consistently with your reporting. This avoids off-by-hours errors when the data and your audience are in different regions.

<figure><img src="/files/7GnbEkuzBEloijdmI5Ru" alt="Zone dropdown listing UTC, America/New_York, America/Los_Angeles, Europe/London, Europe/Paris, CET, JST, SGT"><figcaption><p>Time zone options in the Zone dropdown</p></figcaption></figure>

## Run the query and review results

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

![Query results in the Results tab](/files/EyACHmGEFqRYtQ6E0tL9)

## Source SQL tab

The **Source SQL** tab shows the SQL generated from your field selections and filters. Use it to understand what query the Visual Builder has translated your selections into, or to copy the SQL for use elsewhere.

<figure><img src="/files/G9GsCCTNMyF18wU9F9VK" alt="Source SQL tab showing the generated SQL query for the current Visual Builder selection"><figcaption><p>Source SQL generated from the current Visual Builder query</p></figcaption></figure>

## REST API tab

The **REST API** tab shows how the validated query can run programmatically. It lists the steps, the base URL, and the endpoints to submit a semantic query, check its status, and retrieve the result.

<figure><img src="/files/EZcrUhv5TmqZjol5Fcj7" alt="REST API tab showing steps, base URL, and the submit, status, and result endpoints"><figcaption><p>REST API tab — steps and endpoints for programmatic execution</p></figcaption></figure>

**Steps to follow:**

1. Build your query by selecting dimensions, measures, and segments from the left panel and apply filters (if any).
2. Click **Run** to validate your query and preview results in the Results tab.
3. Copy the REST API endpoint, headers, and request body to integrate into your application.
4. Use **Submit a semantic query** (`POST /api/v1/query/semantic/rest`) to submit the query. Store the statement ID from the response.
5. Use **Check status of submitted query** (`GET /api/v1/query/statement/{id}`) to check the status by passing the statement ID.
6. Use **Get result of submitted query** (`GET /api/v1/query/statement/{id}/result?format=json`) to get the results by passing the statement ID.

All APIs require a Bearer token in the Authorization header. For token creation, see [Authentication](/concepts/foundations/activation/apis/getting-started/authentication.md).

For deeper reference on the REST query workflow, request body structure, and response handling, see:

* [REST querying reference](/concepts/foundations/activation/apis/getting-started/querying-data-products/rest.md)
* [Statement lifecycle](/concepts/foundations/activation/apis/getting-started/querying-data-products/statement-lifecycle.md) — how submitted queries move from pending to complete
* [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

## Query history

Query History lets you return to a run you made earlier instead of rebuilding it — useful when you want to re-check a result or recover a query you closed. Open it from the toolbar, select a run to reopen it, or select **Clear All** to start fresh.

<img src="/files/lPcTwHF5srq5wcT12Pil" alt="Query History panel showing the last run and a Clear All option" width="375">

## Save the result as a Perspective

When the query returns the right result, save it as a [Perspective](/consume/understand/overview/perspectives.md) for reuse and sharing.

## APIs reference

For full endpoint specifications, request and response schemas, authentication, and all query patterns available through the Data Product APIs, see the [APIs section in Concepts](/concepts/foundations/activation/apis.md).


---

# 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/visual-builder.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.