Answer a question within the reader’s access

Purpose

Let staff investigate workspace data through filters, ordering and grouped results evaluated with their own access and calendar.

How It Works

A staff member chooses a dataset and builds a question in the designer. They select fields, add criteria and choose ordering or grouping. Validation gives them located problems to repair before they run the question. Execution checks the resolved dataset model and reads through the protected database reader. Results supply values and record-opening information for the screen. The person can continue through later pages or ask for a matching total. Relative dates use the customer workspace’s calendar. A current-person condition lets colleagues reuse the same question for their own work. Unsupported input, lost access and execution limits produce refusals or failure messages.

Relationships

Execution uses resolved dataset descriptions. Saved questions, navigation and file production reuse its result semantics.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Staff investigate data without writing database statements.Workspace and dataset access constrain results.Paging follows the question’s declared ordering.
Surfaces: consoleapi
Intent sources: services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 8services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 9services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 13services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 15services-platform:docs/queries/semantic-query-layer.md#A value asked for when a saved query runs (`$parameter`, 2026-10-13)

Controls

29 controls apply, from the corpus control catalogue.

TC-AVL-001 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-CRY-001 TC-CRY-002 TC-CRY-003 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

Key	Checked at	Scope
`platform.queries.read`	api	tenant
`<application>.<dataset>.query (the owner's key)`	service	tenant

Business Rules

