Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jackylee-ch wants to merge 2 commits into
base: main
Choose a base branch
from
+51 −0
Open

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

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bc9e242
docs: document the $files and $branches system tables
jackylee-ch Aug 4, 2026
36c39f5
docs: correct the partition and file_path column descriptions
jackylee-ch Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions docs/src/sql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1732,6 +1732,24 @@ Columns:
| `create_time` | TIMESTAMP | Tag creation time |
| `time_retained` | STRING | Retention duration |

### $branches

View all branches of a table:

```sql
SELECT * FROM paimon.default.my_table$branches;
```

Columns:

| Column | Type | Description |
|---|---|---|
| `branch_name` | STRING | Branch name |
| `create_time` | TIMESTAMP | Branch creation time |

Unlike the other system tables, `$branches` ignores a `$branch_<name>` prefix and
always reports the branches of the base table.

### $manifests

View manifest files of the latest snapshot:
Expand All @@ -1754,6 +1772,39 @@ Columns:
| `min_row_id` | BIGINT | Minimum row id covered (when row tracking is enabled) |
| `max_row_id` | BIGINT | Maximum row id covered (when row tracking is enabled) |

### $files

View the data files of the current snapshot, with per-file statistics:

```sql
SELECT * FROM paimon.default.my_table$files;
```

Columns:

| Column | Type | Description |
|---|---|---|
| `partition` | STRING | Partition spec, formatted as a Java row cast string; `{}` for unpartitioned tables |
| `bucket` | INT | Bucket id the file belongs to |
| `file_path` | STRING | Full data file path, or `external_path` when the file has one |
| `file_format` | STRING | Data file format, such as `parquet` or `orc` |
| `schema_id` | BIGINT | Id of the schema the file was written with |
| `level` | INT | LSM level of the file (`0` for unmerged files) |
| `record_count` | BIGINT | Number of rows in the file, including deletes |
| `file_size_in_bytes` | BIGINT | File size in bytes |
| `min_key` | STRING | Minimum primary key in the file, `NULL` for append tables |
| `max_key` | STRING | Maximum primary key in the file, `NULL` for append tables |
| `null_value_counts` | STRING | Per-column null counts, as a `{col=count}` map |
| `min_value_stats` | STRING | Per-column minimum values, as a `{col=value}` map |
| `max_value_stats` | STRING | Per-column maximum values, as a `{col=value}` map |
| `min_sequence_number` | BIGINT | Minimum sequence number in the file |
| `max_sequence_number` | BIGINT | Maximum sequence number in the file |
| `creation_time` | TIMESTAMP | File creation time |
| `delete_row_count` | BIGINT | Number of delete rows in the file |
| `file_source` | STRING | How the file was produced: `APPEND` or `COMPACT` |
| `first_row_id` | BIGINT | First row id in the file (when row tracking is enabled) |
| `write_cols` | ARRAY | Columns actually written, for data-evolution tables |

### $partitions

View all partitions of a table with aggregated record counts and file sizes:
Expand Down
Loading