Query Builder
The Query Builder is how you configure a Platform Query data source. You describe what records you want — the operation, the fields to return, the filter, the ordering, and the page window — and the platform runs it server-side. Nothing is fetched and then trimmed on the page; all narrowing happens before the response leaves the server.
Note: The Query Builder applies only to Platform Query data sources. An API Endpoint source uses a different configuration form (method, URL, headers, body). See Data Source Types for a comparison.
Operation
The operation is the kind of read the query performs. Choose it first — it determines what configuration fields appear below.
| Operation | What it does | Required sub-configuration |
| Lookup — By Query | Fetch records of a given type where a search expression matches. The everyday operation: pick the record type, pick the fields, add filters and sorts. | Record type, fields, optional filter/sort/paging |
| Lookup — By Keys | Fetch the specific records whose keys you supply. Returns only those exact records — at least one key is required. | Record type, fields, one or more key values |
| Aggregate | Compute over records of an entity type instead of listing them raw — counts, sums, averages, grouped results. | Entity type, projections (the computed fields to return), optional time window and filter |
Returned Fields
You list the fields each result row should include. The query returns only what you name — not the whole record. Keeping this list tight keeps responses small and bindings predictable.
Warning: A block bound to a field you did not select reads an empty value — no error or warning appears. If a binding shows nothing, confirm the field is in the returned-fields list.
Selecting Fields
Open the Fields picker: In the data source's configuration form, locate the Fields (for a Lookup) or Projections (for an Aggregate) section.
Check the fields you need: Select only the fields your blocks actually bind to. Selecting fewer fields speeds up the query and keeps the output schema focused.
Verify in the Output panel: After running the data source, open its Output panel. The result shape lists each selected field. Confirm field names match your binding expressions exactly.
Filter Conditions
A filter narrows results on the server. Each condition names a field, an operator, and the values to match. Conditions can be combined with AND or OR logic, and groups can be nested.
| Operator | What it does | Value |
| Equals | The field matches the single given value exactly. | One string or boolean |
| In | The field matches any one of the given values. | Array of strings or booleans |
Note: Platform query conditions support exact match (Equals) and set membership (In). Range comparisons, substring contains, or negation are not supported as filter operators — for those, use a Lookup by Query expression, or reshape the response with a response transform after fetching more records.
Dynamic (Bound) Filter Values
A condition's value can be a binding expression — for example, filtering by a value the user picked in a select block. When the bound value changes and the data source is automatic, the query re-runs with the new filter automatically.
Example — Filter by a select block's chosen value
Filter condition: Field: status Operator: Equals Value: {{ status_filter.value }} // When status_filter changes (e.g. from "open" to "closed"), // the query re-runs automatically and the table updates.
Sort
Sorting orders results on the server before paging is applied. Each sort entry names a field and a direction — ascending (ASC) or descending (DESC). Stack multiple entries: the first is the primary order, later ones break ties.
| Property | Type | Required | Description |
| Field | string | Required (required) | The field to sort by. Must be a field the operation returns. |
| Direction | enum | Required (required) | ASC (ascending, A–Z, oldest-first) or DESC (descending, Z–A, newest-first). |
Warning: Offset paging assumes a stable order. Without an explicit sort, records can shift between page fetches as data changes — a record may appear twice or be skipped when the user pages through results. Always add at least one sort when using paging.
Paging
Paging windows the result set: a limit (how many records per page) and an offset (how many records to skip from the start). Both have defaults — the platform uses limit 10 and offset 0 unless you change them.
| Property | Type | Default | Description |
| Limit | number | 10 | Number of records to return per page. Bind to a page size control to make it user-selectable. |
| Offset | number | 0 | Number of records to skip. Page 3 at 10 rows per page = offset 20. |
Paging vs Infinite Loading
Offset paging fetches one fixed window at a time and replaces the current results when the page changes. For "load more" behavior where new pages append below the already-shown rows, see Infinite Loading — that is a separate capability enabled automatically for supported operation types.
Example — Page-based table navigation
// Assuming a page_number variable (starts at 1) and page_size = 10 Paging: Limit: 10 Offset: {{ (page_number.value - 1) * 10 }} // "Next page" button action: increment page_number variable // The automatic data source re-runs with the new offset
Aggregate Operation
An aggregate computes summary values over a set of records rather than listing them. Use it for dashboards, stat tiles, or any view that needs counts, sums, or grouped breakdowns.
| Property | Description |
| Entity Type | The record type to aggregate over. |
| Projections | The computed output fields — each names a source field and a computation (count, sum, average, min, max). These are what blocks bind to. |
| Time Window | Optional date range to narrow the records included in the computation. Combine with a Date filter block for user-selectable windows. |
| Filter | Optional conditions to further narrow the aggregated records — same Equals / In operators as a lookup filter. |
Practical Tips
| Tip | Details |
| Bind filter values to blocks | An automatic platform query whose filter is bound to a search box re-fetches as the user types, with no event handler needed. |
| Keep the fields list tight | Select only the fields blocks actually use. Fewer fields = smaller payload = faster renders. |
| Always add a sort when paging | Without a deterministic sort, records can shift across page-fetches as the underlying data changes. |
| Use the Output panel to confirm paths | Run the query once, then inspect its Output panel to see the exact field names and nesting before writing binding expressions. |
Related
Data Source Types — The Query Builder applies only to Platform Query sources; API Endpoints configure HTTP requests instead.
Run Behavior & Triggering — Bound filter values drive reactive re-runs; this page explains how.
Infinite Loading — Append-on-scroll pagination for platform query list operations.
Response Transforms — Post-process the result when server-side narrowing isn't enough.