Registry / data / dbt-spark

dbt-spark

JSON →
library1.11.0pypypi✓ verified 25d ago

dbt-spark is the Apache Spark adapter plugin for dbt (data build tool), enabling data analysts and engineers to transform data in Apache Spark using SQL. It leverages Spark's distributed computing capabilities for efficient data transformation. The current version is 1.10.1, and it typically releases new versions in alignment with `dbt-core`'s major and minor releases.

pip install dbt-core dbt-spark
INSTALL
IMPORT
SIG · DBT-SPARK
D
dbt-spark
datapythonv1.11.0
Install
14.9s avg
Import
Disk
149MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.11.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 16.93s
py 3.11
✕ build_error
✓ 15.63s
py 3.12
✕ build_error
✓ 14.2s
py 3.13
✕ build_error
✓ 14.1s
py 3.9
2/3 runs
✓ 13.57s
149MB installed
● package 149MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

dbt-spark
dbt-spark is used primarily via the dbt CLI and configuration files (profiles.yml), not via direct Python import statements in user projects.
dbt adapters are loaded by dbt-core internally; users interact with them through dbt commands and profile configurations.

This quickstart outlines the `profiles.yml` configuration for connecting dbt to a local Spark Thrift server, often set up via docker-compose (as demonstrated in the dbt-spark repository README). It also suggests a basic SQL model for validation.

import os # This quickstart demonstrates configuring dbt-spark with a local Spark Thrift server. # First, ensure you have Docker installed and the dbt-spark local environment set up. # From the dbt-adapters/dbt-spark directory, run: # docker-compose up -d # Create a profiles.yml file in your dbt project's ~/.dbt/ directory or project root profiles_content = ''' spark_local_dev: target: dev outputs: dev: type: spark method: thrift host: 127.0.0.1 port: 10000 user: dbt schema: analytics connect_retries: 5 connect_timeout: 60 retry_all: true ''' # For demonstration, we'll write it to a temporary location # In a real scenario, this goes to ~/.dbt/profiles.yml # or in your dbt project folder directly. profile_path = os.path.expanduser('~/.dbt/profiles.yml') # For a real setup # Or for a quick test in a temporary project directory: # profile_path = 'dbt_project/profiles.yml' # Ensure the directory exists if writing to ~/.dbt/ os.makedirs(os.path.dirname(profile_path), exist_ok=True) with open(profile_path, 'w') as f: f.write(profiles_content) print(f"profiles.yml created at {profile_path} (or its content suggested for it).") print("Next, initialize a dbt project: dbt init my_spark_project") print("Select 'spark_local_dev' as your profile when prompted.") print("Then, create a model, e.g., models/my_model.sql:") print("---\nSELECT 1 AS id, 'hello dbt-spark' AS message\n---") print("Run your dbt models: dbt run --profile spark_local_dev")
dbt --version
Debug
Known issues
breakingThe minor versions of `dbt-spark` and `dbt-core` must match for correct dependency resolution and functionality (e.g., `dbt-spark==1.9.x` requires `dbt-core==1.9.x`). Mixing versions can lead to errors.
fix
Always install `dbt-core` and `dbt-spark` with matching minor versions: `pip install dbt-core==X.Y.Z dbt-spark==X.Y.Z`.
affects: All versions
deprecatedFor Databricks users, the `dbt-databricks` adapter is now the recommended choice over `dbt-spark`, offering easier setup, Unity Catalog support, and better defaults. Migration is advised.
fix
Migrate your project from `dbt-spark` to `dbt-databricks`. Install `dbt-databricks` and update your `profiles.yml` configuration.
affects: All versions when using Databricks
gotchaThe default `incremental_strategy` for `dbt-spark` is `append`, whereas for the `dbt-databricks` adapter, it defaults to `merge`. This can lead to different behavior in incremental models if migrating or using both adapters.
fix
Explicitly set `incremental_strategy: 'merge'` or `incremental_strategy: 'append'` in your incremental models to ensure consistent behavior across adapters.
affects: All versions, especially when considering migration to dbt-databricks
gotchaWhen connecting to a Spark Thrift server, ensure the target `schema` (database) specified in `profiles.yml` already exists in Spark. If it doesn't, dbt will raise a 'Cannot set database in spark!' runtime error.
fix
Manually create the database in Spark (e.g., `CREATE DATABASE your_schema_name;`) before running dbt. Also, ensure the `default` namespace exists when using Thrift.
affects: All versions using Thrift connections
gotchaUsing `dbt-spark` with a schema containing a large number of tables (e.g., thousands) can lead to extremely slow `dbt run` parsing times. This is due to Spark's lack of an information schema layer, forcing dbt to 'discover' all tables.
fix
Consider using dedicated schemas for dbt models with fewer tables or exploring adapter-specific workarounds (if available) for `list_relations_without_caching` limitations.
affects: All versions
Upgrade
Version history
1.11.0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
dbt-corerequiredEssential for dbt functionality; minor versions of dbt-spark and dbt-core should match for compatibility.
pyodbcoptionalRequired for connecting to Spark via ODBC driver.
PyHiveoptionalRequired for connecting to Spark via Thrift or HTTP methods.
pysparkoptionalOften used for session connections or when running Spark locally.
Agent activity
18 hits · last 30 days
node
16
OpenAI (training)
1
Resources
dbt-spark — pip install dbt-spark · libregistry