> 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 KumoRFM to data stored in a DuckDB database

KumoRFM can connect directly to DuckDB databases, automatically inferring table metadata and relationships from the schema.

## Installation

The DuckDB backend requires the ADBC DuckDB driver:

```bash
pip install kumoai[duckdb]
```

## Quick Start

Connect to a file-based DuckDB database:

```python
import kumoai.rfm as rfm

graph = rfm.Graph.from_duckdb(connection="my_database.duckdb")
```

This will:

1. Connect to the DuckDB database
2. Discover all non-temporary, non-internal tables automatically
3. Infer column metadata (data types, semantic types, primary keys, time columns)
4. Detect foreign key relationships
5. Print a summary of the inferred metadata and links

## Specifying Tables

Control which tables to include and customize their configuration:

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

Table configuration options:

| Key               | Description                                                           | Required |
| ----------------- | --------------------------------------------------------------------- | -------- |
| `name`            | The table name used in 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`         | Selected source columns or column specs, including expression columns | No       |

## Connection Options

**In-memory database:**

```python
from kumoai.rfm.backend.duckdb import connect

conn = connect()  # in-memory DuckDB database
graph = rfm.Graph.from_duckdb(connection=conn)
```

**From a file path:**

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

**From an existing ADBC connection:**

```python
from kumoai.rfm.backend.duckdb import connect

conn = connect("path/to/database.duckdb")
graph = rfm.Graph.from_duckdb(connection=conn)
```

**From a connection config dict:**

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

## Controlling Metadata Inference

```python
graph = rfm.Graph.from_duckdb(
    connection="my_database.duckdb",
    infer_metadata=False,
    verbose=False,
)

graph.infer_metadata()
graph.infer_links()
```

## Manual Edge Specification

Override automatic link detection by providing edges explicitly:

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