The dbt Viewpointにおいて、dbtはソフトウエア開発のシナリオで解決されてきた諸々を考慮した
F/Wであることが説明されている。その中で、バージョン管理、継続的なテストによる品質保証、そして、
ドキュメンテーションの重要性が改めて説明されている。dbtの対象はアプリケーション開発と地続き。
The dbt Viewpointについて以下の記事で書いてみた。
dbt Fundamentalsの「Documentations」セクションを読んで理解した内容を書いてみる。
なぜドキュメンテーションが重要なのか?
dbtが想定するAnalytics Engineeringの新ワークフローで色々解決しようとしている。
dbtが備えるドキュメンテーション機能が存在する理由について言及されている。
ちょっとどうかな..と思うことが多かったが言及されている内容をまとめてみる。
ユーザによる自己解決
ソフトウエア開発のシナリオでは、ドキュメントは主に開発者間のコラボレーションが目的だが、
Analytics Engineeringの世界ではデータの作成者と消費者の間のコラボレーションが目的。
データの作成者と消費者がデータの仕様を共有することは実際の運用で最も重要だと思う。
例えば「どうやって計算したのか」、「どこから持ってきたのか」といった各自の疑問を自己解決して
もらいたい、というモチベがあると言及している。
成果物とドキュメントの統合
ソフトウエアの成果物とドキュメントが分離すると管理が面倒になる。
ソフトウエアのアップデートにドキュメントが追いつかず嘘八百となることは良く観察される。
dbtは、ドキュメントを成果物の一部とすることでその問題を解決することを言及している。
記述の簡便さ
YAMLで書けるので新しい文法の理解は不要としている。
ただしYAMLは厳密なので、それはそれで定義を理解する必要はあると思う。
既存のjavadoc的何かとの比較ではなく、何も無いところとの比較ではその通り。
dbtのドキュメンテーション
では、dbtでそれをどうやるのか。
DAGの観察
dbtには、Sourceから最後のモデルまでの流れを自動的に可視化する機能がある。
全てのmodelの依存関係をSoruceから順番に示してくれる。
特に意識せずとも、model内のref関数が依存関係を示す情報として使われる。
動画では”lineage”ではなく”DAG”と言われている。
Model内のドキュメント
dbtには、modelファイルに特定のテキストを記述することでモデルに情報を付与する機能がある。
どこか別のリポジトリではなく、modelファイルに直接書けることが良いのだよ、と言われている。
modelを書いた後、一呼吸おいて別のところで書くのではなく、modelと一緒に書くのだよとか。
これどうだろうな…。急いでたらSQLだけ書いてコメント直さないなんてありそうだが。
Modelのドキュメント 直書きとdoc blocks
STAGING層にある2つのモデルが例として挙げられている。
model定義の並び、column定義の並びにそれぞれdescriptionを直書きスタイルで配置している。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
version: 2 models: - name: stg_customers description: Staged customer data from our jaffle shop app. columns: - name: customer_id description: The primary key for customers. tests: - unique - not_null - name: stg_orders description: Staged order data from our jaffle shop app. columns: - name: order_id description: Primary key for orders. tests: - unique - not_null - name: status description: '{{ doc("order_status") }}' tests: - accepted_values: values: - completed - shipped - returned - placed - return_pending - name: customer_id description: Foreign key to stg_customers.customer_id. tests: - relationships: to: ref('stg_customers') field: customer_id |
もう1つの方法として、docブロック( {{ doc() }} )を使う方法が説明されている。
上のstatusのdescriptionようにdoc()の中に識別子を書いて、
別ファイル(.md)の中でその識別子の詳細を書く。要は、長いテキストを定義の外に書くスタイル。
(さっき、同じファイルに書くところが良いって言ってたばかりなのに…)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
{% docs order_status %} One of the following values: | status | definition | |----------------|--------------------------------------------------| | placed | Order placed, not yet shipped | | shipped | Order has been shipped, not yet been delivered | | completed | Order has been received by customers | | return pending | Customer indicated they want to return this item | | returned | Item has been returned | {% enddocs %} |
Sourceのドキュメント
modelの場合と同様に、source定義,table定義,column定義にdescriptionを配置している。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
version: 2 sources: - name: jaffle_shop description: A clone of a Postgres application database. database: raw schema: jaffle_shop tables: - name: customers description: Raw customers data. columns: - name: id description: Primary key for customers. tests: - unique - not_null - name: orders description: Raw orders data. columns: - name: id description: Primary key for orders. tests: - unique - not_null loaded_at_field: _etl_loaded_at freshness: warn_after: {count: 12, period: hour} error_after: {count: 24, period: hour} |
ドキュメントの生成と閲覧
動画ではdbt Cloudの例が説明されていて、IDE上でシームレスにドキュメントが表示されている。
説明されているもので全部ではなさそうで、きっとFundamentals用に概要が話されている。
動画で説明されているドキュメントの項目は以下の通り。
– dbt docs generate でドキュメントを生成する
– ymlファイルとその他のファイルに付加した情報がドキュメントに出力される
– (dbt Cloudでは) View Docsボタンの押下により生成されたドキュメントを閲覧できる
– 左ペインにプロジェクト内のファイル階層が表示される。(ModelやSourceが表示される)
– 左ペインからModel(yml)を選択すると、そのymlと対応するドキュメントが表示される
– Detailとして、TAGS,OWNER,TYPE,PACKAGE,LANGUAGE,RELATION。
– DESCRIPTIONとして、ymlに付加したdescription。
– descriptionがdoc blocksの場合、押下で展開される。
– Columnsとして、列名,型,description,TESTの有無,追加の情報
– Referenced Byとして、どのモデルから参照されているか(つまり下流にあるモデル)
– またはどのテストからそのモデルが参照されているか
– Depends Onとして、どのモデルに依存しているか(つまり上流にあるモデル)
– Codeとして、ymlファイルの中身、と、コンパイル済みコード
– yml内のjinjaテンプレートがコンパイル済みコードで展開されている。便利。
– model選択中に右下の View Lineage Graphボタン押下でmodelを含むリネージが表示される
– プロジェクトレベルで View Lineage Graphボタン押下で全体のリネージが表示される
まとめ
dbt Fundamentalsの動画を聴いて、dbtのドキュメント自動生成機能を追ってみた。
Model、SourceにDescriptionを付与し、自動生成ドキュメントに出力されることを確認した。
dbt Cloudでしか試していない。dbt Coreで出すとファイルが吐かれるのだろうか。
ちょっと流石にこれだけだと機能が足りない気がする。
きっと他で補完は必要だと思う。読めてないだけで本体に何かあるのかもだけれども
いったんFundamentalsの読みは終了。