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.

Current model-key correction — 8 November 2026. The preserved examples below contain historical camelCase record-type/field keys. Do not copy those keys into the current editor or API: use record type leave_request and the lowercase field keys in the current model worksheet, including request_id, employee_id, manager_id, start_date, end_date, requested_days and decision_comment. Form, rule and case input names are separate declarations; map them explicitly rather than mechanically renaming every input. The preserved body remains historical source material, not a current executable model payload.

Query Builder Manual

Work from a small, known dataset

A QUERY rule is a governed read, not arbitrary SQL and not a workflow action. Begin with a published, executable record source and a handful of synthetic rows whose expected result you can explain. Choose a projection and return shape before adding joins or aggregations. Then declare inputs, validate/test under the intended caller and publish a version. A successful authoring preview is not a new permission for a published interface or machine key.

Our training model has request IDs leave-2026-014, leave-2026-015 and leave-2026-016; the first two are PENDING and the third APPROVED. The actual source IDs, model version, publication and row handles come from the reader’s environment. employeeId is data and must not be presented as an automatic current-user row-security rule. A query filter narrows the business question; native authorization still decides access.

Decision Beginner choice When to change it
Source One explicit published modeled record type Use Fabric only with an actual published fabric and its policy.
Output List with requestId/status/date projection Single/count/exists/envelope answer different questions.
Inputs Named required employee/status values where needed Avoid hidden ambient values or undeclared bare names.
Result size A deliberate bounded page/limit All records still obey platform/source policy bounds.
Relationships None until the basic query is correct Every joined source/field needs current governed coordinates.
Consumer Native rule execution first Each interface adapter has independent shape/input/paging restrictions.

The examples below supplement the deeper rule specification. Use query rule specification for expression/designer round-trip and data-source catalog before connecting a screen.

Worked examples

Example DATA-QUERY-01 — Build a pending-leave list with explicit input ownership

Scenario and inputs. Nadia has the three synthetic leave rows and an executable published source. She wants to ask which requests have a chosen status for a chosen employee, not grant access based on a client’s claim about identity. Both input names and types will be declared in the reusable rule contract.

Procedure. 1. Create a QUERY rule and select the actual published leaveRequest source. 2. Project only requestId, employeeId, status and the dates needed by the reader. 3. Declare required status and employeeId TEXT inputs, then use the guided filter’s expression editor with canonical inputs: references. 4. Let the builder produce its supported expression/designer body and validate their agreement. 5. Test the fixture for matching, nonmatching and missing-required-input cases under the intended caller. 6. Publish the reviewed result and record the actual rule version.

Expected result. A successful test returns only matching readable records in the declared shape. A status filter can narrow PENDING versus APPROVED rows but cannot give the caller visibility of an otherwise denied source or turn an arbitrary employeeId into current-user authorization.

Failure and recovery. If a filter treats inputs:status as literal text, remove the accidental quoting in the expression-value editor. If fields/source are missing, fix the selected published contract or actual access. Do not silently choose a similarly named model, drop a required filter, or convert a denied result into a known empty business answer.

Sources. QueryRuleRuntime.java, RuleInputDefinition.java, RuleDefinitionController.java.

Example DATA-QUERY-02 — Answer count and existence questions without counting the current page

Scenario and inputs. Sara needs both the number of matching requests and a yes/no indicator for whether any are pending. A list view currently shows only the first 25rows. The count, existence and list contracts answer different business questions even when a small test fixture makes their outputs look interchangeable.

Procedure. 1. Use the builder’s Count return mode for the authorized total and Exists for a Boolean question. 2. Keep source and predicate identical when comparing them with the list example. 3. Use a paged envelope when the consumer needs rows plus supported total/paging metadata, rather than treating returned page length as the total. 4. Inspect the actual result shape and capabilities after testing: a count is a scalar, not a reusable record collection. 5. Include a dataset larger than one page and a zero-match case in the reader’s admitted test fixture.

Expected result. An existence result can be true while the first page contains only a bounded subset. A list of 25items does not prove there are exactly 25matches, and a source/permission failure is unavailable rather than an authoritative zero.

Failure and recovery. If a consumer expects rows but receives a scalar, fix the chosen return shape or consumer contract. Do not wrap a scalar in a fake record list simply to satisfy a control, and do not run an unscoped database count to compensate for an authorized query’s limited output.

Sources. QueryRuleRuntime.java, QueryRuleRuntimeViewportTest.java.

Example DATA-QUERY-03 — Publish reusable results and select a compatible control

Scenario and inputs. Nadia’s QUERY returns a record collection with a stable row identity. She wants to reuse it in an interface. One version requires employeeId input; a different intentionally no-input version uses a fixed admitted business filter. These are distinct published contracts and cannot be swapped because they have the same display label.

