--- id: CON-PFM-QRY-002 name: Query feature: FEAT-PFM-QRY-02 product_area: platform module: queries revision: 1 status: draft product_intent: confirmed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A query expresses a question over a dataset through selected values, conditions and ordering, with reusable forms for saved questions, recipes and record-list views. owned_by: MOD-PFM-QRY synonyms: - Saved query - Query definition not_to_be_confused_with: - A presentation that arranges query results - A file retained from a particular execution - The dataset described by the question facets: - name: Draft meaning: An unsaved definition lets a person explore a question. used_for: Trying a question before retaining it. source: 'services-platform:docs/queries/semantic-query-layer.md' provenance: documented - name: Saved query meaning: An owner retains a named definition with a controlled workspace audience. used_for: 'Reusing questions for reports, schedules and application populations.' source: 'services-platform:docs/queries/saved-queries-and-recipes.md' provenance: documented - name: Audience meaning: 'Private, selected-role and organization visibility govern who discovers the saved question.' used_for: Controlling access to the definition. source: 'services-platform:docs/queries/saved-queries-and-recipes.md' provenance: documented - name: Ask-when-run value meaning: A declared input supplies a criterion value at execution with its type and permitted bounds. used_for: Reusing one definition for changing dates or choices. source: 'services-platform:docs/queries/saved-queries-and-recipes.md' provenance: documented - name: Whoever runs it meaning: A user-bearing criterion can resolve to the execution’s person. used_for: Sharing a personal-work question among colleagues. source: 'services-platform:docs/queries/saved-queries-and-recipes.md' provenance: documented - name: Refinement meaning: Additional criteria and presentation choices adapt a stored question without widening its population. used_for: Applying report-specific narrowing. source: 'services-platform:docs/queries/saved-queries-and-recipes.md' provenance: documented - name: Recipe meaning: An application releases a versioned starting definition. used_for: Making an independent draft from a maintained example. source: 'services-platform:docs/queries/saved-queries-and-recipes.md' provenance: documented - name: Explorer view meaning: 'A recipe-anchored arrangement retains a record list’s columns, ordering and criteria.' used_for: Returning to familiar record-list work. source: 'services-platform:docs/explorer.md' provenance: documented - name: Navigation session and selection meaning: Navigation retains a bounded identity window; selection identifies matching records within its cap. used_for: Moving between records and supplying bulk work. source: 'services-platform:modules/explorer/services/navigation/navigation-sessions.ts:locateInNavigationSession' provenance: observed - name: Generated query meaning: A model proposes a definition from a person’s written request. used_for: Accelerating the first draft of a question. source: 'services-platform:modules/queries/services/generate/start-generation.ts:startGeneration' provenance: observed relationships: - to: CON-PFM-QRY-001 statement: 'The base dataset supplies the question’s available vocabulary, including permitted related datasets.' provenance: documented source: 'services-platform:docs/queries/saved-queries-and-recipes.md#1. Concepts' - to: CON-PFM-QRY-003 statement: 'An ordinary stored report uses one saved question, while a dashboard can use as many as fifty sources.' provenance: documented source: 'services-platform:docs/queries/reports.md#1. The record' - to: CON-PFM-QRY-004 statement: 'Query schedules retain a source copy, and query exports record individual executions.' provenance: documented source: >- services-platform:docs/migrations/query-scheduling-exports/README.md#D3. A schedule runs a pinned copy of the saved query (snapshot), and says when the saved query has changed lifecycle: - state: draft meaning: The question is still an unsaved working definition. how_it_changes: Its author saves it or begins it from a recipe. - state: private meaning: The owner retains the question for personal use. how_it_changes: Authorized sharing gives selected roles or the organization visibility. - state: shared meaning: The selected audience can discover the question. how_it_changes: 'Dependent reports constrain narrowing, and reports or schedules can prevent deletion.' acted_on_by: - CAP-PFM-QRY-002 - CAP-PFM-QRY-003 - CAP-PFM-QRY-006 - CAP-PFM-QRY-007 - CAP-PFM-QRY-008 - CAP-PFM-QRY-009 - CAP-PFM-QRY-010 - CAP-PFM-QRY-020 visible_to: - ACT-PFM-013 - ACT-PFM-014 - ACT-PFM-007 - ACT-PFM-016 evidence: - 'Pinned reference: services-platform:docs/migrations/query-scheduling-exports/README.md' - 'Pinned reference: services-platform:docs/queries/reports.md' - 'Pinned reference: services-platform:docs/queries/saved-queries-and-recipes.md' supersedes: [] origin: >- services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change) intent_sources: - >- services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change) --- # Query ## What It Is A query is a question expressed in Rhythm’s data vocabulary. It might ask for people in a region, records changed during a period or totals grouped by a classification. The definition chooses a base dataset, values to display, conditions and ordering. Related datasets and grouped calculations can extend the question. Staff work with those choices rather than writing a database statement. The same idea appears in several forms. A draft supports exploration. A saved query retains an owner, name and audience so the question can be reused. An application recipe offers a maintained starting point. An Explorer view preserves an arrangement suited to a record list. These belong together because they describe questions and their reuse, rather than separate business record kinds. A saved question’s identity remains distinct from its name and from the records its latest run happens to return. Its owner is part of that retained identity. Changing a definition can change later results without creating new source records. ## What It Is Not A query does not determine the appearance of a board pack or dashboard; that belongs to its report. It does not become a file until exported. Its dataset supplies the available vocabulary, whereas the query selects a particular question from that vocabulary. A recipe is an origin for an independent draft, rather than a live link that rewrites every saved derivative. ## How It Is Used Staff build and validate questions, inspect their results and retain the useful ones. Sharing lets colleagues discover a definition while execution continues to use each colleague’s access. Read Only staff can read shared work without acquiring write powers. Customer administrators maintain shared queries, while customer-private queries remain outside their ordinary management view. Rhythm staff access is a separate support exception. Reports and schedules make dependencies on saved questions explicit. A proposed audience change can be refused because a wider report still depends on the question. Deletion can likewise be blocked by a report or schedule. Applications that use questions as populations enumerate the matching identities as the named person and validate that access again as work continues. ## Its Facets **Draft and saved query.** Exploration becomes durable when staff save a named definition. Exact criterion values remain part of that definition. **Audience.** Private, selected roles and organization visibility describe who can find the question. They do not grant its underlying data. **Ask-when-run value.** Inputs let one question cover changing periods or selections. Declarations and supplied values must agree. **Whoever runs it.** A personal criterion lets one shared question refer to each runner’s own work. **Refinement.** Reports add narrowing and presentation choices while retaining the stored population boundaries. **Recipe.** A released starting point supplies a concrete independent draft after its values are filled in. **Explorer view.** A list arrangement carries a recipe anchor and reusable display choices. **Navigation session and selection.** Navigation keeps a bounded window of identities and reads again at some window edges. Selection supplies a bounded population for another application to act on. **Generated query.** A proposed draft can come from a written request and still needs review and ordinary execution checks. ## How It Relates Datasets provide the model. Reports provide presentation, exports preserve individual runs and schedules automate delivery. Security provides current role membership. Internal dated evaluations reuse the query vocabulary for application conditions without becoming staff-saved queries. ## What It Could Become The product should clarify ownership handover, future team visibility and the place of retained pins in the interface. Navigation also needs an explicit decision about stability across renewed reads. These extensions should preserve independent drafts and the distinction between a shared question and access to its data.