Skip to main content

Model properties

Models properties can be declared in .yml files in your models/ directory (as defined by the model-paths config).

You can name these files whatever_you_want.yml, and nest them arbitrarily deeply in subfolders within the models/ directory.

Availability

The latest YAML spec is supported in the following environments:

  • dbt platform (Latest release track)
  • dbt Fusion engine
  • dbt Core v1.12

For more information, refer to Migrate to the latest YAML spec.

Available top-level model properties​

PropertyTypeRequiredDescription
namestringYesThe model name (must match the model filename).
descriptionstringNoDocumentation for the model.
columnsarrayNoList of column definitions.
configobjectNoModel configuration (materialization, tags, etc.).
constraintsarrayNoModel-level constraints (primary key, foreign key, etc.).
data_testsarrayNoModel-level data tests.
testsarrayNoLegacy alias for data_tests.
versionsarrayNoModel version definitions.
latest_versionstring/floatNoThe latest version of the model.
deprecation_datestringNoDate when the model is deprecated.
accessstringNoAccess level: private, protected, or public. Supported at the top-level for backwards compatibility only.
time_spineobjectNoTime spine configuration for the Semantic Layer.
semantic_modelobjectNoLatest YAML spec only. Enable semantic model configuration for the Semantic Layer with enabled: true. For other properties, refer to Semantic model properties.
metricsarrayNoLatest YAML spec only. Metrics derived from this semantic model; list is alongside (not under) semantic_model and columns. For other properties, refer to Metric properties.
(Applies to dbt v1.12 and later)

Example file (latest)​

The latest YAML spec includes Semantic Layer properties: semantic_model:, top-level agg_time_dimension and primary_entity, and metrics:. Columns can include entity: and dimension: blocks and granularity for time dimensions. See Semantic model properties and Metric properties for the full structure.

models/<filename>.yml

models:
  # Model name must match the filename of a model -- including case sensitivity
  - name: model_name
    description: <markdown_string>
    latest_version: <version_identifier>
    deprecation_date: <YAML_DateTime>
    config:
      <model_config>: <config_value>
      docs:
        show: true | false
        node_color: <color_id> # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32")
      access: private | protected | public
    constraints:
      - <constraint>
    data_tests:
      - <test>
      - ... # declare additional data tests
    columns:
      - name: <column_name> # required
        description: <markdown_string>
        quote: true | false
        constraints:
          - <constraint>
        data_tests:
          - <test>
          - ... # declare additional data tests
        config:
          meta: {<dictionary>}
          tags: [<string>]
        
        # only required in conjunction with time_spine key
        granularity: <any supported time granularity>
        # In the latest YAML spec, a column can optionally include an entity or dimension block for Semantic Layer.
        #
        # entity:
        #   type: primary | foreign | unique | natural
        #   name: <entity_name>
        # dimension:
        #   type: time | categorical
        #   name: <dimension_name>

      - name: ... # declare properties of additional columns

    time_spine:
      standard_granularity_column: <column_name>

    # Latest YAML spec only: semantic model and metrics on the model
    semantic_model:
      enabled: true
      name: <semantic_model_name>
    agg_time_dimension: <time_dimension_name>   # top-level; references dimension name
    primary_entity: <primary_entity_name>       # optional; use when no column has type: primary
    metrics:
      - name: <metric_name>
        type: simple | cumulative | ratio | derived | conversion
        # ... type-specific properties; see Metric properties

    versions:
      - v: <version_identifier> # required
        defined_in: <definition_file_name>
        description: <markdown_string>
        constraints:
          - <constraint>
        config:
          <model_config>: <config_value>
          docs:
            show: true | false
          access: private | protected | public
        data_tests:
          - <test>
          - ... # declare additional data tests
        columns:
          # include/exclude columns from the top-level model properties
          - include: <include_value>
            exclude: <exclude_list>
          # specify additional columns
          - name: <column_name> # required
            quote: true | false
            constraints:
              - <constraint>
            data_tests:
              - <test>
              - ... # declare additional data tests
            tags: [<string>]
        - v: ... # declare additional versions

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading