dbt - Documentation

The api variable in the Jinja context contains useful objects and methods for building dbt models and macros.

Relation

New in 0.10.1

The Relation object is used to interpolate schema and table names into SQL code with appropriate quoting. This object should always be used instead of interpolating values with {{ schema }}.{{ table }} directly. Quoting of the Relation object can be configured in the Configuring Quoting section of the documentation.

Creating Relations

A Relation can be created in two ways: from a node, or from scratch.

1. Creating a Relation from a node:

class Relation:
  def create_from_node(node, table_name=None):
  """
    node: The dbt node to create a relation for. In the context of a model,
          this  will be the `model` context variable
    table_name (optional): An optional override for the "identifier" part of
          the Relation. If not provided, the Relation will use `node['name']`.
          This is useful when the name of a table differs from the name of
          the model, as with `__dbt_tmp` suffixes. You likely won't need to
          use this argument outside of building custom materializations.
  """

2. Creating a Relation from scratch:

class Relation:
  def create(database=None, schema=None, identifier=None,
             table_name=None, type=None):
  """
    database (optional): The name of the database for this relation
    schema (optional): The name of the schema (or dataset, if on BigQuery) for this relation
    identifier (optional): The name of the identifier for this relation
    table_name (optional): An optional override for the "table" part of
          the Relation. If not provided, the Relation will use `node['name']`.
          This is useful when the name of a table differs from the name of
          the model, as with `__dbt_tmp` suffixes. You likely won't need to
          use this argument outside of building custom materializations.
    type (optional): Metadata about this relation, eg: "table", "view", "cte"
  """

Using Relations

{% set relation = api.Relation.create(schema='snowplow', identifier='events') %}

-- Return the `database` for this relation
{{ relation.database }}

-- Return the `schema` (or dataset) for this relation
{{ relation.schema }}

-- Return the `identifier` for this relation
{{ relation.identifier }}

-- Return the `table_name` for this relation (Deprecated, exists for backwards compatibility reasons)
{{ relation.table }}

-- Return true if the relation is a table
{{ relation.is_table }}

-- Return true if the relation is a view
{{ relation.is_view }}

-- Return true if the relation is a cte
{{ relation.is_cte }}

Column

The Column object is used to encode information about a column in a relation.

class Column(object):
  def __init__(self, column, dtype, char_size=None, numeric_size=None):
    """
      column: The name of the column represented by this object
      dtype: The data type of the column (database-specific)
      char_size: If dtype is a variable width character type, the size of the column, or else None
      numeric_size: If dtype is a fixed precision numeric type, the size of the column, or else None
   """
    
    
# Example Usage:
col = Column('name', 'varchar', 255)
col.is_string() # True
col.is_numeric() # False
col.string_type() # character varying (255)

Column API

Properties:

name: Returns the name of the column
quoted: Returns the name of the column wrapped in quotes
data_type: Returns the data type of the column

Instance methods:

is_string(): Returns True if the column is a String type (eg. text, varchar), else False
is_numeric(): Returns True if the column is a Numeric type (eg. numeric), else False
string_size(): Returns the width of the column if it is a string type, else, an exception is raised

Static methods:

string_type(size): Returns a database-useable representation of the string type (eg. character varying(255))
numeric_type(dtype, size): Returns a database-useable representation of the numeric type (eg. numeric(12, 4))

BigQuery Columns

The Column type is overridden as a BigQueryColumn in BigQuery dbt projects. This object works the same as the Column type described above, with the exception of extra properties and methods:

Properties

fields: Returns the list of subfields contained within a field (if the column is a STRUCT)
mode: Returns the "mode" of the column, eg. REPEATED

Instance methods

flatten(): Return a flattened list of BigQueryColumns in which subfields are expanded into their own columns. For example, this nested field:

[{"hits": {"pageviews": 1, "bounces": 0}}]

will be expanded to:

[{"hits.pageviews": 1, "hits.bounces": 0}]

Result objects

The execution of a resource in dbt generates a Result object. This object contains information about the node that was executed, as well as its resulting status. The JSON Schema for a Result object can be found here. Note that this contract may be subject to change in the future until dbt's API has reached a "stable" state.

{
    'type': 'object',
    'additionalProperties': False,
    'description': 'The result of a single node being run',
    'properties': {
        'error': {
            'type': ['string', 'null'],
            'description': 'The error string, or None if there was no error',
        },
        'skip': {
            'type': 'boolean',
            'description': 'True if this node was skipped',
        },
        'fail': {
            'type': ['boolean', 'null'],
            'description': 'On tests, true if the test failed',
        },
        'status': {
            'type': ['string', 'null', 'number', 'boolean'],
            'description': 'The status result of the node execution',
        },
        'execution_time': {
            'type': 'number',
            'description': 'The execution time, in seconds',
        },
        'node': <Node Contract>,
    },
    'required': ['node'],
}

api


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.