--- id: CAP-PFM-QRY-007 title: Run a saved question for the current reader feature: FEAT-PFM-QRY-02 product_area: platform module: queries revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-RPT-QRY-001 - CAP-RPT-QRY-012 source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f 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#A3' - 'services-platform:docs/milestones/plans/RPT-M1-plan.md#D1' purpose: 'Apply the stored question, supplied values and permitted refinements for the person who runs it.' outcomes: - One stored question can accept different run-time values. - Presentation refinements preserve its matching population. - Applications receive a person’s permitted record population. concepts: - CON-PFM-QRY-002 actors: - ACT-PFM-013 - ACT-PFM-014 - ACT-PFM-016 surfaces: - console - api - job preconditions: [] postconditions: [] permissions: - key: platform.saved-queries.read where_checked: api scope: tenant - key: ..query (the owner's key) where_checked: service scope: tenant rules: - id: BR-CAP-PFM-QRY-007-01 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] statement: >- Shared queries execute with the runner’s own dataset permissions and never confer additional field, row or dataset access. kind: permission enforced_at: - service must_prove: true provenance: test source: >- 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 origin: >- services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change) - id: BR-CAP-PFM-QRY-007-02 proved_by: [ATS-PFM-QRY-007-02, TST-PFM-QRY-234] statement: >- Runs accept paging changes, requested values and a refinement; paging options merge into stored paging, and other request content is rejected. kind: validation enforced_at: - api must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-PFM-QRY-007-03 proved_by: [ATS-PFM-QRY-007-03, TST-PFM-QRY-234] statement: >- Requested-at-run declarations must match their criterion types and options, and saving rejects undeclared, unused, mismatched or unsupported requests for values. kind: validation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: >- services-platform:docs/queries/saved-queries-and-recipes.md#2. The stored definition (Andrew, 2026-10-13) - id: BR-CAP-PFM-QRY-007-04 proved_by: [ATS-PFM-QRY-007-04, TST-PFM-QRY-234] statement: >- 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. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses a run without the required value as 400 at parameters.updatedBefore origin: >- services-platform:docs/queries/saved-queries-and-recipes.md#2. The stored definition (Andrew, 2026-10-13) - id: BR-CAP-PFM-QRY-007-05 proved_by: [ATS-PFM-QRY-007-05, TST-PFM-QRY-233, TST-PFM-QRY-343] statement: >- 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. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: 'services-platform:docs/milestones/plans/RPT-M1-plan.md#A3' - id: BR-CAP-PFM-QRY-007-06 proved_by: [ATS-PFM-QRY-007-06, TST-PFM-QRY-343] statement: A reader’s refinement can select permitted dataset columns omitted by the author. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: 'services-platform:docs/milestones/plans/RPT-M1-plan.md#D1' - id: BR-CAP-PFM-QRY-007-07 proved_by: [ATS-PFM-QRY-007-07, TST-PFM-QRY-343] statement: A refinement cannot introduce requested-at-run values or substitute for a required supplied value. kind: validation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-PFM-QRY-007-08 proved_by: [ATS-PFM-QRY-007-08, TST-PFM-QRY-347] statement: >- 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. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-PFM-QRY-007-09 proved_by: [ATS-PFM-QRY-007-09, TST-PFM-QRY-341] statement: >- 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. kind: permission enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-PFM-QRY-007-10 proved_by: [ATS-PFM-QRY-007-10, TST-PFM-QRY-341, TST-PFM-QRY-347] statement: >- Recently Viewed queries, unanswered required values and joins that repeat base records are rejected as application populations. kind: validation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-PFM-QRY-007-11 proved_by: [ATS-PFM-QRY-007-11, TST-PFM-QRY-347] statement: >- Population logs identify the query, dataset and criteria structure without including values or record identities. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-platform:modules/queries/tests/integration/services/saved-queries/saved-query-record-ids.integration.spec.js#logs no criteria value and no record id origin: none - id: BR-CAP-PFM-QRY-007-12 proved_by: [] statement: >- Population entry points restrict invocation to their designated application service roles, with separate Accounting and Marketing entry points. kind: permission enforced_at: - service must_prove: false provenance: documented source: >- services-platform:docs/queries/saved-queries-and-recipes.md#5.3 Paging a saved query's ids from another macroservice origin: none scenarios: - id: SC-CAP-PFM-QRY-007-01 given: A saved question requires a date supplied at execution. when: The runner omits that date. then: Execution identifies the missing required value. provenance: test source: >- services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses a run without the required value as 400 at parameters.updatedBefore - id: SC-CAP-PFM-QRY-007-02 given: A saved query matches two thousand six hundred contacts. when: An application pages their identities. then: 'The pages contain one thousand, one thousand and six hundred identities.' provenance: test source: >- 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 edge_cases: [] constraints: [] depends_on: - CAP-PFM-QRY-006 - CAP-PFM-QRY-002 related: - CAP-PFM-QRY-006 - CAP-PFM-QRY-011 journeys: - JNY-PFM-QRY-001 open_questions: [] operations: - runSavedQuery tables: [] evidence: - 'Pinned reference: services-platform:docs/milestones/plans/RPT-M1-plan.md' - 'Pinned reference: services-platform:docs/queries/saved-queries-and-recipes.md' - 'Pinned reference: services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js' - >- Pinned reference: services-platform:modules/queries/tests/integration/services/saved-queries/record-ids-invocation.integration.spec.js - >- Pinned reference: services-platform:modules/queries/tests/integration/services/saved-queries/run-with-refinement.integration.spec.js - >- Pinned reference: services-platform:modules/queries/tests/integration/services/saved-queries/saved-query-record-ids.integration.spec.js controls: [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] exercised_by: [FAS-PFM-QRY-02-01, FAS-PFM-QRY-02-02, FAS-PFM-QRY-02-03, FAS-PFM-QRY-02-04, FAS-PFM-QRY-02-05, FAS-PFM-QRY-04-02] suites: [TST-PFM-QRY-233, TST-PFM-QRY-234, TST-PFM-QRY-341, TST-PFM-QRY-343, TST-PFM-QRY-347] --- # 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.