semduck

Portable semantic view runtime for DuckDB, implemented in Python.

Full documentation lives in the GitHub Pages docs site for this repository. This README stays focused on the package-facing quickstart.

Supported baseline:

• Python 3.11 to 3.13
• DuckDB 1.4+
• dbt-duckdb 1.9.x for the optional dbt plugin path

Install

pip install semduck

Install the dbt support extra only if you are registering the DuckDB plugin in a dbt-duckdb project:

pip install "semduck[dbt]"

Supported Patterns

• Standalone Python package and CLI:
  • YAML semantic specs
  • semantic DDL
• dbt interface through dbt-semduck:
  • inline semantic DDL only

YAML is supported for standalone Python and CLI usage. The dbt interface deliberately uses DDL instead of YAML-in-dbt so semduck stays dbt-agnostic.

Quickstart

Start by initializing a registry. This creates a semantic schema and several supporting tables in the duckdb database you provide.

semduck init --db demo.duckdb

Load a semantic definition from YAML:

semduck load --db demo.duckdb --file orders_semantic.yaml
semduck compile --db demo.duckdb --request "orders_semantic dimensions region metrics total_revenue"

Load a semantic definition from DDL:

semduck load --db demo.duckdb --format ddl --file path/to/orders_semantic.sql
semduck query --db demo.duckdb --request "orders_semantic dimensions region metrics total_revenue"

The CLI accepts --format auto|yaml|ddl for check and load. In auto mode it uses the file extension or the first non-empty line to infer the format.

Configure an Ollama-backed ask provider and run the ask CLI:

semduck ask \
  --db examples/dbt_example/jaffle_shop.duckdb \
  --config packages/semduck/examples/ask_ollama_config.yaml \
  --llm-log-dir .semduck/llm-logs \
  --question "What is total revenue by customer name?" \
  --sql --table

Configure an OpenAI-compatible local server and run the ask CLI:

semduck ask \
  --db examples/dbt_example/jaffle_shop.duckdb \
  --config packages/semduck/examples/ask_openai_compatible_config.yaml \
  --llm-log-dir .semduck/llm-logs \
  --question "What is total revenue by customer name?" \
  --sql --table

Set llm.log_dir in the config file to enable persistent trace logging by default, or use --llm-log-dir to override it per run. Pass --no-llm-log to disable logging even when the config file specifies a directory.

semduck ask uses a planner stage to build the semantic request and, when --summary is requested, a separate summary stage to explain the executed rows. Advanced users can configure different models for those jobs with llm.tasks.ask_plan and llm.tasks.ask_summary. If task-specific config is used, the summary task only needs to be configured when summary output is requested.

During semduck ask, the CLI now prints one-line stage updates such as planning, compile, execution, and summarization to stderr. Final results remain on stdout, so JSON output stays machine-readable.

Start the semduck MCP server over stdio:

semduck mcp --db examples/dbt_example/jaffle_shop.duckdb

Learn More

The docs site covers:

• installation and quickstart
• YAML vs DDL authoring
• request language semantics
• CLI command reference
• Python API guidance
• dbt interface
• MCP server setup
• ask provider configuration

Python API

The package exposes both YAML and DDL loaders:

import duckdb
from semduck import compile_request_sql, init_registry, load_semantic_ddl, load_semantic_yaml

conn = duckdb.connect("demo.duckdb")
init_registry(conn)

load_semantic_yaml(conn, """
name: sample
tables:
  - name: orders
    base_table:
      table: orders
    dimensions:
      - name: region
        expr: region
    metrics:
      - name: order_count
        expr: count(order_id)
""")

load_semantic_ddl(conn, """
create semantic view replacement_sample as
table main.orders as orders
  dimensions (
    region as region
  )
  metrics (
    count(order_id) as order_count
  );
""")

sql = compile_request_sql(conn, "replacement_sample dimensions region metrics order_count")
print(sql)

Relevant API entry points:

• init_registry(conn)
• load_semantic_yaml(conn, yaml_text)
• load_semantic_ddl(conn, ddl_text)
• load_semantic_yaml_file(conn, path)
• load_semantic_ddl_file(conn, path)
• compile_request_sql(conn, request)
• execute_request(conn, request)

dbt Boundary

semduck keeps dbt-specific behavior in the dbt-semduck package.

• Supported in dbt: inline semantic DDL compiled by dbt and then loaded into semduck
• Not supported in dbt: YAML specs containing unresolved ref(...) or source(...)

The design note for that boundary lives in _project/decisions/remove_yaml_in_dbt_support.md.

Repo Examples

• In-memory Python quickstart: examples/quickstart.py
• Query an existing database from Python: examples/query_existing_db.py
• Query an existing database from the CLI: examples/query_existing_db_cli.sh
• Use ask_question(...) from Python: examples/ask_existing_db.py
• Register an Ollama provider config and use semduck ask: examples/ask_existing_db_cli.sh
• Example Ollama provider config: examples/ask_ollama_config.yaml
• Example OpenAI-compatible local provider config: examples/ask_openai_compatible_config.yaml
• Start the MCP server over stdio: examples/mcp_server_stdio.sh
• Example MCP client config: examples/mcp_client_config.json
• MCP startup and client connection guide: examples/mcp_connection_guide.md
• End-to-end dbt example: examples/dbt_example

Development

uv sync
uv run --group dev python -m pytest
uv run tox