dbt doc 生成文档命令示例应用

DBT提供了强大的命令行工具，它使数据分析师和工程师能够更有效地转换仓库中的数据。dbt的一个关键特性是能够为数据模型生成文档，这就是dbt docs命令发挥作用的地方。本教程将指导您完成使用dbt生成和提供项目文档的过程。

dbt doc 命令

dbt docs命令有两个子命令:generate和serve。generate命令用于创建项目文档，而serve命令用于在web浏览器中查看此文档。

• 生成工程文档

要为dbt项目生成文档，在终端中导航到dbt项目的根目录，并运行以下命令:

dbt docs generate

该命令将为您的项目创建一个带有文档的静态站点。该站点包括关于您的模型、测试、源代码等的信息。

• 项目文档服务

生成文档之后，您可以使用serve命令在本地查看它。在终端上运行以下命令:

dbt docs serve

这将启动web服务器实例，并在默认的web浏览器中打开文档。我们可以浏览文档以查看有关dbt项目的信息。

1. 浏览文档

生成的文档提供了关于dbt项目的大量信息。您可以使用project /Database切换在项目文件夹层次结构视图和以数据库为中心的表和视图集合之间切换。您还可以使用搜索栏来查找项目中的特定模型。

2. 数据血缘关系

dbt文档的强大特性是它能够可视化模型之间的关系。我们可以通过点击模型页面中的“Lineage”选项卡来访问这个特性。这将显示所选模型的上游或下游的所有模型的图表，提供数据沿沿性的清晰视图。

dbt docs 示例

假设我们dbt项目有一个简单的模型，可以将原始销售数据转换为更有用的格式。模型定义了名为sales.sql的文件中:

-- models/sales.sql
{{ config(materialized='table') }}

select    
  order_id,    
  product_id,    
  customer_id,    
  quantity,    
  price,    
  quantity * price as total_price,    
  order_date

from raw.sales

同时定义模型的描述文件，sales.yaml：

# models/schema.yml
version: 2

models:  
  - name: sales    
  description: This table contains transformed sales data.    

  columns:      
    - name: order_id        
    description: The unique identifier for each order.      

    - name: product_id        
    description: The unique identifier for each product.      

    - name: customer_id        
    description: The unique identifier for each customer.      

    - name: quantity        
    description: The quantity of the product sold in the order.      

    - name: price        
    description: The price of the product.      

    - name: total_price        
    description: The total price of the order, calculated as quantity * price.      
    - name: order_date        
    description: The date the order was placed.

这里只是示例，当然可以使用中文，更符合用户习惯。

现在可以使用dbt docs generate为这个模型生成文档。在命令行界面中导航到dbt项目根目录并运行生成文档命令:

dbt docs generate

该命令将在dbt项目中生成**target目录。在这个目录中，可以找到manifest.json和catalog.json**文件。这些文件包含有关dbt项目的元数据，基于这些元数据能生成文档web网页。

接下来，我们可以使用dbt docs serve在本地启动文档服务:

dbt docs serve

该命令将启动一个web服务器，并打开文档默认web浏览器。在这里可以看到sales模型的文档页面，其中包含在sales.yaml描述文件中定义的所有列描述和其他信息。

总结

dbt docs命令是为dbt项目生成和提供文档的强大工具。通过使用这个命令，我们可以确保团队和其他相关人员能够访问数据模型的最新的、准确的文档信息。