> 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/build/understand/explore-data/workbench.md).

# Workbench

Connect to a source, run SQL, and inspect the actual values in Workbench.

Once the metadata looks promising, validate the data itself. Workbench connects to a source, runs SQL, views results, and lets you browse schemas and tables from one workspace. Use it before you commit a dataset to a model, a report, or an application.

## What is in Workbench

| Area            | What it is for                                                     |
| --------------- | ------------------------------------------------------------------ |
| Workbench home  | Create a new bench, open a saved one, or pick up a draft           |
| New bench setup | Choose the data source and the Secret to connect with              |
| Query workspace | Write SQL, run queries, browse schemas and tables, inspect results |

## 1. Open Workbench and start a bench

Open **Workbench** from the left navigation. The home page shows your saved benches. From here you can:

* Create a new bench.
* Reopen unsaved benches.
* Return to a previous one.

Click **New bench** to start.

<figure><img src="https://3313158291-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FINSmDF7devOr5hD7KeZA%2Fuploads%2Fgit-blob-8ec4d6f7199c3bfa277f18524c63c822ec757c40%2Fimage%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

## 2. Pick a source and a Secret

Choose the data source (Depot) from the list (filter by type, owner, or date). Then choose the **Secret** Workbench connects with.

Workbench needs both. A single Depot can have several Secrets, each representing a different permission context, so it cannot safely pick one for you. Choose the Secret that matches what you intend to do. Purposes are labels defined for the Secrets when you register the [Depot](/build/understand/connect-sources.md), so the ones you see depend on that Depot. Common ones:

| Purpose  | Use it when                                                          |
| -------- | -------------------------------------------------------------------- |
| `query`  | You only need to query and explore                                   |
| `scan`   | You need metadata scanning or schema discovery                       |
| `rw`     | You need read-write access and have permission for it                |
| `full`   | Custom label: the credential has complete access to the data source. |
| `masked` | Custom label: the credential masks some of the data.                 |

{% hint style="info" %}
Workbench can also query through a Minerva resource. Select the Minerva resource as the query engine; each Depot it declares appears as a catalog, so you address tables as `catalog.schema.table`. You need the **Can Use Minerva** permission on that resource and access to each Depot. See [Minerva](https://v2.dataos.info/references/resources/minerva) and [Querying (Minerva)](https://v2.dataos.info/references/resources/depot/consume/querying) in References.
{% endhint %}

{% hint style="info" %}
When you share a bench, the selected Secret sets the permission context others inherit. As a bench owner, you can choose a masked, read-only Secret so others explore without seeing sensitive fields.
{% endhint %}

## 3. Browse, then query

With the source and Secret selected, the bench opens. The left panel shows the source's schemas, tables, and columns. Expand a schema, select a table, and read its columns and types. Look for identifier fields, categorical fields, possible measures, and fields that will need filtering or transformation. Decide what is relevant before you write SQL.

<figure><img src="https://3313158291-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FINSmDF7devOr5hD7KeZA%2Fuploads%2Fgit-blob-456328a6e0e7dab62d51300ec99b56b6e40ac93e%2Fimage%20(3).png?alt=media" alt=""><figcaption></figcaption></figure>

Type your query into the editor and run a cell, or **Run all** for every cell. The execution time and returned rows tell you whether the query did what you expected.

<figure><img src="https://3313158291-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FINSmDF7devOr5hD7KeZA%2Fuploads%2Fgit-blob-bba59b3158cc3793b5824bad329d289c4e83090e%2Fimage%20(4).png?alt=media" alt=""><figcaption></figcaption></figure>

## 4. Refine with cell references

After the first result, iterate. You can run the next query against the source, or run it locally against the previous cell's output using a cell reference. Cell references skip the round trip to the source, so they are faster and cheaper. Add a cell and click the cell-reference icon to enable it.

<figure><img src="https://3313158291-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FINSmDF7devOr5hD7KeZA%2Fuploads%2Fgit-blob-f1e74b06e9871a4e9f577e912edf5764dd48b768%2Fimage%20(5).png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Cell references run locally. Performance scales with dataset size and your machine's memory.
{% endhint %}

## 5. Work across benches and save

Each bench is a tab. Open several to compare sources or tables, or to keep drafts separate from validated queries. Unsaved benches stay around until you close or save them. Save a bench when you want to continue later, prepare a query for downstream work, or share the exploration.

## What is next

| Outcome               | Next action                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------- |
| Keep exploring        | Inspect more tables, columns, or values                                                      |
| Use it in a build     | The dataset supports a reusable use case. Go to [Productize](/build/productize/overview.md). |
| Try another source    | The selected source does not have the data you need                                          |
| Source the data first | The data is not yet reachable by your engine. See [Move](/build/move/overview.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 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/build/understand/explore-data/workbench.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.