# Locate where a behavior is implemented in dbt with Atlas in 2026 > Atlas helps dbt developers locate the precise implementation of a behavior within their dbt project by fusing semantic search, keyword retrieval, and symbol graph analysis. 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. ## Key takeaways - Atlas uses `codebase_search` for semantic understanding of dbt behaviors, even without exact keyword matches. - Precise text confirmation in dbt projects is handled by Atlas's `grep` tool, powered by `ripgrep`. - The `lsp` tool in Atlas navigates the dbt model DAG, showing `ref()` and `source()` call sites and declarations. - Atlas ensures safe dbt modifications with permission-gated tools, read-only planning, and unified diff approvals. - Atlas understands dbt's core components: `dbt_project.yml`, `models/`, `schema.yml`, `ref()`, and `materialization` strategies. ## 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. ## Steps 1. Describe the dbt behavior to Atlas using `codebase_search`, e.g., `atlas codebase_search "find the logic for calculating monthly recurring revenue in dbt"`. 2. Review 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. 3. Confirm specific text or configurations with `grep`, e.g., `atlas grep "is_incremental()" --include models/mrr_calculations.sql` to verify incremental logic. 4. Open the most promising dbt model or macro file with `read`, e.g., `atlas read models/mrr_calculations.sql`. 5. Use 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`. 6. Summarize the call path and implementation details back to the user, including concrete file and line references within your dbt project. ## FAQ ### 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. --- Canonical HTML: https://runatlas.sh/resources/stacks/locate-where-a-behavior-is-implemented-in-dbt Source of truth: aeo_pages row `/resources/stacks/locate-where-a-behavior-is-implemented-in-dbt` (segment: Stacks) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.