### 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.
```