Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Query Builder Rule Specification
Read this as an implemented contract plus a bounded design history
The current executable QUERY body contains an authoritative expression and a supported guided-designer projection. The extensive enhancement/phasing material later in this page remains useful context; it is not evidence that every premium target or distributed-source idea is implemented. For each example, rely on the owning decoder, codec, runtime and actual source capability. Unsupported guided shapes must be preserved in Expression mode instead of silently simplified.
A source has a human-facing reference and governed coordinates. Once governed coordinates are declared, a coherent model/version/type set is required; a label must not become a fallback for an incomplete pin. A physical publication pin matters when one logical schema can be applied to multiple destinations. Joins have their own target coordinates. Selected fields and output aliases describe a result shape, not permission to read them.
| Part of the body | Review question |
|---|---|
expression |
Is the exact supported grammar preserved? Are inputs canonical and declared? |
designer.source |
Does the model/type/version/publication identify the intended actual source? |
| Projection/return mode | Does the consumer need a record, collection, scalar or aggregate projection? |
| Filters and expressions | Are literal values distinguished from evaluated inputs, with readable field types? |
| Joins/aggregate aliases | Are all source/field/alias identities explicit and supported? |
| Paging/result size | Are policy bounds and actual serverPaged capability respected? |
| Round-trip | Can guided mode represent this expression without information loss? |
Begin with Query Builder, then use these cases for contract review. The source examples establish shape and behavior; they are not fresh provider/runtime qualification.
Worked examples
Example DATA-QUERYSPEC-01 — Review an exact-source QUERY body as a fragment
Scenario and inputs. Nadia’s invoice training source uses actual model ID, source version, record type key and physical publication. The JSON below shows the same supported simple pinned shape used by an owning runtime test. It is the inner QUERY rule body, not the outer create-draft HTTP request; illustrative coordinates must be replaced by the reader’s actual admitted source.
Procedure. 1. Select the source and explicit id/name projection in guided mode. 2. Inspect the generated expression and matching source metadata before saving. 3. Keep modelId, positive sourceVersion and recordTypeKey coherent, retaining publicationId when required. 4. Validate the whole containing rule with its real declared input contract and current publication-impact checks. 5. Test the query under the intended actor, then publish and record its actual rule version rather than assuming the sample 3or model 7 exists.
{
"expression": "queryMany('Invoice', select('id','name'), limit(25))",
"designer": {
"source": {
"recordType": "Invoice",
"modelId": "actual-model-id",
"sourceVersion": 7,
"recordTypeKey": "Invoice",
"publicationId": "actual-publication-id"
},
"returnMode": "MANY",
"selectedFields": [
"id",
"name"
],
"filters": [],
"sorts": [],
"resultSize": {
"mode": "PAGE",
"pageNumber": 1,
"pageSize": 25,
"includeTotalCount": false
}
}
}
Expected result. The supported simple pinned collection shape can resolve through the governed record reader with a bounded viewport. The expression and metadata describe the same source/projection intention; the fragment is not proof that the named source or rows exist in a real workspace.
Failure and recovery. If some governed coordinates are present but others are missing, repair the entire coordinate set. Do not drop the source pin or fall back to a display name to pass validation; that can change which model or physical destination the rule refers to.
Sources. QuerySourceDecoder.java, QueryRuleRuntimeViewportTest.java.
Example DATA-QUERYSPEC-02 — Design grouped output with deliberate aliases
Scenario and inputs. Sara needs a per-status summary of leave requests, not a list of full request records. Nadia chooses Aggregation in the supported builder and groups by status. The resulting rows are projection objects with named measures; they are not arbitrary full records that can be updated through a record action.
Procedure. 1. Select the exact permitted source and verify the grouping/measure fields have suitable declared types. 2. Choose the actual supported aggregate function and give each result measure a unique stable alias in the builder. 3. Add only supported having filters over those aliases, keeping ordinary source-row filters separate. 4. Inspect the generated expression and inferred output schema, then compare expected small-fixture groups before publishing. 5. Bind consumers to that projection shape and declare their labels/formatting without treating an alias as a source-field permission.
Expected result. A successful supported aggregation returns grouped metric rows whose aliases match the declared result shape. The PENDING group’s count derives from the same authorized data contract; it is not a vector estimate, page-length guess or count from another unscoped source.
Failure and recovery. An unsupported measure-level filter, ambiguous alias or unreadable field must remain an authoring issue. Simplify to a supported aggregate or design a separately admitted governed source. Do not claim every target enhancement in this specification is executable or silently drop a measure filter during guided conversion.
Sources. QueryBuilderExpressionCodec.java, QueryRuleRuntime.java.
Example DATA-QUERYSPEC-03 — Resolve a homonymous source through governed coordinates
Scenario and inputs. Two logical models can expose a type labeled Invoice, and one logical release can have more than one physical applied destination. Nadia’s saved query must continue to mean the intended source after another model or destination is added. A human-friendly recordType label alone cannot provide that guarantee.
Procedure. 1. Inspect the source picker’s actual model identity, positive schema version and record type key. 2. Choose a physical publication explicitly where the current source contract requires it. 3. For each supported join, inspect and retain the target model/version/type/publication coordinates as well as the join fields. 4. Validate publication-impact and source eligibility using the exact saved body. 5. Test with a fixture where the other homonymous source would produce a visibly different result so an accidental fallback cannot look correct.
Expected result. A complete governed coordinate set identifies the intended admitted source instead of resolving whichever matching label appears first or newest. Adding another model does not authorize the query to switch data domains.
Failure and recovery. An incomplete coordinate set is refused by the governed decoder; ambiguous runtime identity must not be cured by removing version pins. Reopen the picker and deliberately select/review the intended source. If it is unavailable to the current actor, coordinate with its owner rather than synthesizing another model’s IDs.
Sources. QuerySourceDecoder.java, QuerySourceEligibility.java.
Example DATA-QUERYSPEC-04 — Keep unsupported logic in Expression mode without loss
Scenario and inputs. An advanced consultant edits the generated expression with logic the current guided codec cannot represent. The source text is important business logic and has not been proven equivalent to a simpler visual model. The user now tries to switch back to Guided mode.
Procedure. 1. Preserve the original expression and inspect the parser/codec’s explicit unsupported reason. 2. Compare the unsupported clause with the current supported guided grammar rather than the broader roadmap list. 3. Keep the rule in Expression mode when a no-loss representation is unavailable. 4. If the team intentionally simplifies the rule, review the exact changed semantics and retest normal, boundary and negative input cases before publication. 5. Keep the generated designer metadata consistent with the chosen executable source instead of editing both independently until a validator happens to accept them.
Expected result. A supported round-trip reconstructs the same meaning. An unsupported round-trip remains visibly unsupported and preserves the executable expression; the designer does not silently remove joins, filters or aggregate conditions.
Failure and recovery. If a client discards unsupported text or replaces it with a default expression, restore the original draft from retained work/history and correct the authoring flow. A passing parse of the simplified body is not evidence of semantic equivalence. Escalate only the actual missing grammar capability, not a request to disable publication validation.
Sources. QueryBuilderExpressionCodec.java, RuleAuthoringController.java.
Detailed reference
Status: draft specification.
This spec defines the QUERY rule type and the Studio query builder used to
author it. The query builder is a rule authoring surface, not a separate data
tool. Users reach it through the existing path:
Rules > New rule > Query
The implementation should extend the current rules system rather than creating a parallel query artifact. A query rule has the same draft, validate, publish, execute, version, audit, API exposure, and service-task behavior as other rules.
Reference model: Appian's query editor is a useful benchmark for the authoring experience: select a data source, configure fields, filters, sort/limit, aggregation, output properties, rule inputs, and preview results, with guided and expression modes. Inflow should keep that shape, but make the expression the executable source of truth.
Goals
- Add a first-class
QUERYrule kind to the existing rule catalog. - Let a builder start from a wizard, select a data model type, then configure a business-level query screen.
- Generate InflowEL query expressions while the user edits the visual designer.
- Allow direct expression edits and reflect supported edits back into the visual designer.
- Infer and expose the query output type: single data-model record, multiple records, scalar, count, boolean, projected object, or full query envelope.
- Execute only governed data-model reads. No raw SQL is authored in rules.
- Preview query results safely during authoring.
- Keep data access workspace-scoped, permission-checked, audited, and compatible with existing data-model publication boundaries.
Non-goals
- Raw SQL editing in the Studio.
- Unapproved connector/database queries in query rules.
- Cross-workspace data reads.
- Bypassing data-model field permissions through projections, filters, sorts, or aggregates.
- Replacing AI.Fabric or approved connector queries. Those remain separate sources that a later query-builder phase can reference.
Product Model
A query rule answers a business question over a published data model type:
- "Find the latest active case for this customer."
- "Return all open invoices over the approval threshold."
- "Does this employee have an active delegation?"
- "Count high-risk vendors created this month."
- "Return customer name, risk band, and open balance."
The user does not think in tables, joins, or SQL. The user thinks in record types, fields, relationships, filters, sorting, grouping, and result shape.
Premium Enhancement Direction
The query builder should become a premium Inflow Fabric tool, not a static form that happens to generate code. Guided mode must help business and technical users build valid, governed, explainable queries visually. Expression mode remains available for advanced users, but it should not be the only way to author rich queries.
The target experience is a visual query cockpit:
+--------------------------------------------------------------------------------+
| Query Rule: Find Open High-Value Invoices Validate Run |
+--------------------------------------------------------------------------------+
| Source Graph | Guided Query Designer | Preview |
|---------------------|-----------------------------------------------|---------|
| Invoice | 1. Source | Output |
| primary | Invoice | schema |
| | | |
| + Add model | 2. Relationships | Sample |
| Customer | Invoice.customerId -> Customer.id | rows |
| Payment | Invoice.id -> Payment.invoiceId | |
| | | Issues |
| Fields | 3. Fields | |
| - id | [Invoice.id x] [Invoice.amount x] | |
| - amount | [Customer.name x] [+ Add fields] | |
| - status | | |
| - dueDate | 4. Filters | |
| | ALL | |
| Functions | status = 'OPEN' | |
| Data / Query | amount >= constant('approval-limit') | |
| Text | Customer.region = inputs:currentUser.region | |
| Date | | |
| Rules | 5. Sort & Paging | |
| Constants | Sort: dueDate DESC | |
| | Result size: First 50 records | |
+---------------------+-----------------------------------------------+---------+
| Generated expression: queryMany('Invoice', ... ) expand |
+--------------------------------------------------------------------------------+
The designer should feel like Appian's query editor, a Fabric relationship mapper, a field picker, and an expression IDE working together. The interface must stay dense enough for enterprise work while still being guided and safe.
Current Implementation Baseline
The current implementation on master is the first slice:
QUERYexists as a rule kind.- Users can create it through
Rules > New rule > Query. - The rule stores JSON with an
expressionanddesignersidecar. - Guided mode supports one data model type, return mode, selected fields, filters, sorts, and numeric limit.
- Expression mode shows/edit the generated query expression.
- Query rules execute through the governed data-model record reader.
- Filter value expressions can use rule inputs, functions,
constant(...), andrule(...). - Synced data model queries read the local published record store populated by sync. They do not call the external connector live and do not start a sync.
- Backend and frontend tests cover the first slice.
Current branch progress beyond the first slice:
- Returned fields are selected through a searchable field picker with selected chips.
- Return shape is a card selector covering records, single record, count, exists/boolean, field values, and envelope.
- Filter value rows include an expression editor modal button.
- Filter operators are type-aware in guided mode. Text fields expose text search operators, numeric/date fields expose comparison operators, boolean fields expose boolean-safe equality/null operators, and null operators do not require a value.
- Query functions are exposed in the function catalog and expression completions.
- Result size has first/all/page/cursor controls with page-size presets and large-result warnings.
- Guided mode supports joining additional data model types with explicit projection required for multi-model data returns. Relationship joins support inner, left, exists/semi-join, and not-exists/anti-join modes, with dynamic help text and expression round-trip for supported join clauses.
- Guided filters support
ALL/ANDandANY/ORmatch modes. - Guided mode supports an Aggregation return shape with grouping fields, aliased measures, having filters over aggregate aliases, expression round-trip, and runtime execution over governed data-model records, including joined record contexts.
- Expressions round-trip back into guided state for the supported query shape.
- Unsupported expression clauses keep the rule in Expression mode with a clear reason; guided mode is disabled rather than silently dropping unsupported logic.
- Dedicated backend authoring APIs now expose expression-to-designer parsing and designer-to-expression generation for the supported guided subset, with explicit unsupported reasons when no-loss guided editing is not possible.
- A dedicated backend query-builder preview endpoint validates query bodies, runs authoring dry-runs, and returns output kind, row count, duration, and validation metadata for the Studio preview panel.
Remaining or broader gaps that this enhancement spec must close:
- Guided filters do not yet support nested condition groups or drag/reorder.
- Aggregation does not yet support measure-level filters.
- There is no Fabric relationship graph or true distributed multi-source query planner.
- Live preview has query metadata and tabular rows, but still needs richer paging controls, saved preview profiles, and source-by-source execution diagnostics.
- Saved reusable projection/result types now have a first implementation: query rules can mark their generated output as reusable, and the published latest version is exposed to the rule builder as a versioned object type. Remaining work is richer type lifecycle management, compatibility checks, explicit dependent usage, and generated migration/renaming tools.
Premium UI Principles
- The builder is a guided designer, not a long flat form.
- Each section has a clear job: source, relationships, fields, filters, sort, paging, return, preview.
- The generated expression is always available but can be collapsed.
- Guided mode should prevent invalid choices wherever possible.
- Advanced users can switch to expression mode without losing work.
- Unsupported expression logic must never be silently discarded.
- Unauthorized controls and their requests are absent, using current effective scoped capabilities. Disabled-with-reason applies only to state blocks; denied direct links use the shared neutral unavailable state.
- Fields, functions, rules, constants, and variables are discoverable from the left rail.
- The right rail continuously explains output type, preview data, warnings, and validation issues.
Entry Point
The existing NewRuleDialog already presents type cards. Add QUERY as an
available card:
Query
A governed lookup over a published data model type.
Clicking it opens a creation wizard before the full builder:
- Name, key, and business function, as today.
- Rule type: Query.
- Select data model type.
- Select starting query shape:
- Single record.
- List of records.
- Count.
- Exists.
- Aggregate.
- Full envelope.
- Create draft and navigate to
/:workspaceKey/rules/:ruleKey.
The builder page continues to be RuleBuilderPage, with a QueryRuleEditor
rendered when kind == QUERY.
Query Builder Layout
The query builder should use the same three-region rule-builder shell:
- Left rail: inputs, selected data model type, available fields, relationships, functions, and output type summary.
- Center: business query designer plus generated expression editor.
- Right rail: live preview, test inputs, return-shape sample, and validation findings.
Primary sections in the center:
| Section | Purpose |
|---|---|
| Source | Selected published data model type and relationship scope. |
| Fields | Fields and related fields to return. |
| Filters | Business conditions that restrict records. |
| Sort and limit | Ordering, paging, and maximum returned rows. |
| Aggregate | Optional groupings and measures. |
| Return | Data, first item, count, exists, scalar, projection, or full envelope. |
| Expression | Generated InflowEL query expression with direct editing. |
| Preview | Ten-row preview by default, with explicit "Test query" action for expensive queries. |
The center should be organized by a sticky stepper:
Source -> Relationships -> Fields -> Filters -> Sort -> Paging -> Return
Each step shows a state: incomplete, valid, warning, or error. Users can jump between steps, but the visual hierarchy should still guide them toward a valid query.
Left Rail: Fabric Explorer
The left rail is the available-things library. It should include:
- Selected source models and aliases.
- Available fields grouped by model and relationship.
- Known Fabric relationships.
- Rule inputs and process/form inputs.
- Published constants.
- Published rules.
- Registered expression functions.
- A
Data / Queryfunction category.
Fields display both business and technical names:
Amount
Invoice.amount
Number
Permission-blocked fields stay visible only when useful for explanation, and are disabled with a reason:
Margin
Invoice.margin
Locked: you do not have permission to read this field.
Right Rail: Preview, Output, Issues
The right rail should answer, at all times:
- What will this query return?
- Who will it run as?
- Can it execute safely?
- What sample rows come back?
- What needs fixing?
Recommended tabs:
| Tab | Purpose |
|---|---|
| Preview | Sample result table, execution time, count, paging status. |
| Output | Return type, output schema, selected fields, envelope metadata. |
| Issues | Validation errors, warnings, permission problems, risky query hints. |
Example preview summary:
Returned 50 of 1,284 matching records
Execution time: 142 ms
Running as: Current user
Expression Panel
The generated expression should be a collapsible bottom panel:
Generated expression queryMany('Invoice', select(...), whereAll(...)) [Expand]
When expanded, it uses the normal code editor with completions, diagnostics, and function insertion. If the expression cannot round-trip into guided mode, the UI must show:
This expression uses logic that guided mode cannot fully represent.
Guided mode is read-only until simplified. Nothing will be lost.
Canonical Source Of Truth
The executable source of truth is the InflowEL expression.
The visual designer is a structured projection over that expression. When the designer changes, it regenerates the expression. When the expression changes, the designer parses it and updates all supported sections.
If the expression uses constructs that cannot be represented in guided mode, the builder opens in Expression mode:
- The expression remains executable.
- The preview and validation still work.
- Guided controls that cannot round-trip are disabled with a reason tooltip.
- The user can return to guided mode only after the expression is simplified into the supported subset.
This mirrors the useful behavior of Appian's guided/expression split without making the visual model a second source of truth.
Rule Body Format
RuleDefinitionVersion.body remains a string. For QUERY, the string is JSON
so the rule can persist the canonical expression plus an optional designer
sidecar.
{
"expression": "queryMany('Invoice', select('id', 'customer.name', 'amount'), whereAll(filter('status', '=', inputs:status), filterWhen('amount', '>=', inputs:minAmount, has('inputs:minAmount'))), sortDesc('createdAt'), limit(50))",
"designer": {
"source": {
"recordType": "Invoice"
},
"mode": "GUIDED",
"returnMode": "MANY",
"selectedFields": ["id", "customer.name", "amount"],
"filters": [
{
"field": "status",
"operator": "=",
"valueExpression": "inputs:status",
"applyExpression": "true"
},
{
"field": "amount",
"operator": ">=",
"valueExpression": "inputs:minAmount",
"applyExpression": "has('inputs:minAmount')"
}
],
"sorts": [
{
"field": "createdAt",
"direction": "DESC"
}
],
"limit": 50
}
}
The expression field is authoritative. The designer field is a cache used
for stable layout, labels, and guided controls. On load, the backend validates
the expression and the frontend attempts to reconstruct the designer from it.
If designer disagrees with expression, the expression wins.
InflowEL Query Expressions
The first implementation should avoid grammar changes by adding query-builder functions to the existing function registry. Functions return typed query specification values until the top-level query function executes them.
Required top-level functions:
| Function | Result |
|---|---|
queryOne(recordType, ...) |
One record object or null. |
queryMany(recordType, ...) |
List of record objects. |
queryCount(recordType, ...) |
Number. |
queryExists(recordType, ...) |
Boolean. |
queryScalar(recordType, measure, ...) |
One scalar value. |
queryEnvelope(recordType, ...) |
Full {data,totalCount,page,limit,hasMore,success,errorCode} object. |
Required builder functions:
| Function | Purpose |
|---|---|
select(field...) |
Choose returned fields. |
whereAll(filter...) |
Combine filters with AND. |
whereAny(filter...) |
Combine filters with OR. |
filter(field, operator, value) |
Always-applied filter. |
filterWhen(field, operator, value, applyExpression) |
Conditionally applied filter. |
ignoreEmpty(filter) |
Skip when the value is empty. |
sortAsc(field) |
Ascending sort. |
sortDesc(field) |
Descending sort. |
limit(n) |
Maximum returned rows. |
page(pageNumber, pageSize) |
One-based paging window for preview/API consumers. |
groupBy(field...) |
Aggregate grouping. |
measure(alias, function, field) |
Aggregate measure. |
having(filter...) |
Aggregate filter over aliases. |
The left-side function library and expression editor completion must expose a
Data / Query category with at least:
| Function | Purpose |
|---|---|
query() |
General query over one or more source aliases. |
queryOne() |
Return the first matching record or null. |
queryMany() |
Return a list of matching records. |
queryEnvelope() |
Return data with count, paging, and execution metadata. |
count() / queryCount() |
Return a count. |
exists() / queryExists() |
Return a boolean existence check. |
select() |
Select returned fields or projections. |
filter() |
Define a field/operator/value condition. |
sort() / sortAsc() / sortDesc() |
Define sort order. |
limit() |
Return the first N records. |
page() |
Define page or cursor pagination. |
join() |
Join or relate another source alias. |
groupBy() |
Define aggregation groupings. |
aggregate() / measure() |
Define aggregate measures. |
Each library item must show description, parameters, return type, example, and copy/insert support.
Query expressions are normal InflowEL expressions. Any query argument that is documented as a value expression or boolean expression may reference:
- Rule inputs and local variables.
- Registered expression functions, such as date, text, math, and collection helpers.
- Published rules through
rule('rule-key')orrule('rule-key', version). - Published constants through
constant('constant-key')orconstant('constant-key', version).
Composition follows the same lifecycle guarantees as expression rules: calls resolve only published versions, optional versions pin the dependency, rule-call cycles and excessive nesting fail closed, and dependencies must stay in the caller workspace. The query builder must show referenced rules/constants in the dependency and impact-analysis panels.
Examples:
queryOne(
'Customer',
select('id', 'name', 'riskBand'),
whereAll(filter('id', '=', customerId))
)
queryMany(
'Invoice',
select('id', 'customer.name', 'amount', 'dueDate'),
whereAll(
filter('status', '=', 'OPEN'),
filterWhen('amount', '>=', max(inputs:minAmount, constant('approval-limit')), has('inputs:minAmount')),
filter('region', '=', rule('current-approval-policy').region)
),
sortDesc('dueDate'),
limit(50)
)
queryCount(
'Case',
whereAll(
filter('customer.id', '=', customerId),
filter('status', 'in', ['OPEN', 'PENDING'])
)
)
queryExists(
'Delegation',
whereAll(
filter('fromUser.id', '=', approverId),
filter('active', '=', true),
filter('startsAt', '<=', now()),
filter('endsAt', '>=', now())
)
)
queryEnvelope(
'Invoice',
select('id', 'amount', 'currency'),
whereAll(filter('customer.id', '=', customerId)),
sortDesc('createdAt'),
page(1, 25)
)
Output Type Inference
The return shape is part of authoring, validation, and API schema generation.
| Expression | Output type |
|---|---|
queryOne('Customer', ...) |
Customer or null. |
queryMany('Customer', ...) |
Customer[]. |
queryCount('Customer', ...) |
NUMBER. |
queryExists('Customer', ...) |
BOOLEAN. |
queryScalar('Invoice', measure('total', 'sum', 'amount'), ...) |
Measure scalar type. |
queryEnvelope('Invoice', ...) |
QueryEnvelope<Invoice>. |
queryMany(... select('id','name')) |
Projected object list with selected fields only. |
The builder should display this clearly in the left rail and preview panel:
Returns: List of Invoice
Fields: id, customer.name, amount, dueDate
or:
Returns: Boolean
Reason: queryExists(...)
When the query returns data-model records, downstream rule users can declare a variable as the data model type or list of that type. When the query returns a projection, the type checker treats it as an anonymous object shape.
Query Result Types And Projection Types
Query results are JSON-compatible over the wire, but they must not be treated inside the platform as untyped JSON blobs. A query result has a platform type. That type may be an existing data model type, a scalar, an envelope, an anonymous projection, or a saved reusable projection type.
The query builder must derive output schemas from the existing data-model type
system. Field-level output types should reuse FieldTypeRef and
PortableType wherever possible:
STRING
TEXT
INTEGER
LONG
DECIMAL
BOOLEAN
DATE
TIME
TIMESTAMP
UUID
JSON
ENUM
BINARY
LIST
AUTO_NUMBER
USER
DOCUMENT
Business types must keep their business meaning:
| Type | Query result behavior |
|---|---|
AUTO_NUMBER |
Remains a business-readable platform-generated identifier, not generic text. |
USER |
Remains a user reference so UI and rules can resolve identity behavior. |
DOCUMENT |
Remains a managed document reference so UI can bind document actions. |
ENUM |
Carries its allowed values into filters, output schema, and UI controls. |
LIST |
Preserves element type when known; list of objects requires a projection schema. |
JSON |
Used only when the value is intentionally open or native JSON-shaped. |
Projection Type
A projection type is the typed object shape produced by a query when it does not return a full data model record. Projection types are needed for:
- Selected fields from one model.
- Aliased fields from multiple models.
- Nested objects.
- Primary records with related child collections.
- Aggregation rows.
- Custom object return shapes.
Example flat projection:
{
"name": "PurchasedItemRow",
"fields": [
{ "key": "customerId", "type": "STRING", "source": "Customer.id" },
{ "key": "customerName", "type": "STRING", "source": "Customer.name" },
{ "key": "itemId", "type": "STRING", "source": "Item.id" },
{ "key": "itemName", "type": "STRING", "source": "Item.name" },
{ "key": "quantity", "type": "DECIMAL", "source": "PurchaseLine.quantity" },
{ "key": "lineTotal", "type": "DECIMAL", "expression": "quantity * unitPrice" }
]
}
Example nested projection:
{
"name": "PurchasedItemsByCustomerResult",
"fields": [
{
"key": "customer",
"type": "OBJECT",
"fields": [
{ "key": "id", "type": "STRING", "source": "Customer.id" },
{ "key": "name", "type": "STRING", "source": "Customer.name" },
{ "key": "segment", "type": "STRING", "source": "Customer.segment" }
]
},
{
"key": "purchasedItems",
"type": "LIST",
"elementType": {
"type": "OBJECT",
"fields": [
{ "key": "purchaseId", "type": "STRING", "source": "Purchase.id" },
{ "key": "purchasedAt", "type": "TIMESTAMP", "source": "Purchase.purchasedAt" },
{ "key": "itemId", "type": "STRING", "source": "Item.id" },
{ "key": "sku", "type": "STRING", "source": "Item.sku" },
{ "key": "name", "type": "STRING", "source": "Item.name" },
{ "key": "quantity", "type": "DECIMAL", "source": "PurchaseLine.quantity" },
{ "key": "lineTotal", "type": "DECIMAL", "expression": "quantity * unitPrice" }
]
}
}
]
}
The exact persistence shape may differ from these examples, but the platform capabilities are required: nested object fields, list element schemas, source field lineage, expression-derived fields, and portable/business type metadata.
Saved Reusable Result Types
When publishing a query rule, the builder should offer:
Output type
(*) Use generated anonymous type
( ) Save as reusable type
Name: PurchasedItemsByCustomerResult
Saved result types should be versioned platform artifacts, sometimes called
Query Result Type or Projection Type. They allow other builders to declare
variables and bindings against query output without hand-writing JSON paths.
Current branch implementation:
- The query designer stores
designer.outputTypewithANONYMOUSorREUSABLEmode plus the reusable type name. - Published reusable query outputs are exposed through the rule authoring
catalog as
QueryResultTypeInfo. - The rule builder merges published data-model record types and query result types for variable declaration and expression autocomplete.
- The first reusable contract is derived from the latest visible published
query version. Field names are normalized into stable object keys when the
query projects paths such as
Customer.region. - COUNT, EXISTS, ENVELOPE, AGGREGATION, single/list projection, and field-value outputs are mapped into the platform's declared field type vocabulary.
Use cases:
-
Interface designer local data:
purchaseSummary: PurchasedItemsByCustomerResult -
Rule or process assignment:
purchaseSummary = rule('retrieve-purchased-items-by-customer', customerId) -
UI bindings:
purchaseSummary.customer.name purchaseSummary.purchasedItems[*].name purchaseSummary.purchasedItems[*].lineTotal
Multi-model Return Shapes
Multi-model queries must require an explicit projection. They must not default to returning all fields from all joined models because that causes collisions and unclear types.
Supported multi-model shapes:
| Shape | Description |
|---|---|
| Flat projection | A table-friendly row with explicit aliases, e.g. customerName, itemName. |
| Nested projection | Object grouped by model or business concept, e.g. {customer, purchasedItems}. |
| Primary with related data | Primary model fields plus related objects/collections. |
| Aggregation projection | Grouped metric rows across one or more models. |
| Envelope | Any of the above wrapped with metadata. |
Example for Items in MySQL and Customers in Oracle:
[
{
"purchaseId": "PUR-900124",
"purchasedAt": "2026-07-09T10:30:00Z",
"quantity": 2,
"item": {
"id": "ITEM-1001",
"sku": "SKU-RED-CHAIR",
"name": "Red Chair",
"category": "Furniture",
"unitPrice": 125.00,
"source": {
"dataModel": "items",
"system": "mysql"
}
},
"customer": {
"id": "CUS-501",
"name": "Acme Trading",
"email": "buyer@acme.example",
"segment": "Enterprise",
"source": {
"dataModel": "customers",
"system": "oracle"
}
},
"lineTotal": 250.00
}
]
The optional source metadata is useful for debug/lineage views but should not
be forced into every business return shape. The builder should let the user
include or hide lineage fields.
Compatibility And Versioning
Saved projection types must support compatibility checks:
| Change | Compatibility |
|---|---|
| Add optional field | Compatible. |
| Add required field | Potentially breaking. |
| Remove field | Breaking. |
| Rename field | Breaking unless alias mapping is retained. |
| Change scalar type | Breaking unless safe widening is defined. |
| Change object to list or list to object | Breaking. |
Change business type, e.g. USER to STRING |
Breaking. |
| Remove source field lineage | Compatibility warning. |
The platform should surface dependents before publishing a breaking projection type change: interfaces, process variables, rules, API exposures, templates, and service tasks.
Type-system Integration Work
Implementation must audit and integrate with:
FieldTypeRef.PortableType.BusinessDataTypeRegistry.DataModelTypeProvider.- Dialect type catalogs and nearest portable mappings.
- Expression type registry and type checker.
- Rule variable/object type declarations.
- Interface designer binding and data-source models.
- API exposure/OpenAPI schema generation.
This prevents the query builder from becoming a pretty JSON blob generator. It must produce native, governed, typed platform values.
Return Shape Selector
The current dropdown must become a Return Shape selector. It should use cards, radio cards, or another explicit visual choice instead of a simple dropdown.
Required return shapes:
| Shape | Meaning | Example |
|---|---|---|
| Records | A list of matching records or projections. | [{id, amount}] |
| Single record | First matching record or null; should recommend sort. |
{id, amount} |
| Count | Number of matching records. | 42 |
| Exists / Boolean | true when any record matches. |
true |
| Field values | One selected field across many records. | ['OPEN', 'PAID'] |
| Aggregation | Grouped or scalar aggregate rows. | [{region, totalAmount}] |
| Envelope | Data plus metadata. | {data,totalCount,page,limit,hasMore} |
| Custom object | User-defined object projection. | {customer,invoices,total} |
Each option should show:
- Short explanation.
- Example output.
- Output type.
- Whether fields, aggregation, paging, or custom mapping are required.
The default should be business-friendly, usually Records. Envelope should
be selected only when metadata is needed.
Supported Fields And Relationships
The field picker shows:
- Fields on the selected base data model type.
- Many-to-one and one-to-one relationship fields.
- One-to-many relationship fields only when the selected expression can safely handle a list, such as aggregate counts or explicit quantifiers.
Fields hidden by the caller's permissions must not appear. If the caller loses access after a rule was authored, validation fails closed with a clear issue.
Special-character field keys should be supported only if the data model layer can address them safely. Otherwise they are not shown in guided mode and must fail validation if referenced.
Field Picker
All guided field references should be selected, not typed. This includes:
- Returned fields.
- Filter fields.
- Sort fields.
- Group-by fields.
- Aggregate measure fields.
- Join source and target fields.
- Custom object mapping fields.
The field picker must support:
- Search.
- Display name and technical path.
- Type badges.
- Source/model alias.
- Relationship grouping.
- Select all visible.
- Clear all.
- Removable selected chips.
- Permission-disabled fields with reason tooltips.
Selected fields should appear as chips:
[Invoice.id x] [Invoice.status x] [Invoice.amount x] [Customer.name x]
Typing raw field paths is reserved for expression mode.
Filters
Guided filters use a structured condition builder rather than plain text rows. Each condition has:
- Field.
- Type-compatible operator.
- Value mode.
- Value.
- Optional apply condition.
Value modes:
| Mode | Purpose |
|---|---|
| Literal | User-entered static value. |
| Field reference | Compare one field to another. |
| Rule variable | Use a declared rule input. |
| Form/process input | Use context input from form or process execution. |
| Constant | Use constant('key'). |
| Rule | Use rule('key'). |
| Function | Use a registered expression function. |
| Expression | Open full expression editor. |
| Current user | Use current actor fields such as id, department, region. |
| Current date/time | Use today(), now(), or relative date helpers. |
| Null/empty | Match null, empty, or not-empty values. |
Every filter value must have an expression editor button beside it.
Example visual shape:
Match ALL of the following
Status is 'OPEN' fx
Amount >= constant('approval-limit') fx
AND group
Match ANY
Due Date before today() fx
Priority is 'Urgent' fx
Filters must support:
ANDandORgroups.- Nested groups.
- Drag/reorder of conditions and groups.
- Enable/disable condition.
- Conditional apply logic.
- Clear validation anchored to the exact broken condition.
Default behavior: ignore empty values for optional filters unless the user turns that off. Empty values without ignore-empty produce validation errors.
Minimum operators:
| Type | Operators |
|---|---|
| Text | =, <>, in, not in, starts with, ends with, includes, is null, not null, search |
| Number | =, <>, >, >=, <, <=, between, in, not in, is null, not null |
| Date/datetime | =, <>, >, >=, <, <=, between, in, not in, is null, not null |
| Boolean | =, <>, in, not in, is null, not null |
| Relationship | exists, not exists, field-compatible nested filters |
search maps to the data-model read service's approved search capability, not
database-specific raw full-text syntax.
Sort And Result Size
Sort should be a structured sortable table. Each row includes:
- Field.
- Direction.
- Null handling when supported by the backend.
- Drag handle.
- Remove action.
Multiple sort rules are evaluated in visual order.
Limit should be redesigned into Result Size / Paging. Supported modes:
| Mode | Meaning |
|---|---|
| First N records | Return only the first N records after sort. |
| All records | Return all matching records; requires explicit warning. |
| Pagination | Return page-sized chunks with page metadata. |
| Cursor pagination | Return page-sized chunks using stable cursor fields. |
Controls:
- Page size presets: 10, 25, 50, 100.
- Custom page size.
- Include total count.
- Fail if result exceeds policy limit.
- Preview-only sample limit.
Default limit: 50 for list queries. A user must explicitly choose a larger limit. Hard server-side maximums should be enforced by configuration.
Aggregation
Guided aggregation supports:
- Groupings with required aliases.
- Measures with required aliases.
- Measures:
count,countDistinct,sum,avg,min,max. - Measure filters.
- Having filters over aliases.
- Aggregation return shape.
- Preview of grouped rows rather than raw records.
Aggregation returns projected rows, not full data model records.
Example:
queryMany(
'Invoice',
groupBy('Customer.region'),
aggregate('totalAmount', 'sum', 'Invoice.amount'),
aggregate('invoiceCount', 'count', 'Invoice.id'),
having(filter('totalAmount', '>', 10000))
)
Multi-Model And Multi-Source Queries
The premium query builder must support Fabric-grade queries over multiple data models and eventually multiple approved sources.
Guided mode should allow users to:
- Select a primary data model.
- Add related data models.
- Use known AI.Fabric relationships when available.
- Configure manual joins only when no known relationship exists.
- Assign aliases to each model.
- Choose join type.
- Configure multiple joins.
- See relationships visually.
Join configuration:
| Field | Meaning |
|---|---|
| Source model | Existing model or alias in the query graph. |
| Target model | Model being added. |
| Source field | Field on the source model. |
| Target field | Field on the target model. |
| Relationship | Known Fabric relationship, if available. |
| Join type | Inner, left, exists/semi-join, anti-join. |
Example target expression:
queryMany(
'Invoice',
join('Customer', on('Invoice.customerId', 'Customer.id'), 'left'),
join('Payment', on('Invoice.id', 'Payment.invoiceId'), 'left'),
select('Invoice.id', 'Customer.name', 'Invoice.amount'),
whereAll(
filter('Invoice.status', '=', 'OPEN'),
filter('Customer.region', '=', inputs:currentUser.region)
),
sortAsc('Invoice.dueDate'),
limit(50)
)
The exact function syntax may evolve, but the product contract is stable: business users should not have to write joins manually in guided mode.
Rule Inputs And Variables
The builder reuses the existing variable declaration panel:
- Declared values are inserted and persisted canonically as
inputs:name; for exampleinputs:statusandinputs:minAmount. - Studio materializes newly inferred query references into the draft's typed input contract before autosave. Ambiguous types require an explicit choice.
- Bare names remain readable only for historical empty-contract rules; new query authoring must not use that compatibility spelling.
rule(...)andconstant(...)references become rule dependencies, not user-entered inputs.- Function references are resolved through
ExpressionFunctionRegistry. - Primitive values can be inferred.
- Data model object variables must be declared.
- Query field paths use the selected data model's type registry.
- The test panel builds input controls from the declared variables.
Examples:
customerId Text
minAmount Number
asOfDate Date
selectedCustomer Customer
The query expression may reference variables in filter values, apply conditions, limits, and calculated values. It may also call other published rules, constants, and functions in those same positions.
Preview And Test Query
Preview is a design-time dry run, not a published rule execution.
Requirements:
- Preview uses the current draft body and test inputs.
- Preview always enforces workspace, actor, and data-model permissions.
- Preview defaults to 10 visible rows even when the query limit is higher.
- Expensive query shapes require an explicit "Test query" click.
- The preview shows returned rows, total count when requested, output type, duration, and validation warnings.
- Preview never logs secret values or raw generated SQL.
The preview table should include:
- Returned row count.
- Total count when requested.
- Execution time.
- Page or cursor metadata.
- Current execution actor.
- Applied filters summary.
- Permission omissions.
- Empty-state guidance.
Preview should be behind an explicit action for expensive query shapes.
Query Execution Context
The designer should show who the query runs as:
- Current user.
- System.
- Process owner.
- Service account, if supported.
The execution context changes what data and fields are visible. The UI must surface permission warnings before publish. If a source, relationship, or field is unavailable to the selected context, the builder should disable it with an explanation and validation should fail closed.
Saved Templates
Provide starter templates that pre-fill the guided builder:
| Template | Pre-filled behavior |
|---|---|
| Get record by ID | Single record, id = inputs:inputId. |
| Get active records | Records, active = true, first 50. |
| Count records | Count return shape. |
| Created by current user | createdBy = inputs:currentUser.id. |
| Latest record | Single record, sort created date descending. |
| Records by status | Status input and equality filter. |
| Records needing approval | Business status + assignee / inputs:currentUser.id pattern. |
Templates should remain editable after insertion and should not create hidden logic.
Backend Requirements
Add:
RuleKind.QUERY.- Query body parser and validator.
- Query expression functions in
ExpressionFunctionRegistry. - A
QueryRuleExecutionServiceor compiledQUERYbranch inCompiledRule. - A data-model query port richer than today's
DataRecordReadService.RecordQuery. - JDBC adapter that translates the governed query AST to parameterized SQL.
- In-memory adapter for tests.
- Authoring endpoints for design-time metadata and preview.
Suggested design-time endpoints:
| Endpoint | Purpose |
|---|---|
GET /api/rules/query-builder/record-types |
Published data model types available to the current actor. |
GET /api/rules/query-builder/record-types/{key} |
Fields, relationships, searchable fields, sortable fields, and operator compatibility. |
POST /api/rules/query-builder/parse |
Expression to designer model and round-trip status. |
POST /api/rules/query-builder/generate |
Designer model to canonical expression. |
POST /api/rules/query-builder/preview |
Dry-run preview with test inputs. |
The existing /api/rules/validate and /api/rules/evaluate should accept
QUERY once the backend supports it.
Data Query AST
The backend should not execute the expression directly as SQL. It should evaluate the top-level query expression into a typed query AST:
{
"recordType": "Invoice",
"selection": ["id", "customer.name", "amount"],
"where": {
"operator": "AND",
"filters": [
{ "field": "status", "op": "=", "value": "OPEN" },
{ "field": "amount", "op": ">=", "value": 5000 }
]
},
"sort": [
{ "field": "dueDate", "direction": "DESC" }
],
"page": { "start": 1, "size": 50 },
"returnMode": "MANY"
}
Adapters translate this AST to source-specific execution. The first adapter can target the deployed data-model tables. Later adapters can target AI.Fabric or approved connector queries using the same rule kind.
Security And Governance
- Query rules execute in the caller's workspace.
- The selected data model type must be published and live.
- All reads go through the same data-model access policy as screens and data APIs.
- Hidden fields cannot be selected, filtered, sorted, searched, grouped, or returned.
- Every published query rule execution records rule key, version, caller, record type, result mode, duration, matched flag, and row count.
- Audit records must not store returned data values by default.
- API-exposed query rules use the existing rule API-key model and scoping.
- A query rule must fail closed if the data model is unpublished, removed, access-restricted, or incompatible with the published rule version.
Frontend Requirements
studio/frontend/src/features/rules:
- Extend
RuleKindwithQUERY. - Add a Query card in
RULE_KIND_CARDS. - Extend
EMPTY_BODIESforQUERY. - Add
QueryRuleEditor. - Add query builder API client methods.
- Keep all visual components composed from
src/ui. - Add stable
data-agent-idvalues for every mutating control. - Register invokable commands for validate, preview, publish, and key query builder actions.
- Add
/designgallery states for any new generic UI components.
Potential reusable UI components:
FieldPicker.ConditionBuilder.SortList.ProjectionPicker.QueryPreviewGrid.ReturnShapeSelector.ResultSizeSelector.RelationshipGraph.AggregationBuilder.ExpressionValueButton.
Feature components compose those primitives; feature files do not add ad-hoc styling.
Round-trip Rules
Guided mode is available only when the expression contains supported query functions in supported positions.
Examples that remain guided:
queryMany('Invoice', select('id', 'amount'), whereAll(filter('status', '=', 'OPEN')))
queryCount('Case', whereAny(filter('status', '=', 'OPEN'), filter('priority', '=', 'HIGH')))
Examples that become Expression mode:
if has('inputs:customerId') then queryOne('Customer', whereAll(filter('id', '=', inputs:customerId))) else null
first(queryMany('Invoice', whereAll(filter('status', '=', 'OPEN'))))
Those expressions can still validate and execute. They simply cannot be fully edited through guided controls until the parser supports that shape.
Validation Errors
Required errors:
| Code | Meaning |
|---|---|
QUERY_INVALID_BODY |
Body is not valid query-rule JSON. |
QUERY_EXPRESSION_MISSING |
Body has no expression. |
QUERY_INVALID_EXPRESSION |
Expression does not parse or type-check. |
QUERY_UNSUPPORTED_GUIDED_SHAPE |
Expression executes but cannot round-trip to guided mode. |
QUERY_RECORD_TYPE_NOT_FOUND |
Data model type is not published/live/visible. |
QUERY_FIELD_NOT_FOUND |
Selected field path does not exist. |
QUERY_FIELD_NOT_READABLE |
Caller cannot read a referenced field. |
QUERY_OPERATOR_NOT_COMPATIBLE |
Operator does not match field type. |
QUERY_VALUE_TYPE_MISMATCH |
Filter value cannot be cast to the field type. |
QUERY_LIMIT_EXCEEDED |
Requested page/limit exceeds policy. |
QUERY_AGGREGATE_ALIAS_REQUIRED |
Grouping or measure alias is missing. |
Validation should return business-readable messages and field-level positions for the expression editor where possible.
Phasing
P0 - Spec And Catalog
- Add this spec.
- Add
QUERYto the target rule type docs. - Confirm function names and body shape.
P1 - Premium Single-model Guided UX
- Replace free-text returned fields with
FieldPicker. - Replace return dropdown with
ReturnShapeSelector. - Replace numeric limit with
ResultSizeSelector. - Add expression editor modal button for every filter value.
- Add type-aware operators.
- Add query functions to the left function library and editor completions.
- Add premium section layout with stepper and collapsible expression panel.
- Keep existing single-model execution path working.
P2 - Validation, Preview, And Filter Builder
- Add explicit
Validate Query. - Add anchored validation issues for fields, operators, permissions, missing variables, invalid expressions, and risky unlimited queries.
- Add live preview grid with count, duration, paging, output schema, and execution context.
- Add
AND/ORgroups, nested filters, enable/disable, and drag/reorder. - Add sortable
SortListwith drag/reorder. - Add saved templates.
P3 - Aggregation And Full Envelope
- Groupings, measures, having filters.
queryScalarandqueryEnvelope.- Total count behavior.
- Stronger output schema and OpenAPI schema generation for exposed rules.
P4 - Multi-model Fabric Querying
- Add source graph and model aliases.
- Add relationship discovery from AI.Fabric metadata.
- Add join configuration and multiple joins.
- Allow fields, filters, sorts, and return shapes across aliases.
- Add relationship visualization and permission warnings.
P5 - Relationship Depth And AI Assist
- Deeper relationship navigation.
- One-to-many safe patterns with quantifiers and aggregate helpers.
- Agent "describe query" flow, validated before apply.
- Query explanation and optimization hints.
P6 - Approved Query And AI.Fabric Sources
- Use the same builder shell to select approved AI.Fabric or connector query references.
- Parameter mapping and result mapping.
- Cache policy surfaced from approved query configuration.
P7 - Full Expression Round-trip
- Parse supported expressions back into guided controls.
- Detect unsupported expression logic and keep guided read-only or partially editable with a clear reason.
- Guarantee expression logic is never silently lost.
- Add expression diff/round-trip tests for generated queries.
Test Matrix
Backend:
- Create, update, validate, publish, and execute
QUERYdrafts. - Expression generation parses back to the same query AST.
- Unsupported expression shape remains executable but disables guided mode.
- Field, relationship, operator, value, and limit validation.
- Permission-denied fields are omitted and cannot be referenced.
- Published query rule fails closed after data model unpublish/removal.
- Query preview never records execution audit; published execution does.
service.rule.evaluatecan call a query rule and merge the result variable.- Exposed query rules enforce API key scope and rule exposure.
Frontend:
- New Rule shows
QUERYas available. - Wizard lists only published visible data model types.
- Designer edits regenerate expression.
- Expression edits update designer or switch to Expression mode with reason.
- Preview renders rows/count/boolean/scalar/envelope correctly.
- Output type summary updates as return mode changes.
- All mutating controls have stable
data-agent-id. - ui-guard passes and new reusable components render in
/design.
Screenshot-based QA:
- Capture before and after screenshots.
- Single model query.
- Multi-model query.
- Field picker with selected chips.
- Filter with expression value.
- Nested
AND/ORfilters. - Aggregation query.
- Pagination query.
- Return shape changes.
- Guided to expression.
- Expression to guided.
- Unsupported expression warning.
- Permission-disabled field.
- Empty preview.
- Large result warning.
- Ask another agent to review screenshots for ease of use, help text, visual guidance, and enterprise polish.
- Commit implementation and QA findings together when implementation is requested.
Live proof:
- Create
Find open invoicesfromRules > New rule > Query. - Select
Invoice. - Return many records with fields
id,customer.name,amount,dueDate. - Filter
status = 'OPEN'and optionalamount >= inputs:minAmount. - Sort by
dueDate DESC, limit 50. - Confirm expression is generated.
- Edit the expression to add another guided-compatible filter.
- Confirm the designer updates.
- Preview with test inputs.
- Publish and execute through
service.rule.evaluate.
Open Decisions
- Exact function names:
queryMany/queryOneversus a singlequeryDataModelwithreturnMode. page(pageNumber, pageSize)is one-based in expression code, guided UI, API parse/generate, and runtime execution.- Whether P1 supports
ORin guided mode or expression mode only. - Whether one-to-many relationship traversal waits for aggregation support.
- How much of preview should run automatically versus behind an explicit "Test query" action.