Documentation Flashcards
(40 cards)
What is the primary purpose of documentation in a dbt project?
The primary purpose is to help downstream consumers discover and understand curated datasets. Documentation enhances clarity, trust, and usability of dbt models.
How can dbt documentation be rendered for users to view?
It can be rendered as a website using dbt Docs or enhanced interfaces like Catalog, depending on the dbt plan.
What is required before generating documentation for dbt models?
You must add descriptions to project resources in YAML files where tests are declared.
Where do you add descriptions for models and columns in dbt?
In YAML files such as models/<filename>.yml, using the description: key under each model and column.
What does the dbt docs generate command do?
It compiles information about your dbt project and warehouse into manifest.json and catalog.json files.
What does the dbt docs serve command do?
It launches a local web server that uses the JSON files to render the documentation website.
What is the purpose of the doc() Jinja function in dbt documentation?
It allows referencing markdown content from docs blocks within YAML descriptions.
What are docs blocks in dbt, and how are they defined?
Docs blocks are markdown content defined using Jinja tags {% docs block_name %}...{% enddocs %} in .md files.
How do you use a docs block within a schema.yml file?
By referencing it using description: '{{ doc(\"block_name\") }}', which pulls in the markdown content.
Where should docs block files be saved in a dbt project?
In any resource path such as model-paths, seed-paths, etc., typically with a .md extension.
What is the function of the \_\_overview\_\_ docs block?
It overrides the default overview in dbt Docs with custom content such as company-specific guides or contact info.
Can different dbt packages have custom overview pages?
Yes, by defining docs blocks like \_\_dbt_utils\_\_ or \_\_snowplow\_\_ for each package.
What type of content can go into a docs block?
Markdown content including headers, bullet lists, and links to provide long-form documentation.
Do you need to add a YAML entry for a column for it to appear on the docs site?
Yes, columns must be explicitly defined in YAML with a name and optional description.
Is it possible to document sources, seeds, and snapshots in dbt?
Yes, documentation can be added to these resources similarly to models.
How does dbt Copilot assist with documentation?
It helps generate documentation automatically in the Studio IDE for dbt Enterprise and Enterprise+ users.
What are docs blocks in dbt and what is their purpose?
Docs blocks in dbt are markdown-based documentation sections defined using Jinja. They provide a flexible way to write rich, structured documentation for models and other resources.
What is the correct Jinja syntax for declaring a docs block?
Use {% docs block_name %}...{% enddocs %} to declare a docs block, where block_name is a unique identifier.
What characters are allowed in a docs block name?
Docs block names can include uppercase and lowercase letters, digits, and underscores, but must not start with a digit.
Can docs blocks contain arbitrary markdown?
Yes, they can include any markdown content, such as headers, lists, and links, providing flexibility in how documentation is written.
Where should docs blocks be saved in a dbt project?
Docs blocks should be placed in .md files located in resource paths like model-paths, seed-paths, and others.
How is a docs block used in a schema.yml file?
By referencing it using the Jinja doc() function, like description: '{{ doc(\"block_name\") }}' within the YAML.
In the example provided, what does the {{ doc(\"table_events\") }} expression do?
It embeds the content of the table_events docs block into the description field of the model in the documentation.
Why must docs block names be unique within a dbt project?
To avoid conflicts and ensure that each doc() reference unambiguously maps to a single markdown block.
