@dboio/cli 0.11.4 → 0.15.0

package/plugins/claude/dbo/docs/dbo-output-customsql.md

@@ -0,0 +1,677 @@
+# Output — CustomSQL
+
+A **CustomSQL output** executes a raw SQL body stored in `output.CustomSQL` rather than constructing a query from output value configuration. Use when the required query cannot be expressed through the join model — e.g. needs subqueries, window functions, unions, transactions, etc.
+
+**Output type covered**: `Type = 'CustomSQL'`. For the standard join model see `output-query.local.md`. For schema-driven column selection see `output-entity.md`.
+
+**Endpoint**: `GET /api/output/{uid}`
+
+---
+
+
+
+## Data Model
+
+### `output` table
+
+| Column              | Attributes                     | Purpose                             | Notes                                                                                   |
+| :------------------ | :----------------------------- | :---------------------------------- | :-------------------------------------------------------------------------------------- |
+| `AppID`             | `SMALLINT NN FK`               | Parent app                          |                                                                                         |
+| `Name`              | `VARCHAR(100) NN`              | Display name                        | Also used as the asset filename                                                         |
+| `UID`               | `VARCHAR(22) NN AUTOGENERATED` | Stable identifier                   | Auto-generated on creation; cannot be updated. Used in API calls: `/api/output/{UID}`  |
+| `Type`              | `ENUM`                         | Output rendering mode               | Must be `CustomSQL` for this mode                                                       |
+| `BaseEntityID`      | `BIGINT NN FK`                 | Data source reference               | Required — determines which database connection the SQL executes against. Not used for query construction. |
+| `TemplateContentID` | `BIGINT FK`                    | Content record holding the template | Overridable per request via `_template` or an open embed block                          |
+| `Public`            | `BIT default:false`            | Bypass authentication               | When true, no login is required to execute                                              |
+| `Cache`             | `BIT default:false`            | Cache the result set                | Output structure is always cached automatically; this flag caches the result set beyond runtime |
+| `Parameters`        | `VARCHAR(200)`                 | Fixed parameters injected at execution | Format: `key=value&key2=value2`                                                      |
+| `DataSourceID`      | `BIGINT FK`                    | Override data source                | If set, overrides the data source derived from `BaseEntityID`                           |
+| `CustomSQL`         | `TEXT`                         | SQL body                            | Full SQL statement. Before execution: `#{data_source:uid}` tokens are resolved; filter variables (`@ShortName`) are declared and assigned in a syntax appropriate to the data source type. |
+| `Active`            | `BIT default:true`             | Enable or disable this output       | When false, requests return an asset-not-found exception                                |
+
+> **Note**: `Limit`, `MaxRows`, and `RowsPerPage` are not applied to CustomSQL outputs — paging logic runs only for Query-type outputs. 
+
+
+
+### `output_value_filter` table
+
+Each filter record declares a SQL variable (`@ShortName`) available in the SQL body. Reference it directly: `WHERE col = @ShortName`. A variable declaration is prepended before the query **only when a value is present** — from `PrimaryValue`, `output.Parameters`, or a `_filter@ShortName` request parameter. If no value is supplied, no declaration is generated and the variable is unset. The declaration syntax is determined by the data source type ( `data_source.DataSourceTypeID`, resolved via `entity.DataSourceID` ). 
+
+| Column         | Attributes                                                   | Purpose               | Notes                                                        |
+| :------------- | :----------------------------------------------------------- | :-------------------- | :----------------------------------------------------------- |
+| `OutputID`     | `BIGINT FK`                                                  | Parent output         |                                                              |
+| `UID`          | `VARCHAR(22) NN`                                             | Stable identifier     | Auto-generated on creation; cannot be updated                |
+| `ShortName`    | `VARCHAR(45)`                                                | Variable name         | Injects `@ShortName` into the SQL body                       |
+| `FilterPreset` | `ENUM`                                                       | System-provided value | Overrides `PrimaryValue`; see **Filter Presets** below       |
+| `PrimaryValue` | `VARCHAR(100)`                                               | Static value          | Always applied when set; overridable by `_filter` if `Prompted = 1` |
+| `Prompted`     | `BIT default:false`                                          | Accept URL parameter  | When true, value can be supplied via `?_filter@ShortName=value` |
+| `Required`     | `BIT default:false`                                          | Require a value       | When true and no value supplied, query returns no results    |
+
+> **Note**: `FilterType`, `Operator`, and `Inclusive` are not applicable in CustomSQL mode — comparisons are expressed in the SQL body.
+
+---
+
+
+
+## Writing the SQL Body
+
+The `output.CustomSQL` field holds the full SQL statement. Token substitution is applied before execution.
+
+```sql
+SELECT
+    u.UserID,
+    u.FirstName,
+    u.LastName,
+    r.RoleName
+FROM user u
+INNER JOIN user_role ur ON ur.UserID = u.UserID
+INNER JOIN role r ON r.RoleID = ur.RoleID
+WHERE u.Active = 1
+```
+
+
+
+### Column aliases and token references
+
+SQL column aliases become the resolution keys for `#{value@...}` tokens in the template. There are no `output_value` records with `ShortName` to map — the alias is used directly.
+
+```sql
+SELECT u.FirstName AS FirstName, u.LastName AS LastName
+```
+
+`#{value@FirstName}` and `#{value@LastName}` resolve in the output template.
+
+
+
+### Filter variables
+
+Each `output_value_filter` record with a `ShortName` declares a SQL variable. Reference it in the SQL body as `@ShortName`:
+
+```sql
+WHERE col1 = @Status AND col2 = @UserID
+```
+
+A variable declaration is prepended before the query only when a value is present. If no value is supplied and `Required = 0`, no declaration is generated — write the SQL accordingly.
+
+
+
+### Data source tokens
+
+To reference a physical database name in the SQL body — for cross-database queries — use the data source token:
+
+```sql
+SELECT *
+FROM #{data_source.PhysicalName@core}.dbo.user
+WHERE Active = 1
+```
+
+`#{data_source.PhysicalName@shortname}` resolves to the physical database name of the data source whose `ShortName` matches. `core` refers to the instance's primary data source. This token is resolved at query-build time by a dedicated utility, separate from the standard token render pipeline.
+
+Available properties:
+
+| Property       | Returns                        |
+| :------------- | :----------------------------- |
+| `.PhysicalName`| Physical database name         |
+| `.Name`        | Display name                   |
+| `.UID`         | Stable identifier              |
+
+
+
+### Stored procedures
+
+The SQL body can call a stored procedure:
+
+```sql
+EXEC dbo.sp_GetActiveUsers @Active = 1
+```
+
+`BaseEntityID` determines which data source the call executes against. Filter injection is not available for stored procedure calls.
+
+---
+
+
+
+## Execute / Read
+
+```css
+GET /api/output/[uid]
+GET /api/o/[uid]                              ← shorthand
+```
+
+
+
+### Request parameters
+
+| Parameter                             | Description                                                  |
+| :------------------------------------ | :----------------------------------------------------------- |
+| `_filter@ShortName=value`             | Sets the `@ShortName` variable for the matching filter record — requires `Prompted = 1` |
+| `_filter@ShortName:restrictive=value` | Cannot be overridden by any parameter at a higher level in the request stack |
+| `_template={uid\|name}`               | Override template — pass a content UID or built-in template name. See **System templates** |
+| `_debug_sql=true`                     | Return the generated SQL as `text/plain` instead of executing — administrator only. See **_debug_sql** below |
+
+> **Note**: `_rowcount`, `_limit`, `_sort`, `_search`, `_page`, and `_rowsperpage` are not applicable to CustomSQL outputs — query structure, ordering, and pagination are controlled by the SQL body.
+
+> **Note**: `_filter` defaults to `:overridable` — inner embed values win over outer frame values. To lock a filter, use `_filter@ShortName:restrictive=value`. See **Request Stack** below.
+
+
+
+### Request Stack
+
+When a content record renders, each `<#_embed>` pushes a new frame onto the request stack carrying that embed's URL parameters. When a CustomSQL output resolves a request parameter, it walks the stack and applies the resolution rule for that parameter's modifier. The base HTTP request occupies the outermost frame; embed frames stack inward from there.
+
+Stack depth is capped at 100 frames.
+
+> **Note**: Pass `_debug:embeds=true` on any content request and view source to inspect the live stack. Each embed's output includes a `RequestStack:` block showing frame depth, entity identity, and the parameters each frame contributed:
+>
+> ```css
+> REQUEST + _request@_debug:embeds=true
+> \ content Name=my-page, UID=... +
+> \ \ #_embed url=/api/output/[uid]?_filter@Status=active + _filter@Status=active
+> \ \ \ output [UID=[uid], Name=my-output] +
+> ```
+>
+> `\` marks frame depth. `+` separates the frame from its contributed parameters.
+
+#### Modifier reference
+
+| Modifier | Behavior | Default for |
+|----------|----------|-------------|
+| `:restrictive` | Cannot be replaced by an outer frame. | `_limit` |
+| `:overridable` | Can be replaced by an outer frame. | `_filter`, `_display`, `_strict`, `_request` |
+| `:expansive` | All frames contribute — values from every matching frame are merged. | — (opt-in only) |
+
+Unmodified parameters inherit the default modifier for their type.
+
+#### Usage patterns
+
+**Lock a filter against embed override:**
+
+```http
+GET /api/output/[uid]?_filter@Status:restrictive=active
+```
+
+The `:restrictive` modifier locks `Status` at the request frame — no nested embed using the default `:overridable` can replace it. Without it, `_filter` defaults to `:overridable` and a nested embed targeting the same filter would take precedence.
+
+**Allow a limit to be overridden by a nested embed:**
+
+```html
+<#_embed url="/api/output/[uid]?_limit:overridable=10" name="my.list"/>
+```
+
+The `:overridable` modifier marks this limit as a default — any higher-level caller providing `_limit` takes precedence. Without it, `_limit` defaults to `:restrictive` and no outer frame can replace it.
+
+**Accumulate values across frames:**
+
+```http
+GET /api/output/[uid]?_filter@Tags:expansive=admin
+```
+
+```html
+<#_embed url="/api/output/[uid]?_filter@Tags:expansive=active" name="my.list"/>
+```
+
+Both values are applied — the resolved filter covers both `admin` and `active`.
+
+> **Note**: When multiple prompted values are supplied for the same filter, the `:and` or `:or` modifier controls how they are combined. This applies equally to values accumulated across frames via `:expansive`. Default is OR.
+
+#### Stack-eligible parameters
+
+Any parameter prefixed `_` participates in the stack. `_filter` and `_template` are resolved via the stack on every CustomSQL output request.
+
+###### #req-sta
+
+
+
+### _debug_sql
+
+Append `_debug_sql=true` to any output request to return the generated SQL instead of executing. The response is `text/plain` — no template rendering occurs.
+
+Output format:
+
+```css
+-- Parameters:
+
+SET @ShortName := value;
+
+-- Query:
+
+[SQL body with data_source tokens resolved and filter variables declared]
+```
+
+One declaration per filter variable that has a value. Variables with no value are omitted. Debug output always shows MySQL-style `SET @ShortName := value` syntax regardless of the actual data source type.
+
+**Requires administrator access.** Non-administrators receive a 401 response.
+
+###### #deb-sql
+
+
+
+### System templates
+
+Pass a system template identifier to `_template` to override the output's configured template for the request.
+
+**Verified working formats:**
+
+| Identifier      | Content-Type        | Output structure                                                                              | Notes                                                                                                                              |
+| :-------------- | :------------------ | :-------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
+| `json_indented` | `application/json`  | Pretty-printed JSON array, one object per row                                                 | Direct serialization — native types preserved, column names deduplicated. Preferred for API consumption.                          |
+| `json_raw`      | `application/json`  | Compact JSON array, one object per row                                                        | Same serialization path as `json_indented` — native types, no HTML escaping, no whitespace.                                       |
+| `html`          | `text/html`         | `<table>` with header row, one `<tr>` per row                                                 |                                                                                                                                    |
+| `csv`           | `application/json`* | Header row + one row per result, comma-separated                                              | *Content-Type header incorrectly returns `application/json`. Template-rendered; duplicate aliases produce duplicate columns.       |
+| `txt`           | `text/plain`        | Header row + one row per result, space-separated                                              | Template-rendered; duplicate aliases produce duplicate columns.                                                                    |
+| `xml`           | `text/xml`          | *(empty)*                                                                                     | Returns HTTP 200 with empty body — template file is empty. Not usable.                                                            |
+
+###### #sys-tem
+
+
+
+#### Custom template
+
+Pass a content UID to load a content record as the template:
+
+```http
+GET /api/output/[uid]?_template=[content-uid]
+```
+
+The content record's `Extension` field determines the output format: `html` → HTML, `json` → JSON, `xml` → XML, `css` → CSS, `js` → JSON, anything else → plain text.
+
+#### Priority
+
+1. `_template` request parameter (this section)
+2. `TemplateContentID` on the output record
+3. Framework default — JSON
+
+---
+
+
+
+## Embed Syntax
+
+CustomSQL outputs are embedded inside **content records** using the same embed syntax as all output types. See `content.md` (pending).
+
+
+
+### Closed embed
+
+```css
+<#_embed url="/api/output/[uid]"
+    name="my.output"
+    target="MyOutput"/>
+```
+
+
+
+### Open embed
+
+An open embed passes inline section markup to override the output's configured template for this embed instance. The template is format-agnostic — sections can contain markup, CSV, JSON, plain text, or any structured output.
+
+```css
+<#_embed.list url="/api/output/[uid]" name="myoutput">
+  <#_row>
+    #{value@FirstName},#{value@LastName}
+  </#_row>
+  <#_noresult>
+    no results
+  </#_noresult>
+</#_embed.list>
+```
+
+Any alphanumeric suffix after the `.` is the **serialization id**. A serialization id is required on any open embed that contains another open embed; it must match on open and close tags and be unique at the same nesting level.
+
+### Embed attribute reference
+
+| Attribute         | Required | Default   | Notes                                                                                                                                                |
+| :---------------- | :------- | :-------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`             | yes      | —         | `/api/output/[uid]` or `/api/o/[uid]`                                                                                                               |
+| `name`            | no       | —         | Static name for an embed                                                                                                                            |
+| `target`          | no       | —         | Named context for `:cached` tokens and `#{payload$...}`; comma-separated for multiple                                                               |
+| `secure`          | no       | true      | false bypasses access control for this request                                                                                                      |
+| `execute`         | no       | true      | false skips the call entirely                                                                                                                       |
+| `hide`            | no       | false     | true executes query and caches results but does render a payload                                                                                    |
+| `payload`         | no       | true      | Controls whether the embed's rendered output is cached for `#{payload$...}` access. When `hide=true`, defaults to false — set `payload=true` explicitly to cache a hidden embed's output |
+| `catch_exception` | no       | —         | Codes caught silently; true catches all                                                                                                             |
+
+URL query params after `?` are passed through to the embedded output.
+
+###### #emb-att
+
+
+---
+
+
+
+## Template Tags
+
+A template is a content record (`TemplateContentID`) containing section markup. Sections render in this order:
+
+| Step | Tag                | Renders when                        | Frequency                             |
+| :--- | :----------------- | :---------------------------------- | :------------------------------------ |
+| 1    | `<#_shared>`       | Rows exist + shared columns defined | Once, before header                   |
+| 2    | `<#_header>`       | Defined in template                 | Once                                  |
+| 3    | `<#_row>`          | Rows exist                          | Once per row                          |
+| —    | `<#_rowdelimiter>` | Rows exist                          | Between rows (not after last)         |
+| 4    | `<#_summary>`      | Rows exist + summary values defined | Once, after last row                  |
+| 5    | `<#_footer>`       | Defined in template                 | Once                                  |
+| —    | `<#_noresult>`     | Zero rows                           | Once                                  |
+| —    | `<#_empty>`        | Zero rows                           | Once (after noresult if both defined) |
+
+> **Note**: `<#cell>...</#cell>` defines a per-column template block. Use this pattern when writing a cross-query template that must work across outputs without referencing specific column names. Place `<#cell/>` inside `<#_row>` or `<#_header>` where column output should be injected. Within `<#cell>`, `#{title}` and `#{value}` render a column's title and returned value in this scope.
+
+### Value tag
+
+`<#_value.Alias>` outputs a column value by SQL alias. It supports an open form with attributes for conditional rendering:
+
+| Attribute  | Notes                                                                                                                                                                                                                                                                               |
+| :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`    | Comparison value; `_null` matches null database values (not empty strings)                                                                                                                                                                                                          |
+| `modifier` | Comparison type, logic, and inversion — comma-separated for multiple. Comparison (default: exact, case-insensitive): `contains`, `startswith`, `endswith`, `lessthan`, `lessthanorequalto`, `greaterthan`, `greaterthanorequalto`. Logic: `and` (all `value` constraints must match; default is OR). Inversion: `exclude` (flips the result). |
+
+String renders block conditionally
+
+```css
+-- renders WHEN Status IS NOT NULL
+<#_value.Status>
+  status set
+</#_value.Status>
+
+-- renders WHEN Status IS NOT NULL
+<#_value.Status modifier="exclude" value="_null">
+  #{value@Status}
+</#_value.Status>
+
+-- renders WHEN Status IS NULL
+<#_value.Status value="_null">
+  No status set
+</#_value.Status>
+
+-- renders WHEN Price < 100
+<#_value.Price modifier="lessthan" value="100">
+  under $100
+</#_value.Price>
+
+-- renders WHEN ( Status = 'active' OR Status = 'verified' )
+<#_value.Status value="active,verified">
+  active and verified
+</#_value.Status>
+```
+
+###### #tem-tag
+
+---
+
+
+
+## Data Tokens
+
+### Token syntax
+
+```css
+#{type@reference$target!default:modifier;comment}
+```
+
+> **Note**: type attribute must come first; after that order does not matter.
+
+| Part      | Symbol | Notes                                                        |
+| :-------- | :----- | :----------------------------------------------------------- |
+| type      | —      | See **Token type reference** below. Common: `value`, `id`, `uid`, `output`, `session`, `request` |
+| reference | `@`    | SQL column alias, output property, or named key              |
+| target    | `$`    | Named embed context — required with `:cached`                |
+| default   | `!`    | Fallback value if token resolves empty                       |
+| modifier  | `:`    | Transforms output or controls resolution timing              |
+| comment   | `;`    | Unrendered string                                            |
+
+###### #tok-syn
+
+
+
+### Token type reference
+
+| Type                   | Reference syntax                                              | Resolved in      | Notes                                                                                              |
+| :--------------------- | :------------------------------------------------------------ | :--------------- | :------------------------------------------------------------------------------------------------- |
+| `value` (`data.value`) | `@Alias`                                                     | Result-set pass  | Field value for current row — reference is the SQL column alias                                    |
+| `id` (`data.id`)       | —                                                             | Result-set pass  | Numeric PK of current row's base entity                                                            |
+| `uid` (`data.uid`)     | —                                                             | Result-set pass  | UID of current row's base entity                                                                   |
+| `output.row`           | `@index`                                                      | Result-set pass  | Current row number; `:global` for cross-page value                                                 |
+| `output.row`           | `@count:returned`                                             | Result-set pass  | Count of returned rows                                                                             |
+| `output.[ColumnName]`  | —                                                             | Result-set pass  | Any property of the output record — e.g. `#{output.Name}`, `#{output.AppID}`                      |
+| `payload`              | `$Target`                                                     | Template pass    | Rendered output of named embed; resolved after all embeds execute                                  |
+| `session`              | `@UserID`, `@Email`, `@FirstName`, `@LastName`, `@uid`, others | Template pass  | Resolved in template content render — see **Token scope** below                                    |
+| `request`              | `@ParamName`                                                  | Template pass    | URL query parameter — see **Token scope** below                                                    |
+| `input`                | `@add1.id`, `@add2.id`, …                                     | Input batch      | ID of a record created in the same input batch                                                     |
+| `unique`               | —                                                             | Template pass    | Generates a GUID                                                                                   |
+
+###### #tok-typ
+
+
+
+### Value token modifiers
+
+| Modifier         | Effect                                                                                                                              |
+| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
+| `:cached$Target` | Defers token resolution until all embeds finish executing; `$Target` specifies which embed's context to read from when multiple embeds are present |
+| `:no_escape`     | Bypasses context-aware HTML escaping — use for trusted raw output                                                                   |
+| `:raw`           | Deferred injection via placeholder (final render pass)                                                                              |
+| `:{format}`      | Any .NET format string applied via `.ToString(format)` — see **Modifier Syntax** below                                              |
+
+###### #val-mod
+
+
+
+### Modifier Syntax
+
+Any .NET format string used as a modifier formats the resolved value before output:
+
+```css
+#{value@CreatedOn:d}            → short date (e.g. 1/3/2024)
+#{value@CreatedOn:M}            → month and day (e.g. January 3)
+#{request@Price:f2}             → 12.50
+#{value:c2}                     → $12.50
+```
+
+Format strings are locale-dependent (server locale).
+
+###### #mod-syn
+
+
+
+### Row data
+
+| Token                       | Canonical form            | Returns                                     |
+| :-------------------------- | :------------------------ | :------------------------------------------ |
+| `#{value@Alias}`            | `#{data.value@Alias}`     | Field value for the current row             |
+| `#{value@Alias!fallback}`   | —                         | With default if empty                       |
+| `#{value@Alias:no_escape}`  | —                         | Raw unescaped value                         |
+
+`Alias` is the SQL column alias from the `SELECT` clause.
+
+
+
+### Output metadata
+
+| Token                          | Returns                                                                                     |
+| :----------------------------- | :------------------------------------------------------------------------------------------ |
+| `#{output.row@index}`          | Current row number (within returned rows)                                                   |
+| `#{output.row@count:returned}` | Total returned row count                                                                    |
+| `#{output.PropertyName}`       | Any property of the output record — e.g. `#{output.Name}`, `#{output.UID}`, `#{output.AppID}` |
+
+
+
+### Token scope
+
+Token resolution happens in two sequential passes:
+
+**Content render pass** (first): The template content record (`TemplateContentID`) renders with full token access — session, request, site, meta, unique, payload, and include tokens all resolve. Their values are baked into the template string before row iteration begins.
+
+**Output row render pass** (second): Section blocks (`<#_row>`, `<#_header>`, etc.) are processed per-row. This pass resolves `value`, `id`, `uid`, and `output.*` tokens only. Session, request, and similar tokens are not re-processed here — they were already resolved in the first pass.
+
+The practical consequence: `#{session@UserID}` anywhere in the template (including inside `<#_row>`) resolves to the same value for every row, baked in before the row loop runs.
+
+###### #tok-sco
+
+
+
+### Cached embed reads
+
+`:cached` defers token resolution until after all embeds execute. `$Target` is required — omitting it causes ambiguous resolution when multiple embeds are active.
+
+```css
+<#_embed url="/api/output/[uid]" target="MyOutput"/>
+#{value@SomeField:cached$MyOutput}
+```
+
+
+
+### Payload tokens
+
+`#{payload$Target}` accesses the rendered output of a named embed after execution. The embed must have a matching `target="..."` attribute.
+
+| Token               | Returns                                                                           |
+| :------------------ | :-------------------------------------------------------------------------------- |
+| `#{payload$Target}` | Full rendered output of the embed (HTML, JSON, or whatever the template produces) |
+
+Payload tokens resolve in the same deferred pass as `:cached` value tokens — after all embeds have executed.
+
+```css
+<#_embed url="/api/output/[uid]" target="UserData" hide="true" payload="true"/>
+
+#{payload$UserData} → rendered output of the embed
+```
+
+###### #pay-tok
+
+---
+
+
+
+## Filters
+
+Filters are driven by `output_value_filter` records attached to the output. Each record declares an `@ShortName` variable used directly in the SQL body.
+
+
+
+### Prompted filter
+
+Set `Prompted = 1` and `ShortName` on a filter record to accept a URL parameter at request time:
+
+```css
+?_filter@ShortName=value
+```
+
+The value is injected as a single `@ShortName` variable. Multiple values or compound logic must be handled in the SQL body.
+
+
+
+### Request stack and filter priority
+
+When a CustomSQL output is embedded, its caller can pass filter parameters down to it. The **request stack** tracks these values across embed levels.
+
+The `:restrictive` and `:overridable` modifiers control how a filter value behaves within this stack:
+
+| Modifier       | Behavior                                                                                                                                                                                 |
+| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:restrictive` | The filter value is a hard requirement. It cannot be replaced or removed by any other layer of the stack. Use when a security constraint or scoping rule must be enforced regardless of caller context. |
+| `:overridable` | The filter value is a default. A higher layer of the request stack can replace it. Use when the output provides a sensible default that callers may legitimately need to change.         |
+
+When neither modifier is present, the default behavior is equivalent to `:overridable` — the value is applied unless overridden.
+
+```css
+?_filter@ShortName:restrictive=value
+?_filter@ShortName:overridable=value
+```
+
+
+
+### Filter presets
+
+These preset values can be stored in `output_value_filter.PrimaryValue` or passed as `_filter` parameter values.
+
+| Preset                                                       | Resolves to                                                  |
+| :----------------------------------------------------------- | :----------------------------------------------------------- |
+| `CurrentUserID`                                              | Current user's ID (may differ from logged-in user under impersonation) |
+| `LoggedInUserID`                                             | Logged-in user's ID (unchanged under impersonation)          |
+| `Now`                                                        | Current datetime                                             |
+| `Today`, `ThisWeek`, `ThisMonth`, `ThisYear`, `Yesterday`, `LastWeek`, `LastMonth`, `LastQuarter`, `LastYear` | Date presets generate SQL date ranges (`BETWEEN start AND end`) |
+| `IpAddress`                                                  | Requester's IPV4 address                                     |
+| `SessionUID`                                                 | Current session UID                                          |
+| `CurrentSiteID`                                              | Current site associated to content in request                |
+| `_security@view`                                             | Row IDs the user has View permission for                     |
+| `_security@add`                                             | Row IDs the user has Add permission for                      |
+| `_security@edit`                                             | Row IDs the user has Edit permission for                     |
+| `_security@delete`                                           | Row IDs the user has Delete permission for                   |
+| `_security@associate`                                        | Row IDs the user has Associate permission for                |
+| `_security@execute`                                          | Row IDs the user has Execute permission for                  |
+| `_security@impersonate`                                      | Row IDs the user has Impersonate permission for              |
+
+###### #fil-pre
+
+---
+
+
+
+## Row Limit
+
+`output.Limit` and `output.MaxRows` are not applied to CustomSQL outputs — paging logic runs only for Query-type outputs. Write `LIMIT` directly in the SQL body:
+
+```sql
+SELECT u.UserID, u.FirstName
+FROM user u
+LIMIT 100
+```
+
+---
+
+
+
+## Caching
+
+`Cache = 1` caches the result set. Output structure (SQL body, filter config) is cached automatically.
+
+Output metadata is cached under two separate keys. `output:meta:[uid]` is populated during normal rendering. `secure:output:meta:[uid]` is populated when the DBO security system internally evaluates the output for row-level access control — external parameters are blocked in that mode to prevent request values from influencing security decisions. Both entries are independent and must be cleared explicitly:
+
+```http
+GET /api/cache/refresh?_key=output:meta:[output.UID]
+GET /api/cache/refresh?_key=secure:output:meta:[output.UID]
+```
+
+`voidcache` flushes all caches globally:
+
+```http
+GET /api/output/[uid]?voidcache=true
+```
+
+---
+
+
+
+## Legacy
+
+### Legacy filter injection syntax
+
+`#{filter:targetField:uid_or_shortname}` was the mechanism for placing filter conditions inside a CustomSQL body. Superseded by `@ShortName` variable injection.
+
+```sql
+-- Legacy
+WHERE #{filter:u.RoleID:RoleID}
+
+-- Current
+WHERE u.RoleID = @RoleID
+```
+
+### Legacy URL parameters
+
+| Parameter         | Superseded by                                     | Notes                                                                                                                                                                             |
+| :---------------- | :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_maxrows=N`      | Write `LIMIT N` in SQL body                       | Not equivalent — `_maxrows` was never applied to CustomSQL outputs                                                                                                                |
+| `_template=json`  | `_template=json_indented` or `_template=json_raw` | Routes through the DBO content rendering pipeline — values serialized as strings, duplicate aliases produce duplicate keys, slower than direct serialization. Prefer `json_indented` or `json_raw`. |
+
+### Legacy embed syntax
+
+`<EmbedToken>` and `<#embed>` were the predecessors to `<#_embed>`.
+
+```css
+<!-- Legacy -->
+<EmbedToken url="/api/output/[uid]" name="my.output" />
+
+<!-- Legacy -->
+<#embed url="/api/output/[uid]" name="my.output"/>
+```