From efd99212b38d67ea5f629be5ef5cff5beea9e921 Mon Sep 17 00:00:00 2001 From: Kevin Longe <273747162+kvlonge@users.noreply.github.com> Date: Sun, 13 Sep 2026 06:37:30 +0100 Subject: [PATCH] docs: explain grouped declarations --- concepts/declaration-scopes.mdx | 31 +++++++++++++--------- concepts/declaration-scopes/explorer.mdx | 2 +- concepts/declaration-scopes/placement.mdx | 18 +++++++------ concepts/declaration-scopes/visibility.mdx | 25 ++++++++++------- 4 files changed, 45 insertions(+), 31 deletions(-) diff --git a/concepts/declaration-scopes.mdx b/concepts/declaration-scopes.mdx index ba4f2b1..9f71a30 100644 --- a/concepts/declaration-scopes.mdx +++ b/concepts/declaration-scopes.mdx @@ -13,8 +13,8 @@ decide which files can access it. No TOML configuration is required. | Where the declaration lives | Who can use it | |-------------------------------------|--------------------| | Top-level `macros/`, `constants/`, or `enums/` | The whole project | -| Nested `macros/`, `constants/`, or `enums/` | Files in that folder and folders below it | -| Nested `_macros/`, `_constants/`, or `_enums/` | Files directly in that folder only | +| Nested `_sqlbuild/macros/`, `_sqlbuild/constants/`, or `_sqlbuild/enums/` | Files in the owner folder and folders below it | +| Nested `_sqlbuild/_macros/`, `_sqlbuild/_constants/`, or `_sqlbuild/_enums/` | Files directly in the owner folder only | | An underscored constant or enum inside `MODEL()` | That model and its inline SQL hooks only | Macro declarations are Python files (`.py`). Constant and enum declarations are SQL files @@ -29,22 +29,27 @@ models/ ├── constants/ published throughout models/ │ └── warehouse.sql └── commerce/ - ├── macros/ published throughout commerce/ - │ └── currency.py - ├── _enums/ exact commerce/ directory only - │ └── grain.sql + ├── _sqlbuild/ + │ ├── macros/ published throughout commerce/ + │ │ └── currency.py + │ └── _enums/ exact commerce/ directory only + │ └── grain.sql ├── orders.sql sees warehouse, currency, and grain ├── finance/ - │ ├── macros/ published throughout finance/ - │ │ └── tax.py + │ ├── _sqlbuild/ + │ │ └── macros/ published throughout finance/ + │ │ └── tax.py │ └── revenue.sql sees warehouse, currency, and tax └── fulfillment/ └── shipments.sql sees warehouse and currency ``` -A nested unprefixed role applies to its folder and everything below it. An underscored role applies -only to files directly beside it. The same unprefixed role name applies to the whole project only -when it is at the project root. +The folder containing `_sqlbuild/` is the declaration owner. An unprefixed role applies to that +owner and everything below it. An underscored role applies only to files directly in the owner. +Legacy declaration roles directly below an owner remain supported. + +`_sqlbuild/` is reserved for the six declaration-role directories shown above. Other direct files or +folders are rejected, and a project-root `_sqlbuild/` is invalid because it has no resource owner. | Resource | Visible from the example tree | Not visible | |----------|-------------------------------|-------------| @@ -79,8 +84,8 @@ versioned JSON schema rather than parsing text labels. | Where the value is needed | Placement | |---------------------------|-----------| | One model only | In that model's `MODEL()` header | -| Files directly in one folder | In an underscored role beside those files | -| Files across one folder tree | In an unprefixed role at their nearest shared parent folder | +| Files directly in one folder | In an underscored role under the owner's `_sqlbuild/` folder | +| Files across one folder tree | In an unprefixed role under the nearest shared owner's `_sqlbuild/` folder | | Different resource trees, such as models and tests | In a top-level declaration role | SQLBuild computes the lowest common owner of every declaration's runtime consumers. A project-wide diff --git a/concepts/declaration-scopes/explorer.mdx b/concepts/declaration-scopes/explorer.mdx index 2959650..6ff8b8b 100644 --- a/concepts/declaration-scopes/explorer.mdx +++ b/concepts/declaration-scopes/explorer.mdx @@ -153,7 +153,7 @@ Explanation Promotion impact: model:orders Diagnostics (1) - ERROR S008 models/commerce/macros/orders.py: Declaration 'macro:formatted_order_total' is currently descendant-public at 'models/commerce' (models/commerce/macros/orders.py); required exact-owner-private at 'models/commerce'. Consumers: model:orders. Move it to 'models/commerce/_macros/' + ERROR S008 models/commerce/macros/orders.py: Declaration 'macro:formatted_order_total' is currently descendant-public at 'models/commerce' (models/commerce/macros/orders.py); required exact-owner-private at 'models/commerce'. Consumers: model:orders. Move it to 'models/commerce/_sqlbuild/_macros/' Completeness: complete ``` diff --git a/concepts/declaration-scopes/placement.mdx b/concepts/declaration-scopes/placement.mdx index 5fc7a5d..f0117de 100644 --- a/concepts/declaration-scopes/placement.mdx +++ b/concepts/declaration-scopes/placement.mdx @@ -19,8 +19,8 @@ tree. | Where it is needed | Location | |--------------------|----------| | One model only | Inside that model's `MODEL()` header, for enums and constants | -| SQL files directly in one directory | `_macros/`, `_enums/`, or `_constants/` | -| A directory and its descendants | `macros/`, `enums/`, or `constants/` | +| SQL files directly in one directory | `_sqlbuild/_macros/`, `_sqlbuild/_enums/`, or `_sqlbuild/_constants/` | +| A directory and its descendants | `_sqlbuild/macros/`, `_sqlbuild/enums/`, or `_sqlbuild/constants/` | | Different trees, such as models and tests | Top-level `macros/`, `enums/`, or `constants/` | ## One directory @@ -30,13 +30,14 @@ These two models use the same constant and both sit directly in `commerce/`: ```text models/ └── commerce/ - ├── _constants/ - │ └── minimum_value.sql + ├── _sqlbuild/ + │ └── _constants/ + │ └── minimum_value.sql ├── orders.sql └── customers.sql ``` -Use `_constants/` because no descendant directory needs the value. +Use `_sqlbuild/_constants/` because no descendant directory needs the value. ## One directory tree @@ -45,15 +46,16 @@ These models use the same constant across two child directories: ```text models/ └── commerce/ - ├── constants/ - │ └── reporting_day.sql + ├── _sqlbuild/ + │ └── constants/ + │ └── reporting_day.sql ├── finance/ │ └── revenue.sql └── fulfillment/ └── shipments.sql ``` -Use `constants/` in `commerce/` so both child directories can use it. +Use `_sqlbuild/constants/` in `commerce/` so both child directories can use it. ## Different resource trees diff --git a/concepts/declaration-scopes/visibility.mdx b/concepts/declaration-scopes/visibility.mdx index be24ebc..ab9ffa0 100644 --- a/concepts/declaration-scopes/visibility.mdx +++ b/concepts/declaration-scopes/visibility.mdx @@ -5,8 +5,9 @@ description: "See which enums, constants, and macros are available to each SQL f For most SQL, the rule is simple: -> A file can use declarations available to the whole project, declarations in unprefixed role -> folders beside or above it, and declarations in an underscored role folder directly beside it. +> A file can use declarations available to the whole project, declarations in unprefixed roles +> under `_sqlbuild/` folders owned beside or above it, and declarations in an underscored role owned +> directly beside it. ## Start from the SQL file @@ -18,10 +19,11 @@ models/ ├── constants/ available throughout models/ │ └── warehouse.sql └── commerce/ - ├── enums/ available throughout commerce/ - │ └── order_status.sql - ├── _constants/ available directly in commerce/ only - │ └── minimum_value.sql + ├── _sqlbuild/ + │ ├── enums/ available throughout commerce/ + │ │ └── order_status.sql + │ └── _constants/ available directly in commerce/ only + │ └── minimum_value.sql ├── orders.sql └── history/ └── archived_orders.sql @@ -34,12 +36,12 @@ From this tree: | `orders.sql` | `warehouse`, `order_status`, and `minimum_value` | | `history/archived_orders.sql` | `warehouse` and `order_status` | -`minimum_value` is not available in `history/` because `_constants/` applies only to files -directly beside it. +`minimum_value` is not available in `history/` because `_sqlbuild/_constants/` applies only to files +directly in the `_sqlbuild/` owner's folder. ## Supported resource trees -Scoped declaration directories can be placed below these SQL resource roots: +Grouped declaration directories can be placed below these SQL resource roots: | Root | Contents | |------|----------| @@ -57,6 +59,11 @@ when it must be available across different resource trees. Project-root `_consta and `_macros/` directories are invalid because there is no owner folder at the project root for them to be private to. +Existing scoped declaration roles directly below an owner remain supported. `_sqlbuild/` is the +preferred layout because it keeps all declarations together without changing their visibility. +Only the six public/private declaration-role directories are valid directly under `_sqlbuild/`; +other entries are rejected. A project-root `_sqlbuild/` is invalid because it has no resource owner. + ## Which file controls visibility? | SQL being compiled | SQLBuild starts from |