@dboio/cli 0.11.4 → 0.13.2

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

@@ -0,0 +1,967 @@
+# Output — Query
+
+A **Query output** is a named, configurable SQL query stored in the dbo core database. Its structure maps directly to SQL: a base entity (FROM), output values (SELECT), join records (JOIN), and filter records (WHERE / HAVING). Rendered results can be styled through a template stored in a content record.
+
+**Output type covered**: `Type = 'Query'` (default). For `CustomSQL` see `output-customsql.md`.
+
+
+---
+
+
+
+## Data Model
+
+### `output` table
+
+Query metadata and FROM 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                  | `Query` type required   |
+| `BaseEntityID`      | `BIGINT NN FK`      | Table set in the FROM clause           | Required for query output                            |
+| `TemplateContentID` | `BIGINT FK`         | Content record holding the template    | Overridable per request via `_template` or an open embed block |
+| `Limit`             | `INT`               | Rows returned                          |                                                              |
+| `RowsPerPage`       | `INT`               | Rows per page when paginating          | Use with `_page=N` at request time                           |
+| `Public`            | `BIT default:false` | Bypass authentication                  | When true, no login is required to execute                   |
+| `AdhocFilters`      | `BIT default:false` | Allow dynamic column filtering         | When true, columns without pre-configured filters can be targeted with `_filter` |
+| `Cache`             | `BIT default:false` | Cache the result set                   | Output structure is always cached automatically; this flag caches the results set beyond runtime. Not required to acces `:cache` modifier on render tokens. |
+| `Parameters`        | `VARCHAR(200)`      | Fixed parameters injected at execution |                               |
+| `DataSourceID`      | `BIGINT FK`         | Table data source                      | If entity is present in multiple envirnment schemas, this will allow one to switch between connection strings |
+| `CustomSQL`         | `TEXT`              | Custom SQL body                        | Must be null for Query type                                  |
+| `Active`            | `BIT default:true`  | Enable or disable this output          | When false, requests return an asset-not-found exception     |
+
+
+
+### `output_value` table
+
+One output_value record per SELECT column
+
+
+| Column                         | Attributes                                                   | Purpose                                | Notes                                                        |
+| :----------------------------- | :----------------------------------------------------------- | :------------------------------------- | :----------------------------------------------------------- |
+| `OutputID`                     | `BIGINT NN FK`                                               | Parent output                          |                                                              |
+| `UID`                          | `VARCHAR(22) NN AUTOGENERATED`                               | Stable identifier                      | Auto-generated on creation; cannot be updated                |
+| `OrderNumber`                  | `SMALLINT NN`                                                | Column rendering order                 |                                                              |
+| `Title`                        | `VARCHAR(100) NN`                                            | Column label                           | Not available as a column reference                          |
+| `ShortName`                    | `VARCHAR(45)`                                                | Token reference key                    | `#{value@ShortName}`; if null, only UID references this column |
+| `ReferencedEntityColumnID`     | `BIGINT FK`                                                  | Column to SELECT                       |                                                              |
+| `CustomSQL`                    | `LONGTEXT`                                                   | Custom expression                      | Accommodates `CASE` statements, format, and other computations in the SELECT |
+| `OutputValueEntityColumnRelID` | `BIGINT FK`                                                  | Join context for display column        | If null, defaults to base entity                             |
+| `Hide`                         | `BIT default:false`                                          | Exclude from SELECT output             | Useful for columns that are desrired in the `WHERE`, `HAVING`, or `ORDER BY` but not desired the `SELECT` |
+| `Aggregate`                    | `ENUM( 'Group', 'Count', 'Sum', 'Average', 'Min', 'Max')`    |                                        |                                                              |
+| `Summary`                      | `ENUM( 'Count', 'Sum', 'Min', 'Max', 'Average')`             | Row summary aggregate                  | Computed across all rows; renders in `<#_summary>`           |
+| `Shared`                       | `BIT default:false`                                          | Shared value optimization              | When true and all rows share the same value, renders once in `<#_shared>` |
+| `Distinct`                     | `BIT default:false`                                          | Add DISTINCT to SELECT and Aggregation |                                                              |
+| `SortOrder`                    | `SMALLINT`                                                   | Sort priority                          | 1 = primary sort; null = unsorted                            |
+| `SortType`                     | `ENUM( 'Ascending', 'Descending')` `default:ascending`       | Sort type                              |                                                              |
+| `Format`                       | `VARCHAR(30)`                                                | Default value format                   | .NET format string (e.g. `C2`, `d`) — inline token modifier overrides per request |
+| `EnforceSecurity`              | `ENUM( 'Add', 'Edit', 'Delete', 'View', 'Execute', 'Associate')` | Auto-filter rows by user access        | Restricts result rows to those the user can access for the given operation; see **EnforceSecurity** below |
+
+
+
+### EnforceSecurity
+When set, dbo generates an automatic WHERE IN clause at query execution time. This restricts results to rows  accessible to the logged in user for the specified operation (View, Add, Edit, Delete, Execute, Associate). This access is controlled by the security table. Security access is cached at request scope. The output must include the primary key of the source entity — if absent, dbo throws an error at query execution time. For more information see authenticate.md (pending).
+
+> **Note**: `secure=false` on an embed bypasses the Execute permission check for that embed only. It does *not* suppress `EnforceSecurity` row filtering — the WHERE IN clause is generated at query-build time, before the embed's security bypass takes effect.
+
+###### #enf-sec
+
+
+
+
+### `output_value_entity_column_rel` table — one record per JOIN clause
+
+Attach to the output (`OutputID`) to define joins shared across all output values.
+
+| Column                     | Attributes                                                      | Purpose                 | Notes                                                            |
+| :------------------------- | :-------------------------------------------------------------- | :---------------------- | :--------------------------------------------------------------- |
+| `OutputID`                 | `BIGINT NN FK`                                                  | Parent output           |                                                                  |
+| `OutputValueID`                 | `BIGINT FK`                                                  | must be null for `Query` type output. | This column is only  for `Legacy` type output's per-column join system |
+| `UID`                      | `VARCHAR(22) NN`                                                | Stable identifier       | Auto-generated on creation; cannot be updated                    |
+| `SourceEntityColumnID`     | `BIGINT NN FK`                                                  | Join from column        |                                                                  |
+| `ReferencedEntityColumnID` | `BIGINT FK`                                                     | Join to column          | dbo infers ON clause table from the column; NN for `Query` type |
+| `JoinType`                 | `ENUM( 'InnerJoin', 'LeftOuterJoin', 'RightOuterJoin', 'FullOuterJoin') NN` | Join type |                                                                  |
+| `OrderNumber`              | `BIGINT NN`                                                     | Join sequence (1-based) | Determines the order joins are applied                           |
+| `SourceJoinID`             | `BIGINT FK`                                                     | Join from a prior aliased join | Self-reference — see **Child joins** below               |
+| `Alias`                    | `VARCHAR(50)`                                                   | Explicit table alias    | Used when two joins target the same table                 |
+| `CustomSQL`                | `VARCHAR(1000)`                                                 | Custom ON clause        | Replaces the standard column-equality condition                  |
+
+>  **Note**: Join columns are not required to be PK/FK pairs— as in SQL, any columns of matching type can be joined (e.g., varchar to varchar).
+
+**Child joins**: set `SourceJoinID` to the ID of a prior join record to join from it. `SourceJoinID` is **required** when a table has been joined to elsewhere in the query. Without it, the engine cannot determine which table alias is the intended source and throws an ambiguous-source error. For simple joins, where the source table appears only once, `SourceJoinID` may be omitted.
+
+
+
+### `output_value_filter` table — one record per WHERE / HAVING condition
+
+Create a filter record linked to an output value to filter on a specific column. 
+
+| Column             | Attributes                                                                                                          | Purpose                        | Notes                                                                                                                          |
+| :----------------- | :------------------------------------------------------------------------------------------------------------------ | :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
+| `OutputID`         | `BIGINT FK`                                                                                                         | Output-level filter attachment | Mutually exclusive with `OutputValueID`                                                                                        |
+| `OutputValueID`    | `BIGINT FK`                                                                                                         | Column-level filter attachment | Mutually exclusive with `OutputID`                                                                                             |
+| `UID`              | `VARCHAR(22) NN`                                                                                                    | Stable identifier              | Auto-generated on creation; cannot be updated                                                                                  |
+| `OrderNumber`      | `BIGINT NN`                                                                                                         | Filter sequence (1-based)      | No default — must be supplied on create                                                                                        |
+| `ShortName`        | `VARCHAR(45)`                                                                                                       | URL parameter key              | Required for prompted filters: `?_filter@ShortName=value`                                                                     |
+| `FilterType`       | `ENUM( 'Exact', 'Contains', 'StartsWith', 'EndsWith', 'LessThan', 'LessThanOrEqualTo', 'GreaterThan', 'GreaterThanOrEqualTo') default:Exact` | Comparison type |                                                                                                                                |
+| `PrimaryValue`     | `VARCHAR(100)`                                                                                                      | Stored filter value      | Can be overriden when `Prompted` set to true. Preset strings also accepted; see **Filter Presets**                     |
+| `Prompted`         | `BIT default:false`                                                                                                 | Accept URL parameter           | When true, value can be set in query string — see **Filters** |
+| `Required`         | `BIT default:false`                                                                                                 | Require a value                | When true,  if no prompted value is supplied at runtime, query throws exception                             |
+| `Inclusive`        | `BIT default:true`                                                                                                  | Include or exclude             | true = include matches (default); false = exclude matches (NOT)                                                                |
+| `Operator`         | `ENUM( 'OR', 'AND') default:OR`                                                                                     | Multi-value logic              | Applies when multiple values are passed                                                     |
+| `ApplyToAggregate` | `BIT default:false`                                                                                                 | Filter aggregated column    | When true, generates HAVING instead of WHERE                                                                                   |
+
+
+
+**Output attached tokens**: Filters applied at the output level can pass values into the query without restricting the result set. Unlike row filters, these do not generate a WHERE clause — instead, the supplied value is available to calculated columns, SQL formulas, and CASE expressions within the output. Common uses include parameterized formatting, dynamic thresholds, and conditional logic that depends on request or session context.
+
+**Filter value tokens:**  Values passed to the query via `_filter` parameter are available inside CustomSQL expressions as filter_value tokens. The filter_value key uses filter uid or shortname as the reference: e.g. `#{filter_value@Shortname}`. These can be combined with output-level filters (set `OutputID` with no `OutputValueID`) which are not appended to the WHERE clause. 
+
+
+
+---
+
+
+
+## Create
+
+Submit via `POST /api/input/submit?_confirm=true`. All output records can be created in a single transaction using pairing keys (`add1`, `add2`, …). Cross-references within the batch use `=add1` syntax. See `input.md` for details. 
+
+Column references use UID, which in the dbo core are prettified as  `entityName.ColumnName` . See `schema-catalog.md` for system entity column names.
+
+### Example — User list, filter by FirstName, join DefaultMedia, return FullPath
+
+Five records in one transaction: output → two output values (FirstName, FullPath) → one join (user → media) → one filter (FirstName, prompted).
+
+> **Note**: the owning app (`AppID`) must already exist — it cannot be created in the same transaction as the output records.
+
+```css
+POST /api/input/submit?_confirm=true
+
+# add1 — output record (FROM clause)
+RowID:add1;column:output.AppID                                    = [app.UID OR app.AppID]
+RowID:add1;column:output.Name                                     = User List
+RowID:add1;column:output.Type                                     = Query
+RowID:add1;column:output.BaseEntityID                             = user
+
+# add2 — output_value: FirstName (base entity, no join needed)
+RowID:add2;column:output_value.OutputID                           = add1
+RowID:add2;column:output_value.OrderNumber                        = 1
+RowID:add2;column:output_value.Title                              = First Name
+RowID:add2;column:output_value.ShortName                          = FirstName
+RowID:add2;column:output_value.ReferencedEntityColumnID           = user.FirstName
+
+# add3 — output_value: FullPath (from joined media table)
+RowID:add3;column:output_value.OutputID                           = add1
+RowID:add3;column:output_value.OrderNumber                        = 2
+RowID:add3;column:output_value.Title                              = Media Path
+RowID:add3;column:output_value.ShortName                          = MediaPath
+RowID:add3;column:output_value.ReferencedEntityColumnID           = media.FullPath
+
+# add4 — output_value_entity_column_rel: join user.DefaultMediaID → media.MediaID
+RowID:add4;column:output_value_entity_column_rel.OutputID         = add1
+RowID:add4;column:output_value_entity_column_rel.SourceEntityColumnID      = user.DefaultMediaID
+RowID:add4;column:output_value_entity_column_rel.ReferencedEntityColumnID  = media.MediaID
+RowID:add4;column:output_value_entity_column_rel.JoinType         = LeftOuterJoin
+RowID:add4;column:output_value_entity_column_rel.OrderNumber      = 1
+
+# add5 — output_value_filter: filter FirstName by prompted URL param
+RowID:add5;column:output_value_filter.OutputValueID               = add2
+RowID:add5;column:output_value_filter.ShortName                   = FirstName
+RowID:add5;column:output_value_filter.FilterType                  = Contains
+RowID:add5;column:output_value_filter.Prompted                    = 1
+```
+
+Execute with filter: `GET /api/output/[uid]?_filter@FirstName:contains=a`
+
+---
+
+
+
+## Execute / Read
+
+```css
+GET /api/output/[uid]
+GET /api/o/[uid]
+```
+
+### Request parameters
+
+| Parameter                             | Description                                                  |
+| :------------------------------------ | :----------------------------------------------------------- |
+| `_filter@ShortName=value`             | Filter applies to pre-configured `Prompted` filter records   |
+| `_filter@ShortName:restrictive=value` | Cannot be overridden by any parameter at a higher level in the request stack |
+| `_limit=N`                            | Number of rows returned                                      |
+| `_limit=M-N`                          | Range of rows returned                                       |
+| `_rowcount=false`                     | Omit pagination metadata from response — removes a second result table with `Offset`, `MaxRows`, and `TotalRowCount`; result rows are unchanged |
+| `_template={uid\|name}`               | Override template — pass a content UID or built-in template name (e.g., `json_indented`, `json`, `csv`, `xml`). See **System templates** |
+| `_sort=ShortName:[asc\|desc]`         | Sort column and direction                                    |
+| `_search@ShortName1,ShortName2=term`  | Full-text search across specified columns. **See Performance caution —** `_search` |
+| `_page=N`                             | Page number (when `RowsPerPage` is set)                      |
+| `_rowsperpage=N`                      | Override `RowsPerPage` for this request                      |
+| `_debug_sql=true`                     | Return the generated SQL as `text/plain` instead of executing — administrator only. See **_debug_sql** below |
+
+> **Note**: `_filter` defaults to `:overridable` — inner embed values win over outer frame values. To lock a filter against embed override, use `_filter@Field:restrictive=value`. See **Request Stack** below.
+
+**Performance caution — `_rowcount`**: adds `SQL_CALC_FOUND_ROWS` to the SELECT and runs a second `SELECT FOUND_ROWS()` after the main query. MySQL must count all rows matching the WHERE clause regardless of `LIMIT`, which defeats index range scans on large tables. Avoid on high-traffic or large-dataset outputs unless pagination is a hard requirement.
+
+**Performance caution — `_search`**: generates a `CONCAT` of all specified columns (each cast to `VARCHAR`, null-handled) and applies `LIKE '%term%'` to the result. The leading wildcard prevents index use. Expensive on large tables — always pair with `_limit` to cap results. Use `@Shortname` to specify columns to reduce the CONCAT width.
+
+
+
+### Request Stack
+
+When a content record renders, each `<#_embed>` brings its own URL parameters into scope. To resolve a request parameter, dbo works through the embed chain and applies the rule for that parameter's modifier. The original HTTP request is the outermost level; nested embeds build inward from there. Parameters from outer levels are available to inner ones — the modifier determines whether an inner value holds firm, yields to an outer one, or merges with values from multiple levels. 
+
+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]?_limit=2 + _limit=2 ; _request@_limit=2
+> \ \ \ output [UID=[uid], Name=my-output] +
+> ```
+>
+> `\` marks frame depth. `+` separates the frame from its contributed parameters.
+
+#### Modifier reference
+
+| Modifier | Behavior | Default for |
+|----------|----------|-------------|
+| `:restrictive` | Param value cannot be replaced by an outer frame. | `_limit` |
+| `:overridable` | Param value 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
+```
+
+In this example, 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:**
+
+```css
+<#_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:**
+
+```
+GET /api/output/[uid]?_filter@Tags:expansive=admin
+```
+
+```css
+<#_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**: The `output_value_filter.Operator` setting (`OR` / `AND`, default `OR`) controls how multiple prompted values are combined in SQL. This applies equally to values accumulated across frames via `:expansive` — cross-frame values merge into the same filter array and Operator governs their SQL combination.
+
+### Request Keys
+
+URL parameters are available as request tokens regardless of which syntax is used. Any URL parameter `key=value` resolves at `#{request@key}`. The explicit form `_request@Key=value` is equivalent — both produce the same token on the request stack.
+
+| Syntax | URL parameter | Token |
+|--------|---------------|-------|
+| Concise | `?status=active` | `#{request@status}` |
+| Verbose | `?_request@Status=active` | `#{request@Status}` |
+| Quoted reference | `?_filter@Status=active` | `#{request@"_filter@Status"}` |
+
+Use the concise form for application-defined parameters. Use the verbose form when the key would otherwise be parsed as a system token type — for example, when the key begins with `_filter`, `_limit`, or another reserved prefix.
+
+###### #req-key
+
+
+### Request Tokens
+
+`#{request@Key}` reads the value of URL parameter `Key` from the current request context. The parameter can be supplied in either the concise or verbose form — see **Request Keys**.
+
+```css
+#{request@Status}                          ← reads ?Status= or ?_request@Status=
+#{request@CustomerID!0}                    ← falls back to 0 if not present
+#{request@Mode!#{session@DefaultMode}}     ← token as default
+```
+
+Parameters supplied on the outer request URL are available to inner embeds by default — they flow inward through the embed chain. A parameter set inside an embed is scoped to that embed and does not propagate outward.
+
+When the full parameter key contains a reserved string— such as in `#{request@"_filter@Status"}` — quote the reference to prevent the parser from treating it as a property boundary. The quotes are stripped from the resolved reference; single quotes are equivalent.
+
+> **Note**: All standard request parameters (`_filter`, `_sort`, `_limit`, `_template`, `_page`, `_rowsperpage`) are resolved via the stack on every output request.
+
+###### #req-tok
+
+### _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 @ParamName := value;
+
+-- Query:
+
+SELECT ... FROM ... WHERE ... LIMIT ...;
+SELECT 0 AS `Offset`, N AS `MaxRows`, FOUND_ROWS() AS `TotalRowCount`
+```
+
+One declaration per filter parameter that has a value. Parameters with no value are omitted. Debug output always shows MySQL-style `SET @ParamName := value` syntax regardless of the actual data source type.
+
+The second `SELECT` is a pagination metadata query present by default; omit with `_rowcount=false`.
+
+Column aliases in the SELECT use the format `{outputValueUID}_{ShortName}`.
+
+**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. `_template` takes precedence over the output record's `TemplateContentID`; pass a content UID to use a custom template instead.
+
+| 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, summary row if configured | Renders `<#_summary>` when any output value has `Summary` set. |
+| `csv` | `application/json`* | Header row + one row per result, comma-separated | *Content-Type header incorrectly returns `application/json`. Template-rendered; duplicate ShortNames produce duplicate columns. |
+| `txt` | `text/plain` | Header row + one row per result, space-separated | Template-rendered; duplicate ShortNames produce duplicate columns. |
+| `xml` | `text/xml` | *(empty)* | Returns HTTP 200 with empty body — template file is empty. Not usable. |
+
+#### json_indented & json_raw
+
+Both templates serialize the result set as a JSON array of row objects — no wrapper, no entity metadata. Column names are taken from each output value's `Title` field. Primary key columns and internal `Metadata:Count` columns are excluded.
+
+```json
+[
+  { "FirstName": "Jane", "LastName": "Doe", "Email": "jane@example.com" },
+  { "FirstName": "John", "LastName": "Smith", "Email": "john@example.com" }
+]
+```
+
+The default `json` template wraps the result in an entity object with structural metadata:
+
+```json
+{
+  "recordState": "MultiRecord",
+  "metadata": { "entityID": 42, "uid": "...", "displayName": "User", ... },
+  "records": [ { ... } ]
+}
+```
+
+`json_indented` and `json_raw` use the same serialization path — the only difference is whitespace. Both preserve native types (numbers, nulls) without HTML escaping.
+
+**`_format_values=true`**: pass alongside `_template=json_raw` to apply token formatting to cell values before serialization. Without it, raw database values are used directly.
+
+> **Note**: If two output values share the same `Title`, their JSON keys collide — the last value wins. Ensure output value titles are unique when using these templates.
+
+###### #sys-tem
+
+
+
+#### Custom template
+
+Pass a content UID to load a content record as the template:
+
+```css
+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
+
+Outputs are embedded inside **content records** — content is the primary medium through which outputs are composed into pages. Output templates are themselves content records. 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@Name},#{value@Email}
+  </#_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                      |
+
+
+
+###### #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.ShortName>` outputs a column value by ShortName. 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 | `@`    | Column ShortName, UID, 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`)      | `@ShortName`, `@UID`                                         | Result-set pass  | Field value for current row                                                                        |
+| `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.row`                | `@count:global`                                               | Result-set pass  | Total rows across all pages; requires `RowsPerPage`                                               |
+| `output.page`               | `@index`                                                      | Result-set pass  | Current page number; requires `RowsPerPage`                                                       |
+| `output.page`               | `@count`                                                      | Result-set pass  | Total page count; requires `RowsPerPage`                                                          |
+| `output.[ColumnName]` | —                                                             | Result-set pass  | Any property of the output record — e.g. `#{output.Name}`, `#{output.AppID}`                      |
+| `output_value.[ColumnName]` | —                                                             | Result-set pass  | Any property of the output_value record; requires `<#cell>` context                               |
+| `summary`                   | `@ShortName`                                                  | Result-set pass  | Aggregate value for the column; aggregate function configured in `output_value.Summary`            |
+| `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 TemplateContentID 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
+
+
+
+
+### Token modifiers
+
+Modifiers refine how a token resolves or renders. Multiple modifiers may be combined with comma separation. Unless noted, all modifiers apply to all token types.
+
+| Modifier         | Effect                                                                                                                             | Applies to                    |
+| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- |
+| `:cached$Target` | Defers resolution until all embeds finish executing; `$Target` names the embed context                                             | `value`, `request`, `session` |
+| `:raw`           | Defers output injection to the final render pass via placeholder — does not re-parse token syntax within field values              | all                           |
+| `:no_escape`     | Bypasses all format-based escaping (HTML, JSON, XML, CSV) — use for trusted raw output                                             | all                           |
+| `:escape_json`   | Forces JSON-safe escaping regardless of output format — use when embedding a value in a JSON string in non-JSON output             | all                           |
+| `:escape_html`   | Applies HTML encoding; deprecated — HTML output format already encodes by default                                                  | all                           |
+| `:url_encode`    | URL percent-encodes the value via `Uri.EscapeDataString()`                                                                         | all                           |
+| `:url_decode`    | URL-decodes the value via `Uri.UnescapeDataString()`                                                                               | all                           |
+| `:truncate`      | Truncates to 100 characters, appending "..."                                                                                       | all                           |
+| `:global`        | Returns value across all pages; requires `RowsPerPage`                                                                             | `output.row`                  |
+| `:uid`           | 22-character base-62 UID (default `unique` format)                                                                                 | `unique`                      |
+| `:guid`          | Standard GUID format                                                                                                               | `unique`                      |
+| `:integer`       | Auto-incrementing integer per render; combined with `:request`, returns a consistent random 6-digit number for the request         | `unique`                      |
+| `:request`       | Caches the generated value for the duration of the request — same value returned on repeated use                                   | `unique`                      |
+| `:{format}`      | .NET format string applied via `.ToString(format)` — see **Modifier Syntax** below                                                 | `value`, `request`, `summary` |
+
+###### #tok-mod
+
+
+
+
+### Value output escaping
+
+By default, token values are escaped based on the output format: HTML output applies `HttpUtility.HtmlEncode()`, JSON output applies `JsonConvert.ToString()`, XML applies `SecurityElement.Escape()`, and plain-text applies no escaping. This is independent of token type — all types use the same format-driven escaping rules.
+
+Three modifiers override this behavior:
+
+**`:no_escape`** — Suppresses all format-based escaping and returns the raw value string. Use for trusted content that must render verbatim — for example, HTML markup stored in a field, or pre-escaped content injected inline.
+
+**`:raw`** — Defers output injection to a final render pass by substituting a placeholder during template rendering, then replacing it with the resolved value after all rendering completes. Useful when a token in an embed URL would otherwise be replaced prematurely. Does not re-parse token syntax within field values — a database field containing a string like `#{content.UID}` is treated as literal text, not resolved.
+
+**`:escape_json`** — Forces JSON-safe escaping regardless of the current output format. Use when embedding a value inside a JSON string literal in an HTML or plain-text context.
+
+###### #val-esc
+
+
+
+
+### 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
+#{summary@Count:f0}             → 42
+#{value:c2}                     → $12.50
+```
+
+###### #mod-syn
+
+
+
+
+### Row data
+
+| Token                          | Canonical form            | Returns                                     |
+| :----------------------------- | :------------------------ | :------------------------------------------ |
+| `#{value@ShortName}`           | `#{data.value@ShortName}` | Field value for the current row             |
+| `#{value@ShortName!fallback}`  | —                         | With default if empty                       |
+| `#{value@ShortName:no_escape}` | —                         | Raw unescaped value                         |
+| `#{id}`                        | `#{data.id}`              | Numeric PK of the current row's base entity |
+| `#{uid}`                       | `#{data.uid}`             | UID of the current row's base entity        |
+
+The short forms (`#{value@ShortName}`, `#{id}`, `#{uid}`) are backwards-compatibility aliases for `#{data.value@ShortName}`, `#{data.id}`, `#{data.uid}`.
+
+
+
+### Output metadata
+
+| Token                          | Returns                                                                                     |
+| :----------------------------- | :------------------------------------------------------------------------------------------ |
+| `#{output.row@index}`          | Current row number (within returned rows)                                                   |
+| `#{output.row@index:global}`   | Current row number (across all pages)                                                       |
+| `#{output.row@count:returned}` | Total returned row count                                                                    |
+| `#{output.row@count:global}`   | Total row count across all pages                                                            |
+| `#{output.page@index}`         | Current page number                                                                         |
+| `#{output.page@count}`         | Total page count                                                                            |
+| `#{output.PropertyName}`       | Any property of the output record — e.g. `#{output.Name}`, `#{output.UID}`, `#{output.AppID}` |
+
+
+
+### Output value metadata (column context)
+
+| Token                          | Returns                                 |
+| :----------------------------- | :-------------------------------------- |
+| `#{output_value.Title}`        | Column title (`output_value.Title`)     |
+| `#{output_value.ShortName}`    | Column ShortName                        |
+| `#{output_value.UID}`          | Column UID                              |
+| `#{output_value.PropertyName}` | Any property of the output_value record |
+
+
+
+### Token scope
+
+Token resolution happens in two sequential passes:
+
+**Content render pass** (first): The template 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`, `output.*`, `output_value.*`, and `summary` 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. This is expected behavior for session data. For per-row variation, use `#{value@...}` tokens backed by output values.
+
+###### #tok-sco
+
+
+
+### Summary (use in `<#_summary>` or `<#_footer>`)
+
+The `summary` token renders an aggregate value for a column. The aggregate function — `sum`, `count`, `min`, `max`, or `average` — is configured in the `output_value.Summary` field on the database record. It cannot be specified or overridden in the template.
+
+```css
+#{summary@ShortName}
+```
+
+`ShortName` references the output_value's ShortName. The aggregate runs over all returned rows. Place in `<#_summary>` (renders once after the last row, only when summary values are defined) or `<#_footer>`.
+
+
+
+### 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. A token will only resolve when one value is available in the cached record set.
+
+```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
+```
+
+`hide="true"` is commonly paired with payload reads — the embed executes and its rendered output is available via `#{payload$Target}` without rendering at embed site. Useful if you want to pass an embed's payload as a filter value in another embed's URL, for example.
+
+###### #pay-tok
+
+---
+
+
+
+## Filters
+
+### Static filter
+
+Set `PrimaryValue` on an `output_value_filter` record. Always applied — no URL parameter needed.
+
+
+
+### Prompted filter modifiers
+
+Set `Prompted = 1` and `ShortName` on the filter record to enable URL parameter at request time:
+
+```css
+?_filter@ShortName=value
+```
+
+Multiple values: `?_filter@Status=active,pending` — combined with `OR` (default) or `AND` per `Operator` field.
+
+Combine with `Required = 1` on the filter record to throw a 500 error if no value is supplied.
+
+
+
+### Request stack and filter priority
+
+When an output is embedded, its caller can pass filter parameters down to it. The **request stack** tracks these values across embed levels — an embed may pass filters to its embedded outputs, and those outputs may be embedded in turn.
+
+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
+```
+
+These modifiers are only meaningful when the output is invoked through an embed chain. For direct HTTP requests, there is no outer stack and the distinction has no effect.
+
+###### #req-sta
+
+
+
+### Ad-hoc filter modifiers
+
+When `AdhocFilters = 1` on the output, filter type and behavior can be set inline in the URL key without pre-configured filter records. Modifiers are comma-separated after the colon; multiple values are comma-separated after `=`.
+
+```css
+?_filter@Field:mod1,mod2=value1,value2
+```
+
+**Comparison modifiers**
+
+| Modifier                | SQL Equivalent                |
+| :---------------------- | :---------------------------- |
+| `:exact`                | `= '[FilterValue]'` (default) |
+| `:contains`             | `LIKE '%[FilterValue]%'`      |
+| `:startswith`           | `LIKE '[FilterValue]%'`       |
+| `:endswith`             | `LIKE '%[FilterValue]'`       |
+| `:lessthan`             | `< [FilterValue]`             |
+| `:lessthanorequalto`    | `<= [FilterValue]`            |
+| `:greaterthan`          | `> [FilterValue]`             |
+| `:greaterthanorequalto` | `>= [FilterValue]`            |
+
+**Inclusion modifier** (maps to `Inclusive`):
+
+| Modifier   | Effect                                          |
+| :--------- | :---------------------------------------------- |
+| `:exclude` | Excludes matching rows. The default is include. |
+
+**Operator modifier** (maps to `Operator`, applies when multiple values supplied):
+
+| Modifier | Effect                      |
+| :------- | :--------------------------- |
+| `:and`   | All values must match        |
+| `:or`    | Any value matches (default)  |
+
+Modifiers can be combined in any order:
+
+```css
+?_filter@Price:lessthan=100
+?_filter@Tags:contains,and=admin,active          → Tags LIKE '%admin%' AND Tags LIKE '%active%'
+```
+
+
+
+#### Multi-value behavior
+
+Multiple values are comma-separated after `=`. The `:or` / `:and` modifier controls how they combine (default: OR).
+
+```css
+?_filter@Status=active,pending            → Status = 'active' OR Status = 'pending'
+?_filter@Tags:contains,and=admin,active   → Tags LIKE '%admin%' AND Tags LIKE '%active%'
+```
+
+**Caution**: with `:exclude` and multiple values— `:exclude` with default OR combines as `NOT x OR NOT y`, since a single field cannot simultaneously equal two different values, this condition is always true — no rows are excluded at all. To exclude rows matching *any* value, use `:and,exclude`.
+
+```css
+?_filter@FirstName:contains,exclude=foo,bar       → NOT LIKE '%foo%' OR NOT LIKE '%bar%'   (no filtering)
+?_filter@FirstName:and,contains,exclude=foo,bar   → NOT LIKE '%foo%' AND NOT LIKE '%bar%'  (excludes rows containing either)
+```
+
+###### #mul-val
+
+
+
+### Cross-column filter logic
+
+Each `output_value_filter` record generates one WHERE clause condition. Multiple records are ANDed together at the clause level — there is no parenthetical grouping and no way to express OR across separate filter records via the filter system alone. The `Operator` field (`AND`/`OR`) applies only within a single multi-value prompted filter.
+
+To express cross-column OR, conditional grouping, or comparisons between columns, use a `CASE` command in `output_value.CustomSQL` and add a filter to that column.
+
+```sql
+-- output_value.CustomSQL example CASE:
+CASE
+  WHEN #{value@Amount} > #{value@Threshold}
+  THEN 1
+  ELSE 0
+END
+```
+
+> **Note**: this is an advanced pattern. For construction steps, schema details, and worked examples see the `building-guide.md`.
+
+
+
+### Filter presets
+
+These preset values can be stored in `output_value_filter.PrimaryValue` or set as `_filter` parameter value.
+
+| Preset                                                       | Resolves to                                                  |
+| :----------------------------------------------------------- | :----------------------------------------------------------- |
+| `CurrentUserID`                                              | Current user's ID (unchanged under impersonation)            |
+| `LoggedInUserID`                                             | Logged-in user's ID (may differ from logged-in user 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
+
+## Pagination
+
+Set `RowsPerPage` on the output record or via `_rowsperpage` parameter to control how many rows are visible per page. Pagination is activated by passing `?_page=N` at request time.
+
+
+
+---
+
+
+
+## Caching
+
+`Cache = 1` caches the result set. Output structure (query config, joins, values) 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:
+
+```css
+GET /api/cache/refresh?_key=output:meta:[output.UID]
+GET /api/cache/refresh?_key=secure:output:meta:[output.UID]
+```
+
+`voidcache` is accepted on any API endpoint to flush all caches globally.
+
+```css
+GET /api/output/[uid]?voidcache=true
+```
+
+---
+
+
+
+## Legacy
+
+### User-defined sections
+
+`<#SectionName>` defines a named block that calling templates can target by name OR if `<#SectionName>` maps to a output_value.Shortname, will render if that row has a value :
+
+```css
+<#TagName>
+	Some string which can comprise #{value@Shortname1}
+</#TagName>
+<#_row>
+	<#TagName/>
+	<#ShortName2>
+  	#{value@ShortName2} has a value
+	</#ShortName2>
+</#_row>
+```
+
+
+
+
+
+### Legacy token types
+
+| Token              | Current form                   | Notes                                                                                                               |
+| :----------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------ |
+| `#{entity_column}` | `#{data.entity_column.uid}`    | Renders the EntityColumn UID for the current column in context; source-confirmed but behavior uncertain — do not use in new templates |
+| `#{row}`           | `#{output.row@index}`          | Current row number; use explicit form                                                                               |
+| `#{page}`          | `#{output.page@index}`         | Current page number; use explicit form                                                                              |
+| `#{count}`         | `#{output.row@count:returned}` | Returned row count; use explicit form                                                                               |
+| `#{column}`        | `#{data.value@ShortName}`      | Field value by column reference; use `#{value@ShortName}`                                                           |
+| `#{title}`         | `#{output_value.Title}`        | Column title in `<#cell>` context; use explicit form                                                                |
+
+### Legacy columns
+
+| Column       | Table          | Notes                                                                              |
+| :----------- | :------------- | :--------------------------------------------------------------------------------- |
+| `MaxRows`    | `output`       | Superseded by `Limit`; both are read for backward compatibility                    |
+| `DatePart`   | `output_value` | Date component extraction; exists in schema, not actively supported                |
+| `OutputType` | `output_value` | Controls EntityColumn vs CustomSQL expression mode; exists in schema, not actively supported |
+
+### Legacy URL parameters
+
+| Parameter    | Superseded by | Notes                                            |
+| :----------- | :------------ | :----------------------------------------------- |
+| `_maxrows=N`      | `_limit=N`                                    | Exact equivalent — use `_limit`                                                                                                                                                                              |
+| `_rows=M,N`       | `_limit=M-N`                                  | Row range using hyphen separator in current form                                                                                                                                                             |
+| `_template=json`  | `_template=json_indented` or `_template=json_raw` | Routes through the DBO content rendering pipeline — values serialized as strings, duplicate `ShortName` values produce duplicate keys, slower than direct serialization. Prefer `json_indented` or `json_raw`. |
+| `_escape_html=false` | `:no_escape` modifier | Disabled HTML encoding globally for the request. HTML output only. Use `:no_escape` on specific tokens instead. |
+
+### 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"/>
+```