Rhythm 2.0 Specifications

Appearance

CAP-PFM-QRY-014Download the complete answer to a query

Markdown

CAP-PFM-QRY-014

Download the complete answer to a query

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-QRY-05
Exercised by
FAS-PFM-QRY-05-01, FAS-PFM-QRY-05-02, FAS-PFM-QRY-05-03, FAS-PFM-QRY-05-04, FAS-PFM-QRY-05-05, FAS-PFM-QRY-07-02, JNY-PFM-QRY-004
Key concepts
CON-PFM-QRY-004
Actors
ACT-PFM-013, ACT-PFM-007, ACT-PFM-012
Journeys
JNY-PFM-QRY-002
Depends on
CAP-PFM-QRY-002
Related
CAP-PFM-QRY-002, CAP-PFM-QRY-013, CAP-PFM-QRY-015
Open questions
OQ-PFM-QRY-002
Proved by
ATS-PFM-QRY-014

Implementation

Executable suites
TST-PFM-QRY-108, TST-PFM-QRY-109, TST-PFM-QRY-301, TST-PFM-QRY-302, TST-PFM-QRY-394, TST-PFM-QRY-395

KindCapabilityProduct areaPlatformModuleQuestions, record exploration and data deliveryRevision1

Read atservices-platform ad3f6a65react-console baf6dae3

Download the complete answer to a query ​

Purpose ​

Write the query’s full result to a spreadsheet file while preserving its order and checking access again.

How It Works ​

A staff member chooses export for the query they have on screen or have saved. They select a supported format and heading options. Platform validates the question and queues file generation. The worker checks access again and pages through the complete result. Writers preserve result ordering and handle values safely for spreadsheets. Row and duration limits can stop generation with a useful failure message. The requester follows the export until its file is ready. A download then redirects to a short-lived storage link. Scheduled recipients use their own delivery links.

Relationships ​

Query files use ordinary query execution and export records. Scheduled delivery reuses the file-building path.

The Formal Contract

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

Outcomes
The complete result can be processed outside the screen.Generation rechecks the requester’s data access.Download paths use the export’s permitted audience.
Surfaces
consoleapijob
Intent sources
services-platform:docs/migrations/query-scheduling-exports/README.md#D1. One execution path for interactive, exported and scheduled queriesservices-platform:docs/migrations/query-scheduling-exports/README.md#D5. Permissionsservices-platform:docs/migrations/query-scheduling-exports/README.md#D7. Delivery: one e-mail per recipient with a secure link, through the communications moduleservices-platform:docs/migrations/query-scheduling-exports/README.md#D9. Exports: two formats, independent heading and description optionsservices-platform:docs/migrations/query-scheduling-exports/README.md#D10. One asynchronous path, which feels synchronous for small exportsservices-platform:docs/migrations/query-scheduling-exports/README.md#D11. Storage: the Rhythm 1.0 bucket, under its protected prefixservices-platform:docs/migrations/query-scheduling-exports/README.md#Remaining differences (accepted by Andrew 2026-10-17)

Controls

33 controls apply, from the corpus control catalogue.

TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-005 TC-IAM-001 TC-IAM-002 TC-IAM-003 TC-IAM-004 TC-IAM-005 TC-IAM-006 TC-LOG-001 TC-LOG-005 TC-MON-001 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-TEN-004 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
platform.queries.readapitenant
<application>.<dataset>.query (the owner's key)servicetenant
platform.query-schedules.manage (to follow and download anyone's export)servicetenant

Business Rules

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

IdRuleKindEnforced atProvenance
01must prove
Confirmed
Query export uses the same access as query execution with no extra export permission, validating the request before creating an export.
origin: services-platform:docs/migrations/query-scheduling-exports/README.md#D5. Permissions
proved by ATS-PFM-QRY-014-01, TST-PFM-QRY-301, TST-PFM-QRY-302
permissionapi, servicetest
services-platform:modules/queries/tests/integration/services/exports/query-export-routes.integration.spec.js#refuses a caller who may not query the dataset (403)
02must prove
Confirmed
Exports require exactly one saved-query source with values or an on-screen definition, support CSV or Excel and label, technical-name or absent headings, allow descriptions only in Excel, and default to Excel with labels without descriptions.
origin: services-platform:docs/migrations/query-scheduling-exports/README.md#D9. Exports: two formats, independent heading and description options
proved by ATS-PFM-QRY-014-02, TST-PFM-QRY-301
validationapitest
services-platform:modules/queries/tests/integration/services/exports/query-export-routes.integration.spec.js#refuses a body naming both a saved query and a definition (400)
03must prove
Confirmed
Exports queue asynchronously and read the query engine in pages of one thousand to write its complete result once in its column and row order.
origin: services-platform:docs/migrations/query-scheduling-exports/README.md#D1. One execution path for interactive, exported and scheduled queries
proved by ATS-PFM-QRY-002-19, ATS-PFM-QRY-014-03, ATS-PFM-QRY-014-11, TST-PFM-QRY-301, TST-PFM-QRY-302
invariantservicetest
services-platform:modules/queries/tests/integration/services/exports/run-query-export.integration.spec.js#writes every planted row exactly once, in the query’s sort, with no gap
04must prove
Confirmed
CSV uses UTF-8 with a byte-order mark, CRLF and quoting, calendar dates and workspace-offset instants; Excel retains native value types, and formula-like text is neutralized without altering negative numbers.
origin: services-platform:docs/migrations/query-scheduling-exports/README.md#D9. Exports: two formats, independent heading and description options
proved by ATS-PFM-QRY-014-04, TST-PFM-QRY-394
calculationservicetest
services-platform:modules/queries/tests/unit/services/exports/csv-writer.spec.ts#prefixes a value starting with = with an apostrophe
05must prove
Confirmed
Exports fail with an actionable message above one million CSV rows, Excel’s sheet capacity or fourteen minutes of work.
origin: services-platform:docs/migrations/query-scheduling-exports/README.md#D9. Exports: two formats, independent heading and description options
proved by ATS-PFM-QRY-014-05, TST-PFM-QRY-302
validationservicetest
services-platform:modules/queries/tests/integration/services/exports/run-query-export.integration.spec.js#fails too_many_rows with the sentence a person reads
06must prove
Confirmed
Export execution rechecks query access and produces no file when it is lost, while Rhythm staff need a current workspace grant.
origin: services-platform:docs/migrations/query-scheduling-exports/README.md#D4. Whose access a run uses: the schedule's owner, checked fresh at every run
proved by ATS-PFM-QRY-014-06, TST-PFM-QRY-302
policyservicetest
services-platform:modules/queries/tests/integration/services/exports/run-query-export.integration.spec.js#fails access_lost for staff holding no grant into the tenant
07must prove
Confirmed
Export status and downloads are available to the requester, the relevant schedule owner and schedule managers; others receive not found, unfinished files return not ready, and expired files return gone.
origin: services-platform:docs/migrations/query-scheduling-exports/README.md#D7. Delivery: one e-mail per recipient with a secure link, through the communications module
proved by ATS-PFM-QRY-013-14, ATS-PFM-QRY-014-07, ATS-PFM-QRY-014-12, ATS-PFM-QRY-018-15, TST-PFM-QRY-108, TST-PFM-QRY-301
permissionservicetest
services-platform:modules/queries/tests/integration/services/exports/query-export-routes.integration.spec.js#answers 404 to a colleague who did not ask for it, even once the file exists
08must prove
Confirmed
Files remain for thirty days under their workspace and export identities, and download redirects last five minutes.
origin: services-platform:docs/migrations/query-scheduling-exports/README.md#D11. Storage: the Rhythm 1.0 bucket, under its protected prefix
proved by ATS-PFM-QRY-014-08, TST-PFM-QRY-109, TST-PFM-QRY-302
lifecycleservicetest
services-platform:modules/queries/tests/integration/services/exports/run-query-export.integration.spec.js#records the rows, the bytes, the completion and the expiry 30 days later
09must prove
Confirmed
Personal delivery links need no login, bind workspace, export, recipient and a seven-day expiry, require current recipient membership and an existing file, record downloads, and otherwise return an invalid-link page.
origin: services-platform:docs/migrations/query-scheduling-exports/README.md#D7. Delivery: one e-mail per recipient with a secure link, through the communications module
proved by ATS-PFM-QRY-014-09, ATS-PFM-QRY-014-13, ATS-PFM-QRY-015-20, TST-PFM-QRY-301, TST-PFM-QRY-395
policyservicetest
services-platform:modules/queries/tests/integration/services/exports/query-export-routes.integration.spec.js#answers the plain page for a recipient no longer on the schedule
10
Confirmed
Interactive and scheduled exports use separate queues and concurrency allocations.
origin: services-platform:docs/migrations/query-scheduling-exports/README.md#D10. One asynchronous path, which feels synchronous for small exports
policyservicedocumented
services-platform:docs/migrations/query-scheduling-exports/README.md#D10. One asynchronous path, which feels synchronous for small exports
11must prove
Confirmed
Exported references show their display values with identity columns only when selected, and an empty result still writes headings.
proved by ATS-PFM-QRY-014-10, TST-PFM-QRY-302
calculationservicetest
services-platform:modules/queries/tests/integration/services/exports/run-query-export.integration.spec.js#writes no id at all when the Spouse ID is not selected

Scenarios

IdGivenWhenThenProvenance
01A query export requests technical-name headings.The worker writes the result file.Headings retain the query’s output-column order.test
services-platform:modules/queries/tests/integration/services/exports/run-query-export.integration.spec.js#heads the file with the technical names in the query’s output order

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software