---
id: WF-PFM-QRY-009
title: Publish a custom query table version
trigger: A staff author saves custom-table SQL and a permitted publisher requests its release.
product_area: platform
module: queries
revision: 1
status: draft
design_intent: confirmed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
inference: []
implements:
  - CAP-PFM-QRY-005
moves:
  - STATE-PFM-QRY-001
crosses:
  - SVC-PFM-QRY-queries
idempotency: >-
  Analysis of the same SQL can produce the same canonical content, but saving is still a versioned
  write. Repeating an already committed publication with its old version conflicts.
concurrency: >-
  Definition locks and read versions coordinate draft, publication and assignment changes.
  Cross-workspace dependency inspection is limited to identifying affected saved queries.
hops:
  - 'n': 1
    actor_or_service: Staff author (HQ console)
    action: 'Save authored SQL, reviewed columns and defaults with the version previously read.'
    anchor: 'services-platform:modules/queries/services/custom-tables/custom-table-library.ts:saveDraft'
    seam: sync
    on_failure: Return a conflict when the version has changed.
    left_inconsistent: A refused stale save does not replace the draft.
    observer: the author
    provenance: observed
    source: 'services-platform:modules/queries/services/custom-tables/custom-table-library.ts'
  - 'n': 2
    actor_or_service: Custom table analyzer
    action: >-
      Parse SQL with PostgreSQL grammar, reject disallowed constructs and sources, derive canonical
      SQL and fingerprint, and analyze in the validation workspace.
    anchor: >-
      services-platform:modules/queries/services/custom-tables/analyze-custom-table.ts:analyzeCustomTable
    seam: sync
    on_failure: Keep structured analysis problems; missing validation configuration refuses the operation.
    left_inconsistent: A draft without passing matching analysis cannot be published.
    observer: the author (every problem at once)
    provenance: observed
    source: 'services-platform:modules/queries/services/custom-tables/analyze-sql.ts'
  - 'n': 3
    actor_or_service: Preview
    action: >-
      Preview the chosen version in the configured validation workspace and return release-check
      information.
    anchor: >-
      services-platform:modules/queries/services/custom-tables/preview-custom-table.ts:previewCustomTable
    seam: sync
    on_failure: Refuse an unavailable validation workspace or unsupported customer-workspace preview.
    left_inconsistent: Only preview history can be retained; no publication is implied.
    observer: the author
    provenance: observed
    source: 'services-platform:modules/queries/services/custom-tables/validation-tenant.ts'
  - 'n': 4
    actor_or_service: Publisher
    action: >-
      Compare released and proposed output shape, identify breaking changes and enumerate
      saved-query dependants.
    anchor: 'services-platform:modules/queries/services/custom-tables/version-changes.ts'
    seam: sync
    on_failure: Refuse publication without the required dependency acknowledgements.
    left_inconsistent: The existing released version remains selected.
    observer: the publisher
    provenance: observed
    source: 'services-platform:modules/queries/services/custom-tables/custom-table-library.ts:publish'
  - 'n': 5
    actor_or_service: Publisher
    action: >-
      Verify matching analysis and non-null unique record identity, then promote the draft,
      supersede the old version, create another draft and record release history.
    anchor: >-
      services-platform:modules/queries/services/persistence/custom-query-tables.ts:publishCustomTableDraft
    seam: sync
    on_failure: Refuse failed checks or roll back the publication transaction.
    left_inconsistent: No partial publication is committed by that transaction.
    observer: the publisher; history
    provenance: observed
    source: 'services-platform:modules/queries/services/persistence/custom-query-tables.ts'
  - 'n': 6
    actor_or_service: Assigner
    action: >-
      Apply inclusion, exclusion or released-version pin assignments with version checks and
      description-stamp updates.
    anchor: 'services-platform:modules/queries/services/custom-tables/custom-table-library.ts:assign'
    seam: sync
    on_failure: Refuse stale assignment writes.
    left_inconsistent: A successful assignment can change which workspaces resolve the dataset.
    observer: history; workspace dataset catalogs
    provenance: observed
    source: 'services-platform:modules/queries/services/custom-tables/assignment-visibility.ts'
branches:
  - Removing an assignment can make dependent saved questions stop resolving.
  - Definition availability changes are separate lifecycle operations.
waits: []
evidence:
  - >-
    services-platform at ad3f6a6: modules/queries/services/custom-tables/*.ts;
    services/persistence/custom-query-tables.ts; aws/api/custom-tables.routes.ts;
    docs/queries/custom-query-tables/rhythm-custom-query-tables-architecture.md (phase 1 accepted
    2026-10-12)
  - 'react-console at baf6dae: app/(console)/hq/customQueryTables/**; lib/api/custom-query-tables.ts'
controls: [TC-AVL-001, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Publish a custom query table version

## What It Does

A staff author saves custom-table SQL and a permitted publisher requests its release. Removing an assignment can make dependent saved questions stop resolving.

## The Flow

```mermaid
sequenceDiagram
  participant C as Request or schedule
  participant H0 as Staff author HQ console
  participant H1 as Custom table analyzer
  participant H2 as Preview
  participant H3 as Publisher
  participant H4 as Publisher
  participant H5 as Assigner
  C->>H0: Save authored SQL, reviewed columns and defaults with the version previously read
  H0->>H1: Parse SQL with PostgreSQL grammar, reject disallowed constructs and sources, derive canonical SQL an
  opt Optional preview
    C->>H2: Preview the chosen version in the configured validation workspace and return release-check informati
  end
  H2->>H3: Compare released and proposed output shape, identify breaking changes and enumerate saved-query depe
  H3->>H4: Verify matching analysis and non-null unique record identity, then promote the draft, supersede the 
  opt Separate assignment action
    C->>H5: Apply inclusion, exclusion or released-version pin assignments with version checks and description-s
  end
```

Save authored SQL, reviewed columns and defaults with the version previously read. Parse SQL with PostgreSQL grammar, reject disallowed constructs and sources, derive canonical SQL and fingerprint, and analyze in the validation workspace. Preview the chosen version in the configured validation workspace and return release-check information. Compare released and proposed output shape, identify breaking changes and enumerate saved-query dependants. Verify matching analysis and non-null unique record identity, then promote the draft, supersede the old version, create another draft and record release history. Apply inclusion, exclusion or released-version pin assignments with version checks and description-stamp updates.

## When Something Fails

Return a conflict when the version has changed. A refused stale save does not replace the draft. Keep structured analysis problems; missing validation configuration refuses the operation. A draft without passing matching analysis cannot be published. Refuse an unavailable validation workspace or unsupported customer-workspace preview. Only preview history can be retained; no publication is implied. Refuse publication without the required dependency acknowledgements. The existing released version remains selected. Refuse failed checks or roll back the publication transaction. No partial publication is committed by that transaction. Refuse stale assignment writes. A successful assignment can change which workspaces resolve the dataset.

## Idempotency and Concurrency

Analysis of the same SQL can produce the same canonical content, but saving is still a versioned write. Repeating an already committed publication with its old version conflicts. Definition locks and read versions coordinate draft, publication and assignment changes. Cross-workspace dependency inspection is limited to identifying affected saved queries.