Java API

Use the Java API to access Paimon tables without a processing engine, or to implement an engine integration. This page sets up a catalog and a sample table used by the reading and writing guides.

Task	Guide
Manage databases, tables, and schemas	Catalog API
Plan splits, filter rows, and follow new snapshots	Java Reads
Prepare and commit batch or streaming writes	Java Writes
Convert row values and build predicates	Types and Predicates

For a Flink application, use the Flink API so the engine can manage checkpoints and commits.

Dependency

Maven dependency:

<dependency>
  <groupId>org.apache.paimon</groupId>
  <artifactId>paimon-bundle</artifactId>
  <version>2.1.0</version>
</dependency>

Or download the jar file:

Paimon Bundle.

Add the Hadoop libraries required by your environment to the runtime classpath. For remote storage, configure the corresponding filesystem dependencies and credentials.

Create Catalog

CatalogFactory selects a catalog from the supplied options. The helper below uses a local filesystem warehouse. Save it as CreateCatalog.java alongside the example classes, and change the warehouse path for your environment.

import org.apache.paimon.catalog.Catalog;
import org.apache.paimon.catalog.CatalogContext;
import org.apache.paimon.catalog.CatalogFactory;
import org.apache.paimon.fs.Path;
import org.apache.paimon.options.Options;

public class CreateCatalog {

    public static Catalog createFilesystemCatalog() {
        CatalogContext context =
                CatalogContext.create(new Path("file:///tmp/paimon-api-warehouse"));
        return CatalogFactory.createCatalog(context);
    }

    public static Catalog createHiveCatalog() {
        // Add the Hive client libraries and configure these paths for your environment.
        Options options = new Options();
        options.set("warehouse", "hdfs:///path/to/warehouse");
        options.set("metastore", "hive");
        options.set("uri", "thrift://localhost:9083");
        options.set("hive-conf-dir", "/path/to/hive/conf");
        options.set("hadoop-conf-dir", "/path/to/hadoop/conf");
        return CatalogFactory.createCatalog(CatalogContext.create(options));
    }
}

Keep the catalog open while using its tables, and close it when the application finishes. See Catalogs for other catalog implementations and their configuration.

Create Table

Run this example once in a fresh warehouse. It creates my_db.my_table with a string primary key f0, an integer value f1, and two fixed buckets. The following guides use this same schema.

import org.apache.paimon.catalog.Catalog;
import org.apache.paimon.catalog.Identifier;
import org.apache.paimon.schema.Schema;
import org.apache.paimon.types.DataTypes;

public class CreateTable {

    public static void main(String[] args) throws Exception {
        Schema schema = Schema.newBuilder()
                .column("f0", DataTypes.STRING().notNull())
                .column("f1", DataTypes.INT())
                .primaryKey("f0")
                .option("bucket", "2")
                .build();

        try (Catalog catalog = CreateCatalog.createFilesystemCatalog()) {
            catalog.createDatabase("my_db", true);
            catalog.createTable(Identifier.create("my_db", "my_table"), schema, false);
        }
    }
}

true in createDatabase ignores an existing database; false in createTable reports an existing table. This avoids silently reusing a table with a different schema. For an append table, omit the primary key and choose the appropriate append table layout.

Get Table

Load the table by identifier within the catalog's lifetime:

import org.apache.paimon.catalog.Catalog;
import org.apache.paimon.catalog.Identifier;
import org.apache.paimon.table.Table;

try (Catalog catalog = CreateCatalog.createFilesystemCatalog()) {
    Table table = catalog.getTable(Identifier.create("my_db", "my_table"));
    // Create read or write builders here.
}

Next, run the batch write example, followed by the batch read example. Catalog operations and examples that show a complete class declare throws Exception for brevity; applications should handle failures at their own error-handling boundary.

Read and write data

Batch Read

See Java Reads: Batch Read for split planning, projection, and row filtering.

Adjust Read Batch Size at Runtime

See runtime batch sizing for Parquet and ORC readers.

Batch Write

See Java Writes: Batch Write for preparing and committing a batch.

Stream Read

See Java Reads: Stream Read for continuous planning and checkpoint recovery.

Stream Write

See Java Writes: Stream Write for commit identities and retry handling.

Reference

Data Types

See the internal value mapping before constructing InternalRow values.

Predicate Types

See the predicate reference for supported filter builders.