CLI: Query and Inspect
Inspect schemas, snapshots, manifests, partitions, scan plans, and table rows from the terminal. Configure a catalog with the CLI quick start first. The examples use existing tables and illustrative output; replace table and column names with your own.
Table Read
Read data from a Paimon table and display it in a tabular format.
paimon table read mydb.users
Options:
--select, -s: Select specific columns to read (comma-separated)--where, -w: Filter condition in SQL-like syntax--limit, -l: Maximum number of results to display (default: 100)--format, -f: Output format:table(default) orjson
Examples:
# Read with limit
paimon table read mydb.users -l 50
# Read specific columns
paimon table read mydb.users -s id,name,age
# Filter with WHERE clause
paimon table read mydb.users --where "age > 18"
# Combine select, where, and limit
paimon table read mydb.users -s id,name -w "age >= 20 AND city = 'Beijing'" -l 50
# Output as JSON (for programmatic use)
paimon table read mydb.users --format json
WHERE Operators
The --where option supports SQL-like filter expressions:
| Operator | Example |
|---|---|
=, !=, <> | name = 'Alice' |
<, <=, >, >= | age > 18 |
IS NULL, IS NOT NULL | deleted_at IS NULL |
IN (...), NOT IN (...) | status IN ('active', 'pending') |
BETWEEN ... AND ... | age BETWEEN 20 AND 30 |
LIKE | name LIKE 'A%' |
Multiple conditions can be combined with AND and OR (AND has higher precedence). Parentheses are supported for grouping:
# AND condition
paimon table read mydb.users -w "age >= 20 AND age <= 30"
# OR condition
paimon table read mydb.users -w "city = 'Beijing' OR city = 'Shanghai'"
# Parenthesized grouping
paimon table read mydb.users -w "(age > 18 OR name = 'Bob') AND city = 'Beijing'"
# IN list
paimon table read mydb.users -w "city IN ('Beijing', 'Shanghai', 'Hangzhou')"
# BETWEEN
paimon table read mydb.users -w "age BETWEEN 25 AND 35"
# LIKE pattern
paimon table read mydb.users -w "name LIKE 'A%'"
# IS NULL / IS NOT NULL
paimon table read mydb.users -w "email IS NOT NULL"
Literal values are automatically cast to the appropriate Python type based on the table schema (e.g., INT fields cast to int, DOUBLE to float).
Output:
id name age city
1 Alice 25 Beijing
2 Bob 30 Shanghai
3 Charlie 35 Guangzhou
4 David 28 Shenzhen
5 Eve 32 Hangzhou
Table Explain
Show the scan plan of a query without reading any data: the target snapshot, the pushed-down predicate / projection / limit, the partition / bucket / file-stats pruning funnel, and split-level signals (raw-convertible ratio, deletion-vector ratio, level histogram, files-per-split and split-size distribution). Useful for previewing the pruning effect of a predicate before actually running the read.
paimon table explain mydb.events
Options:
--select, -s: Project specific columns (comma-separated)--where, -w: Filter condition in SQL-like syntax (same operators astable read)--limit, -l: Row limit to push down--verbose, -v: List every split with its files--format, -f: Output format:table(default) orjson
Examples:
# Whole-table scan plan
paimon table explain mydb.events
# Push filter and projection through the planner
paimon table explain mydb.events --where "dt = '2026-05-16' AND id = 7" -s dt,id,val
# List every split (and its files) instead of just the aggregates
paimon table explain mydb.events -w "dt = '2026-05-16'" --verbose
# Machine-readable output for scripting (level_histogram keys are JSON strings)
paimon table explain mydb.events --format json
Output:
== PyPaimon Scan Plan ==
Table: mydb.events (PK, HASH_FIXED)
Snapshot: 5 (schema 0)
Predicate: (dt = '2026-05-16') AND (id = 7)
Projection: [dt, id, val]
Limit: <none>
Partition pruning: 20 -> 4 (pruned 16)
Bucket pruning: 4 -> 1 (pruned 3)
File skipping: 1 -> 1 (pruned 0)
Splits: 1
raw-convertible: 1 / 1
with DV: 0 / 1
all-above-L0: 0 / 1
files/split: min=1 max=1 avg=1.00
size/split: min=2.6 KiB p50=2.6 KiB p95=2.6 KiB max=2.6 KiB
Files: 1
Total size: 2.6 KiB
Estimated rows: 10 (merged: 10)
Level histogram: L0=1
Deletion files: 0
explain reads the manifest list and manifest files but never opens any data files, so it is dramatically cheaper than a real read on large tables.
Table Get
Get and display table schema information in JSON format. The output format is the same as the schema JSON format used in table create, making it easy to export and reuse table schemas.
paimon table get mydb.users
Output:
{
"fields": [
{"id": 0, "name": "user_id", "type": "BIGINT"},
{"id": 1, "name": "username", "type": "STRING"},
{"id": 2, "name": "email", "type": "STRING"},
{"id": 3, "name": "age", "type": "INT"},
{"id": 4, "name": "city", "type": "STRING"},
{"id": 5, "name": "created_at", "type": "TIMESTAMP"},
{"id": 6, "name": "is_active", "type": "BOOLEAN"}
],
"partitionKeys": ["city"],
"primaryKeys": ["user_id"],
"options": {
"bucket": "4",
"changelog-producer": "input"
},
"comment": "User information table"
}
Note: The output JSON can be saved to a file and used directly with the table create command to recreate the table structure.
Use an explicit schema ID or resolve the schema referenced by a historical snapshot:
paimon table get mydb.users --schema-id 0
paimon table get mydb.users --schema-id 3 --format json
paimon table get mydb.users --snapshot-id 42 --format json
paimon table get mydb.users --schema-id 3 --format table
Options:
--schema-id: Schema ID to inspect, including0. Defaults to the current table schema.--snapshot-id: Read the schema ID recorded in this snapshot, then load that schema. Mutually exclusive with--schema-id.--format, -f: Output format,json(default) ortable.
Table List Schemas
List available schema versions in ascending numeric schema-ID order. JSON is the default output
format. Each array element contains the complete serialized TableSchema, including its ID,
metadata version, field definitions and IDs, highest field ID, keys, options, comment, and update
time. Field definitions preserve nested types, nullability, and column comments.
# List all available schema versions as JSON
paimon table list-schemas mydb.users
# Return the oldest 20 available versions
paimon table list-schemas mydb.users --limit 20
# Display schema definitions and update times in a readable table
paimon table list-schemas mydb.users --format table
Options:
--limit, -l: Maximum number of schemas to return, starting with the oldest. Must be positive; omitted by default, which returns all available schemas.--format, -f: Output format,json(default) ortable.
Example JSON for a table with one schema version:
[
{
"version": 3,
"id": 0,
"fields": [
{"id": 0, "name": "user_id", "type": "BIGINT NOT NULL"}
],
"highestFieldId": 0,
"partitionKeys": [],
"primaryKeys": [],
"options": {"bucket": "-1"},
"comment": null,
"timeMillis": 1700000000123
}
]
Table Snapshot
Get the latest snapshot or inspect a specific retained snapshot. JSON remains the default output format for compatibility with existing scripts. The snapshot includes its schema ID, manifest-list references, commit information, record counts, and other available metadata.
paimon table snapshot mydb.users
# Inspect a historical snapshot without falling back to the latest snapshot
paimon table snapshot mydb.users --snapshot-id 42 --format json
# Display all available fields as a readable table
paimon table snapshot mydb.users --snapshot-id 42 --format table
Options:
--snapshot-id: Positive snapshot ID to inspect. Omit it to resolve the latest snapshot once.--format, -f: Output format:json(default) ortable. Table output includes the UTC commit time alongside the original epoch-millisecond value.
The command fails with a non-zero exit status if the table has no snapshots, the requested snapshot is unavailable, or its metadata cannot be read. Errors are written to stderr.
Output:
{
"version": 3,
"id": 5,
"schemaId": 1,
"baseManifestList": "manifest-list-5-base-...",
"deltaManifestList": "manifest-list-5-delta-...",
"changelogManifestList": null,
"totalRecordCount": 1000,
"deltaRecordCount": 100,
"changelogRecordCount": null,
"commitUser": "user-123",
"commitIdentifier": 1709123456789,
"commitKind": "APPEND",
"timeMillis": 1709123456789,
"watermark": null,
"statistics": null,
"nextRowId": null
}
Table List Snapshots
List retained snapshots in ascending numeric snapshot-ID order. The default table output shows
the snapshot ID, schema ID, commit time in UTC, commit kind, commit user, and total, delta, and
changelog record counts. Missing optional counts are displayed as -.
# List all available snapshots, oldest first
paimon table list-snapshots mydb.users
# Show the first 20 snapshots in that order
paimon table list-snapshots mydb.users --limit 20
# Export complete snapshot metadata as a JSON array
paimon table list-snapshots mydb.users --format json
Options:
--limit, -l: Maximum number of snapshots to display; must be a positive integer. Omit it to list all available snapshots.--format, -f: Output format:table(default) orjson.
JSON output contains the same snapshot objects as table snapshot, preserving metadata field
names such as schemaId, timeMillis, and baseManifestList. Timestamps remain epoch milliseconds
and record counts remain integers. Optional fields with no value are omitted.
An empty table returns an empty JSON array or a No snapshots found message, with a successful
exit status. Expired snapshots are not reconstructed. If a snapshot disappears during listing,
it is skipped; other metadata read errors fail the command. These commands read snapshot metadata
without opening manifest or data files or modifying the table.
Table List Manifests
List the manifests referenced by the latest or a specific retained snapshot. By default, the command includes base, delta, and changelog manifest lists, in that order.
paimon table list-manifests mydb.orders
# Inspect one manifest-list type in a historical snapshot
paimon table list-manifests mydb.orders --snapshot-id 42 --type delta
# Limit the total number of manifests and export structured JSON
paimon table list-manifests mydb.orders --limit 20 --format json
Options:
--snapshot-id: Positive snapshot ID. Omit it to use the latest snapshot.--type:all(default),base,delta, orchangelog.--limit, -l: Positive maximum number of manifests across all selected lists. Omit it to show all.--format, -f: Output format:table(default) orjson.
Table output groups manifests by type and manifest-list file, showing file names, sizes in bytes,
added/deleted file counts, schema IDs, partition statistics, and row-ID bounds. Missing values are
displayed as -. JSON output contains table, snapshot_id, and a manifests array.
Output:
Table: mydb.orders
Snapshot: 6
base (manifest-list-example):
file_name file_size num_added_files num_deleted_files schema_id min_partition_stats max_partition_stats min_row_id max_row_id
manifest-example 2317 1 0 0 {} {} - -
Table Manifest
Read a manifest file and display its original ADD and DELETE entries, including file metadata
and statistics. JSON is the default output format. Use the file_name returned by list-manifests:
paimon table manifest mydb.orders --file manifest-example
# Display complete metadata as a readable table
paimon table manifest mydb.orders --file manifest-example --format table
Options:
--file: Manifest file name within the table'smanifest/directory, not a path. Required.--format, -f: Output format:json(default) ortable.
Output contains table, manifest_file, manifest_path, and entries. Table output displays
the complete entries array as JSON in a single field. Historical manifests can be inspected
while their files remain available.
Output:
{
"table": "mydb.orders",
"manifest_file": "manifest-example",
"manifest_path": "/warehouse/mydb.db/orders/manifest/manifest-example",
"entries": [
{
"kind": "ADD",
"partition": {},
"bucket": 0,
"total_buckets": -1,
"file": {
"file_name": "data-example.parquet",
"file_size": 803,
"row_count": 2,
"schema_id": 0,
"value_stats": {"min_values": {}, "max_values": {}, "null_counts": {}},
"first_row_id": null
}
}
]
}
Table List Files
List the live data files referenced by the latest or a specific retained snapshot.
paimon table list-files mydb.orders
paimon table list-files mydb.orders --snapshot-id 1 --format json
paimon table list-files mydb.orders --bucket 0 --limit 20
Options:
--snapshot-id: Positive snapshot ID. Omit it to use the latest snapshot.--bucket: Only display files in the specified bucket.--limit, -l: Positive maximum number of live files after filtering. Omit it to show all.--format, -f: Output format:table(default) orjson.
Table output follows the $files system table, with snapshot_id as the first column and
delete_row_count for the delete-row count. It includes partition, bucket, full file path, format,
file schema ID, level, record count, size, key bounds, column statistics, sequence-number bounds,
creation time, file source, first row ID, and written columns. JSON output contains
table, snapshot_id, and a files array.
Output (selected columns):
snapshot_id bucket file_path file_format record_count file_size_in_bytes creation_time
1 0 /warehouse/mydb.db/orders/bucket-0/data-example.parquet parquet 2 803 2026-11-14T18:23:49.778000
Table File
Inspect a Parquet file's schema and footer metadata without reading data records. Use the
file_path returned by list-files:
paimon table file mydb.orders --file /warehouse/mydb.db/orders/bucket-0/data-example.parquet
paimon table file mydb.orders --file /warehouse/mydb.db/orders/bucket-0/data-example.parquet --format table
Options:
--file: Actual Parquet file path or filesystem URI. Required.--format, -f: Output format:json(default) ortable.
If a file: input matches both a literal path and a different URL-decoded file, the command
reports an ambiguity. Use a plain filesystem path to select the intended file.
Output includes the file path, format, size, schema, and Parquet metadata such as row groups and
column statistics. Table output displays schema and metadata as indented, multiline JSON.
Output (selected fields):
{
"table": "mydb.orders",
"file_path": "/warehouse/mydb.db/orders/bucket-0/data-example.parquet",
"file_format": "parquet",
"file_size_in_bytes": 803,
"schema": {"arrow": "id: int64\nname: string"},
"metadata": {"num_columns": 2, "num_rows": 2, "num_row_groups": 1}
}
Table List Partitions
List partitions of a Paimon table. Supports optional pattern filtering to match specific partitions.
paimon table list-partitions mydb.orders
Options:
--pattern, -p: Partition name pattern to filter partitions--format, -f: Output format:table(default) orjson
Examples:
# List all partitions
paimon table list-partitions mydb.orders
# List partitions matching a pattern
paimon table list-partitions mydb.orders --pattern "dt=2024*"
# Output as JSON (for programmatic use)
paimon table list-partitions mydb.orders --format json
Output:
Partition RecordCount FileSizeInBytes FileCount LastFileCreationTime UpdatedAt UpdatedBy
dt=2024-01-01,region=us 500 1048576 10 1704067200000 1704153600000 admin
dt=2024-01-02,region=eu 300 524288 5 1704153600000 1704240000000 user1
dt=2024-01-03,region=us 200 262144 3 1704240000000 1704326400000 admin
Table Full-Text Search
Perform full-text search on a Paimon table with a native full-text index and display matching rows.
paimon table full-text-search mydb.articles --column content --query "paimon lake"
Options:
--column: Text column to search on - Required--query, -q: Query text to search for - Required--limit, -l: Maximum number of results to return (default: 10)--select, -s: Select specific columns to display (comma-separated)--format, -f: Output format:table(default) orjson
Examples:
# Basic full-text search
paimon table full-text-search mydb.articles --column content -q "paimon lake"
# Search with limit
paimon table full-text-search mydb.articles --column content -q "streaming data" -l 20
# Search with column projection
paimon table full-text-search mydb.articles --column content -q "paimon" -s "id,title,content"
# Output as JSON
paimon table full-text-search mydb.articles --column content -q "paimon" -f json
Output:
id content
0 Apache Paimon is a streaming data lake platform
2 Paimon supports real-time data ingestion and...
4 Data lake platforms like Paimon handle large-...
Note: The table must have a full-text index built on the target column. PyPaimon uses the tokenizer settings stored in the index metadata and requires the full-text extra for full-text reads:
pip install 'pypaimon[full-text]'
See Global Index for how to create full-text indexes.