Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Align Postgres slow-query duration schemas with fractional responses

Aperta
  • Qualcosa non va?
#796 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
45/100
Tipo di issue
Bug
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
openapi, rust
Ambito
api, backend-api-design

Direzione di ricerca

Iniziare da crates/clickhouse-cloud-api/clickhouse_cloud_openapi.json, esaminando le operazioni slowQueryPatternsGetList e slowQueryPatternGet e lo schema PostgresSlowQueryPattern. Confermare il contratto numerico aggregato con i responsabili di Cloud API/OpenAPI, quindi aggiornare gli schemi confermati e aggiungere esempi frazionari per elenco e dettaglio, in modo che i test dei client generati coprano le risposte distribuite.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

blocked bug cloud

Blocked on upstream — 2026-09-18

The owner confirmed this needs an upstream API/team change or authoritative contract and has raised the group with the team. Apply/retain the blocked label. This is outside the current CLI implementation queue.

Clear next step: Confirm the duration/percentile numeric contract and correct OpenAPI integer/number schemas with representative fractional responses. Client tolerance is already implemented; do not replace it with stricter integer parsing.

Keep this issue open. Add the upstream ticket or owner response when available; neither a ticket ID nor an individual assignee has been supplied in this discussion. After the upstream answer/fix, revalidate and scope any required library/CLI follow-up. Do not treat a local workaround or previous partial fix as completion of the backend issue.

Earlier scope and evidence (preserved)

Focused scope — 2026-09-15

Deferred until the direction below is resolved.

Keep the upstream schema issue; the client already tolerates recorded fractions.

Acceptance criteria

API owners confirm percentile/aggregate numeric types, correct schemas and add representative fractional examples.

Direction needed

Requires upstream numeric-contract confirmation/schema correction.

The focused scope above supersedes implementation suggestions and prior pass-specific deferrals below. Completed work and rejected assumptions remain recorded as history.

Original report and earlier audit history

OpenAPI declares Postgres slow-query aggregate durations as integers but the API returns fractions

Blocked on: Cloud API/OpenAPI owners confirming the aggregate numeric contract and correcting the response schemas. The client tolerance fix in #758 can proceed independently.

Problem

The deployed Postgres slow-query list and detail endpoints return fractional microsecond aggregate values. The current ClickHouse Cloud OpenAPI declares those fields as integers, so strict generated clients can reject successful HTTP 200 responses unless they add out-of-contract tolerance.

This is the upstream schema remainder from ClickHousectl #758. The CLI stack now preserves fractional values, but the public schema captured after that fix remains incompatible with live responses.

Snapshot under review: OpenAPI 3.1.2 retrieved 2026-09-08T19:50:35Z, SHA-256 c4811d18b26701aa61794b1d6ea1fa1b375493776bdac2c2033383849ba047d9. The repository snapshot at commit 4c17bc55d89108a0a73579b0655baf8189d97207 has the same SHA.

Affected operations and schema

  • GET /v1/organizations/{organizationId}/postgres/{postgresId}/slowQueryPatterns — slowQueryPatternsGetList (operation)
  • GET /v1/organizations/{organizationId}/postgres/{postgresId}/slowQueryPatterns/{queryId} — slowQueryPatternGet (operation); its aggregate reuses PostgresSlowQueryPattern (schema ref).

The exact observed pointers are:

  • #/components/schemas/PostgresSlowQueryPattern/properties/avgDurationUs
  • #/components/schemas/PostgresSlowQueryPattern/properties/p95DurationUs
  • #/components/schemas/PostgresSlowQueryPattern/properties/p99DurationUs

All remain type: integer in the latest snapshot (duration fields).

Direct HTTPS evidence

A fresh read-only direct HTTPS capture on 2026-09-08 at approximately 19:53Z returned HTTP 200. Query text and all service, organization, database, user, application, and query identifiers were excluded from the evidence.

The first list result contained:

{
  "avgDurationUs": 1210.2717391304348,
  "p95DurationUs": 1220.7,
  "p99DurationUs": 1859.259999999998
}

The detail result's aggregate contained:

{
  "avgDurationUs": 1207.566758747698,
  "p99DurationUs": 2439.639999999985
}

In those responses, totalDurationUs, maxDurationUs, and p50DurationUs happened to be integral. That does not prove they are always integral, but this issue should not assert that they are fractional without evidence.

Reproduction

The following read-only list request emits only numeric duration fields with a fractional part; it does not print SQL or identifiers. Use a window known to contain slow-query patterns, with exact-millisecond UTC timestamps accepted by the current endpoint.

export CLICKHOUSE_CLOUD_API='https://api.clickhouse.cloud/v1'
export CLICKHOUSE_CLOUD_API_KEY_ID='...'
export CLICKHOUSE_CLOUD_API_KEY_SECRET='...'
export ORG_ID='...'
export POSTGRES_ID='...'
export FROM_DATE='2026-09-08T16:30:00.000Z'
export TO_DATE='2026-09-08T17:35:00.000Z'

curl --fail-with-body --silent --show-error \
  --user "$CLICKHOUSE_CLOUD_API_KEY_ID:$CLICKHOUSE_CLOUD_API_KEY_SECRET" \
  --get \
  --data-urlencode "from_date=$FROM_DATE" \
  --data-urlencode "to_date=$TO_DATE" \
  --data-urlencode 'limit=1' \
  "$CLICKHOUSE_CLOUD_API/organizations/$ORG_ID/postgres/$POSTGRES_ID/slowQueryPatterns" \
  | jq '{status,fractions:[.result[0] | to_entries[] | select(.key|test("DurationUs$")) | select((.value|type)=="number") | select(.value != (.value|floor)) | {field:.key,value:.value}]}'

The detail endpoint can be checked without printing identifying fields by supplying the required lookup values as environment variables and filtering to aggregate:

export QUERY_ID='...'
export DB_NAME='...'
export DB_USER='...'
export DB_OPERATION='SELECT'

curl --fail-with-body --silent --show-error \
  --user "$CLICKHOUSE_CLOUD_API_KEY_ID:$CLICKHOUSE_CLOUD_API_KEY_SECRET" \
  --get \
  --data-urlencode "db_name=$DB_NAME" \
  --data-urlencode "db_user=$DB_USER" \
  --data-urlencode "db_operation=$DB_OPERATION" \
  "$CLICKHOUSE_CLOUD_API/organizations/$ORG_ID/postgres/$POSTGRES_ID/slowQueryPatterns/$QUERY_ID" \
  | jq '{status,fractions:[.result.aggregate | to_entries[] | select(.key|test("DurationUs$")) | select((.value|type)=="number") | select(.value != (.value|floor)) | {field:.key,value:.value}]}'

Both requests are read-only; no cleanup is required.

Expected resolution

  • Change the confirmed fractional aggregate fields avgDurationUs, p95DurationUs, and p99DurationUs from integer to number.
  • Confirm the calculation and serialization contract for p50DurationUs; update it too if fractional percentiles are possible.
  • Keep totalDurationUs and maxDurationUs integral if the service guarantees that contract.
  • Add representative fractional list and detail examples so generated-client tests exercise the deployed values.
Lingua principale
Rust
Stelle
80
Fork
9
Merge medio
4g 13h
PR unite (30g)
59

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di ClickHouse/clickhousectl

Tutte le issue di ClickHouse/clickhousectl

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.