Procedure. 1. Mark the supported record output reusable and publish the intended rule version. 2. Discover it through the actual screen catalog under the builder’s current permissions. 3. Inspect the control-specific capabilities and whether required inputs/defaults can be satisfied. 4. For a Repeater, use only a supported exact immutable QUERY source that its no-caller-input collection path can execute. 5. For a rule-query grid, satisfy the actual paged adapter contract, including supported source/subset and declared capabilities. 6. Save/review/publish the screen as a separate release operation.

Expected result. The screen’s immutable node names a coherent supported rule/source/shape; published runtime does not accept arbitrary replacement rule keys, inputs or projection from the browser. Reusability metadata alone does not make every QUERY executable by every control.

Failure and recovery. If the selected query has required inputs that a Repeater adapter cannot supply, keep it unavailable and design a supported input mapping or another consumer. Do not make the backend accept arbitrary client rule inputs by inventing a request field, and do not silently switch to a different no-input rule version.

Sources. QueryRuleRuntime.java, RuleQueryCollectionController.java, DataGridQueryController.java.

Example DATA-QUERY-04 — Explain stale synchronized data without secretly calling the provider

Scenario and inputs. An external employee source changed five minutes ago, but Nadia’s query still returns the previous admitted local snapshot. The selected source is synchronized/materialized according to its own policy. Running the QUERY again must not be presented as a provider-refresh operation or a guarantee that remote state has been observed.

Procedure. 1. Identify whether the chosen source is modeled, synced or a published Fabric type and read its actual materialization policy. 2. Compare the source publication and last successful sync/materialization checkpoint with the time of the external change. 3. Inspect authorized sync/readiness diagnostics and any retained failure rather than assuming empty/stale rows mean the query expression is wrong. 4. Ask the source operator to run or restore the supported sync only within its existing authority. 5. Refresh the query after a confirmed successful checkpoint and compare the same predicate/projection.

Expected result. The query reads the source defined by its admitted runtime contract. For a synchronized local published-record snapshot, it neither opens a hidden connector call nor starts a new sync merely because a user pressed Live test.

Failure and recovery. If the upstream call or checkpoint outcome is uncertain, preserve the original execution evidence and request an accountable reconciliation. Do not fabricate freshness, broaden credentials, repeat an uncertain external mutation, or replace the last successful snapshot with invented rows to make the tutorial look current.

Sources. QueryRuleRuntime.java, QuerySourceEligibility.java.

Detailed reference

The query builder creates QUERY rules. A query rule reads governed data and returns the shape the rule asks for: one record, a list of records, a field-value list, an aggregate projection, a count, an exists value, or a response envelope.

Two source kinds are supported:

  1. Data model type — a published (make-live / applied) record type in this workspace.
  2. Fabric (published) — a published Studio virtual fabric (fabric:<workspaceId>:<fabricKey>). Cross-source relationships defined on the fabric are applied by the fabric query engine.

For synced data models, the query runs against the platform's local published record store populated by sync. It reads the last successfully synced snapshot; executing a query rule does not call the external connector live and does not start a new sync run.

Fabric sources use the latest published fabric version. Bound-table materialization (LIVE / CACHED / REPLICATED) follows the fabric type policy; the rule does not start a new fabric sync by itself.

Open The Builder

  1. Open Studio.
  2. Go to Rules.
  3. Select New rule.
  4. Choose Query under "Look up and connect".
  5. Enter the rule name and key, then select Create Query.

The rule opens in the normal rule-builder workspace with the outline on the left, the query designer in the center, and the live test panel on the right.

Choose Data

Use Source kind:

  • Data model type — then pick a published record type. The builder lists record types already visible to the workspace. If none appear, publish and make-live the data model first, or check the actor's data-model view permission.
  • Fabric (published) — then pick a fabric that has at least one published version. Draft-only fabrics do not appear. If none appear, open Fabric, bind sources, publish a version, then return here.

After a source is selected, fields become available to the fields, filters, and sort controls. For multi-type fabrics, field keys are often namespaced as typeKey.fieldKey (matching the fabric query field universe).

Relationships / Joins in the query designer are for data-model sources only. Fabric graph relationships are applied automatically by the fabric query engine — do not re-author those joins in the designer.

Choose The Return Shape

Use Return to choose what the rule outputs:

Return mode Output
List of records A list of matching records.
Single record The first matching record, or null if none match.
Count The number of matching records.
Exists yes/no true when at least one record matches.
Field values One selected field across matching records.
Aggregation Grouped metric rows with aliases.
Full envelope {data, totalCount, page, limit, hasMore, success}.

Fields controls projection for record-returning modes. Leave it empty to return all readable fields. Count and exists ignore selected fields.

