### Install and Bundle Dependencies Source: https://github.com/dbt-labs/dbt-docs/blob/main/CONTRIBUTING.md Install project dependencies using bundler. Ensure bundler is installed first. ```bash gem install bundler bundle install ``` -------------------------------- ### Start Development Server Source: https://github.com/dbt-labs/dbt-docs/blob/main/CONTRIBUTING.md Start the development server for dbt-docs. Ensure manifest.json and catalog.json are copied to the src/ directory before running. ```bash npm install npm start ``` -------------------------------- ### HTML for Bootstrap Tooltip Example Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Example HTML structure for implementing a Bootstrap tooltip with custom placement. ```html Info icon ``` -------------------------------- ### Navigate to Jaffle Shop Directory Source: https://github.com/dbt-labs/dbt-docs/blob/main/ci-project/README.md Change into the jaffle_shop directory from the command line to begin setup. ```bash $ cd jaffle_shop ``` -------------------------------- ### Development Server Start Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/module-system.md Starts the Webpack development server for hot module reloading and loading manifest.json and catalog.json via HTTP. ```bash npm start ``` -------------------------------- ### HTML for Bootstrap Popover Example Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Example HTML structure for implementing a Bootstrap popover. ```html ``` -------------------------------- ### Install Node Modules and Build with Webpack Source: https://github.com/dbt-labs/dbt-docs/blob/main/CONTRIBUTING.md Install Node.js dependencies and build the project using webpack. This command generates the index.html file. ```bash npm install npx webpack ``` -------------------------------- ### Fully Qualified Name (FQN) Example Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/README.md Demonstrates the FQN as a path array representing a resource's location, which can be used with FQN selectors. ```javascript fqn = ['project', 'models', 'marts', 'customers'] // Can be matched with FQN selector: 'marts.customers' or 'models.marts.*' ``` -------------------------------- ### Search Component Usage Example Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/components-controllers.md An example of how to use the `docs-search` directive in an HTML template, binding scope properties to component inputs. ```html ``` -------------------------------- ### Dependency Grouping Example Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/components-controllers.md Demonstrates how to retrieve parent dependencies for a node using `dagUtils.getParents`. The result is an object that can be grouped by resource type in templates. ```javascript $scope.parents = dagUtils.getParents(project, node); // Returns: { // 'model': [model1, model2], // 'source': [source1], // 'macro': [macro1] // } // Template can group by resource_type ``` -------------------------------- ### Selector Expressions Examples Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/README.md Provides examples of dbt selectors, including base selectors, graph traversal, and set operations for flexible node filtering. ```plaintext // Base selectors 'tag:daily' // Nodes with tag 'source:raw.customers' // Specific source 'fqn:models.marts.customers' // FQN-based // Graph traversal '+model_name+' // Model + ancestors + descendants '+2model_name+' // Model + 2 hops of ancestors 'model_name+3' // Model + 3 hops of descendants // Set operations 'tag:daily tag:critical' // Union (A OR B) 'tag:daily,resource_type:model' // Intersection (A AND B) ``` -------------------------------- ### ES6 Import Pattern Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/module-system.md Demonstrates importing modules and specific components using the ES6 `import` syntax. This example includes importing Prism.js, a Prism.js component for SQL, and the deep-merge library. ```javascript import Prism from 'prismjs'; import 'prismjs/components/prism-sql'; import merge from 'deepmerge'; ``` -------------------------------- ### Graph Layout Configurations Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Provides examples of graph layout configurations using Dagre for Left-Right orientation and a preset for Top-Down layouts, detailing parameters for spacing and positioning. ```javascript // Left-Right (Dagre) { name: 'dagre', rankDir: 'LR', rankSep: 200, // Space between ranks edgeSep: 30, // Space between edges nodeSep: 50 // Space between nodes } // Top-Down (Preset) { name: 'preset', positions: function(node) { ... } } ``` -------------------------------- ### Get Nodes by File Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md Matches nodes by their exact filename. Use this for precise selection when you know the specific file name of the node. ```javascript getNodesByFile(elements: object, filename: string): array ``` ```javascript getNodesByFile(elements, 'customers.sql'); ``` -------------------------------- ### Complex Selector Example Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md This example demonstrates a complex selector combining inclusion and exclusion criteria to target specific materialized tables within a directory, while excluding archives and tests. ```text # Include models in marts directory, all their parents, # excluding archived models, excluding tests, keeping only materialized tables --select path:models/marts+ --exclude path:*archive* --exclude path:*test* --select config.materialized:table ``` -------------------------------- ### excludeNode Method Example Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md Shows how to use the excludeNode method to add an exclusion clause for a node, with options to include or exclude its parents and children. ```javascript selectorService.excludeNode(node, {parents: true, children: false}); // Excludes: "+node_name" ``` -------------------------------- ### Get Nodes by Package Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md Matches nodes that belong to a specified package. Use this to isolate nodes originating from a particular dbt package. ```javascript getNodesByPackage(elements: object, package_name: string): array ``` ```javascript getNodesByPackage(elements, 'my_package'); ``` -------------------------------- ### resetSelection Method Example Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md Demonstrates how to use the resetSelection method to focus the selection on a single node, automatically generating an include pattern based on the node's type. ```javascript selectorService.resetSelection(modelNode); ``` -------------------------------- ### dbt-docs Data Flow Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/README.md Illustrates the data flow within dbt-docs, starting from manifest.json and catalog.json inputs to the final visualization and search index. ```mermaid graph TD A[manifest.json + catalog.json] B(projectService.loadProject()) C(merged project object with all nodes) D1(graphService.pristine.nodes + edges) D2(projectService.searchable) D3(projectService.tree.*) E(Cytoscape.js visualization) F(Search index) G(Navigation trees (project, database, groups, etc.)) A --> B B --> C C --> D1 C --> D2 C --> D3 D1 --> E D2 --> F D3 --> G ``` -------------------------------- ### Create New Changelog Entry Source: https://github.com/dbt-labs/dbt-docs/blob/main/CONTRIBUTING.md Generate a new changelog entry using the changie tool. This command will guide you through the process. Commit the generated file to complete the entry. ```shell changie new ``` -------------------------------- ### CommonJS Require Pattern Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/module-system.md Shows how to import modules using the CommonJS `require` syntax, commonly used in Node.js environments and older JavaScript module systems. Includes examples for underscore, angular, jquery, and custom selectors. ```javascript const _ = require('underscore'); const angular = require('angular'); const $ = require('jquery'); const selectorMethods = require('./selector_methods'); ``` -------------------------------- ### Get Macro Dependencies Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Returns all macros that a given macro depends on, grouped by resource type. Helps in understanding macro composition and potential circular dependencies. ```javascript getMacroParents(project: object, macro: object): object ``` -------------------------------- ### Route-Specific URL Parameters Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Details the parameters applicable to specific routes within the documentation, such as unique IDs, sections, and visibility flags, providing examples for various resource types. ```plaintext `/model/:unique_id` | unique_id, section, g_v, g_i, g_e | `/model/model.proj.my_model?section=compiled` `/source/:unique_id` | unique_id, section, g_v, g_i, g_e | `/source/source.raw.customers` `/seed/:unique_id` | unique_id, section, g_v, g_i, g_e | `/seed/seed.proj.lookup_table` `/snapshot/:unique_id` | unique_id, section, g_v, g_i, g_e | `/snapshot/snapshot.proj.user_history` `/test/:unique_id` | unique_id, section, g_v, g_i, g_e | `/test/test.proj.my_test` `/analysis/:unique_id` | unique_id, section, g_v, g_i, g_e | `/analysis/analysis.proj.report` `/macro/:unique_id` | unique_id, section | `/macro/macro.proj.my_macro` `/exposure/:unique_id` | unique_id, section, g_v, g_i, g_e | `/exposure/exposure.proj.dashboard` `/metric/:unique_id` | unique_id, section, g_v, g_i, g_e | `/metric/metric.proj.revenue` `/semantic_model/:unique_id` | unique_id, section, g_v, g_i, g_e | `/semantic_model/semantic_model.proj.customers` `/saved_query/:unique_id` | unique_id, section, g_v, g_i, g_e | `/saved_query/saved_query.proj.report` `/function/:unique_id` | unique_id, section, g_v, g_i, g_e | `/function/function.proj.custom_fn` `/source_list/:source` | source, section, g_v, g_i, g_e | `/source_list/raw?section=docs` `/overview` | project_name (optional), g_v, g_i, g_e | `/overview` `/graph` | None | `/graph` ``` -------------------------------- ### Get Macro References Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Finds all nodes and macros that call a specific macro, categorized by resource type. Useful for impact analysis when refactoring macros. ```javascript const references = getMacroReferences(project, myMacro); ``` -------------------------------- ### Get Nodes by Path Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md Matches nodes based on their file path, supporting glob patterns. Use this to select nodes located in specific directories or matching a file pattern. ```javascript getNodesByPath(elements: object, path: string): array ``` ```javascript getNodesByPath(elements, 'models/marts'); getNodesByPath(elements, 'models/*/staging/stg_*.sql'); ``` -------------------------------- ### Get Model Dependencies Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Retrieves all nodes and macros that a given model depends on, grouped by resource type. Useful for understanding data lineage and upstream dependencies. ```javascript const node = projectService.node('model.project.fct_orders'); const parents = getParents(project, node); // Returns: { // source: [source1, source2], // model: [dim_customers, dim_date], // macro: [macro1] // } ``` -------------------------------- ### Horizontal Graph Configuration Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/graph-service.md Configuration options for the graph in a fullscreen view. This setup allows for user panning and zooming. Note the broader zoom range compared to the vertical configuration. ```javascript { userPanningEnabled: true, boxSelectionEnabled: false, maxZoom: 1, minZoom: 0.05 } ``` -------------------------------- ### Circular Dependency Example Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/module-system.md Illustrates how two services can reference each other in AngularJS, with dependencies injected at runtime to resolve circularity. This pattern is enabled by services being factories and CommonJS module loading. ```javascript angular.module('dbt').factory('graphService', ['project', function(projectService) { ... }]); angular.module('dbt').factory('project', ['$q', '$http', function($q, $http) { ... }]); ``` -------------------------------- ### Get Model Tree Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/project-service.md Builds and retrieves a hierarchical tree of models organized by project structure, database schema, groups, sources, exposures, metrics, semantic models, saved queries, and functions. The tree is updated in `service.tree` and can be highlighted by a selected node. ```javascript service.getModelTree(select: string, callback: function) ``` ```javascript projectService.getModelTree('model.project.customers', function(tree) { console.log(tree.project); // Directory structure console.log(tree.database); // Database/schema structure }); ``` -------------------------------- ### Serve dbt Project Documentation Source: https://github.com/dbt-labs/dbt-docs/blob/main/ci-project/README.md View the generated documentation for the dbt project in a local web server. ```bash $ dbt docs serve ``` -------------------------------- ### init Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/project-service.md Initializes the Project Service by calling the `loadProject()` function. ```APIDOC ## init() ### Description Initializes the service by calling `loadProject()`. ### Returns void ### Example: ```javascript projectService.init(); ``` ``` -------------------------------- ### Project Service Initialization Lifecycle Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/module-system.md Outlines the sequence of operations for initializing the Project Service. This includes loading manifest and catalog data, and resolving loaded callbacks. ```text projectService.init() ↓ loadProject() starts ↓ HTTP load manifest.json ↓ HTTP load catalog.json ↓ Merge and process ↓ service.loaded.resolve() ↓ All ready() callbacks execute ``` -------------------------------- ### ready(callback) Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/project-service.md Registers a callback function to be executed once the project data has been fully loaded and processed. ```APIDOC ## ready(callback) ### Description Registers a callback to be executed when project data is fully loaded. ### Method service.ready(callback: function) ### Parameters #### Path Parameters - **callback** (function) - Required - Called with project object when ready. Receives project as parameter. ### Returns void ### Example ```javascript projectService.ready(function(project) { const models = project.nodes.filter(n => n.resource_type === 'model'); }); ``` ``` -------------------------------- ### Initialize Project Service Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/project-service.md Initializes the Project Service by calling `loadProject()`. This function does not return any value. ```javascript service.init() ``` ```javascript projectService.init(); ``` -------------------------------- ### Production Build Command Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/module-system.md Bundles all modules, inlines manifest.json and catalog.json, minifies output, and creates a single HTML file with embedded JS and data for production deployment. ```bash npm run build ``` -------------------------------- ### Import Prism.js for Syntax Highlighting Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Import Prism.js and necessary components for code syntax highlighting in dbt-docs. Includes SQL, Python, and line-number support. ```javascript import Prism from 'prismjs'; import 'prismjs/components/prism-sql'; import 'prismjs/components/prism-python'; import 'prismjs/plugins/line-numbers/prism-line-numbers.js'; ``` -------------------------------- ### Get Referencing Nodes Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Returns all nodes that depend on (reference) a given model, grouped by their resource type (e.g., model, test, exposure). ```javascript const node = projectService.node('model.project.customers'); const references = getReferences(project, node); // Returns: { // model: [model1, model2], // test: [test1], // exposure: [exposure1] // } ``` -------------------------------- ### Initialize Git Submodules Source: https://github.com/dbt-labs/dbt-docs/blob/main/CONTRIBUTING.md Initialize and update git submodules required for the project. This command should be run after cloning the repository. ```bash git submodule update --init --recursive ``` -------------------------------- ### Get Canvas Height Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/graph-service.md Retrieves the calculated height of the graph canvas as a percentage of the window height. The returned value is a string formatted as 'XXXpx'. ```javascript service.getCanvasHeight(): string ``` ```javascript const height = graphService.getCanvasHeight(); // "720px" ``` -------------------------------- ### trackingService.init Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Initializes the tracking service. This must be called before any tracking occurs. It loads the Snowplow tracker if enabled and accepts configuration options. ```APIDOC ## trackingService.init(opts) ### Description Initializes tracking service. Must be called before tracking occurs. Loads Snowplow tracker if enabled. ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body * **opts** (object) - Required - Configuration object * **track** (boolean) - Optional - Enable/disable tracking * **project_id** (string) - Optional - dbt project ID for context ### Request Example ```javascript trackingService.init({ track: true, project_id: 'abc-123' }); ``` ### Response None #### Success Response (200) None #### Response Example None ``` -------------------------------- ### Get Node by Unique ID Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/project-service.md Directly returns a node object by its unique ID. Returns undefined if the node is not found. This method is synchronous. ```javascript const node = projectService.node('model.project.my_model'); console.log(node.raw_code); // Source code ``` -------------------------------- ### Controller Initialization Pattern Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/components-controllers.md Standard pattern for initializing dbt controllers, including dependency injection, route parameter extraction, and asynchronous data loading via service callbacks. ```javascript angular.module('dbt') .controller('ControllerName', [ '$scope', '$state', 'project', 'graph', 'code', function($scope, $state, projectService, graphService, codeService) { // Get parameter from route $scope.model_uid = $state.params.unique_id; // Wait for project to load projectService.ready(function(project) { // Get node from project let node = project.nodes[$scope.model_uid]; $scope.model = node; // Build dependency info $scope.references = dagUtils.getReferences(project, node); $scope.parents = dagUtils.getParents(project, node); // Prepare display data $scope.highlighted = codeService.highlight(node.raw_code); }); // User interactions $scope.copy_to_clipboard = function(text) { codeService.copy_to_clipboard(text); }; } ]); ``` -------------------------------- ### Generate dbt Project Documentation Source: https://github.com/dbt-labs/dbt-docs/blob/main/ci-project/README.md Create documentation for the dbt project, including model information and lineage. ```bash $ dbt docs generate ``` -------------------------------- ### ready Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/graph-service.md Registers a callback function to be executed once the graph is fully initialized and ready for user interaction. The callback receives the service instance as an argument. ```APIDOC ## ready(callback) ### Description Registers callback to execute when graph is ready for interaction. ### Method `service.ready(callback: function)` ### Parameters #### Path Parameters - **callback** (function) - Required - Called with service as parameter ### Returns void ### Example: ```javascript graphService.ready(function(service) { const elements = service.graph.elements; }); ``` ``` -------------------------------- ### Execute Callback When Project is Ready Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/project-service.md Registers a callback function to be executed once the project data has been fully loaded and processed. The callback receives the project object as an argument. ```javascript projectService.ready(function(project) { const models = project.nodes.filter(n => n.resource_type === 'model'); }); ``` -------------------------------- ### Documentation Structure Overview Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/MANIFEST.md Illustrates the hierarchical organization of the generated documentation files. ```text output/ ├── INDEX.md [Master index - start here] ├── MANIFEST.md [This file] ├── README.md [Main overview and architecture] ├── types.md [All type definitions] ├── configuration.md [All configuration options] ├── module-system.md [Module organization and dependencies] └── api-reference/ [API documentation by service] ├── project-service.md [Project data management] ├── graph-service.md [DAG visualization] ├── selector-services.md [Node filtering and selection] ├── utility-services.md [Supporting services] └── components-controllers.md [UI components and pages] ``` -------------------------------- ### Get Nodes by Config Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md Matches nodes based on their configuration properties, including nested values. Use this to filter nodes by specific dbt configurations like `materialized`. ```javascript getNodesByConfig(elements: object, config_spec: object): array ``` ```javascript getNodesByConfig(elements, {config: 'materialized', value: 'table'}); ``` -------------------------------- ### Graph Service Ready Callback Lifecycle Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/module-system.md Details the process for the Graph Service becoming ready and executing provided callbacks. It shows internal calls to projectService.ready() and graph building steps. ```text graphService.ready(callback) ↓ projectService.ready() called internally ↓ Build graph nodes and edges ↓ Create graphlib DAG ↓ setGraphReady(cytoscape_instance) ↓ service.loaded.resolve() ↓ Callback executes ``` -------------------------------- ### Get Nodes by Source Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md Matches source nodes based on a source name or a specific source and table pattern. Use this to filter nodes belonging to a particular source. ```javascript getNodesBySource(elements: object, source_pattern: string): array ``` ```javascript getNodesBySource(elements, 'raw.customers'); getNodesBySource(elements, 'raw'); // All tables in raw source ``` -------------------------------- ### Complete Selection Workflow Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md Demonstrates a full workflow for selecting nodes, including resetting the selection, excluding archived models, updating the selection criteria, and executing the selection against the DAG. This is useful for complex selection scenarios. ```javascript // 1. Set up initial selection selectorService.resetSelection(customerModel); // 2. Exclude archived models selectorService.excludeNode(archivedNode, {parents: false, children: false}); // 3. Apply changes const clean = selectorService.updateSelection(); // 4. Execute selection against DAG const spec = { ...clean, hops: 2 }; const result = selectorMethods.selectNodes(dag, pristine, spec); // 5. Update graph graphService.updateGraph(spec); ``` -------------------------------- ### parseSpec Function Output Example Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md Illustrates the output structure of the parseSpec function when parsing a selector string, detailing the parsed components like traversal depth and selector type. ```javascript { select_parents: true, parents_depth: 2, select_children: true, children_depth: 3, selector_type: 'tag', selector_value: 'daily' } ``` -------------------------------- ### Building dbt Navigation Trees Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/README.md Generate navigation trees for a selected node, organized by project structure, database, and sources. ```javascript projectService.getModelTree(selected_id, function(tree) { console.log(tree.project); // Directory structure console.log(tree.database); // Database/schema structure console.log(tree.sources); // Sources by source_name }); ``` -------------------------------- ### showFullGraph Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/graph-service.md Renders the complete project dependency graph in fullscreen mode, allowing for user panning and a left-to-right layout. An optional node can be specified to focus the graph on that particular node and its connections. ```APIDOC ## showFullGraph(node_name) ### Description Shows full project graph in fullscreen mode with optional node focus. Uses left-to-right layout. ### Method `service.showFullGraph(node_name: string): array` ### Parameters #### Path Parameters - **node_name** (string) - Optional - Optional node to include and highlight ### Returns Array of visible node IDs ### Graph Settings: - Orientation: `fullscreen` - Layout: `left_right` (Dagre layout) - Options: Horizontal configuration (user panning enabled) ### Example: ```javascript graphService.showFullGraph('my_model'); ``` ``` -------------------------------- ### loadProject() Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/project-service.md Loads the project manifest and catalog files, processes nodes, and builds searchable data. This is a prerequisite for most other project service operations. ```APIDOC ## loadProject() ### Description Loads the project manifest and catalog files from `manifest.json` and `catalog.json`. Processes nodes, sources, exposures, metrics, semantic models, saved queries, unit tests, functions, and macros. Merges catalog data with manifest, builds searchable node list, and applies test metadata. ### Method service.loadProject() ### Parameters None ### Returns void (uses internal deferred promise `service.loaded`) ### Triggers `service.loaded.resolve()` when complete ### Side Effects - Populates `service.files.manifest` and `service.files.catalog` - Builds `service.project` with merged manifest/catalog data - Processes nodes and adds labels for versioned models - Incorporates sources, exposures, metrics, semantic models, saved queries, unit tests, functions into main nodes collection - Cleans and filters macros by adapter type - Creates test metadata and attaches tests to columns - Builds `service.project.searchable` containing indexable nodes ### Example ```javascript projectService.loadProject(); projectService.ready(function(project) { console.log(project.nodes); // Access all nodes console.log(project.macros); // Access all macros }); ``` ``` -------------------------------- ### Loading dbt Project Data Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/README.md Inject the project service and access project data like nodes and macros once the service is ready. ```javascript // Inject service app.controller('MyCtrl', ['project', function(projectService) { projectService.ready(function(project) { console.log(project.nodes); // All nodes console.log(project.macros); // All macros }); }]); ``` -------------------------------- ### Load Project Data Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/project-service.md Loads and processes the dbt manifest and catalog files. This method populates internal service data structures and prepares the project for other operations. Use the `ready` method to access the loaded project data. ```javascript projectService.loadProject(); projectService.ready(function(project) { console.log(project.nodes); // Access all nodes console.log(project.macros); // Access all macros }); ``` -------------------------------- ### Get Quote Character for Column Names Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Retrieve the appropriate quote character based on project metadata for handling column names, especially when tests are attached and quote: true is set. ```javascript var quote_char = getQuoteChar(project.metadata); // Strips quotes from column names for matching when quote: true is set ``` -------------------------------- ### Load Project Data Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Initializes the project service to load data from manifest.json and catalog.json. These files are generated by `dbt docs generate`. ```javascript projectService.loadProject() ``` -------------------------------- ### Get Database Adapter Quote Character Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Returns the appropriate quote character for the project's database adapter. BigQuery, Spark, and Databricks use backticks, while others use double quotes. ```javascript const quoteChar = getQuoteChar(project.metadata); const quotedName = quoteChar + 'customer_id' + quoteChar; // BigQuery: ` + 'customer_id' + ` = `customer_id` // Postgres: " + 'customer_id' + " = "customer_id" ``` -------------------------------- ### Run dbt Models Source: https://github.com/dbt-labs/dbt-docs/blob/main/ci-project/README.md Execute the dbt models to transform raw data into analytical tables. Adjust SQL if facing issues with specific database flavors. ```bash $ dbt run ``` -------------------------------- ### Node Configuration Options Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Defines the structure for node configuration and documentation settings, including general, model-specific, source-specific, test-specific, and custom configurations. ```javascript node.config = { // General enabled: boolean, // Whether node is enabled (true by default) tags: array, // Tags for categorization // Model-specific materialized: string, // 'view', 'table', 'incremental', 'ephemeral' incremental_strategy: string, // 'delete+insert', 'merge', etc. // Source-specific loaded_at_field: string, // Timestamp field for freshness // Test-specific severity: string, // 'error' or 'warn' // Custom configs from dbt_project.yml [custom_key]: any // Any custom config defined in project } node.docs = { show: boolean, // True to show in docs (default true) node_color: string // Custom color: CSS color name or hex code } ``` -------------------------------- ### Configure Bootstrap Tooltips Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Initialize Bootstrap tooltips using jQuery data attributes. Configures selector, placement logic, and container. ```javascript // Tooltips $(document).tooltip({ selector: '[data-toggle="tooltip"]', placement: function(tip, element) { return $(element).attr('data-placement') || 'auto'; }, container: 'body' }); ``` -------------------------------- ### Seed Demo Data Source: https://github.com/dbt-labs/dbt-docs/blob/main/ci-project/README.md Load the CSVs with the demo data set to materialize them as tables in your target schema. This step is not required for typical dbt projects where raw data is already in the warehouse. ```bash $ dbt seed ``` -------------------------------- ### Show Fullscreen Project Graph Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/graph-service.md Displays the full project graph in fullscreen mode with an optional node focus. It uses a left-to-right layout and enables user panning. ```javascript service.showFullGraph(node_name: string): array ``` ```javascript graphService.showFullGraph('my_model'); ``` -------------------------------- ### UI Components Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/MANIFEST.md Documentation for various UI components used in the dbt interface. ```APIDOC ## UI Components ### Description Documentation for various UI components. ### Documented Components - Search Component - Model Tree Component - Code Block Component - Graph Components (2) - Column Details Component - Table Details Component - Macro Arguments Component - References Component ``` -------------------------------- ### Internal Requires and Exports in selector_methods.js Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/module-system.md Demonstrates the internal module dependencies and export pattern for the selector_methods.js file, utilizing underscore and selector_matcher. ```javascript // Internal requires const _ = require('underscore'); const selectorMatcher = require('./selector_matcher'); // Exports module.exports = { selectNodes: function(dag, pristine, selected_spec) { ... } } ``` -------------------------------- ### Define 'customers' Table Source: https://github.com/dbt-labs/dbt-docs/blob/main/ci-project/etc/dbdiagram_definition.txt Defines a table named 'customers' with columns for id, first_name, last_name, and email. 'id' is marked as the primary key. ```dbdiagram Table customers { id int PK first_name varchar last_name varchar email varchar } ``` -------------------------------- ### Execute Callback When Graph is Ready Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/graph-service.md Registers a callback function to be executed once the graph is initialized and ready for interaction. The service instance is passed as a parameter to the callback. ```javascript graphService.ready(function() { // Graph is initialized and ready }); ``` ```javascript graphService.ready(function(service) { const elements = service.graph.elements; }); ``` -------------------------------- ### Build Jekyll CSS Files Source: https://github.com/dbt-labs/dbt-docs/blob/main/CONTRIBUTING.md Build the CSS files required for webpack by running Jekyll build within the styles directory. Navigate back to the root directory after completion. ```bash cd styles bundle exec jekyll build cd - ``` -------------------------------- ### Debug dbt Profile Source: https://github.com/dbt-labs/dbt-docs/blob/main/ci-project/README.md Ensure your dbt profile is set up correctly to connect to your data warehouse. ```bash $ dbt debug ``` -------------------------------- ### Code Service - highlight Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Highlights code using Prism.js syntax highlighter. Returns HTML-safe highlighted markup. ```APIDOC ## highlight(code, language) ### Description Highlights code using Prism.js syntax highlighter. Returns HTML-safe highlighted markup. ### Method ```javascript highlight(code: string, language: string): SafeHtml ``` ### Parameters #### Path Parameters - **code** (string) - Required - Code to highlight - **language** (string) - Optional - Default: 'sql' - Language: 'sql' or 'python' ### Response #### Success Response - **SafeHtml** - Angular $sce.SafeHtml trusted HTML ### Request Example ```javascript $scope.highlighted = codeService.highlight( 'select * from customers where id = 1', 'sql' ); $scope.pythonHighlighted = codeService.highlight( 'def my_func():\n return 42', 'python' ); ``` ``` -------------------------------- ### Configure Bootstrap Popovers Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Initialize Bootstrap popovers using jQuery data attributes. Configures container and HTML content rendering. ```javascript // Popovers $('[data-toggle=popover]').popover({ container: 'body', html: true }); ``` -------------------------------- ### Adapter Compatibility Configuration Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/types.md Defines the structure for specifying database adapter compatibility, including the adapter type and quote character. ```javascript { adapter_type: string, // Database adapter (postgres, bigquery, snowflake, spark, databricks, etc.) quote_char: string // Quote character for identifiers (" or `) } ``` -------------------------------- ### Initialize Tracking Service Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Initializes the tracking service. This must be called before any tracking occurs. It loads the Snowplow tracker if tracking is enabled. ```javascript trackingService.init({ track: true, project_id: 'abc-123' }); ``` -------------------------------- ### Code Service - copy_to_clipboard Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Copies text to system clipboard using document.execCommand('copy'). ```APIDOC ## copy_to_clipboard(text) ### Description Copies text to system clipboard using document.execCommand('copy'). Creates temporary textarea, selects content, executes copy command, then removes element. ### Method ```javascript copy_to_clipboard(text: string) ``` ### Parameters #### Path Parameters - **text** (string) - Required - Text to copy ### Response #### Success Response - **void** ### Request Example ```javascript codeService.copy_to_clipboard(node.raw_code); ``` ``` -------------------------------- ### Project Service Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/INDEX.md Manages project data by loading manifest and catalog files, processing nodes, building tree structures, and providing search capabilities. ```APIDOC ## Project Service API ### Description Manages project data, including loading `manifest.json` and `catalog.json`, processing nodes, building tree structures, and enabling search functionality. ### Methods - `loadProject()`: Load manifest and catalog. - `ready(callback)`: Wait for the project to load. - `node(unique_id)`: Get a node by its unique ID. - `find_by_id(uid, callback)`: Find a node by its ID and execute a callback. - `search(query)`: Perform a fuzzy search for nodes. - `getModelTree(select, callback)`: Build navigation trees based on selection criteria. - `updateSelected(select)`: Mark a node as active based on selection criteria. ``` -------------------------------- ### File Statistics Breakdown Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/MANIFEST.md Provides a breakdown of generated documentation files by name and size. ```text Total files generated: 10 Total size: 156 KB Average file size: 15.6 KB Breakdown: - README.md: 14 KB - INDEX.md: 17 KB - types.md: 15 KB - configuration.md: 14 KB - module-system.md: 16 KB - project-service.md: 9.7 KB - graph-service.md: 11 KB - selector-services.md: 15 KB - utility-services.md: 13 KB - components-controllers.md: 13 KB ``` -------------------------------- ### AngularJS Dependency Injection (Safe) Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/module-system.md Demonstrates the minification-safe array syntax for AngularJS dependency injection. Use this pattern to ensure services remain functional after minification. ```javascript // Good (minification-safe) angular.module('dbt').factory('service', [ 'dep1', 'dep2', function(dep1, dep2) { ... } ]) ``` -------------------------------- ### Initialize Node Selection Service Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Initializes the selector service with default selection values and available filtering options. The defaults object specifies include/exclude patterns, packages, tags, resource types, and traversal depth. ```javascript selectorService.init(defaults) ``` ```javascript { include: string, exclude: string, packages: array, tags: array, resource_types: array, depth: number } ``` ```javascript selectorService.init({ include: '', exclude: '', packages: ['my_project', 'dbt_packages'], tags: [null, 'daily', 'weekly'], resource_types: [ 'model', 'seed', 'snapshot', 'source', 'test', 'unit_test', 'analysis', 'exposure', 'metric', 'semantic_model', 'saved_query', 'function' ], depth: 1 }); ``` -------------------------------- ### getQuoteChar Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Returns the appropriate quote character for the project's database adapter based on provided project metadata. ```APIDOC ## getQuoteChar(project_metadata) ### Description Returns the appropriate quote character for the project's database adapter. ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body * **project_metadata** (object) - Required - Project metadata with adapter_type property ### Request Example ```javascript const quoteChar = getQuoteChar(project.metadata); const quotedName = quoteChar + 'customer_id' + quoteChar; // BigQuery: ` + 'customer_id' + ` = `customer_id` // Postgres: " + 'customer_id' + " = "customer_id" ``` ### Response #### Success Response (200) * **string** - Quote character: `` ` `` for BigQuery/Spark/Databricks, `"` for others. #### Response Example None ``` -------------------------------- ### Define 'orders' to 'customers' Relationship Source: https://github.com/dbt-labs/dbt-docs/blob/main/ci-project/etc/dbdiagram_definition.txt Establishes a foreign key relationship where 'orders.user_id' references 'customers.id'. ```dbdiagram Ref: orders.user_id > customers.id ``` -------------------------------- ### Copy Text to Clipboard Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Copies provided text to the system clipboard using document.execCommand('copy'). This method creates a temporary textarea, selects its content, executes the copy command, and then removes the element. ```javascript codeService.copy_to_clipboard(node.raw_code); ``` -------------------------------- ### Mark Graph as Ready Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/graph-service.md Marks the graph as ready for interaction. This is called when the Cytoscape instance is initialized. It sets loading to false and resolves the loaded promise. ```javascript service.setGraphReady(graph_element: cytoscape) ``` -------------------------------- ### Initialize Tracking Service Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Initializes the tracking service for Snowplow event tracking. Requires a boolean to enable/disable tracking and a dbt project ID for analytics context. ```javascript trackingService.init({ track: boolean, // Enable/disable Snowplow tracking project_id: string // dbt project ID for analytics context }) ``` ```javascript angular.module('dbt').controller('AppCtrl', [ 'trackingService', function(trackingService) { trackingService.init({ track: true, project_id: 'a1b2c3d4' }); } ]); ``` -------------------------------- ### getModelTree Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/project-service.md Builds and returns a categorized tree structure of project models, organized by directory, database, groups, sources, exposures, metrics, semantic models, saved queries, and functions. It highlights a specified active node. ```APIDOC ## getModelTree(select, callback) ### Description Builds model tree organized by project directory structure, database schema, groups, sources, exposures, metrics, semantic models, saved queries, and functions. Updates `service.tree` property with categorized node hierarchies. ### Parameters #### Path Parameters - **select** (string) - Yes - Active/selected node unique_id for highlighting - **callback** (function) - Yes - Called with tree object ### Returns void ### Tree Structure: - `tree.project` - Directory-based tree - `tree.database` - Database/schema organized tree - `tree.groups` - Nodes grouped by dbt groups - `tree.sources` - Sources organized by source name - `tree.exposures` - Exposures organized by type - `tree.metrics` - Metrics organized by package - `tree.semantic_models` - Semantic models organized by package - `tree.saved_queries` - Saved queries organized by package - `tree.functions` - Functions organized by package ### Example: ```javascript projectService.getModelTree('model.project.customers', function(tree) { console.log(tree.project); // Directory structure console.log(tree.database); // Database/schema structure }); ``` ``` -------------------------------- ### Match Nodes by Fully Qualified Name (FQN) Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md Matches nodes using their fully qualified name. Supports exact matches, versioned models, partial paths with globbing, and dot-separated namespaces. ```javascript // Exact match getNodesByFQN(elements, 'customers'); // Partial path with glob getNodesByFQN(elements, 'marts.*.customers'); // Versioned model variants getNodesByFQN(elements, 'dim_customers.v2'); ``` -------------------------------- ### Basic Node Selection Types Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/selector-services.md These selectors specify which nodes to include based on their properties like name, tag, source, exposure, metric, semantic model, saved query, function, path, file, package, group, configuration, test name, or test type. ```text model_name # Implicit: matches FQN or path fqn:path.to.model # Explicit FQN tag:daily # Tag matching source:raw.customers # Source selection exposure:dashboard_name # Exposure selection metric:revenue # Metric selection semantic_model:dim_date # Semantic model selection saved_query:report_query # Saved query selection function:custom_function # Function selection path:models/marts # Path matching file:stg_customers.sql # File matching package:my_package # Package matching group:finance # dbt group matching config.materialized:table # Config matching test_name:not_null # Test name matching test_type:generic # Test type matching ``` -------------------------------- ### Highlight Code Snippet Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/utility-services.md Highlights a given code string using Prism.js syntax highlighter. Returns HTML-safe highlighted markup. Language defaults to 'sql'. ```javascript $scope.highlighted = codeService.highlight( 'select * from customers where id = 1', 'sql' ); $scope.pythonHighlighted = codeService.highlight( 'def my_func():\n return 42', 'python' ); ``` -------------------------------- ### Search Component Methods Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/components-controllers.md Illustrates various methods available within the search component for filtering results, formatting model names, and highlighting text. ```javascript // Filters results based on `max_results` and `show_all` flag. // Returns AngularJS state name for node type: `'dbt.' + node.resource_type` // Formats display name based on resource type: // - Sources: `source_name.table_name` // - Macros: `package_name.macro_name` // - Versioned models: label with version // - Others: name // Filters columns by query tokens. Returns matching column names. // Highlights all query tokens in text with CSS class `search-result-match`. // Shortens text to 150-char window around first query token match. ``` -------------------------------- ### None Layout Configuration Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/graph-service.md Configuration for applying no specific layout algorithm to the graph. Use this when you intend to manually position elements or rely on a preset. ```javascript { name: 'null' } ``` -------------------------------- ### AngularJS Controller Pattern Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/module-system.md Illustrates the standard AngularJS controller definition pattern used in dbt Docs, showing common dependencies injected into the controller function. ```javascript angular.module('dbt') .controller('ModelCtrl', [ '$scope', '$state', 'project', 'code', '$anchorScroll', '$location', function($scope, $state, projectService, codeService, $anchorScroll, $location) { // ... } ]) ``` -------------------------------- ### Configure Markdown Rendering with Marked.js Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Configure the Marked.js library for markdown rendering in index.module.js. Enables GitHub Flavored Markdown and HTML sanitization, and customizes table rendering. ```javascript markedProvider.setOptions({ gfm: true, // GitHub Flavored Markdown sanitize: true // Sanitize HTML }); markedProvider.setRenderer({ table: function(header, body) { return "" + header + ""+ body + "
" } }); ``` -------------------------------- ### Code Service Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/MANIFEST.md Provides utility methods for interacting with code, such as highlighting, copying to clipboard, and generating SQL. ```APIDOC ## Code Service ### Description Provides utility methods for interacting with code. ### Methods - **highlight()**: Highlights code. - **copy_to_clipboard()**: Copies code to the clipboard. - **generateSourceSQL()**: Generates SQL for a given source. ``` -------------------------------- ### URL Query Parameters for State Management Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/configuration.md Lists documented route parameters used for managing state in URLs, including graph visibility, inclusion/exclusion selectors, package filters, resource type filters, and active section/tab parameters. ```plaintext `g_v` | string | Graph visibility flag (1 = show graph) | `?g_v=1` `g_i` | string | Include selector (URL encoded) | `?g_i=%2Bmodel%2B` `g_e` | string | Exclude selector (URL encoded) | `?g_e=tag:temp` `g_p` | string | Package filter (comma-separated) | `?g_p=my_pkg,dep_pkg` `g_n` | string | Resource type filter | `?g_n=model,test` `section` | string | Active section on detail page | `?section=docs` `tab` | string | Active tab on detail page | `?tab=code` ``` -------------------------------- ### Compatibility Service Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/MANIFEST.md Provides functions for ensuring compatibility across different environments. ```APIDOC ## Compatibility Service ### Description Provides functions for ensuring compatibility. ### Functions - **getQuoteChar()**: Retrieves the appropriate quote character for the environment. ``` -------------------------------- ### Top-Down Preset Layout Configuration Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/api-reference/graph-service.md Configuration for a preset layout algorithm that positions nodes in a top-down hierarchy. This is used in the vertical sidebar, arranging parent nodes above their children based on a topological sort. ```javascript { name: 'preset', positions: function(node) { ... } } ``` -------------------------------- ### Components and Controllers Source: https://github.com/dbt-labs/dbt-docs/blob/main/_autodocs/INDEX.md Documents the UI components (directives) and page controllers that constitute the dbt-docs interface. ```APIDOC ## Components and Controllers API ### Description Details the various UI components (directives) and page controllers that form the dbt-docs interface, outlining their functionalities and common usage patterns. ### Components (Directives) - Search component with filtering and highlighting capabilities. - Model tree navigation component. - Code block display with syntax highlighting. - Graph visualization component. - Column details display. - Table details display. - Macro arguments display. - References display component. ### Page Controllers - Controllers for Model, Source, Seed, and Snapshot pages. - Controllers for Test, Analysis, and Macro pages. - Controllers for Exposure, Metric, Semantic Model, Saved Query, and Function pages. - Controllers for Source List, Overview, and Graph pages. ### Common Patterns - Asynchronous data loading using Promises. - Management of scope properties. - Grouping of dependencies. - Feedback mechanisms for copy-to-clipboard actions. ```