> ## 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.

# Database

> toradb.local, Database methods

## Module functions

### `toradb.local(path: str) -> Database`

Open or create a database at `path`.

```python theme={null}
import toradb
db = toradb.local("./my_db")
```

### `toradb.connect(path: str) -> Database`

Alias for `local`.

***

## `Database`

### `Database(path: str)`

Same as `toradb.local(path)`.

### `create_table(name, mode=None, schema=None) -> Table`

<ParamField path="name" type="str" required>
  Table name.
</ParamField>

<ParamField path="mode" type="str" default="text">
  `text` or `hybrid`.
</ParamField>

<ParamField path="schema" type="dict" optional>
  Column definitions for hybrid tables, e.g. `{"embedding": "vector[8]"}`.
</ParamField>

```python theme={null}
docs = db.create_table("docs", mode="text")
```

### `table(name: str) -> Table`

Open an existing table without running `CREATE TABLE`.

### `list_tables() -> list[str]`

Return table names in the database.

### `sql(query: str) -> str | SearchResults | AnalyticsResults`

Execute one SQL statement. Return type depends on the statement:

* Retrieval `SELECT` → `SearchResults`
* Analytics `SELECT` with `GROUP BY` → analytics object with `.to_pandas()`
* DDL / catalog → `str` message

### `sql_stream(query: str, batch_size=128) -> list[SearchResults]`

Page through a retrieval `SELECT`. Does not support `GROUP BY` or `EXPLAIN`.

### `reindex(table, using=None, column=None) -> str`

<ParamField path="using" type="str" default="BM25">
  Index type: `BM25`, `HNSW`, `DISKANN`, etc.
</ParamField>

<ParamField path="column" type="str" default="text">
  Column to index.
</ParamField>

```python theme={null}
db.reindex("articles", using="BM25")
```

### `begin_bulk_ingest(table: str) -> None`

Start a bulk load session on `table`. Defers per-batch dense index rebuilds and table-level index writes until [`finish_bulk_ingest`](#finish_bulk_ingesttable-compactfalse-reindex_bm25false---none).

### `bulk_ingest_active(table: str) -> bool`

Return whether `table` is in an active bulk ingest session.

### `finish_bulk_ingest(table, compact=False, reindex_bm25=False) -> None`

Finalize indexes after bulk load: builds deferred segment BM25 sidecars, merges table indexes, and reloads corpus texts for search.

<ParamField path="compact" type="bool" default="false">
  Run segment compaction after writing table indexes.
</ParamField>

<ParamField path="reindex_bm25" type="bool" default="false">
  Extra `CREATE INDEX` BM25 pass (usually unnecessary — finish already builds BM25).
</ParamField>

```python theme={null}
db.begin_bulk_ingest("docs")
# ... many add / add_arrow calls ...
db.finish_bulk_ingest("docs", compact=True)
```

### `fetch_documents(table: str, ids: list[int]) -> dict[int, dict]`

Load **text** and **metadata** for specific document ids. Uses the in-memory corpus when loaded; otherwise reads only the Parquet segments that can contain those ids (via `segment_id_ranges` in the table manifest). On disk, ToraDB maps contiguous ids to row offsets and uses Parquet row selection (plus optional page indexes) instead of scanning whole segments. Pairs with [`segment_only`](#) bulk ingest when search returns ids without loading the full table into RAM.

```python theme={null}
results = db.table("passages").search("diabetes treatment", top_k=10)
ids = [int(r["id"]) for r in results.to_pandas()["id"]]
docs = db.fetch_documents("passages", ids)
print(docs[ids[0]]["text"])
```

### `index_build_status(table: str) -> dict | None`

Read `{table}/indexes/build_status.json` without loading the full corpus. Returns `None` when no build is in progress and no status file exists.

### `resume_index_build(table: str, compact=False) -> None`

Resume or rerun index build after crash or partial finish (idempotent segment BM25 skip when sidecars are current).

See [Bulk load](/guides/ingest#bulk-load-100k-rows).


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