SQL Procedures, Views & Configuration Reference on Mooncake

Create Columnstore Table

Mon, 01 Jan 0001 00:00:00 +0000

In pg_mooncake, columnstore tables are created as real-time mirrors of existing PostgreSQL rowstore (heap or partitioned) tables using the mooncake.create_table procedure.

Procedure Signature

CALL mooncake.create_table(
    dst text,
    src text,
    src_uri text DEFAULT NULL,
    table_config json DEFAULT NULL
);

Parameter	Type	Default	Description
`dst`	`text`	(Required)	Name of the destination columnstore mirror table to create (supports `schema.table`, defaults to `public` if unqualified).
`src`	`text`	(Required)	Name of the source PostgreSQL rowstore or partitioned table to replicate from (supports `schema.table`).
`src_uri`	`text`	`NULL`	Connection URI (`postgresql://user:pass@host:port/dbname`) of a remote PostgreSQL instance when replicating from an external database. When `NULL`, replicates from the current local database.
`table_config`	`json`	`NULL`	Optional JSON object configuring Moonlink storage and ingestion settings (such as `write_buffer_size` or initial data copy behavior).

Parameter Name: src_uri (Not source_uri)

Earlier upstream documentation contained a typo showing source_uri => 'postgresql://...'. The actual parameter name in pg_mooncake’s SQL definition (src/functions.rs) is src_uri. Always use src_uri => 'postgresql://...' when calling mooncake.create_table with named arguments.

Query Columnstore Table & Supported Query Shapes

Mon, 01 Jan 0001 00:00:00 +0000

Columnstore mirror tables created with CALL mooncake.create_table(dst, src) are queried using standard PostgreSQL SELECT syntax. Behind the scenes, pg_mooncake and pg_duckdb 1.2.0 translate and route analytical scans to the embedded DuckDB v2.0.0 vectorized execution engine.

How Queries Work

When you query a USING mooncake table:

LSN Synchronization: duckdb_mooncake checks PostgreSQL’s current WAL write LSN and waits for moonlink to ingest all committed transactions up to that LSN.
Segment Elimination: DuckDB 2.0 inspects multi-file Parquet column min/max statistics to skip files and row groups that cannot match your WHERE predicates.
Zero-Copy Hybrid Scan: Flushed Parquet files, Roaring Bitmap deletion vectors, and the in-memory Apache Arrow write buffer are scanned in parallel across DuckDB worker threads (duckdb.threads).

You can verify that DuckDB is executing your query by running EXPLAIN:

Apache Iceberg v2 & Object Storage Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Every columnstore mirror table in pg_mooncake (v0.3.0) is backed by moonlink, which writes data as standard Parquet files and maintains Apache Iceberg v2 table metadata.

By default, Moonlink writes files to the local filesystem under $PGDATA/pg_mooncake/. You can configure pg_mooncake to write directly to Amazon S3, Cloudflare R2, MinIO, or Google Cloud Storage (GCS) so external engines (DuckDB, Apache Spark, Trino, Snowflake, PyIceberg) can query your PostgreSQL tables directly from object storage.

Query Your Data Lake in Postgres

Mon, 01 Jan 0001 00:00:00 +0000

Because pg_mooncake (v0.3.0) embeds DuckDB v2.0.0 via pg_duckdb 1.2.0, you can query external files in your data lake (local disk, S3, Cloudflare R2, GCS, HTTP, or HuggingFace hf:// datasets) directly from PostgreSQL without loading them into heap tables first.

Supported External Formats

Apache Parquet (duckdb.read_parquet)
CSV / TSV (duckdb.read_csv)
JSON / NDJSON (duckdb.read_json)
Apache Iceberg (duckdb.iceberg_scan)
Delta Lake (duckdb.delta_scan)

v0.2 / v0.3 (duckdb.*) vs Legacy v0.1 (mooncake.*) Functions

In pg_mooncake v0.2 and v0.3.0, external file readers are provided directly by pg_duckdb (duckdb.read_parquet, duckdb.read_csv, duckdb.iceberg_scan, duckdb.delta_scan). For the legacy v0.1 mooncake.read_parquet syntax, see v0.1 Query External Files.