How does Atlas find dbt models when I only know what they do?

Atlas uses `codebase_search` with hybrid semantic and keyword retrieval. You describe the behavior in natural language, and Atlas intelligently returns relevant dbt models, macros, or `schema.yml` definitions, even if your exact words aren't in the code.

Can Atlas find specific column names or configurations in my dbt project?

Yes, after an initial semantic search, Atlas's `grep` tool allows you to run precise regex searches across your dbt project. This is perfect for finding specific column names, `unique_key` definitions, or `materialization` settings.

How does Atlas help me understand dbt model dependencies?

Atlas integrates the `lsp` tool, which provides a symbol graph. You can use `lsp findReferences` on a `ref()` call or a model name to see all its downstream dependencies and usage within your dbt project, mapping out your DAG.

Is it safe to let Atlas modify my dbt code?

Atlas is designed with multiple safety layers. All tool calls are permission-gated, plans are drafted in a read-only agent, and every proposed file edit generates a unified diff for your explicit approval before any changes are written to your dbt project files.

Does Atlas understand dbt-specific file structures and commands?

Absolutely. Atlas is configured to understand `dbt_project.yml`, `models/` directories, `schema.yml` files, and dbt idioms like `ref()`, `source()`, `is_incremental()`, and `materialization` strategies. It also integrates with `dbt test`, `dbt deps (packages.yml)`, and `sqlfmt`.

Can Atlas help me find where a dbt schema test is defined?

Yes, you can use `codebase_search` to describe the test's purpose, or `grep` to search for specific test names or column definitions within your `schema.yml` files. Atlas will pinpoint the exact location of `not_null` or `unique` tests.

Locate where a behavior is implemented in dbt with Atlas in 2026

Atlas empowers dbt developers to find the exact file and symbol responsible for a behavior, even when only knowing what the software does, not what the code is called, by combining semantic search, precise text matching, and symbol graph navigation across your `dbt_project.yml` and `models/` directory.

How Atlas finds dbt behavior with semantic search

Atlas helps dbt developers locate behavior implementations by leveraging 3 distinct search angles, starting with semantic retrieval. In 2026, dbt projects can grow to hundreds of models, making keyword-only searches inefficient for understanding complex data transformations and `ref()` calls.

When you need to find where a specific data transformation or business logic is implemented in your dbt project, but you don't know the exact file or function name, Atlas's `codebase_search` tool is your starting point. Instead of relying on exact keywords, `codebase_search` uses hybrid semantic and keyword retrieval, fused by reciprocal rank fusion, to understand the meaning of your query. This means you can describe the behavior in natural language, such as "find the logic for calculating customer lifetime value" or "where is the daily sales aggregation defined," and Atlas will return candidate declarations from your `models/` directory, `schema.yml` files, and even custom macros. Atlas builds its code index using AST declarations via tree-sitter, ensuring that it understands the structure of your dbt SQL and Jinja, not just blind line windows. This capability is crucial for navigating large dbt codebases where `ref()` and `source()` calls define complex data lineage.

How to confirm dbt code with exact text search

After an initial semantic search, Atlas allows dbt developers to confirm findings with precise text matching using the `grep` tool, powered by `ripgrep`. This ensures that even specific string literals or unique column names, like `customer_id_v2`, are located accurately within your `models/` directory.

While semantic search is excellent for initial discovery, sometimes you need to confirm the presence of an exact string, a specific column name, or a unique configuration within your dbt project. Atlas's `grep` tool provides this capability, running `ripgrep` under the hood. You can provide a real regex, along with include and path filters, to narrow down your search. For instance, if `codebase_search` suggested a model related to customer data, you might then use `grep` to find all occurrences of `unique_key: customer_id` within `models/staging/` or `schema.yml` files. This two-pronged approach ensures that you can both semantically understand the code's purpose and precisely locate specific textual elements, providing a robust method for identifying the exact implementation details of any dbt behavior.

How to navigate dbt's symbol graph with LSP

To fully understand a dbt model's dependencies and usage, Atlas integrates the `lsp` tool, providing a symbol graph for `ref()` and `source()` calls. This allows you to jump directly to a declaration or find all 10 references to a specific macro within your `dbt_project.yml`.

Once you've identified a candidate file or symbol, Atlas's `lsp` tool becomes invaluable for understanding its context within the dbt project's Directed Acyclic Graph (DAG). The `lsp` tool offers operations like `findReferences` to see every callsite of a dbt model, macro, or column definition, and `workspaceSymbol` to jump directly to a declaration by name. For example, if you've located a `materialization: incremental` model, you can use `lsp findReferences` on its `unique_key` column to see all downstream models or tests that depend on it. This is critical for dbt projects where `ref()` and `source()` calls define complex interdependencies. Atlas can also use the `read` tool to open the best candidate file, and if a wrong guess is made, it fails loudly with "File not found" and a "Did you mean" list, ensuring you don't waste time on incorrect paths.

How Atlas ensures safe dbt code changes

Atlas prioritizes safety and transparency when suggesting changes to dbt projects, offering multiple layers of review before any file is written. Every Atlas tool call is permission-gated, and all proposed edits generate a unified diff for your approval, preventing unintended modifications to your 2026 data pipelines.

