Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Align Postgres slow-query duration schemas with fractional responses

Abierto
  • ¿Algo no está bien?
#796 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
45/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
openapi, rust
Área
api, backend-api-design

Línea de trabajo

Comience en crates/clickhouse-cloud-api/clickhouse_cloud_openapi.json, revisando las operaciones slowQueryPatternsGetList y slowQueryPatternGet y el esquema PostgresSlowQueryPattern. Confirme el contrato numérico agregado con los responsables de Cloud API/OpenAPI y, a continuación, actualice los esquemas confirmados y añada ejemplos fraccionarios de lista y detalle para que las pruebas de los clientes generados cubran las respuestas desplegadas.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
Rust
Estrellas
80
Forks
9
Merge medio
4 d 13 h
PR fusionados (30 d)
59

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de ClickHouse/clickhousectl

Todos los issues de ClickHouse/clickhousectl

Issues similares

Más issues de Rust

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.