Result size controls list, field-value, aggregation, and envelope outputs. Supported modes are first N records, all records with platform policy limits, page-number pagination, and cursor pagination. Page-size presets are available for common sizes, and total-count metadata can be included when supported.

Add Filters

Use Add filter for each condition. A filter has:

  • Field: the data-model field or relation id path.
  • Operator: comparison such as =, !=, >, >=, <, <=, in, contains, or starts with.
  • Value: an expression, not just text.

Literal text values should be quoted, for example 'OPEN'. Rule inputs can be referenced through the declared canonical input namespace, for example inputs:minAmount or inputs:currentUser.department. A current-user-looking input is still supplied data; it is not a server-issued identity or access grant. Because query filter values and apply conditions are InflowEL expressions, they can also call published rules, constants, and registered functions. Use constant('approval-limit') for centrally managed values, rule('policy-key') for another published rule's result, and normal functions such as today(), now(), lower(...), or round(...) wherever the value type is compatible.

Example:

status = 'OPEN'
amount >= inputs:minAmount
amount >= constant('approval-limit')
department = rule('current-approval-policy').department

The validation panel infers variables used by filter value expressions, so missing inputs can be declared and tested like expression rules.

Add Sorts

Use Add sort to order records before the result is limited. Sorts can be ascending or descending. Numeric values sort numerically; other values sort as case-insensitive text.

Edit The Generated Expression

The builder writes a query expression while you use the guided controls. You can switch to Expression mode, edit the code, and keep the expression in the rule body. The expression is the authoritative code representation of the rule. The guided designer is the no-code projection over that expression.

Publish-time validation checks that the guided designer and expression describe the same supported query. If expression logic cannot be represented in guided mode, the builder keeps the rule in Expression mode and explains why instead of silently dropping logic.

The supported generated shape uses functions such as:

queryMany('Invoice', select('id', 'amount'), whereAll(filter('status', '=', 'OPEN')), sortDesc('amount'), limit(50))

Expression mode is still normal InflowEL. Query rules may reference inputs, constants, functions, and other published rules, subject to the same rule-call permissions, cycle detection, and nesting limits as expression rules.

The query-expression helper catalog includes:

Function Purpose
queryOne(recordType, ...) Return the first matching record or null.
queryMany(recordType, ...) Return matching records.
queryValues(recordType, select(field), ...) Return values for one selected field.
queryCount(recordType, ...) Return the matching row count.
queryExists(recordType, ...) Return whether at least one row matches.
queryEnvelope(recordType, ...) Return data plus paging/count metadata.
select(field...) Pick returned fields.
whereAll(filter...) / whereAny(filter...) Combine filters with AND or OR.
filter(field, operator, value) Add a filter.
sortAsc(field) / sortDesc(field) Add sort order.
limit(n) / page(pageNumber, pageSize) Control result size.
includeTotalCount() Request total-count metadata when supported.
join(recordType, on(sourceField, targetField), type) Add a related model.
groupBy(field...) / aggregate(alias, function, field) Build grouped metrics.
having(filter...) Filter aggregate aliases.

The editor autocomplete suggests query functions, record types, fields, aggregate aliases, filter operators, and published callable rule keys.

Add Relationships And Aggregations

Guided mode can add related data model types when a governed relationship or manual equality join is available. For multi-model record returns, choose an explicit projection so the returned object shape is predictable.

Supported join types are inner, left, exists/semi-join, and not-exists/anti-join. Join fields are selected from published record metadata; they are not typed by hand in guided mode.

Aggregation mode supports groupings, aliased measures, and having filters over aggregate aliases. Aggregate rows are projected objects, not full data-model records.

Test And Publish

Use Live test to run the draft with sample input values. The test path uses the same governed data-record reader as published execution, so workspace access and readable-field policies apply.

When the test result is correct:

  1. Select Validate.
  2. Fix any missing source, malformed expression, or filter-value issues.
  3. Select Publish.

Published query rules can be called anywhere normal rules are available, including rule composition and API-exposed rules.

Troubleshooting

Symptom Check
No data model types are listed Publish the data model and confirm workspace visibility.
Query returns empty data Confirm data exists, filters match, and the actor has DATA_MODEL_VIEW.
Synced source changes are not visible Run or wait for sync to complete; query rules read the last successful local sync snapshot.
Fields are missing from records The governed reader omits unreadable fields. Check field-level policy.
Validation reports an unknown variable Declare the variable or use a quoted literal value.
Publish fails with QUERY_RECORD_TYPE_NOT_FOUND Select a data model type before publishing.
Publish fails with QUERY_EXPRESSION_MISSING Use guided controls or write the generated query expression.

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