Skip to main content

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) or json

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:

OperatorExample
=, !=, <>name = 'Alice'
<, <=, >, >=age > 18
IS NULL, IS NOT NULLdeleted_at IS NULL
IN (...), NOT IN (...)status IN ('active', 'pending')
BETWEEN ... AND ...age BETWEEN 20 AND 30
LIKEname 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 as table read)
  • --limit, -l: Row limit to push down
  • --verbose, -v: List every split with its files
  • --format, -f: Output format: table (default) or json

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, including 0. 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) or table.

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) or table.

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) or table. 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) or json.

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, or changelog.
  • --limit, -l: Positive maximum number of manifests across all selected lists. Omit it to show all.
  • --format, -f: Output format: table (default) or json.

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's manifest/ directory, not a path. Required.
  • --format, -f: Output format: json (default) or table.

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) or json.

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) or table.

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) or json

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

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) or json

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.