Skip to content

docs: document the $files and $branches system tables - #669

Open
jackylee-ch wants to merge 1 commit into
apache:mainfrom
jackylee-ch:docs/system-tables-files-branches
Open

docs: document the $files and $branches system tables#669
jackylee-ch wants to merge 1 commit into
apache:mainfrom
jackylee-ch:docs/system-tables-files-branches

Conversation

@jackylee-ch

Copy link
Copy Markdown
Contributor

$files and $branches are registered system tables — SYSTEM_TABLE_NAMES lists
both, and the 0.3.0 release notes already advertise $files — but the SQL
reference documented only 9 of the 11, so users had no way to learn the column
names without reading system_tables/files.rs. $files is the most useful of the
set for debugging compaction and skew, which makes the omission the more visible
one.

Fix: add a ### $files and a ### $branches section to docs/src/sql.md,
following the existing $tags/$table_indexes shape (purpose sentence, sample
query, column table). Column names and order are taken verbatim from
files_schema() (20 columns) and branches_schema() (2 columns); Arrow types are
rendered in the SQL spelling the surrounding sections already use. The
$branches section also notes the one behavior that sets it apart from its
neighbours: it ignores a $branch_<name> prefix and always reports the base
table's branches.

Docs only — no code or test changes.

Comment thread docs/src/sql.md

| Column | Type | Description |
|---|---|---|
| `partition` | STRING | Partition spec for the file, or `NULL` for unpartitioned tables |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Rust implementation returns "{}" for unpartitioned tables, not NULL, so this description does not match the actual $files output.

Comment thread docs/src/sql.md
|---|---|---|
| `partition` | STRING | Partition spec for the file, or `NULL` for unpartitioned tables |
| `bucket` | INT | Bucket id the file belongs to |
| `file_path` | STRING | Data file name |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

file_path contains the full data file path, using external_path when present, rather than only the data file name.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants