> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Data Store

> Read from a structured knowledge base with full SQL SELECT

## What it does

`query_data_store` runs a read-only SQL `SELECT` against a
[data store](/features/data-stores) (a structured knowledge base) and returns the
rows. The agent writes the query directly, so it has the full expressive power of
SQL — joins, aggregates, `GROUP BY`, `HAVING`, window functions, and CTEs.

<Info>
  For an overview of structured data stores, see [Data Stores](/features/data-stores).
</Info>

## Parameters

| Parameter           | Type    | Required | Description                                                |
| ------------------- | ------- | -------- | ---------------------------------------------------------- |
| `knowledge_base_id` | integer | Yes      | The structured knowledge base to read                      |
| `query`             | string  | Yes      | A single SQL `SELECT` against the store's tables and views |

## Key behaviors

* **Read-only and safe.** Queries run in a read-only transaction scoped to the
  store's own schema; they cannot modify data or reach another store.
* **Large results spill to CSV.** Up to 10,000 rows are returned inline (subject
  to a token budget); anything larger is attached as a downloadable CSV so no
  result is ever lost.
* **Aggregate in the database.** For totals and rollups over large tables, let
  the query do the work (`SELECT count(*), sum(amount) ... GROUP BY ...`) rather
  than pulling rows and reducing them afterward.

## Common use cases

### Read a table

```
knowledge_base_id: 954
query: SELECT * FROM project_stages ORDER BY sort_order
```

### Aggregate

```
knowledge_base_id: 954
query: SELECT status, count(*) AS n FROM project_stages GROUP BY status
```

## Related

* [Manage Data Store](/tools/manage_data_store) — create tables, columns, views
* [Write Data Store](/tools/write_data_store) — insert, update, delete, upsert
* [Data Stores](/features/data-stores) — the feature overview