Documentation overview

datahashi is a semantic layer. It gives the same metric to people and to AI agents. An agent cannot write SQL.

datahashi is between your warehouse and the consumers. It compiles a Semantic Query into SQL. The warehouse then runs that SQL.

flowchart TD
    BI["BI tools<br/>SQL Wire"] --> E
    AG["AI agents<br/>MCP"] --> E
    AP["Apps and services<br/>REST"] --> E
    E["datahashi engine<br/>resolve join graph · compile dialect SQL · data roles and RLS<br/>rollup router (DuckDB) · result caching · usage metering"] -->|"bound SQL (HTTP)"| QR["Query Runner<br/>holds warehouse password · kill switch · on-disk audit"]
    QR -->|"native driver"| W[("Your warehouse<br/>Postgres · MySQL · Snowflake · BigQuery · and five more")]

The system has three boundaries:

1. Consumers ask for metrics. They never write SQL joins. They never read raw tables.
2. The engine applies policy and compiles SQL. It never holds warehouse passwords. It never opens a warehouse connection.
3. Query Runner runs in your network. It holds the password and the audit log. It runs the SQL.

Start here

Pick the page that matches your goal.

Getting started and architecture

• Getting started: Hosted cloud or community edition. Same query pipeline. Same Query Runner.
• System architecture: Trust boundaries, query lifecycle, and isolation.

Concepts

• Semantic model: Entity, Dimension, Measure, Metric, and Grain.
• Query Runner: Password, kill switch, and audit log stay on your side.
• Rollups: Pre-aggregated Parquet files. DuckDB serves a hit. The warehouse serves a miss.
• Data roles and row-level security: Deny by default. Grants and row filters on the caller.
• PostgreSQL wire protocol: Metabase, Superset, Tableau, and Power BI on port 5432.
• Model Vibe and Insights: Author a model in Studio. Ask questions on published metrics.

Guides

• Write your first model: Two warehouse tables into entities, relationships, and metrics.
• Advanced semantic modeling: Calculated dimensions, filtered measures, rolling windows, derived metrics, offset(), and avg_per().
• Query the REST API: Run a query, page results, stream CSV, and list dimension values.
• Connect an LLM agent: Claude Desktop, Cursor, or a custom agent. Six MCP tools.
• Connect a warehouse: Nine engines. Read-only grants and DSN. Table policy is PostgreSQL only.
• Caching and query lanes: Live cache, Redis cache, and admission lanes.
• Install Query Runner: Deploy the process, set table policy, and reload config.
• Self-host the community engine: Docker Compose. No control plane.

Reference

• REST API: HTTP paths, request bodies, and status codes.
• Query Runner protocol: HTTP contract between engine and runner.
• Semantic model YAML: Every field in model.yaml.
• Semantic query syntax: JSON for queries, operators, filter groups, and having.
• Environment variables: Engine and runner configuration.

Quick lookup

Goal	Page
Run a local proof of concept	Self-host the community engine
Author YoY or derived metrics	Advanced semantic modeling
Connect Claude Desktop or Cursor	Connect an LLM agent
Connect Tableau or Metabase	PostgreSQL wire protocol
Restrict rows by region or tenant	Data roles and row-level security
Speed up a hot query	Rollups
Grant read access in Snowflake or BigQuery	Connect a warehouse
Set query lanes and live cache	Caching and query lanes
Pause Query Runner	Install Query Runner
Exact JSON errors and HTTP paths	REST API
Full model.yaml schema	Semantic model YAML

Next: Getting started · System architecture.