adapter

Overview

adapter is a wrapper around the internal database adapter used by dbt. It allows users to make calls to the database in their dbt models. The adapter methods below will be translated into specific SQL statements depending on the type of adapter your project is using.

The following functions are available:

Deprecated adapter functions

The following adapter functions are deprecated, and will be removed in a future release.

get_missing_columns

Args:

Returns a list of Columns that is the difference of the columns in the from_table and the columns in the to_table, i.e. (set(from_relation.columns) - set(to_table.columns)). Useful for detecting new columns in a source table.

Usage:

models/example.sql
{%- set target_relation = api.Relation.create(
database='database_name',
schema='schema_name',
identifier='table_name') -%}
{% for col in adapter.get_missing_columns(target_relation, this) %}
alter table {{this}} add column "{{col.name}}" {{col.data_type}};
{% endfor %}

expand_target_column_types

Args:

  • from_relation: The source Relation to use as a template
  • to_relation: The Relation to mutate

Expand the to_relation table's column types to match the schema of from_relation. Column expansion is constrained to string and numeric types on supported databases. Typical usage involves expanding column types (from eg. varchar(16) to varchar(32)) to support insert statements.

Usage:

example.sql
{% set tmp_relation = adapter.get_relation(...) %}
{% set target_relation = adapter.get_relation(...) %}
{% do adapter.expand_target_column_types(tmp_realtion, target_relation) %}

get_relation

Args:

  • database: The database of the relation to fetch
  • schema: The schema of the relation to fetch
  • identifier: The identifier of the relation to fetch

Returns a Relation object identified by the database.schema.identifier provided to the method, or None if the relation does not exist.

Usage:

example.sql
{%- set source_relation = adapter.get_relation(
database="analytics",
schema="dbt_drew",
identifier="orders") -%}
{{ log("Source Relation: " ~ source_relation, info=true) }}

get_columns_in_relation

Args:

  • relation: The Relation to find the columns for

Returns a list of Columns in a table.

Usage:

example.sql
{%- set columns = adapter.get_columns_in_relation(this) -%}
{% for column in columns %}
{{ log("Column: " ~ column, info=true) }}
{% endfor %}

create_schema

Args:

  • relation: A relation object with the database and schema to create. Any identifier on the relation will be ignored.

Creates a schema (or equivalent) in the target database. If the target schema already exists, then this method is a no-op.

Usage:

example.sql
{% do adapter.create_schema(api.Relation.create(database=target.database, schema="my_schema"))) %}

drop_schema

Args:

  • relation: A relation object with the database and schema to drop. Any identifier on the relation will be ignored.

Drops a schema (or equivalent) in the target database. If the target schema does not exist, then this method is a no-op. The specific implementation is adapter-dependent, but adapters should implement a cascading drop, such that objects in the schema are also dropped. Note: this adapter method is destructive, so please use it with care!

Usage:

example.sql
{% do adapter.drop_schema(api.Relation.create(database=target.database, schema="my_schema"))) %}

drop_relation

Args:

  • relation: The Relation to drop

Drops a Relation in the database. If the target relation does not exist, then this method is a no-op. The specific implementation is adapter-dependent, but adapters should implement a cascading drop, such that bound views downstream of the dropped relation are also dropped. Note: this adapter method is destructive, so please use it with care!

The drop_relation method will remove the specified relation from dbt's relation cache.

Usage:

example.sql
{% do adapter.drop_relation(this) %}

rename_relation

Args:

  • from_relation: The Relation to rename
  • to_relation: The destination Relation to rename from_relation to

Renames a Relation the database. The rename_relation method will rename the specified relation in dbt's relation cache.

Usage:

example.sql
{%- set old_relation = adapter.get_relation(
database=this.database,
schema=this.schema,
identifier=this.identifier) -%}
{%- set backup_relation = adapter.get_relation(
database=this.database,
schema=this.schema,
identifier=this.identifier ~ "__dbt_backup") -%}
{% do adapter.rename_relation(old_relation, backup_relation) %}

get_columns_in_table

Deprecated

This method is deprecated and will be removed in a future release. Please use get_columns_in_relation instead.

Args:

  • schema_name: The schema to test
  • table_name: The table (or view) from which to select columns

Returns a list of Columns in a table.

models/example.sql
{% set dest_columns = adapter.get_columns_in_table(schema, identifier) %}
{% set dest_cols_csv = dest_columns | map(attribute='quoted') | join(', ') %}
insert into {{ this }} ({{ dest_cols_csv }}) (
select {{ dest_cols_csv }}
from {{ref('another_table')}}
);

already_exists

Deprecated

This method is deprecated and will be removed in a future release. Please use get_relation instead.

Args:

  • schema: The schema to test
  • table: The relation to look for

Returns true if a relation named like table exists in schema schema, false otherwise.

models/example.sql
select * from {{ref('raw_table')}}
{% if adapter.already_exists(this.schema, this.name) %}
where id > (select max(id) from {{this}})
{% endif %}