---
id: WF-PFM-QRY-003
title: Keep cached dataset descriptions current
trigger: >-
  A description-affecting table changes and a later query or description request resolves that
  metadata.
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-001
  - CAP-PFM-QRY-002
crosses:
  - SVC-PFM-QRY-queries
idempotency: >-
  Stamp sequence values are not reused after rollback. Writing identical cache content under one key
  is harmless, but a stable key does not prove snapshot-consistent resolution.
concurrency: >-
  Stamps and metadata are read separately. No common database snapshot or final stamp recheck
  ensures that concurrent metadata writes yield an internally consistent cached description.
hops:
  - 'n': 1
    actor_or_service: Any writer (Platform or another service)
    action: >-
      The writing transaction’s table trigger advances the affected workspace stamps or the global
      stamp.
    anchor: >-
      services-platform:modules/queries/db/query-description-stamps.table.ts:platform.bump_query_description_stamp
    seam: sync
    on_failure: Trigger failure rolls back its transaction.
    left_inconsistent: The stamp cannot commit independently of that write.
    observer: >-
      the stamp-coverage integration test fails the build for a description table without the
      trigger
    provenance: observed
    source: 'services-platform:modules/queries/db/query-description-stamps.table.ts'
  - 'n': 2
    actor_or_service: Query model resolution
    action: 'Read workspace and global stamps, construct the key, then check memory and the shared cache.'
    anchor: 'services-platform:modules/queries/services/describe/resolve-query-model.ts:resolveQueryModel'
    seam: sync
    on_failure: A failing cache read is handled as a miss.
    left_inconsistent: The request can proceed through metadata resolution instead of failing on cache availability.
    observer: a single warn line per container when the shared store fails
    provenance: observed
    source: 'services-platform:modules/queries/services/describe/description-cache.ts'
  - 'n': 3
    actor_or_service: Query model resolution
    action: >-
      On a miss, resolve registry and workspace configuration and cache the result under the key
      already read. Old entries expire rather than receiving invalidation messages.
    anchor: 'services-platform:modules/queries/services/describe/description-reads.ts'
    seam: sync
    on_failure: A cache-store error does not prevent returning the resolved result.
    left_inconsistent: Concurrent metadata changes can span these reads; the recorded consistency gap remains.
    observer: debug lines naming the layer that answered
    provenance: observed
    source: 'services-platform:modules/queries/services/describe/valkey-description-cache.ts'
branches:
  - Person-specific authorization is applied after reading reusable workspace metadata.
waits: []
evidence:
  - >-
    services-platform at ad3f6a6: modules/queries/db/query-description-stamps.table.ts;
    services/describe/description-cache.ts, valkey-description-cache.ts, resolve-query-model.ts;
    aws/resources/query-description-cache.elasticache.ts; docs/queries/semantic-query-layer.md (The
    description cache)
controls: [TC-AVL-001, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, 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]
---

# Keep cached dataset descriptions current

## What It Does

A description-affecting table changes and a later query or description request resolves that metadata. Person-specific authorization is applied after reading reusable workspace metadata.

## The Flow

```mermaid
sequenceDiagram
  participant C as Request or schedule
  participant H0 as Any writer Platform or another service
  participant H1 as Query model resolution
  participant H2 as Query model resolution
  C->>H0: The writing transaction’s table trigger advances the affected workspace stamps or the global stamp
  H0->>H1: Read workspace and global stamps, construct the key, then check memory and the shared cache
  H1->>H2: On a miss, resolve registry and workspace configuration and cache the result under the key already r
```

The writing transaction’s table trigger advances the affected workspace stamps or the global stamp. Read workspace and global stamps, construct the key, then check memory and the shared cache. On a miss, resolve registry and workspace configuration and cache the result under the key already read. Old entries expire rather than receiving invalidation messages.

## When Something Fails

Trigger failure rolls back its transaction. The stamp cannot commit independently of that write. A failing cache read is handled as a miss. The request can proceed through metadata resolution instead of failing on cache availability. A cache-store error does not prevent returning the resolved result. Concurrent metadata changes can span these reads; the recorded consistency gap remains.

## Idempotency and Concurrency

Stamp sequence values are not reused after rollback. Writing identical cache content under one key is harmless, but a stable key does not prove snapshot-consistent resolution. Stamps and metadata are read separately. No common database snapshot or final stamp recheck ensures that concurrent metadata writes yield an internally consistent cached description.