16 rules, 16 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Query execution confines source records and joins to the requested workspace, with database row security also preventing cross-workspace reads when a compiled predicate is absent. origin: services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 9 proved by `ATS-PFM-QRY-001-12`, `ATS-PFM-QRY-002-01`, `ATS-PFM-QRY-002-17`, `ATS-PFM-QRY-002-19`, `ATS-PFM-QRY-003-12`, `ATS-PFM-QRY-004-08`, `ATS-PFM-QRY-014-11`, `TST-PFM-QRY-296`	invariant	service, database	test services-platform:modules/queries/tests/integration/services/execute/run-query.integration.spec.js#confines a statement carrying no tenant predicate at all, so row-level security holds beneath the compiler
`02`must prove Proposed	Queries use a read-only reader transaction with a time limit; timeouts produce an actionable limit message, and other failures reveal neither statement text nor stored data. proved by `ATS-PFM-QRY-002-02`, `TST-PFM-QRY-289`	invariant	service, database	test services-platform:modules/queries/tests/integration/services/execute/read-only-execution.integration.spec.js#refuses a write, whatever the statement carries, because the transaction is read-only
`03`must prove Proposed	Unsupported fields, operators and relationships are rejected without distinguishing inaccessible metadata from metadata that does not exist. proved by `ATS-PFM-QRY-002-03`, `TST-PFM-QRY-296`	validation	service	test services-platform:modules/queries/tests/integration/services/execute/run-query.integration.spec.js#refuses a column no owner registered exactly as it refuses one that does not exist at all
`04`must prove Proposed	Criterion validation rejects blank text, empty identity lists, fractional integer values, unsafe whole numbers and dates outside the required calendar-date form. proved by `ATS-PFM-QRY-002-04`, `TST-PFM-QRY-296`	validation	service	test services-platform:modules/queries/tests/integration/services/execute/run-query.integration.spec.js#refuses a blank text value, which would match every contact rather than narrow anything
`05`must prove Proposed	Paging cursors carry the query’s ordered position, and malformed cursors, cursors from another query or cursors with incompatible keys are rejected. proved by `ATS-PFM-QRY-002-05`, `TST-PFM-QRY-296`	validation	service	test services-platform:modules/queries/tests/integration/services/execute/run-query.integration.spec.js#refuses a cursor issued for a different query, rather than paging the wrong rows
`06`must prove Proposed	Requested totals count all matching base records or groups in the page’s database snapshot, independently of cursor position and join multiplication; unrequested totals are omitted. proved by `ATS-PFM-QRY-002-06`, `TST-PFM-QRY-287`	calculation	service	test services-platform:modules/queries/tests/integration/services/execute/query-totals.integration.spec.js#counts the base records, not the rows the joins produced
`07`must prove Proposed	Recently Viewed returns this person’s workspace records once each at their latest viewing time, newest first, and rejects system executions without a person. origin: services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 15 proved by `ATS-PFM-QRY-002-07`, `TST-PFM-QRY-290`	policy	service	test services-platform:modules/queries/tests/integration/services/execute/recently-viewed-scope.integration.spec.js#answers each caller the records that caller viewed, and no other caller’s
`08`must prove Proposed	The current-person criterion resolves from the execution identity on a user-bearing field with a compatible operator, and rejects unsuitable fields, operators and non-person executions. proved by `ATS-PFM-QRY-002-08`, `TST-PFM-QRY-270`	policy	service	test services-platform:modules/queries/tests/integration/services/execute/current-user-criterion.integration.spec.js#answers a second caller their own tasks, from the very same criterion
`09`must prove Proposed	Unsaved execution rejects requested-at-run values and supplied parameter maps, while validation reports those uses as located problems in a successful validation response. origin: services-platform:docs/queries/semantic-query-layer.md#A value asked for when a saved query runs (`$parameter`, 2026-10-13) (Andrew, 2026-10-13) proved by `ATS-PFM-QRY-002-09`, `TST-PFM-QRY-234`	validation	api, service	test services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses a token sent to the validate route, which judges a request on its own
`10`must prove Proposed	Calendar and relative-date criteria use the workspace’s time zone and calendar, and date previews report the calendar used. proved by `ATS-PFM-QRY-002-10`, `ATS-PFM-QRY-020-07`, `TST-PFM-QRY-226`, `TST-PFM-QRY-296`	calculation	service	test services-platform:modules/queries/tests/integration/services/execute/run-query.integration.spec.js#reads a day as that day in the tenant's zone, not in UTC
`11`must prove Proposed	Validation collects located query problems without executing the query, while execution stops at its first invalid part. proved by `ATS-PFM-QRY-002-11`, `ATS-PFM-QRY-002-18`, `TST-PFM-QRY-234`	validation	service	test services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#answers 200 and the problems for a query it will not run, rather than a refusal
`12`must prove Proposed	Linked result cells identify records whose identities the reader may select, and an override referring to a record absent from the result is rejected. proved by `ATS-PFM-QRY-002-12`, `TST-PFM-QRY-225`	policy	service	test services-platform:modules/queries/tests/e2e/datasets.e2e.spec.js#refuses a link override naming a record the result does not have as 400 QueryLinkInvalid
`13`must prove Proposed	Reference columns display the referenced record’s name, fall back to its identity when nameless, and remain empty when absent; an explicitly selected identity stays separate. proved by `ATS-PFM-QRY-002-13`, `TST-PFM-QRY-293`	calculation	service	test services-platform:modules/queries/tests/integration/services/execute/reference-display-values.integration.spec.js#shows each spouse’s name, the id as text where the spouse has no name, and null where there is no spouse
`14`must prove Proposed	A field reached through a record reference supports one many-to-one traversal and rejects a second traversal. origin: services-platform:docs/queries/semantic-query-layer.md#Decisions Recorded (Andrew, 2026-10-08) 13 proved by `ATS-PFM-QRY-002-14`, `TST-PFM-QRY-296`	validation	service	test services-platform:modules/queries/tests/integration/services/execute/run-query.integration.spec.js#refuses a second hop through the referenced record's own reference
`15`must prove Proposed	The documented query bounds are 255 selected fields, five sort keys, 100 criteria at depth six, two to-one hops and pages of at most one thousand rows, defaulting to one hundred. proved by `ATS-PFM-QRY-002-15`	validation	api, service	documented services-platform:docs/queries/semantic-query-layer.md#10.6 Complexity limits (first release)
`16`must prove Proposed	Grouped calculations apply sums, averages, minima and maxima to the matching group rows, preserve appropriate result types, and yield no value for a field absent from every row. proved by `ATS-PFM-QRY-002-16`, `TST-PFM-QRY-286`	calculation	service	test services-platform:modules/queries/tests/integration/services/execute/query-aggregates.integration.spec.js#answers one group for the three contacts, every aggregate computed over exactly those rows

Scenarios

Id	Given	When	Then	Provenance
`01`	Two workspaces use identical contact and employer identities.	A person queries contacts with an employer value in the first workspace.	The answer includes only records and related values from that workspace.	test services-platform:modules/queries/tests/integration/services/execute/run-query.integration.spec.js#answers no row, pick or joined value belonging to another tenant, though the ids are the same
`02`	A task question uses the current-person criterion.	Two people execute that same question.	Each result contains the tasks assigned to its own runner.	test services-platform:modules/queries/tests/integration/services/execute/current-user-criterion.integration.spec.js#answers a second caller their own tasks, from the very same criterion
`03`	The workspace calendar uses a time zone different from UTC.	A datetime criterion asks for records on a calendar day.	Matching follows the full workspace day.	test services-platform:modules/queries/tests/integration/services/execute/run-query.integration.spec.js#reads a day as that day in the tenant's zone, not in UTC

Planning

Implementation

Answer a question within the reader’s access ​

Purpose ​

How It Works ​

Relationships ​