Indexes

In-memory hash indexes accelerate eq (==) and in_ lookups on fields declared with index=True, unique=True, or primary_key=True. Indexes are rebuilt from table data on each access — the source of truth is always the data.

index

In-memory hash indexes rebuilt from table data.

TinyStore stores data as JSON files loaded fully into memory. An index accelerates point lookups (eq, in_) on indexed fields from O(n) row scans to O(1) hash-map probes.

Design decisions (Phase 6, correctness-first MVP):

• Source of truth is the table data, not the index. Indexes are rebuilt from the current rows list — they are never persisted to disk and never the authority. A rebuild is O(n), no worse than the JSON parse that already happened.
• Rebuild-on-change. :meth:IndexManager.ensure rebuilds only when the rows list identity changes (tracked via id()), avoiding redundant builds within a single operation that reads state once.
• PK index is always built (primary keys are always indexed). Unique and secondary indexes are built for fields declared unique=True or index=True in the schema.

IndexManager

IndexManager(schema: TableSchema)

In-memory hash index over a table's rows.

Each indexed field maps to {value: [row_indices]}. Built from a rows list via :meth:build / :meth:ensure; queried via :meth:lookup.

has_index

has_index(field: str) -> bool

Return True if field has an index.

build

build(rows: list[dict[str, Any]]) -> None

Build all index maps from rows.

ensure

ensure(rows: list[dict[str, Any]]) -> None

Rebuild the index from rows.

Always rebuilds for correctness. The source of truth is the table data, and since all rows are already in memory (parsed from JSON), the O(n) build cost is negligible compared to the I/O already paid.

lookup

lookup(field: str, value: Any) -> list[int] | None

Return row indices where field == value.

Returns None if field is not indexed (caller should scan). Returns an empty list if indexed but no match.

lookup_many

lookup_many(
    field: str, values: list[Any]
) -> list[int] | None

Return row indices where field is in values.

Returns None if field is not indexed. Duplicates in the result are not removed — callers should deduplicate if needed.