> This page is for Structured Data Models Client.

> 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

There are two ways to use DuckDB data: sample it in place with `DuckDBSource`, or read a table into memory with `read()`.

## Installation

```bash
pip install "structured-data-models-client[relational,duckdb]"
```

## Sample in place with `DuckDBSource`

```python
import duckdb
from sdm_client import PredictiveQuery, Schema
from sdm_connectors import DuckDBSource

connection = duckdb.connect("warehouse.duckdb", read_only=True)
source = DuckDBSource(connection)

schema = Schema.from_source(source, {"users": "USERS", "orders": "ORDERS"})
request = PredictiveQuery(
    "PREDICT COUNT(orders.*, 0, 30, days) FOR EACH users.user_id", schema
).materialize(indices=[7, 12, 3])
```

`tables` maps the names your query uses to the names in DuckDB; leave it out to describe every table in the database. The connection is yours — close it when you are done sampling.

## Read into memory instead

```python
from sdm_connectors import read
from sdm_client import Schema

users = read("duckdb", database="warehouse.duckdb", table="USERS")
orders = read("duckdb", database="warehouse.duckdb", table="ORDERS")

schema = Schema.from_data({"users": users, "orders": orders})
```

`database` and `uri` are aliases for the same argument; pass exactly one. Omitting it opens an in-memory database. Pass `query=` instead of `table=` to read the result of an arbitrary SQL statement.

Review the inferred schema and relationships before predicting — see [Build a Schema](/sdgm/kumo-relational/user-guide/build-a-relational-graph/graph-creation).