Locating a behavior is often the first step towards modifying it. Atlas is designed with robust safety features to ensure that any subsequent changes to your dbt project are intentional and approved. Every Atlas tool call, including those that might modify files, is permission-gated against allow, ask, and deny rules. Before making any changes, Atlas drafts a plan in a read-only plan agent and asks for your approval before switching to a build agent. When Atlas proposes an edit, it computes a unified diff for every file change and surfaces it for your explicit approval before writing. This means you'll see exactly what changes are being made to your `models/`, `schema.yml`, or `dbt_project.yml` files. Atlas also snapshots file changes as git patches, allowing edits to be easily diffed and rolled back, providing a secure environment for evolving your dbt codebase.

Step by step

01Describe the dbt behavior to Atlas using `codebase_search`, e.g., `atlas codebase_search "find the logic for calculating monthly recurring revenue in dbt"`.
02Review the semantic index's candidate declarations, which might include `models/mrr_calculations.sql` or relevant `schema.yml` entries, even if your exact words don't appear.
03Confirm specific text or configurations with `grep`, e.g., `atlas grep "is_incremental()" --include models/mrr_calculations.sql` to verify incremental logic.
04Open the most promising dbt model or macro file with `read`, e.g., `atlas read models/mrr_calculations.sql`.
05Use the `lsp` tool's `findReferences` operation on a key `ref()` call or column to understand its dependencies, e.g., `atlas lsp findReferences models/mrr_calculations.sql:15:10`.
06Summarize the call path and implementation details back to the user, including concrete file and line references within your dbt project.

Frequently asked questions

How does Atlas find dbt models when I only know what they do?: Atlas uses `codebase_search` with hybrid semantic and keyword retrieval. You describe the behavior in natural language, and Atlas intelligently returns relevant dbt models, macros, or `schema.yml` definitions, even if your exact words aren't in the code.
Can Atlas find specific column names or configurations in my dbt project?: Yes, after an initial semantic search, Atlas's `grep` tool allows you to run precise regex searches across your dbt project. This is perfect for finding specific column names, `unique_key` definitions, or `materialization` settings.
How does Atlas help me understand dbt model dependencies?: Atlas integrates the `lsp` tool, which provides a symbol graph. You can use `lsp findReferences` on a `ref()` call or a model name to see all its downstream dependencies and usage within your dbt project, mapping out your DAG.
Is it safe to let Atlas modify my dbt code?: Atlas is designed with multiple safety layers. All tool calls are permission-gated, plans are drafted in a read-only agent, and every proposed file edit generates a unified diff for your explicit approval before any changes are written to your dbt project files.
Does Atlas understand dbt-specific file structures and commands?: Absolutely. Atlas is configured to understand `dbt_project.yml`, `models/` directories, `schema.yml` files, and dbt idioms like `ref()`, `source()`, `is_incremental()`, and `materialization` strategies. It also integrates with `dbt test`, `dbt deps (packages.yml)`, and `sqlfmt`.
Can Atlas help me find where a dbt schema test is defined?: Yes, you can use `codebase_search` to describe the test's purpose, or `grep` to search for specific test names or column definitions within your `schema.yml` files. Atlas will pinpoint the exact location of `not_null` or `unique` tests.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Locate Where a Behavior Is Implemented with Atlas in 2026

How to locate where a behavior is implemented with Atlas in 2026: codebase_search for meaning, grep for exact text, and the lsp tool for the symbol graph.

Atlas for dbt: Terminal-Native AI Coding in 2026

Atlas is a terminal-native AI coding agent for dbt. Read the ref() DAG, convert a table model to incremental, run dbt build against dev, and add tests in 2026.

Diagnose a Hanging or Long-Running dbt Command with Atlas in 2026

Diagnose hanging dbt commands in 2026 with Atlas. Quickly determine if your `dbt build` or `dbt test` is genuinely slow or silently blocked on input, and get it unstuck.

Onboard to an Unfamiliar dbt Codebase with Atlas in 2026

Atlas helps dbt developers in 2026 quickly build a mental model of new repositories. Leverage semantic search, `ref()` analysis, `dbt test`, and `sqlfmt` to understand complex dbt projects without reading every file.

Self-review your working diff before committing in dbt with Atlas in 2026

Catch your own dbt mistakes before they reach review or CI. Atlas helps dbt developers self-review uncommitted changes, run dbt test, and format with sqlfmt in 2026.

Trace a runtime bug from a stack trace in dbt with Atlas in 2026

Pinpoint and fix dbt runtime bugs from production stack traces using Atlas, the terminal-native AI coding agent. Leverage `dbt test`, `sqlfmt`, and `dbt deps` for rapid resolution.

Research a Third-Party API Before Integrating it in dbt with Atlas in 2026

Learn how dbt developers use Atlas in 2026 to research external APIs, fetch documentation, and integrate new data sources with confidence, ensuring proper `ref()` calls and schema tests.

Plan a multi-file change before editing in dbt with Atlas in 2026

Design complex, multi-file dbt changes with Atlas's plan agent. Get your dbt project modifications reviewed and approved before a single line of code is written, ensuring safety and collaboration.

Browse this resource hub