Inflow.aiDocs

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 QUERY rule 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:

  • QUERY exists as a rule kind.
  • Users can create it through Rules > New rule > Query.
  • The rule stores JSON with an expression and designer sidecar.
  • 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(...), and rule(...).
  • 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/AND and ANY/OR match 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:

  1. Name, key, and business function, as today.
  2. Rule type: Query.
  3. Select data model type.
  4. Select starting query shape:
    • Single record.
    • List of records.
    • Count.
    • Exists.
    • Aggregate.
    • Full envelope.
  5. 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 / Query function 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') or rule('rule-key', version).
  • Published constants through constant('constant-key') or constant('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.outputType with ANONYMOUS or REUSABLE mode 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:

  • AND and OR groups.
  • 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 example inputs:status and inputs: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(...) and constant(...) 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 QueryRuleExecutionService or compiled QUERY branch in CompiledRule.
  • 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 RuleKind with QUERY.
  • Add a Query card in RULE_KIND_CARDS.
  • Extend EMPTY_BODIES for QUERY.
  • Add QueryRuleEditor.
  • Add query builder API client methods.
  • Keep all visual components composed from src/ui.
  • Add stable data-agent-id values for every mutating control.
  • Register invokable commands for validate, preview, publish, and key query builder actions.
  • Add /design gallery 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 QUERY to 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/OR groups, nested filters, enable/disable, and drag/reorder.
  • Add sortable SortList with drag/reorder.
  • Add saved templates.

P3 - Aggregation And Full Envelope

  • Groupings, measures, having filters.
  • queryScalar and queryEnvelope.
  • 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 QUERY drafts.
  • 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.evaluate can call a query rule and merge the result variable.
  • Exposed query rules enforce API key scope and rule exposure.

Frontend:

  • New Rule shows QUERY as 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/OR filters.
  • 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:

  1. Create Find open invoices from Rules > New rule > Query.
  2. Select Invoice.
  3. Return many records with fields id, customer.name, amount, dueDate.
  4. Filter status = 'OPEN' and optional amount >= inputs:minAmount.
  5. Sort by dueDate DESC, limit 50.
  6. Confirm expression is generated.
  7. Edit the expression to add another guided-compatible filter.
  8. Confirm the designer updates.
  9. Preview with test inputs.
  10. Publish and execute through service.rule.evaluate.

Open Decisions

  • Exact function names: queryMany/queryOne versus a single queryDataModel with returnMode.
  • page(pageNumber, pageSize) is one-based in expression code, guided UI, API parse/generate, and runtime execution.
  • Whether P1 supports OR in 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.

Try “document generation”, “integrations” or “first form”.