Run a saved question for the current reader

Purpose

Apply the stored question, supplied values and permitted refinements for the person who runs it.

How It Works

A person opens a saved query and supplies any values it asks for. Platform combines those values with the stored definition. A report can also supply a permitted refinement. Execution then follows the viewer’s access rather than the author’s grants. Other applications can request the matching record identities for their own work. That population flow rebuilds the named person’s access on every page. Some queries cannot serve as populations and return a specific refusal. Cursors and definition fingerprints let an application continue without treating a changed question as the old population.

Relationships

Parameterized execution uses the saved-question library and ordinary query execution; other applications can consume identifier pages.

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: One stored question can accept different run-time values.Presentation refinements preserve its matching population.Applications receive a person’s permitted record population.
Surfaces: consoleapijob
Intent sources: services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change)services-platform:docs/queries/saved-queries-and-recipes.md#2. The stored definition (Andrew, 2026-10-13)services-platform:docs/milestones/plans/RPT-M1-plan.md#A3services-platform:docs/milestones/plans/RPT-M1-plan.md#D1

Controls

23 controls apply, from the corpus control catalogue.

TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-DAT-001 TC-DAT-003 TC-LOG-001 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 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.saved-queries.read`	api	tenant
`<application>.<dataset>.query (the owner's key)`	service	tenant

Business Rules

12 rules, 11 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	Shared queries execute with the runner’s own dataset permissions and never confer additional field, row or dataset access. origin: services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change) proved by `ATS-PFM-QRY-006-17`, `ATS-PFM-QRY-007-01`, `ATS-PFM-QRY-007-12`, `ATS-PFM-QRY-007-13`, `TST-PFM-QRY-234`	permission	service	test services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses to run it for a caller who may not query the dataset as 403, however it was shared
`02`must prove Proposed	Runs accept paging changes, requested values and a refinement; paging options merge into stored paging, and other request content is rejected. proved by `ATS-PFM-QRY-007-02`, `TST-PFM-QRY-234`	validation	api	test services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses a page carrying a key the query language does not have as 400
`03`must prove Proposed	Requested-at-run declarations must match their criterion types and options, and saving rejects undeclared, unused, mismatched or unsupported requests for values. origin: services-platform:docs/queries/saved-queries-and-recipes.md#2. The stored definition (Andrew, 2026-10-13) proved by `ATS-PFM-QRY-007-03`, `TST-PFM-QRY-234`	validation	service	test services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses a save whose declaration does not match its criterion as 400 at definition.parameters[0].dataType
`04`must prove Proposed	Execution supplies given values or defaults, preserves text exactly, and rejects missing required values, wrong types, out-of-bound values, disallowed options and unrequested names at their locations. origin: services-platform:docs/queries/saved-queries-and-recipes.md#2. The stored definition (Andrew, 2026-10-13) proved by `ATS-PFM-QRY-007-04`, `TST-PFM-QRY-234`	validation	service	test services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses a run without the required value as 400 at parameters.updatedBefore
`05`must prove Proposed	Refinement adds criteria to the stored criteria, may replace columns, grouping and ordering, and retains the stored scope, joins, links and requested values without widening the matching population. origin: services-platform:docs/milestones/plans/RPT-M1-plan.md#A3 proved by `ATS-PFM-QRY-007-05`, `TST-PFM-QRY-233`, `TST-PFM-QRY-343`	policy	service	test services-platform:modules/queries/tests/integration/services/saved-queries/run-with-refinement.integration.spec.js#never widens: criteria naming a contact outside the query answer none of it
`06`must prove Proposed	A reader’s refinement can select permitted dataset columns omitted by the author. origin: services-platform:docs/milestones/plans/RPT-M1-plan.md#D1 proved by `ATS-PFM-QRY-007-06`, `TST-PFM-QRY-343`	policy	service	test services-platform:modules/queries/tests/integration/services/saved-queries/run-with-refinement.integration.spec.js#answers the columns the refinement names instead of the stored ones, over the same rows
`07`must prove Proposed	A refinement cannot introduce requested-at-run values or substitute for a required supplied value. proved by `ATS-PFM-QRY-007-07`, `TST-PFM-QRY-343`	validation	service	test services-platform:modules/queries/tests/integration/services/saved-queries/run-with-refinement.integration.spec.js#still asks for the value: a refinement does not stand in for a required parameter
`08`must prove Proposed	Applications can enumerate a saved query’s record identities in ordered pages of one thousand, resume with a criteria-bound cursor and definition fingerprint, and request a count that reports when its supplied cap is reached. proved by `ATS-PFM-QRY-007-08`, `TST-PFM-QRY-347`	policy	service	test services-platform:modules/queries/tests/integration/services/saved-queries/saved-query-record-ids.integration.spec.js#answers every planted contact once, none repeated and none missed, in record id order
`09`must prove Proposed	Each population page rebuilds the named person’s access and rejects missing, suspended, portal or wrong-customer users and missing permissions; inaccessible saved queries are reported as missing. proved by `ATS-PFM-QRY-007-09`, `TST-PFM-QRY-341`	permission	service	test services-platform:modules/queries/tests/integration/services/saved-queries/record-ids-invocation.integration.spec.js#refuses a suspended user as access_denied, naming the status
`10`must prove Proposed	Recently Viewed queries, unanswered required values and joins that repeat base records are rejected as application populations. proved by `ATS-PFM-QRY-007-10`, `TST-PFM-QRY-341`, `TST-PFM-QRY-347`	validation	service	test services-platform:modules/queries/tests/integration/services/saved-queries/record-ids-invocation.integration.spec.js#answers saved_query_invalid for a saved query of the person’s recently viewed records
`11`must prove Proposed	Population logs identify the query, dataset and criteria structure without including values or record identities. proved by `ATS-PFM-QRY-007-11`, `TST-PFM-QRY-347`	invariant	service	test services-platform:modules/queries/tests/integration/services/saved-queries/saved-query-record-ids.integration.spec.js#logs no criteria value and no record id
`12` Proposed	Population entry points restrict invocation to their designated application service roles, with separate Accounting and Marketing entry points.	permission	service	documented services-platform:docs/queries/saved-queries-and-recipes.md#5.3 Paging a saved query's ids from another macroservice

Scenarios

Id	Given	When	Then	Provenance
`01`	A saved question requires a date supplied at execution.	The runner omits that date.	Execution identifies the missing required value.	test services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses a run without the required value as 400 at parameters.updatedBefore
`02`	A saved query matches two thousand six hundred contacts.	An application pages their identities.	The pages contain one thousand, one thousand and six hundred identities.	test services-platform:modules/queries/tests/integration/services/saved-queries/saved-query-record-ids.integration.spec.js#answers three pages of 1,000, 1,000 and 600 ids

Planning

Implementation

Run a saved question for the current reader ​

Purpose ​

How It Works ​

Relationships ​