Skip to main content
This guide explains how to use dbt’s meta configuration to customize how your dbt resources are displayed and categorized in SYNQ.Prerequisites:
  • A working dbt Core or dbt Cloud integration with SYNQ
  • Familiarity with dbt’s meta configuration

​
Overview

SYNQ reads custom metadata from your dbt project’s meta configuration to enhance how resources are displayed and organized. By adding SYNQ-specific options to your dbt models and tests, you can:
  • Categorize tests into specific Check categories
  • Improve organization and filtering in the SYNQ interface

​
Check category

Use the check_category option to assign a dbt test to a specific Check category in SYNQ. This is useful for organizing standalone dbt tests (generic or singular) into meaningful groups.

​
Configuration

Add the synq configuration to your test’s meta block: 
{{ config(
    meta = {
        'synq': {'check_category': 'e2e'}
    }
)
}}

​
Example: Singular test

For a singular test file (e.g., tests/e2e_order_flow.sql): 
{{ config(
    meta = {
        'synq': {'check_category': 'e2e'}
    }
)
}}

-- Test that verifies the complete order flow from creation to fulfillment
SELECT order_id
FROM {{ ref('orders') }}
WHERE status = 'created'
  AND created_at < CURRENT_TIMESTAMP - INTERVAL '24 hours'
  AND fulfilled_at IS NULL

​
Example: Generic test in schema.yml

For generic tests defined in your schema files: 
models:
  - name: orders
    columns:
      - name: order_id
        tests:
          - unique:
              meta:
                synq:
                  check_category: 'data-quality'
          - not_null:
              meta:
                synq:
                  check_category: 'data-quality'

​
Example: Custom generic test

For custom generic tests, add the config at the top of the test file: 
{% test custom_validation(model, column_name) %}

{{ config(
    meta = {
        'synq': {'check_category': 'validation'}
    }
)
}}

SELECT {{ column_name }}
FROM {{ model }}
WHERE {{ column_name }} IS NOT NULL
  AND NOT {{ column_name }} REGEXP '^[A-Z]{2}[0-9]{6}$'

{% endtest %}

​
How it works

SYNQ automatically categorizes dbt tests based on the test type and package (e.g., dbt, dbt_expectations, dbt_utils). However, for singular tests or custom generic tests, SYNQ may not be able to determine the appropriate category automatically. Using check_category allows you to:
  • Override the automatic categorization for any test
  • Assign meaningful categories to singular tests that would otherwise be uncategorized
  • Group related tests together for better filtering and analysis in SYNQ

​
Custom categories

You can use any category name that makes sense for your organization. Common examples:
CategoryDescription
e2eEnd-to-end tests that validate complete workflows
data-qualityTests for data completeness, accuracy, and consistency
business-rulesTests that enforce business logic and constraints
reconciliationTests that compare data across sources
validationInput validation and format checks
slaService level agreement compliance tests

​
Default categories

SYNQ automatically assigns the following categories to known test types from dbt, dbt_expectations, dbt_utils, and other packages:
CategoryDescription
accepted_valuesTests that validate values are within an allowed set
nullnessTests for null or not-null constraints
uniqueUniqueness validation tests
relationshipsReferential integrity and foreign key tests
freshnessData timeliness and recency tests
row_countRow count validation and volume tests
range_validationTests that check values are within expected ranges
comparisonTests comparing values between columns or tables
structureSchema structure and column existence tests
match_regexPattern matching and regex validation tests
Setting check_category will override the default categorization for any test.

​
Best practices

  1. Use custom categories to group tests by business domain or testing strategy
  2. Be consistent with category names across your project
  3. Document your categories so team members understand what each category represents