> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# DuckDB Connector

> Connect Kumo Relational to data stored in a DuckDB database

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:

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

## Quick Start

Create a graph from a file-based DuckDB database:

```python
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:

```python
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:

| Key               | Description                                                                              | Required |
| ----------------- | ---------------------------------------------------------------------------------------- | -------- |
| `name`            | The table name used in Predictive Query Language (PQL) queries                           | Yes      |
| `source_name`     | The actual table name in the database (if different from `name`)                         | No       |
| `primary_key`     | Override the auto-detected primary key                                                   | No       |
| `time_column`     | The name of the time column for this table                                               | No       |
| `end_time_column` | The name of the end time column for this table                                           | No       |
| `columns`         | The source columns to include, or column specifications that define computed expressions | No       |

## Connection Options

**To connect by using a file path:**

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

**To connect by using a connection configuration dictionary:**

```python
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:

```python
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:

```python
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.