Guide
Build an AI Context Layer
Free step-by-step guide: map your warehouse tables and generate an AI context layer with two open-source commands, bruin import database and bruin ai enhance.
What
An AI context layer is a machine-readable description of your warehouse that an AI agent reads before it writes SQL. In this guide you build one: a single YAML file per table carrying a plain-language description, the meaning of every column, executable data quality checks, tags, and the inferred relationships between tables.
An agent that can only see column names and types has to guess what your data means, and guessing produces SQL that runs, returns a number, and is wrong. The context layer removes the guessing. It lives in your git repository as text, so you review it in a pull request and edit it in any editor.
How
Two commands from the open-source Bruin CLI do the work. bruin import database connects to your warehouse and writes one asset file per table. bruin ai enhance reads those files, pulls column statistics from the warehouse, and hands both to an AI CLI you already have installed so it can write the descriptions, checks, and tags.
Both commands run locally. You do not need a Bruin account, and you do not need to move your existing pipelines - dbt, Airflow, Fivetran, and hand-written SQL can stay exactly where they are.
Across four steps you will install the tools, connect one warehouse, import one schema, enhance it with AI, review what the model wrote, and register the result with an AI agent over MCP. No warehouse handy? Step 2 includes a DuckDB path that runs entirely on your machine.
These are the first two steps of building your own AI data analyst. For the shorter written version, read how to build an AI context layer for your data warehouse.
Before you start
- A terminal on macOS, Linux, or WSL
- Read access to a database or warehouse (
SELECTon one schema is enough) - One AI coding CLI: Claude Code, Codex, OpenCode, or Cursor
Guide overview
- 1Install the ToolsInstall the open-source Bruin CLI and one AI coding CLI - the two pieces that generate your context layer.
- 2Create a Project & ConnectScaffold a Bruin project, add a read-only connection to your warehouse, and find the schema you want to map.
- 3Import Your TablesRun bruin import database to turn every table in a schema into a version-controlled asset file.
- 4Generate Context with AIRun bruin ai enhance to fill your asset files with descriptions and checks, then ask an AI agent questions about your data and correct it when it is wrong.
Frequently asked questions
What is an AI context layer for a data warehouse?
An AI context layer is a machine-readable description of your tables: what each table represents, what every column means, which values are valid, and how the tables relate. An AI agent reads it before writing SQL, so it stops guessing at column names and business meaning. With Bruin the context layer is a folder of plain YAML asset files in your git repository, so you review it in a pull request and edit it in any text editor.How do I generate table and column descriptions with AI?
Install the open-source Bruin CLI, import your schema with `bruin import database --connection <name> --schema <schema> <pipeline-path>`, then run `bruin ai enhance <pipeline-path> --model claude-sonnet-5`. The enhance command pulls column statistics from your warehouse and uses your local AI CLI - Claude Code, Codex, OpenCode, or Cursor - to write descriptions, data quality checks, and tags into each asset file. Pass --model on the first run: the CLI's built-in default is an end-of-life model.Is this guide free, and do I need a Bruin account?
The guide is free and no Bruin account is required. The Bruin CLI is open source under Apache 2.0 and both commands run locally. You need one AI coding CLI installed and you pay your own AI provider for the tokens it uses.Which databases can I document this way?
Snowflake, BigQuery, PostgreSQL, Redshift, Athena, Databricks, DuckDB, ClickHouse, Azure Synapse, MS SQL Server, and MongoDB. The generated asset type follows the connection, for example sf.source, bq.source, or pg.source. A read-only account with SELECT on one schema is enough.How long does this guide take?
About 24 minutes of active work across four steps, plus waiting time while the AI enhances your assets - a few minutes for 15 to 20 tables, and 10 minutes or more for 50 or more tables.Do I have to move my pipelines to Bruin?
No. Both commands only read warehouse metadata and write YAML files into a local folder. dbt, Airflow, Fivetran, and hand-written SQL can stay exactly where they are, and you can use the context layer purely as documentation for your AI agent.Does bruin ai enhance send my data to an AI provider?
It sends schema plus aggregate column statistics such as row counts, null counts, distinct counts, and min/max ranges, along with the small samples needed to infer things like accepted values. It does not replicate your tables. Everything goes through the AI CLI already installed on your machine, so the traffic path is the one your coding agent already uses.
Resources
Get help & contribute