Catalogs

On this page

Presenting a worker as a database: schemas, tables, views, versioning.

class Builder

source

public static final class Builder

Description

Fluent builder for CatalogTable.

Members

Builder comment(String c)

Sets the table comment.

Builder tags(Map<String, String> t)

Replaces the table’s metadata tags.

Builder tag(String k, String v)

Adds or overwrites a single metadata tag.

Builder scanFunction(String fnName)

Sets the backing scan function with no arguments.

Builder scanFunction(String fnName, List<Object> positional, Map<String, Object> named)

Sets the backing scan function with bound arguments.

Builder rpcScanFunction()

Keeps the same backing function but skips the TableInfo.scan_function inline so the C++ extension fires catalog_table_scan_function_get.

Builder cardinality(long estimate, long max)

Sets the inline cardinality estimate and maximum.

Builder primaryKey(List<List<Integer>> pk)

Sets the primary-key column-index groups.

Builder unique(List<List<Integer>> u)

Sets the UNIQUE constraint column-index groups.

Builder check(List<String> c)

Sets the CHECK constraint SQL expressions.

Builder foreignKeys(List<ForeignKey> fks)

Sets the foreign-key constraints.

Builder statistics(List<ColumnStatistics> s)

Sets the per-column statistics.

Builder requiredFilters(List<List<String>> groups)

Sets the required WHERE-filter groups (conjunctive normal form): the outer list is an AND of OR-groups, each inner group a list of dotted column paths satisfied when any one of its paths is filtered. So [["accession_number"], ["ticker", "cik"]] means “accession_number AND one of (ticker, cik)”.

CatalogTable build()

Builds the immutable CatalogTable.

CatalogTable withCardinality(long estimate, long max)

Returns a copy with the inline cardinality estimate and maximum set.

CatalogTable withRpcScanFunction()

Returns a copy that keeps the same backing function but skips the TableInfo.scan_function inline so the C++ extension fires catalog_table_scan_function_get.

CatalogTable withConstraints(List<List<Integer>> pk, List<List<Integer>> unique, List<String> check, List<ForeignKey> fks)

Returns a copy with PK/UNIQUE/CHECK/FK constraints attached.

CatalogTable withStatistics(List<ColumnStatistics> stats)

Returns a copy with per-column statistics attached; used by the optimizer for filter elimination.

CatalogTable withRequiredFilters(List<List<String>> groups)

Returns a copy with the required WHERE-filter groups (conjunctive normal form): the outer list is an AND of OR-groups, each inner group a list of dotted column paths satisfied when any one of its paths is filtered. So [["accession_number"], ["ticker", "cik"]] means “accession_number AND one of (ticker, cik)”.

record CatalogTable

source

public record CatalogTable( String schema, String name, byte[] columns, String comment, Map<String, String> tags, String scanFunctionName, List<Object> scanFunctionPositional, Map<String, Object> scanFunctionNamed, Long cardinalityEstimate, Long cardinalityMax, boolean inlineCardinality, boolean inlineScanFunction, List<List<Integer>> primaryKey, List<List<Integer>> uniqueConstraints, List<String> checkConstraints, List<ForeignKey> foreignKeys, List<ColumnStatistics> statistics, List<List<String>> requiredFilters)

Description

A catalog table. columns is the table’s Arrow schema serialized as IPC bytes. scanFunctionName (with scanFunctionArgs) inlines the scan function so the C++ extension can skip catalog_table_scan_function_get; if null, the worker must implement that RPC manually.

record ColumnStatistics

source

public record ColumnStatistics( String columnName, ArrowType arrowType, Object min, Object max, boolean hasNull, boolean hasNotNull, Long distinctCount, Boolean containsUnicode, Long maxStringLength)

Description

Per-column statistics returned by catalog_table_column_statistics_get or table_function_statistics.

arrowType pins the sparse-union member type for min/max. When both are null (column has no usable min/max), set arrowType to new ArrowType.Null().

min and max are boxed Java values matching arrowType: Long for INT64, Double for FLOAT64, String for UTF8, etc.

Members

ColumnStatistics ofInt64(String name, long min, long max, boolean hasNull, Long distinctCount)

Statistics for an INT64 column.

ColumnStatistics ofFloat64(String name, double min, double max, boolean hasNull, Long distinctCount)

Statistics for a FLOAT64 column.

ColumnStatistics ofUtf8(String name, String min, String max, boolean hasNull, Long distinctCount, Boolean containsUnicode, Long maxStringLength)

Statistics for a UTF8 string column.

ColumnStatistics ofGeometry(String name, byte[] min, byte[] max, boolean hasNull, Long distinctCount)

Geometry-column stats: min/max are WKB-encoded corner-point geometries (the spatial bounding box). Sent as plain binary on the sparse-union wire — the C++ extension correlates name with the table’s geoarrow.wkb-typed column and rebuilds the spatial extent.

record ForeignKey

