如何在dbt的schema.yml中引用markdown文件表格的对应列描述？

云原生阿岚

2026-10-3

解决方案

问题原因

dbt 的 doc() 宏会直接渲染你指定的{% docs %}块内的全部内容，你把所有列的描述都放在同一个column_description块里，引用时自然会返回整张表格
你之前写的{{ doc(column_description") }}存在语法错误：缺少左侧引号、docs块名称没有用引号包裹，运行时会触发语法报错

具体操作步骤

步骤1：调整doc.md的结构，给每个列单独定义docs块

把原来的整表拆分成多个独立的docs块，块名和列名一一对应即可，示例如下：

{% docs cycle_id %}
Customer cycle_id(todays start sleep time to next days start sleep time)
{% enddocs %}

{% docs user_id %}
Customers user_id
{% enddocs %}

{% docs yes_alcohol %}
User consumed alcohol or not
{% enddocs %}

{% docs blank_alcohol %}
User did not answer or user answered "No"
{% enddocs %}

步骤2：修正schema.yml中的引用语法

注意yaml缩进要正确，doc()宏的参数要用双引号包裹，修改后的schema.yml示例：

version: 2

models:
  - name: journal_pivot_dev
    description: One record for each journal entry within one customer cycle
    columns:
      - name: cycle_id
        description: '{{ doc("cycle_id") }}'
        tests: &not_null
          - not_null:
              severity: warn
      - name: user_id
        description: '{{ doc("user_id") }}'
        tests:
          - not_null:
              severity: warn
      - name: yes_alcohol
        description: '{{ doc("yes_alcohol") }}'
        tests: &values_accepted
          - accepted_values:
              severity: warn
              values: [0,1]
      - name: blank_alcohol
        description: '{{ doc("blank_alcohol") }}'          
        tests: *values_accepted