Skip to content

Commit

Permalink
Differentiate between expressions that print and statements that don't (
Browse files Browse the repository at this point in the history
#4546)

[Preview](https://docs-getdbt-com-git-dbeatty-jinja-statements-dbt-labs.vercel.app/docs/build/jinja-macros#jinja)

## What are you changing in this pull request and why?

Instigated by
dbt-labs/dbt-core#9113 (comment)

We want to briefly explain the differences between expressions that
print out and statements that don't.

At the same time, we don't want to fully replicate all the [Jinja
documentation](https://jinja.palletsprojects.com/en/3.0.x/templates/).

Here's a quick table to explain the behavioral differences between the
types of delimiters ("curlies"):

| Name       | Delimiter   | Executes | Prints |
|------------|-------------|:--------:|:------:|
| Expression | `{{ ... }}` |     ✅    |    ✅   |
| Statement  | `{% ... %}` |     ✅    |    ❌   |
| Comment    | `{# ... #}` |     ❌    |    ❌   |

The Jinja docs for the different [types of
delimiters](https://jinja.palletsprojects.com/en/3.0.x/templates/#synopsis:~:text=The%20default%20Jinja%20delimiters%20are%20configured%20as%20follows)
has the advantage of being brief, but lacks clarity especially as it
relates to whether statements print out or not (they don't). Since the
[“do” aka
expression-statement](https://jinja.palletsprojects.com/en/3.1.x/templates/#expression-statement)
is an [optional
extension](https://jinja.palletsprojects.com/en/3.0.x/extensions/#expression-statement)
in Jinja, it isn't documented in list of [control
structures](https://jinja.palletsprojects.com/en/3.0.x/templates/#list-of-control-structures).

## 🎩 

<img width="600" alt="image"
src="https://github.com/dbt-labs/docs.getdbt.com/assets/44704949/23a302e0-d68e-42b4-baca-ff1fb36c4fb0">


## Checklist
- [x] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
- [x] I have checked that the preview renders correctly
- [x] I have checked that the new links work correctly
  • Loading branch information
dbeatty10 authored Dec 18, 2023
1 parent a6d6e6f commit 69c859f
Showing 1 changed file with 2 additions and 2 deletions.
4 changes: 2 additions & 2 deletions website/docs/docs/build/jinja-macros.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,8 +71,8 @@ group by 1

You can recognize Jinja based on the delimiters the language uses, which we refer to as "curlies":
- **Expressions `{{ ... }}`**: Expressions are used when you want to output a string. You can use expressions to reference [variables](/reference/dbt-jinja-functions/var) and call [macros](/docs/build/jinja-macros#macros).
- **Statements `{% ... %}`**: Statements are used for control flow, for example, to set up `for` loops and `if` statements, or to define macros.
- **Comments `{# ... #}`**: Jinja comments are used to prevent the text within the comment from compiling.
- **Statements `{% ... %}`**: Statements don't output a string. They are used for control flow, for example, to set up `for` loops and `if` statements, to [set](https://jinja.palletsprojects.com/en/3.1.x/templates/#assignments) or [modify](https://jinja.palletsprojects.com/en/3.1.x/templates/#expression-statement) variables, or to define macros.
- **Comments `{# ... #}`**: Jinja comments are used to prevent the text within the comment from executing or outputing a string.

When used in a dbt model, your Jinja needs to compile to a valid query. To check what SQL your Jinja compiles to:
* **Using dbt Cloud:** Click the compile button to see the compiled SQL in the Compiled SQL pane
Expand Down

0 comments on commit 69c859f

Please sign in to comment.