DuckDB Connector

Use the DuckDB connector to create a Kumo relational graph from a file-based DuckDB database. The graph describes your tables, columns, and relationships so that Kumo can make predictions from the connected data. By default, the connector discovers tables and infers their metadata and relationships from the database schema.

Installation

Install the Kumo Relational SDK with its DuckDB dependencies:

pip install "kumo-relational-client[relational,duckdb]"

Quick Start

Create a graph from a file-based DuckDB database:

from kumo_relational_client import relational
graph = relational.Graph.from_duckdb(connection="my_database.duckdb")

The connector builds the graph by performing the following actions:

1. Connects to the DuckDB database.
2. Discovers all non-temporary, non-internal tables automatically.
3. Infers column metadata, including data types, how Kumo should interpret each column, primary keys, and time columns.
4. Detects foreign-key relationships.
5. Prints a summary of the inferred metadata and table relationships.

Specifying Tables

Use the tables parameter when you want to include only specific tables or override their inferred configuration. A string includes a table with its existing name, while a dictionary lets you configure that table:

graph = relational.Graph.from_duckdb(
    connection="my_database.duckdb",
    tables=[
        "USERS",
        {"name": "ORDERS", "source_name": "ORDERS_SNAPSHOT"},
        {"name": "ITEMS", "primary_key": "ITEM_ID"},
    ],
)

The following table describes the table configuration options:

Connection Options

To connect by using a file path:

graph = relational.Graph.from_duckdb(connection="path/to/database.duckdb")

To connect by using a connection configuration dictionary:

graph = relational.Graph.from_duckdb(
    connection={"uri": "path/to/database.duckdb"},
)

Controlling Metadata Inference

By default, from_duckdb() infers metadata and relationships when it creates the graph. Set infer_metadata=False to postpone that work, and set verbose=False to suppress the initial summary. You can then run inference explicitly when you are ready:

graph = relational.Graph.from_duckdb(
    connection="my_database.duckdb",
    infer_metadata=False,
    verbose=False,
)
graph.infer_metadata()
graph.infer_links()

Manual Edge Specification

Use the edges parameter to specify table relationships instead of relying on automatic detection. Each tuple identifies the source table, its foreign-key column, and the referenced table, in that order:

graph = relational.Graph.from_duckdb(
    connection="my_database.duckdb",
    edges=[
        ("ORDERS", "USER_ID", "USERS"),
        ("ORDERS", "ITEM_ID", "ITEMS"),
    ],
)

Pass edges=None to allow declared or inferred relationships. Pass edges=[] to create the graph without relationships and suppress relationship inference.