Skip to main content

Row Index

Row index sections store lookup metadata for fast access to specific rows in a table data section.

--- row_index:<table_name>:<primary_key_columns>

Row indexes are machine sections. They live at the bottom of the file with other machine sections and do not replace CSV data.

Required Encoding​

Row indexes use fixed-width records with no section-local headers. The row index section title is padded with spaces to section_title_length. Record keys use machine_key_width; record values use machine_value_width.

--- row_index:workers:id                                                        
w_001                                                                                                                  1                                      46
w_002                                                                                                                  2                                      50
w_003                                                                                                                  3                                      48

Records store primary-key values, row numbers, and row lengths, not byte offsets. The indexed columns are the table schema primary key columns.

The row-index section suffix names the primary-key column set. Single-column primary keys use the column name, such as id. Composite primary keys join column names with +, such as worker_id+work_date.

The row index record count is derived from the section length stored in section_index.

Supported Strategy​

CSDB v1 supports one row index strategy:

  • sorted_binary: sorted fixed-width entries searched with binary search.

Primary-key row indexes implicitly use sorted_binary; the strategy is not repeated inside the section.

Row Locations​

Each row record stores at least:

<KEY> <ROW_NUMBER> <ROW_LENGTH>

ROW_NUMBER is 1-based and excludes the CSV header.

ROW_LENGTH is the exact byte length of the row, including the row ending when present.

Readers compute row offsets by summing row lengths before the target row number. The absolute row offset is:

table_data_section_offset + sum(row_lengths before ROW_NUMBER)

Composite keys must use a stable encoded key, such as JSON-array text, before padding.

Non-primary indexes are not machine-indexed in v1.

Stale Indexes​

A row index is stale when it points to rows that no longer match the CSV data.

Readers must detect stale row indexes when validation is requested. Readers may support recovery mode by scanning the CSV data and rebuilding lookup metadata in memory.