source

public record ForeignKey( List<String> fkColumns, List<String> pkColumns, String referencedSchema, String referencedTable)

Description

Foreign-key constraint declaration. Wire shape uses column NAMES (not indices) for both sides — matches the vgi-go fkSchema.

Members

CatalogTable(String schema, String name, byte[] columns, String comment, Map<String, String> tags, String scanFunctionName, List<Object> scanFunctionPositional, Map<String, Object> scanFunctionNamed, Long cardinalityEstimate, Long cardinalityMax, boolean inlineCardinality, boolean inlineScanFunction)

Builds a table with no constraints, statistics, or required filter paths.

CatalogTable(String schema, String name, byte[] columns, String comment, Map<String, String> tags, String scanFunctionName, List<Object> scanFunctionPositional, Map<String, Object> scanFunctionNamed, Long cardinalityEstimate, Long cardinalityMax, boolean inlineCardinality, boolean inlineScanFunction, List<List<Integer>> primaryKey, List<List<Integer>> uniqueConstraints, List<String> checkConstraints, List<ForeignKey> foreignKeys)

Builds a table with constraints but no statistics or required filter paths.

CatalogTable functionBacked( String schema, String name, byte[] columns, String comment, String scanFunction)

Convenience factory for a table whose rows come from an inlined, argument-less scan function.

Builder builder(String schema, String name, byte[] columns)

Start a Builder for a catalog table. The three required pieces are the schema-name, table-name, and IPC-serialised column schema; all other knobs (comment, tags, scan function, constraints, stats, cardinality) are optional and set via chained methods. Prefer this over calling the record’s many-arg constructor directly — the canonical constructor’s field order has historically drifted as new wire fields landed.

record Macro

source

public record Macro(String schema, String name, MacroType macroType, List<String> parameters, Map<String, String> parameterDefaults, Map<String, String> parameterDocs, String definition, String comment, Map<String, String> tags)

Description

A SQL macro exposed in the catalog. parameterDefaults is an optional ordered map of parameter-name → SQL expression (used when the macro has named-with-default parameters). parameterDocs is an optional parameter-name → description map: each documented parameter’s description flows over the wire via the macro arguments_schema’s vgi_doc field metadata (the same channel functions use for per-argument docs), so the DuckDB extension’s vgi_function_arguments() can surface it. Keys must appear in parameters.

Members

Macro

Canonical constructor: validates that every documented parameter name appears in parameters.

Macro(String schema, String name, MacroType macroType, List<String> parameters, String definition, String comment)

Builds a macro with no parameter defaults, docs, or tags.

Macro(String schema, String name, MacroType macroType, List<String> parameters, Map<String, String> parameterDefaults, String definition, String comment)

Builds a macro with parameter defaults but no docs or tags.

Macro(String schema, String name, MacroType macroType, List<String> parameters, Map<String, String> parameterDefaults, String definition, String comment, Map<String, String> tags)

Builds a macro with parameter defaults and tags but no docs.

enum MacroType

source

public enum MacroType

Description

Kind of SQL macro: scalar-valued or table-valued.

record ScanBranch

source

public record ScanBranch( String functionName, List<Object> positional, Map<String, Object> named, String branchFilter, boolean writable, String sourceCatalog, String sourceSchema, String sourceTable)

Description

One physical source backing a multi-branch VGI table. The C++ extension’s optimizer rewrites a multi-branch scan into UNION_ALL of one arm per branch, binding each functionName against DuckDB’s function catalog. Mirrors vgi-python ScanBranch.

Members

ScanBranch

Validates the branch and defensively copies the argument collections, normalizing null to empty. A branch is either a function branch (functionName set) or a catalog-table branch (functionName empty and sourceTable set — it scans sourceCatalog.sourceSchema.sourceTable in a companion catalog).

ScanBranch of(String functionName, Object… positional)

Read-only branch with positional args and no filter.

ScanBranch filtered(String functionName, String branchFilter, Object… positional)

Read-only branch with positional args and a branch filter.

ScanBranch writable(String functionName, Object… positional)

Writable branch with positional args (the table’s INSERT target).

ScanBranch catalogTable( String sourceCatalog, String sourceSchema, String sourceTable, String branchFilter)

Catalog-table branch (lakehouse federation): scans the base table sourceCatalog.sourceSchema.sourceTable in a companion catalog instead of calling a table function.

record View

source

public record View(String schema, String name, String definition, String comment, Map<String, String> tags, Map<String, String> columnComments)

Description

A SQL view exposed in the catalog. schema is the schema name; definition is a SQL query string evaluated by DuckDB.

Members

View(String schema, String name, String definition, String comment)

Builds a view with no tags and no column comments.

View(String schema, String name, String definition, String comment, Map<String, String> tags)

Builds a view with tags but no column comments.

View withColumnComments(Map<String, String> columnComments)

Returns a copy with the given per-column comment map (name → comment).