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

# Overview

> Mental model for databases, tables, indexes, and queries

ToraDB organizes data as a **local database directory** containing **tables**. Each table holds documents (text and optional vectors/metadata), stored in Parquet **segments** with optional **index sidecars** for fast retrieval.

## Flow

```mermaid theme={null}
flowchart LR
  DB[Database] --> T1[Table]
  T1 --> Ingest[add / ingest]
  Ingest --> Seg[Parquet segments]
  Seg --> Idx[Index sidecars]
  Idx --> Q[search / sql]
```

## Core objects

| Object | Role |
| - | - |
| `Database` | Open a path on disk (`toradb.local(path)`). |
| `Table` | Named collection of documents; created with `mode="text"` or `mode="hybrid"`. |
| `SearchResults` | Ranked hits from `table.search` or retrieval `SELECT`. |
| `SearchResults.provenance` | Structured JSON trace of candidate flow across retrieval tiers (when `explain=True`). |
| Analytics result | Tabular output from `GROUP BY` / aggregates via `db.sql`. |

## Two ways to query

1. **Python SDK** — `table.search(...)` for retrieval; `db.sql(...)` for SQL.
2. **CLI** — `toradb query`, `toradb sql`, `toradb tables`, `toradb reindex`.

Indexes are built automatically on ingest where possible; use [reindex and compact](/guides/reindex-compact) to rebuild BM25, HNSW, or DiskANN after bulk changes.

## Related

* [Table modes](/concepts/table-modes)
* [On-disk layout](/concepts/on-disk-layout)
* [Python SDK guide](/guides/python)
* [Retrieval provenance](/guides/provenance)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.