DOSIIn-process SQL execution
DuckDB fileStart with a small, real model
Map a local orders dataset to the metric and dimensions you want to share. Review the calculation before any agent relies on it.
Datus + DuckDB
A semantic layer for local DuckDB analysis.
Define a metric against a DuckDB file, review it with your team, and run it locally through DOSI. Use the same explicit business meaning in agent workflows without requiring a cloud warehouse for the first iteration.
Local data + existing SQLTeam reviewApache Ossie model
Agents + apps · MCP / API / CLIDOSIIn-process SQL execution
DuckDB file
Results return through DOSI to your tools
The default DOSI build executes locally with its bundled DuckDB library; your model remains separate from the data file.
Local file or in-memoryIn-process executionNative Arrow results
Where Datus fits
DuckDB SQL objects and a separate semantic model.
DuckDB views and macros reuse SQL logic inside the database. DOSI adds a team-reviewed Apache Ossie model for named metrics that agents and applications can request, while DuckDB remains the local execution engine.
DuckDB views + macros
Local tables or files + authored SQL
Views and macros
SQL clients, notebooks and apps
DuckDB in-process
Reusable SQL definitions live in DuckDB catalog objects.
DuckDB + Datus / DOSI
Team-reviewed Apache Ossie model
DOSI semantic layer
Agents and apps · MCP / API / CLI
DuckDB in-process
The semantic model is managed separately from the DuckDB file.
Inspect locally
The default DOSI build opens DuckDB in process and returns Arrow-native results. You can inspect the generated SQL and result without provisioning a remote warehouse.
Bring in Datus Agent
DuckDB is also a built-in Datus Agent adapter. The Agent can work with the local database while DOSI handles the separate semantic execution path.
A concrete workflow
Use a local file as your first execution target.
Point DOSI at a DuckDB database file, validate your model, then ask for a metric by a named dimension.
dosi-connections.yaml
datasources:
local_duckdb:
type: duckdb
uri: duckdb:////absolute/path/analytics.duckdbDOSI CLI · example request
dosi query --model model.yaml \
--metrics revenue --group-by orders.status \
--execute --connection local_duckdbReplace the sample path and model.yaml with your own file and validated model. This example shows the invocation, not an invented output. The default DOSI build bundles DuckDB; the lean build has different requirements.
Connect DuckDB
DOSI DuckDB connector docsFrom file to first metric query.
The default DOSI build includes an in-process DuckDB executor. A file-backed connection uses a duckdb: URI; omit the URI for an in-memory connection.
- 01
Choose a database file
Use an absolute DuckDB file path while getting started. Confirm the file is accessible and contains the tables your model references.
- 02
Write and review the model
Define the dataset, metric, dimension and relevant relationships in an Apache Ossie model. Validate the model before asking DOSI to execute it.
- 03
Run a bounded query
Use --connection local_duckdb and inspect generated SQL and Arrow-backed results. Keep the DuckDB file and model under your own versioning and access controls.
The default DOSI download bundles DuckDB. The lean build instead requires a compatible DuckDB CLI on PATH and cannot persist an in-memory batch across separate processes. Datus Agent’s built-in DuckDB adapter is a related but separate path.
Useful for teams
A practical place to begin semantic modeling.
Local execution makes the first model easier to inspect before a wider rollout.
Prototype a metric
Try the definition against a local dataset, compare the result to known numbers and revise the model before sharing it.
Give agents a named calculation
Expose the reviewed metric through DOSI interfaces so an agent can request it without recreating the calculation from column names.
FAQ
DuckDB semantic layer FAQ
How local execution works with DOSI and Datus Agent.
How does DOSI differ from DuckDB views and macros?
Views and macros let you reuse SQL within DuckDB. DOSI keeps metric and dimension definitions in a separately reviewed Apache Ossie model and exposes them through MCP, API and CLI. DuckDB still executes the generated query.
Do I need a cloud warehouse to try DOSI with DuckDB?
No. The default DOSI build includes DuckDB for local in-process execution. Connect to a local file or use an in-memory database where appropriate.
Can I use the same DuckDB file with Datus Agent?
Datus Agent includes a DuckDB adapter. Configure its datasource separately from DOSI’s semantic connection, then use each path for the task it supports.
Does the lean DOSI build work the same way?
No. The lean build invokes a DuckDB CLI installed on your PATH and has different in-memory behavior. Consult the connector guide before choosing it.
Try the first metric on a local DuckDB file.
Start with a definition and a dataset your team can verify, then decide where to reuse it.