Command Line Interface

Use paimon to manage catalogs and tables, inspect data, and run queries from your terminal. Start with the local walkthrough, then use the task references below for the full command options.

Installation

The paimon command is included in the base package:

python -m pip install pypaimon
paimon --help

See Installation for environment setup and optional packages.

Basic Usage

Commands read catalog options from paimon.yaml in the current directory. Pass -c before the command to select a different configuration:

paimon -c paimon.yaml catalog list-dbs
paimon table read --help

For local storage, save the following as paimon.yaml. Use a fresh warehouse for the walkthrough, or choose new database and table names if you run it again.

metastore: filesystem
warehouse: /tmp/paimon-cli-warehouse

For a REST catalog, replace the configuration with your server and warehouse:

metastore: rest
uri: http://localhost:8080
warehouse: catalog_name

Try a local workflow

The following steps use the filesystem configuration above. They create a small append table and import two rows without a catalog server.

Save this schema as people-schema.json:

{
  "fields": [
    {"id": 0, "name": "id", "type": "BIGINT"},
    {"id": 1, "name": "name", "type": "STRING"}
  ],
  "options": {"bucket": "-1"}
}

Save the input rows as people.json:

[
  {"id": 1, "name": "Alice"},
  {"id": 2, "name": "Bob"}
]

Run these commands from the directory containing the three files:

paimon db create demo --ignore-if-exists
paimon table create demo.people --schema people-schema.json
paimon table import demo.people --input people.json
paimon table read demo.people --select id,name --where "id = 2" --format json

The query returns the row with id 2 and name Bob. Inspect what you created:

paimon table get demo.people
paimon table snapshot demo.people
paimon table explain demo.people --where "id = 2"

Table Commands

Task	Reference
Read rows, inspect a plan, or search text	Query and inspect
Show schemas, snapshots, and partitions	Table metadata
Create a table or import local files	Create and change tables
Alter a schema or table options	Table alter

Catalog Commands

List the databases available in the configured catalog.

Database Commands

Create, inspect, change, or drop databases, and list their tables.

Tag Commands

Create and inspect tags to retain a snapshot for future reads.

Branch Commands

Manage branches to keep separate table histories.

SQL Command

Run a query or start the interactive SQL shell. SQL requires Python 3.10 or newer and the sql extra.