Participant Query Store

The Participant Query Store (PQS) streams the ledger from the participant into a PostgreSQL database, so applications can query contract state with SQL instead of walking the Ledger API.

Use PQS when	Skip it when
Applications need to query current contract state by attribute, not just by contract ID.	Applications only stream transactions and maintain their own state.
You want reporting or analytics over ledger data.	You have no read-heavy consumers.
Read load would otherwise fall on the participant.	The extra database and workload are not worth the benefit.

PQS is a projection, not a source of truth. The participant's own database remains authoritative — PQS can be rebuilt from the ledger at any time.

Enabling it

Two things are needed on the Validator: the component, and a database for it.

spec:
  pqs:
    enabled: true
    version: "3.4.1"
    ledgerStart: Latest

  database:
    host: postgres.default.svc.cluster.local
    participantDb: participant_my_validator
    validatorDb: validator_my_validator
    pqsDatabase: pqs_my_validator
    pqsSchema: pqs
    credentialsSecretRef:
      name: my-validator-db-credentials

Field	Notes
pqs.enabled	Defaults to false.
pqs.version	Required when enabled. It does not fall back to spliceVersion — PQS is versioned independently of the Splice components.
pqs.ledgerStart	Where the pipeline begins reading. Defaults to Latest.
database.pqsDatabase	Required when enabled. The operator creates the database for you.
database.pqsSchema	Defaults to pqs.
pqs.resources, pqs.jvm	Optional overrides. Defaults are requests 500m / 1Gi, limits 3 / 2Gi, heap 512m–1536m.

ledgerStart: Latest means PQS begins from the current ledger end and does not backfill history. If you need historical contracts in the store, set the start point when you first enable PQS — changing it later requires rebuilding the store.

What gets created

Enabling PQS adds a sixth component to the validator: a pqs application with its own deployment and service, plus the PQS database and schema.

It appears as a PQS row on the validator's Summary tab and as an entry on the Applications list, with the same health, resource, and log surface as every other component. The validator's overall readiness includes it.

There is no PQS-specific screen in the UI — no query browser and no pipeline status view. PQS is monitored like any other component. Query the store directly with your own SQL tooling.

Connecting to it

The store is an ordinary PostgreSQL database. Connect with the credentials from the validator's database credentials secret, at the host, database, and schema you configured.

For the schema itself and the query patterns it supports, see Canton's Participant Query Store documentation.

Operating it

Sizing. PQS holds a projection of contract state, so its size tracks your active contract set and retention rather than the full transaction history. Start from the defaults and measure.

Backups. PQS can be rebuilt from the ledger, so it does not strictly need backing up — but rebuilding a large store takes time. Back it up if your recovery time matters more than the storage cost.

Restarts. PQS resumes from where it left off. A restart causes a lag in the projection, not data loss.

If PQS is not ready, the whole validator reports Degraded — its readiness is included in the validator's. A PQS pipeline problem will therefore show up as a validator-level alert. Check the PQS row on the Summary tab to distinguish it from a participant problem.

Extra environment variables. Unlike the participant, validator app, and UIs, PQS does not support spec.overrides environment variables. Configuration is limited to the fields above.