0
# dbt-core
1

2
dbt (data build tool) is a command-line tool that enables data analysts and engineers to transform data in their warehouses by writing SQL select statements. dbt handles turning these statements into tables and views through a transformation workflow that includes dependency management, testing, documentation, and version control, bringing software engineering practices to analytics workflows.
3

4
## Package Information
5

6
- **Package Name**: dbt-core
7
- **Package Type**: pypi  
8
- **Language**: Python
9
- **Installation**: `pip install dbt-core`
10
- **Version**: 1.10.10
11
- **License**: Apache-2.0
12
- **Documentation**: https://docs.getdbt.com/
13

14
## Core Imports
15

16
```python
17
# Main programmatic interface
18
from dbt.cli.main import dbtRunner, dbtRunnerResult
19

20
# Exception handling
21
from dbt.exceptions import (
22
    ContractBreakingChangeError,
23
    DbtInternalError,
24
    DbtRuntimeError,
25
    DbtConfigError,
26
    DbtValidationError,
27
    CompilationError,
28
    CommandResultError
29
)
30

31
# Configuration and flags
32
from dbt.flags import get_flags, set_flags
33
from dbt.constants import DBT_PROJECT_FILE_NAME, MANIFEST_FILE_NAME
34

35
# Version information
36
from dbt.version import get_version_information, get_installed_version
37
```
38

39
## Basic Usage
40

41
### Command Line Interface
42

43
dbt is primarily used via its command-line interface:
44

45
```bash
46
# Initialize a new dbt project
47
dbt init my_project
48

49
# Install dependencies
50
dbt deps
51

52
# Parse and validate project
53
dbt parse
54

55
# Run all models
56
dbt run
57

58
# Run tests
59
dbt test
60

61
# Generate documentation
62
dbt docs generate
63
dbt docs serve
64
```
65

66
### Programmatic API
67

68
For Python applications that need to invoke dbt programmatically:
69

70
```python
71
from dbt.cli.main import dbtRunner, dbtRunnerResult
72

73
# Initialize the runner
74
runner = dbtRunner()
75

76
# Execute a dbt command
77
result: dbtRunnerResult = runner.invoke(['run', '--select', 'my_model'])
78

79
if result.success:
80
    print("dbt run succeeded")
81
    print(f"Result: {result.result}")
82
else:
83
    print(f"dbt run failed: {result.exception}")
84
```
85

86
## Architecture
87

88
dbt-core follows a modular architecture:
89

90
- **CLI Layer**: Click-based command-line interface with 15+ commands
91
- **Runner Layer**: Programmatic execution engine (dbtRunner)
92
- **Compilation Engine**: Transforms dbt models into executable SQL
93
- **Execution Engine**: Runs compiled SQL against data warehouses
94
- **Artifact System**: Generates structured metadata about runs and results
95
- **Plugin System**: Extensible adapter architecture for different databases
96
- **Event System**: Structured logging and event handling
97

98
## Capabilities
99

100
### Command-Line Interface
101

102
Complete CLI with commands for project lifecycle management, model execution, testing, and documentation generation.
103

104
```python { .api }
105
def cli() -> None:
106
    """Main CLI entry point with sub-commands for all dbt operations."""
107
```
108

109
[CLI Commands](./cli-commands.md)
110

111
### Programmatic Interface
112

113
Python API for embedding dbt operations in applications and workflows.
114

115
```python { .api }
116
class dbtRunner:
117
    """Programmatic interface for invoking dbt commands."""
118
    
119
    def __init__(
120
        self,
121
        manifest: Optional[Manifest] = None,
122
        callbacks: Optional[List[Callable[[EventMsg], None]]] = None,
123
    ) -> None: ...
124
    
125
    def invoke(self, args: List[str], **kwargs) -> dbtRunnerResult: ...
126

127
class dbtRunnerResult:
128
    """Result container for dbtRunner invocations."""
129
    
130
    success: bool
131
    exception: Optional[BaseException] = None
132
    result: Union[
133
        bool,  # debug
134
        CatalogArtifact,  # docs generate
135
        List[str],  # list/ls
136
        Manifest,  # parse
137
        None,  # clean, deps, init, source
138
        RunExecutionResult,  # build, compile, run, seed, snapshot, test, run-operation
139
    ] = None
140
```
141

142
[Programmatic API](./programmatic-api.md)
143

144
### Configuration Management
145

146
System for managing global flags, project configuration, and runtime settings.
147

148
```python { .api }
149
def get_flags():
150
    """Get current global flags."""
151

152
def set_flags(flags):
153
    """Set global flags."""
154

155
def set_from_args(args: Namespace, project_flags):
156
    """Set flags from command arguments."""
157
```
158

159
[Configuration](./configuration.md)
160

161
### Exception Handling
162

163
Comprehensive exception hierarchy for structured error handling and reporting.
164

165
```python { .api }
166
class ContractBreakingChangeError(DbtRuntimeError):
167
    """Breaking change to enforced contract."""
168

169
# Additional exceptions from dbt-common:
170
# DbtInternalError, DbtRuntimeError, DbtConfigError, 
171
# DbtValidationError, CompilationError, CommandResultError
172
```
173

174
[Exception Handling](./exceptions.md)
175

176
### Artifact System
177

178
Schema definitions and utilities for dbt artifacts like manifests, catalogs, and run results.
179

180
```python { .api }
181
# Artifact schemas available in dbt.artifacts.schemas:
182
# - base: Base artifact schema classes
183
# - results: Result artifact schemas  
184
# - catalog: Catalog artifact schemas
185
# - freshness: Source freshness schemas
186
# - manifest: Manifest artifact schemas
187
# - run: Run result schemas
188
```
189

190
[Artifacts](./artifacts.md)
191

192
### Version Management
193

194
Utilities for version checking and information display.
195

196
```python { .api }
197
def get_version_information() -> str:
198
    """Get formatted version information including core and plugins."""
199

200
def get_installed_version():
201
    """Get currently installed dbt-core version."""
202

203
def get_latest_version():
204
    """Get latest available version from PyPI."""
205
```
206

207
[Version Management](./version.md)
208

209
## Types
210

211
```python { .api }
212
from typing import List, Optional, Union, Callable
213
from argparse import Namespace
214

215
# Core types
216
Manifest = Any  # From dbt.contracts.graph.manifest
217
EventMsg = Any  # From dbt_common.events.base_types
218
CatalogArtifact = Any  # From dbt.artifacts.schemas.catalog
219
RunExecutionResult = Any  # From dbt.artifacts.schemas.run
220
```