> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/v4.7-en/le-druide/interroger-des-datasets.md).

# Query datasets

Query your datasets in natural language directly from Le Druide thanks to the Dataset Search tool.

The Cleyrop Dataset Search tool automatically translates your questions into SQL queries and runs them on the datasets you can access.

***

## Prerequisites

Before using the Dataset Search tool from Le Druide:

1. **Have an accessible dataset** : the dataset must be available in your project or in the catalog, and your user permissions must allow you to access it.
2. **Configure the token** : the Dataset Search tool requires an access token. Generate it from your **Personal Space → Profile & Tokens**, then enter it in the tool configuration using the ⚙️ button in Le Druide.

## Accessible datasets

You can query **any dataset your user account has access to** on the platform. The tool respects your access rights: it cannot query datasets for which you do not have read permissions.

You can ask the tool to list your available datasets before getting started.

{% hint style="warning" %}
The more datasets you have access to, the longer the list may take to display.
{% endhint %}

## Available features

The Dataset Search tool lets you interact with your data in several ways:

| Capability                  | What the tool does                                                    | Example question                                               |
| --------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------- |
| **Schema exploration**      | Describes the structure of a dataset (columns, types, example values) | Describe the schema of the sales\_results dataset for me.      |
| **Data retrieval**          | Generates a `SELECT` query on your data                               | "Show me the last 10 sales."                                   |
| **Filtering**               | Builds a `WHERE` clause to filter the results                         | "List the sales with revenue greater than €5,000."             |
| **Aggregations**            | Uses `GROUP BY` and `SUM`, `AVG`, `COUNT`...                          | "What is the total revenue by region for 2024?"                |
| **Joins**                   | Joins several tables and aggregates the results                       | "Give me the product categories and their total revenue."      |
| **Time-based queries**      | Uses date functions to group by period                                | "How many sales per month in 2023?"                            |
| **Statistics**              | Calculates `AVG`, `STDDEV` and other indicators                       | "What is the average value and standard deviation of revenue?" |
| **Top-N / Bottom-N**        | Uses `ORDER BY ... DESC LIMIT N`                                      | "What are the top 5 sales?"                                    |
| **Conditional logic**       | Adds conditions `CASE` or `WHERE` based on complex criteria           | "Which sales were made on a Friday?"                           |
| **Cross-table comparisons** | Runs several queries and compares the results                         | "Compare last year's revenue with this year's."                |

{% hint style="info" %}
**Note:**

* Read-only: the tool can only read data; it cannot modify or delete it.
* Simplified SQL: very complex queries (recursive CTEs, nested subqueries) may be truncated or simplified.
  {% endhint %}

## Download the result of a query on a dataset

When a question concerns a dataset you have access to, Le Druide runs SQL queries to retrieve the requested information. The steps of this search are visible in the conversation, and the result can be retrieved as a file.

1. From Le Druide, make a request by mentioning the **techname** of the dataset concerned.
2. View the search details in the **expandable block** : datasets analyzed and SQL queries run.
3. Download the **file** corresponding to the query result.

{% hint style="warning" %}
This feature is based on the Cleyrop Dataset Tool **Cleyrop Dataset**. A file provided as an attachment is not interpreted as a dataset: no SQL query is generated and the result cannot be downloaded in that case.
{% endhint %}

## Generate a chart

Le Druide can visually represent data present in the conversation: the result of a query on a dataset, the content of an attachment, or a table produced during the exchange.

1. Ask for the chart in natural language, specifying the desired type: "Make me a bar chart of sales by region," "Plot the revenue curve by month," "A pie chart of the distribution by category."
2. The chart is displayed directly in the response, with its legend. It remains visible when you reopen the conversation from your history.
3. To modify it (change the type, filter the data, rename an axis), simply rephrase your request.

Available types: **bars**, **line**, **pie chart** and **scatter plot**.

{% hint style="info" %}
A chart represents at most 500 points and 10 series. Beyond that, ask Druide to aggregate the data (by month, by category, etc.) before plotting.
{% endhint %}

## Use Cleyrop Dataset from your own apps

The Cleyrop Dataset Tool is an MCP server deployed on the platform. An App or a Tool deployed in The Factory, a DevSpace, or a notebook in Codelab can call it directly via its **internal URL**, without going through Le Druide:

* **internal URL** : `http://cleyrop-mcp-dataset.cleyrop-mcp-dataset.svc.cluster.local:8000/mcp` (MCP HTTP transport, `POST` requests on `/mcp`)
* **Authentication** : pass your personal token in the `DATASET_USER_ACCESS_TOKEN`header. The Tool queries datasets using the rights granted by this token.
* **Scope** (optional): the `CLEYROP-Datasets`header, a JSON list of technames, limits the queryable datasets.

The exposed tools (schema exploration, SQL query, export) are the ones described in the **Tools** tab of the Tool details page in The Factory.

***

## Best practices

* **Mention the dataset name** : if you know it, specify it in your question (for example, `sales_results`). Otherwise, ask the tool to list the available datasets or describe a dataset's schema.
* **Name the columns** : if you need a specific metric, cite its exact name (for example, "Show me `customer_id` and `revenue_usd` for customers with more than 5 purchases").
* **Ask natural questions** : there's no need to write SQL; phrase your question as you would to a colleague (for example, "Which products sold best in Q2 2024?").
* **Add limits** : for large volumes of data, specify a limit in your question (for example, "the first 20 rows") to get a faster response.