Skip to content

OpenAPI drift: 61 gaps between live spec and library #203

Open
#205
Open
OpenAPI drift: 61 gaps between live spec and library#203
#205
Assignees
sdairs
Labels
openapi-driftAutomated: live OpenAPI spec has operations/schemas not covered by the Rust library
@github-actions

Description

@github-actions
github-actions
bot
opened on May 21, 2026

The live ClickHouse Cloud OpenAPI spec has operations or schemas that the
Rust library (client.rs / models.rs) does not cover yet.

  • Live spec: https://api.clickhouse.cloud/v1
  • Client: crates/clickhouse-cloud-api/src/client.rs
  • Models: crates/clickhouse-cloud-api/src/models.rs
  • Beta metadata: crates/clickhouse-cloud-api/src/meta.rs

Summary

Change Count
Missing client methods 3
Extra client methods (not in spec) 0
Missing model types 18
Missing struct fields 19
Field optionality mismatches 0
Beta status changes 0
Stale snapshot changes 21

Missing Client Methods

The live spec has these operations but client.rs has no matching pub async fn.

upgrade_window_delete

DELETE /v1/organizations/{organizationId}/services/{serviceId}/upgradeWindow

Delete service upgrade window

Operation spec JSON 
{
  "summary": "Delete service upgrade window",
  "description": "Deletes the upgrade window for a service, restoring the default scheduling behaviour. The upgrade window can only be deleted on primary services. Deletion succeeds even if the organization has lost the scheduled upgrades entitlement, so a window can be cleared after entitlement loss.\n\nErrors:\n- 400: the service is a secondary service.\n- 401: missing, invalid, or disabled API key.\n- 403: caller lacks `control-plane:service:manage` on the service.\n- 404: service does not exist, is not visible to the caller, or no upgrade window is configured.",
  "operationId": "upgradeWindowDelete",
  "parameters": [
    {
      "in": "path",
      "name": "organizationId",
      "description": "ID of the organization that owns the service.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "path",
      "name": "serviceId",
      "description": "ID of the service.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "number",
                "description": "HTTP status code.",
                "example": 200
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "number",
                "description": "HTTP status code.",
                "example": 400
              },
              "error": {
                "type": "string",
                "description": "Detailed error description."
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer",
                "description": "HTTP status code.",
                "example": 500
              },
              "error": {
                "type": "string",
                "description": "Detailed error description."
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    "Service"
  ]
}

upgrade_window_get

GET /v1/organizations/{organizationId}/services/{serviceId}/upgradeWindow

Get service upgrade window

References missing types: UpgradeWindow

Operation spec JSON 
{
  "summary": "Get service upgrade window",
  "description": "Returns the configured upgrade window for a service.\n\nErrors:\n- 401: missing, invalid, or disabled API key.\n- 403: caller lacks `control-plane:service:view` on the service.\n- 404: service does not exist, is not visible to the caller, or no upgrade window has been configured.",
  "operationId": "upgradeWindowGet",
  "parameters": [
    {
      "in": "path",
      "name": "organizationId",
      "description": "ID of the organization that owns the service.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "path",
      "name": "serviceId",
      "description": "ID of the service.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "number",
                "description": "HTTP status code.",
                "example": 200
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              },
              "result": {
                "$ref": "#/components/schemas/UpgradeWindow"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "number",
                "description": "HTTP status code.",
                "example": 400
              },
              "error": {
                "type": "string",
                "description": "Detailed error description."
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer",
                "description": "HTTP status code.",
                "example": 500
              },
              "error": {
                "type": "string",
                "description": "Detailed error description."
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    "Service"
  ]
}

upgrade_window_update

PUT /v1/organizations/{organizationId}/services/{serviceId}/upgradeWindow

Set service upgrade window

References missing types: UpgradeWindow, UpgradeWindowPutRequest

Operation spec JSON 
{
  "summary": "Set service upgrade window",
  "description": "Creates or fully replaces the upgrade window for a service. The upgrade window currently lasts 6 hours from `startHourUtc`. The upgrade window can only be set on primary services; secondary services inherit the primary service window.\n\nErrors:\n- 400: invalid field values (`weekday` not in 0\u20136, `startHourUtc` not in {0, 6, 12, 18}), or the service is a secondary service.\n- 401: missing, invalid, or disabled API key.\n- 403: caller lacks `control-plane:service:manage` on the service, or the organization does not have the scheduled upgrades feature enabled.\n- 404: service does not exist or is not visible to the caller.",
  "operationId": "upgradeWindowUpdate",
  "parameters": [
    {
      "in": "path",
      "name": "organizationId",
      "description": "ID of the organization that owns the service.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "path",
      "name": "serviceId",
      "description": "ID of the service.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpgradeWindowPutRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "number",
                "description": "HTTP status code.",
                "example": 200
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              },
              "result": {
                "$ref": "#/components/schemas/UpgradeWindow"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "number",
                "description": "HTTP status code.",
                "example": 400
              },
              "error": {
                "type": "string",
                "description": "Detailed error description."
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer",
                "description": "HTTP status code.",
                "example": 500
              },
              "error": {
                "type": "string",
                "description": "Detailed error description."
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    "Service"
  ]
}

Missing Model Types

The live spec defines these schemas but models.rs has no matching
pub struct, pub enum, or pub type.

ClickPipePatchPubSubSource (spec name: ClickPipePatchPubSubSource)

Schema JSON 
{
  "properties": {
    "authentication": {
      "description": "Authentication method to use with GCP Pub/Sub. Currently only SERVICE_ACCOUNT is supported.",
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "SERVICE_ACCOUNT"
      ],
      "example": "SERVICE_ACCOUNT"
    },
    "ackDeadline": {
      "description": "Acknowledgement deadline for messages, in seconds. Must be between 10 and 600.",
      "type": [
        "integer",
        "null"
      ],
      "minimum": 10,
      "maximum": 600
    },
    "serviceAccountKey": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/ServiceAccount"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "authentication",
    "serviceAccountKey"
  ]
}

ClickPipePostPubSubSource (spec name: ClickPipePostPubSubSource)

Schema JSON 
{
  "properties": {
    "format": {
      "description": "Format of messages in the Pub/Sub topic. GCP Pub/Sub ClickPipes are in limited preview \u2014 contact support to enable this feature for your organization.",
      "type": "string",
      "enum": [
        "JSONEachRow",
        "Avro",
        "Protobuf"
      ],
      "example": "JSONEachRow"
    },
    "projectId": {
      "description": "GCP project ID that owns the Pub/Sub topic.",
      "type": "string",
      "example": "my-gcp-project"
    },
    "topic": {
      "description": "Pub/Sub topic name (not the fully-qualified path).",
      "type": "string",
      "example": "my-topic"
    },
    "authentication": {
      "description": "Authentication method to use with GCP Pub/Sub. Currently only SERVICE_ACCOUNT is supported.",
      "type": "string",
      "enum": [
        "SERVICE_ACCOUNT"
      ],
      "example": "SERVICE_ACCOUNT"
    },
    "seekType": {
      "description": "Starting position strategy for consuming the subscription. Companion fields (seekTimestamp, seekSnapshot) are required only when matching the seek type; setting a companion for a mismatched seek type is rejected.",
      "type": "string",
      "enum": [
        "latest",
        "earliest",
        "timestamp",
        "snapshot"
      ],
      "example": "earliest"
    },
    "seekTimestamp": {
      "description": "RFC 3339 / ISO 8601 timestamp to seek to. Required when seekType is \"timestamp\"; must be omitted otherwise.",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-04-10T12:00:00Z"
    },
    "seekSnapshot": {
      "description": "Pub/Sub snapshot identifier to seek to. Required when seekType is \"snapshot\"; must be omitted otherwise.",
      "type": [
        "string",
        "null"
      ]
    },
    "filter": {
      "description": "Optional Pub/Sub subscription filter expression (CEL). Maximum 256 characters.",
      "type": [
        "string",
        "null"
      ],
      "maxLength": 256
    },
    "enableOrdering": {
      "description": "Whether to enable ordered delivery of messages (requires messages to be published with ordering keys).",
      "type": [
        "boolean",
        "null"
      ]
    },
    "ackDeadline": {
      "description": "Acknowledgement deadline for messages, in seconds. Must be between 10 and 600.",
      "type": [
        "integer",
        "null"
      ],
      "minimum": 10,
      "maximum": 600
    },
    "serviceAccountKey": {
      "$ref": "#/components/schemas/ServiceAccount"
    }
  },
  "required": [
    "format",
    "projectId",
    "topic",
    "authentication",
    "seekType",
    "serviceAccountKey"
  ]
}

ClickPipePubSubSource (spec name: ClickPipePubSubSource)

Schema JSON 
{
  "properties": {
    "format": {
      "description": "Format of messages in the Pub/Sub topic. GCP Pub/Sub ClickPipes are in limited preview \u2014 contact support to enable this feature for your organization.",
      "type": "string",
      "enum": [
        "JSONEachRow",
        "Avro",
        "Protobuf"
      ],
      "example": "JSONEachRow"
    },
    "projectId": {
      "description": "GCP project ID that owns the Pub/Sub topic.",
      "type": "string",
      "example": "my-gcp-project"
    },
    "topic": {
      "description": "Pub/Sub topic name (not the fully-qualified path).",
      "type": "string",
      "example": "my-topic"
    },
    "authentication": {
      "description": "Authentication method to use with GCP Pub/Sub. Currently only SERVICE_ACCOUNT is supported.",
      "type": "string",
      "enum": [
        "SERVICE_ACCOUNT"
      ],
      "example": "SERVICE_ACCOUNT"
    },
    "seekType": {
      "description": "Starting position strategy for consuming the subscription. Companion fields (seekTimestamp, seekSnapshot) are required only when matching the seek type; setting a companion for a mismatched seek type is rejected.",
      "type": "string",
      "enum": [
        "latest",
        "earliest",
        "timestamp",
        "snapshot"
      ],
      "example": "earliest"
    },
    "seekTimestamp": {
      "description": "RFC 3339 / ISO 8601 timestamp to seek to. Required when seekType is \"timestamp\"; must be omitted otherwise.",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "example": "2026-04-10T12:00:00Z"
    },
    "seekSnapshot": {
      "description": "Pub/Sub snapshot identifier to seek to. Required when seekType is \"snapshot\"; must be omitted otherwise.",
      "type": [
        "string",
        "null"
      ]
    },
    "filter": {
      "description": "Optional Pub/Sub subscription filter expression (CEL). Maximum 256 characters.",
      "type": [
        "string",
        "null"
      ],
      "maxLength": 256
    },
    "enableOrdering": {
      "description": "Whether to enable ordered delivery of messages (requires messages to be published with ordering keys).",
      "type": [
        "boolean",
        "null"
      ]
    },
    "ackDeadline": {
      "description": "Acknowledgement deadline for messages, in seconds. Must be between 10 and 600.",
      "type": [
        "integer",
        "null"
      ],
      "minimum": 10,
      "maximum": 600
    }
  },
  "required": [
    "format",
    "projectId",
    "topic",
    "authentication",
    "seekType"
  ]
}

ClickStackDashboardContainer (spec name: ClickStackDashboardContainer)

Schema JSON 
{
  "properties": {
    "id": {
      "description": "Unique identifier for the container within the dashboard.",
      "type": "string",
      "example": "service-health"
    },
    "title": {
      "description": "Display title for the container.",
      "type": "string",
      "example": "Service Health"
    },
    "collapsed": {
      "description": "Persisted default collapse state. Per-viewer state lives in the URL.",
      "type": "boolean",
      "example": false
    },
    "collapsible": {
      "description": "Whether the user can collapse the group.",
      "type": "boolean",
      "example": true
    },
    "bordered": {
      "description": "Whether to show a visual border around the group.",
      "type": "boolean",
      "example": true
    },
    "tabs": {
      "type": "array",
      "description": "Optional tabs. 2+ entries renders a tab bar; 0-1 entries renders a plain group header. Tiles join a tab via tabId.",
      "items": {
        "$ref": "#/components/schemas/ClickStackDashboardContainerTab"
      }
    }
  },
  "required": [
    "id",
    "title",
    "collapsed"
  ]
}

ClickStackDashboardContainerTab (spec name: ClickStackDashboardContainerTab)

Schema JSON 
{
  "properties": {
    "id": {
      "description": "Unique identifier for the tab within its container.",
      "type": "string",
      "example": "errors"
    },
    "title": {
      "description": "Display title for the tab.",
      "type": "string",
      "example": "Errors"
    }
  },
  "required": [
    "id",
    "title"
  ]
}

ClickStackHeatmapChartConfig (spec name: ClickStackHeatmapChartConfig)

Schema JSON 
{
  "properties": {
    "displayType": {
      "description": "Display type discriminator. Must be \"heatmap\" for heatmap tiles.",
      "type": "string",
      "enum": [
        "heatmap"
      ],
      "example": "heatmap"
    },
    "sourceId": {
      "description": "ID of the data source to query.",
      "type": "string",
      "example": "65f5e4a3b9e77c001a111111"
    },
    "select": {
      "type": "array",
      "description": "Exactly one heatmap select item.",
      "items": {
        "$ref": "#/components/schemas/ClickStackHeatmapSelectItem"
      }
    },
    "where": {
      "description": "Row-level filter (syntax depends on whereLanguage).",
      "type": "string",
      "example": "ServiceName = 'api'"
    },
    "whereLanguage": {
      "description": "Query language for the where clause.",
      "type": "string",
      "enum": [
        "sql",
        "lucene"
      ]
    },
    "numberFormat": {
      "$ref": "#/components/schemas/ClickStackNumberFormat"
    }
  },
  "required": [
    "displayType",
    "sourceId",
    "select"
  ]
}

ClickStackHeatmapSelectItem (spec name: ClickStackHeatmapSelectItem)

Schema JSON 
{
  "properties": {
    "valueExpression": {
      "description": "SQL expression for the value being bucketed on the y-axis. Must be non-empty.",
      "type": "string",
      "example": "Duration"
    },
    "countExpression": {
      "description": "SQL expression for the count contributing to each bucket. Defaults to \"count()\" in the editor when omitted.",
      "type": "string",
      "example": "count()"
    },
    "heatmapScaleType": {
      "description": "Scale type used to bucket values on the y-axis.",
      "type": "string",
      "enum": [
        "log",
        "linear"
      ],
      "example": "log"
    }
  },
  "required": [
    "valueExpression"
  ]
}

ClickStackLogSourceMetadataMaterializedViews (spec name: ClickStackLogSourceMetadataMaterializedViews)

Schema JSON 
{
  "properties": {
    "keyRollupTable": {
      "description": "ClickHouse table name for the key rollup (field discovery).",
      "type": "string",
      "example": "otel_logs_key_rollup_15m"
    },
    "kvRollupTable": {
      "description": "ClickHouse table name for the key-value rollup (value autocomplete).",
      "type": "string",
      "example": "otel_logs_kv_rollup_15m"
    },
    "granularity": {
      "description": "The time granularity of the rollup tables.",
      "type": "string",
      "example": "15m"
    }
  }
}

ClickStackOnClick (spec name: ClickStackOnClick)

Schema JSON 
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/ClickStackOnClickSearch"
    },
    {
      "$ref": "#/components/schemas/ClickStackOnClickDashboard"
    }
  ]
}

ClickStackOnClickDashboard (spec name: ClickStackOnClickDashboard)

Schema JSON 
{
  "properties": {
    "type": {
      "description": "OnClick variant discriminator. Must be \"dashboard\" for dashboard link-outs.",
      "type": "string",
      "enum": [
        "dashboard"
      ],
      "example": "dashboard"
    },
    "target": {
      "$ref": "#/components/schemas/ClickStackOnClickTarget"
    },
    "whereTemplate": {
      "description": "Optional WHERE clause template applied to the destination dashboard.",
      "type": "string",
      "example": "ServiceName = '{{ServiceName}}'"
    },
    "whereLanguage": {
      "description": "Language of the rendered whereTemplate.",
      "type": "string",
      "enum": [
        "sql",
        "lucene"
      ]
    },
    "filters": {
      "type": "array",
      "description": "Optional dashboard filter templates rendered against the clicked row.",
      "items": {
        "$ref": "#/components/schemas/ClickStackOnClickFilterTemplate"
      }
    }
  },
  "required": [
    "type",
    "target"
  ]
}

ClickStackOnClickFilterTemplate (spec name: ClickStackOnClickFilterTemplate)

Schema JSON 
{
  "properties": {
    "kind": {
      "description": "Filter template kind. Currently only \"expressionTemplate\" is supported.",
      "type": "string",
      "enum": [
        "expressionTemplate"
      ],
      "example": "expressionTemplate"
    },
    "expression": {
      "description": "The column/expression to filter the destination by (e.g. \"ServiceName\").",
      "type": "string",
      "example": "ServiceName"
    },
    "template": {
      "description": "Value template rendered against the clicked row; supports row column variables in `{{column}}` form (e.g. `{{ServiceName}}`).",
      "type": "string",
      "example": "{{ServiceName}}"
    }
  },
  "required": [
    "kind",
    "expression",
    "template"
  ]
}

ClickStackOnClickSearch (spec name: ClickStackOnClickSearch)

Schema JSON 
{
  "properties": {
    "type": {
      "description": "OnClick variant discriminator. Must be \"search\" for search link-outs.",
      "type": "string",
      "enum": [
        "search"
      ],
      "example": "search"
    },
    "target": {
      "$ref": "#/components/schemas/ClickStackOnClickTarget"
    },
    "whereTemplate": {
      "description": "Optional WHERE clause template applied to the destination search.",
      "type": "string",
      "example": "ServiceName = '{{ServiceName}}'"
    },
    "whereLanguage": {
      "description": "Language of the rendered whereTemplate.",
      "type": "string",
      "enum": [
        "sql",
        "lucene"
      ]
    },
    "filters": {
      "type": "array",
      "description": "Optional dashboard filter templates rendered against the clicked row.",
      "items": {
        "$ref": "#/components/schemas/ClickStackOnClickFilterTemplate"
      }
    }
  },
  "required": [
    "type",
    "target"
  ]
}

ClickStackOnClickTarget (spec name: ClickStackOnClickTarget)

Schema JSON 
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/ClickStackOnClickTargetIdVariant"
    },
    {
      "$ref": "#/components/schemas/ClickStackOnClickTargetTemplateVariant"
    }
  ]
}

ClickStackOnClickTargetIdVariant (spec name: ClickStackOnClickTargetIdVariant)

Schema JSON 
{
  "properties": {
    "mode": {
      "description": "Target is a single dashboard or log/trace source",
      "type": "string",
      "enum": [
        "id"
      ],
      "example": "id"
    },
    "id": {
      "description": "ID of the target source (for search) or dashboard (for dashboard).",
      "type": "string",
      "example": "65f5e4a3b9e77c001a567890"
    }
  },
  "required": [
    "mode",
    "id"
  ]
}

ClickStackOnClickTargetTemplateVariant (spec name: ClickStackOnClickTargetTemplateVariant)

Schema JSON 
{
  "properties": {
    "mode": {
      "description": "Target is matched by name against the template.",
      "type": "string",
      "enum": [
        "template"
      ],
      "example": "template"
    },
    "template": {
      "description": "Name template rendered against the clicked row; supports `{{column}}` variables.",
      "type": "string",
      "example": "{{ServiceName}}"
    }
  },
  "required": [
    "mode",
    "template"
  ]
}

ClickStackTraceSourceMetadataMaterializedViews (spec name: ClickStackTraceSourceMetadataMaterializedViews)

Schema JSON 
{
  "properties": {
    "keyRollupTable": {
      "description": "ClickHouse table name for the key rollup (field discovery).",
      "type": "string",
      "example": "otel_traces_key_rollup_15m"
    },
    "kvRollupTable": {
      "description": "ClickHouse table name for the key-value rollup (value autocomplete).",
      "type": "string",
      "example": "otel_traces_kv_rollup_15m"
    },
    "granularity": {
      "description": "The time granularity of the rollup tables.",
      "type": "string",
      "example": "15m"
    }
  }
}

UpgradeWindow (spec name: UpgradeWindow)

Schema JSON 
{
  "properties": {
    "weekday": {
      "description": "Day of the week the upgrade window starts. 0 = Sunday, 1 = Monday, \u2026, 6 = Saturday.",
      "type": "integer",
      "minimum": 0,
      "maximum": 6,
      "example": 3
    },
    "startHourUtc": {
      "description": "UTC hour when the upgrade window starts. Must be one of 0, 6, 12, or 18.",
      "type": "integer",
      "enum": [
        0,
        6,
        12,
        18
      ],
      "example": 12
    },
    "duration": {
      "description": "Length of the upgrade window in hours. Currently only a 6-hour window is supported.",
      "type": "integer",
      "enum": [
        6
      ],
      "example": 6
    }
  },
  "required": [
    "weekday",
    "startHourUtc",
    "duration"
  ]
}

UpgradeWindowPutRequest (spec name: UpgradeWindowPutRequest)

Schema JSON 
{
  "properties": {
    "weekday": {
      "description": "Day of the week the upgrade window starts. 0 = Sunday, 1 = Monday, \u2026, 6 = Saturday.",
      "type": "integer",
      "minimum": 0,
      "maximum": 6,
      "example": 3
    },
    "startHourUtc": {
      "description": "UTC hour when the upgrade window starts. Must be one of 0, 6, 12, or 18. The upgrade window currently lasts 6 hours from this start time.",
      "type": "integer",
      "enum": [
        0,
        6,
        12,
        18
      ],
      "example": 12
    }
  },
  "required": [
    "weekday",
    "startHourUtc"
  ]
}

Missing Struct Fields

These properties exist in the OpenAPI spec but have no corresponding
field in the Rust struct. API response data for these fields is silently
dropped during deserialization.

Schema Field
ClickPipePatchSource pubsub
ClickPipePostSource pubsub
ClickPipeSource pubsub
ClickStackAlertResponse note
ClickStackCreateAlertRequest note
ClickStackCreateDashboardRequest containers
ClickStackDashboardResponse containers
ClickStackLogSource metadataMaterializedViews
ClickStackSelectItem numberFormat
ClickStackTableBuilderChartConfig groupByColumnsOnLeft
ClickStackTableBuilderChartConfig onClick
ClickStackTableRawSqlChartConfig onClick
ClickStackTileInput containerId
ClickStackTileInput tabId
ClickStackTileOutput containerId
ClickStackTileOutput tabId
ClickStackTraceSource metadataMaterializedViews
ClickStackUpdateAlertRequest note
ClickStackUpdateDashboardRequest containers

Stale Snapshot

The committed clickhouse_cloud_openapi.json is behind the live spec.
Tests that run against the snapshot may pass even though the library is
missing coverage for new endpoints or schemas.

New operations in live spec (not in snapshot):

  • upgrade_window_delete
  • upgrade_window_get
  • upgrade_window_update

New schemas in live spec (not in snapshot):

  • ClickPipePatchPubSubSource
  • ClickPipePostPubSubSource
  • ClickPipePubSubSource
  • ClickStackDashboardContainer
  • ClickStackDashboardContainerTab
  • ClickStackHeatmapChartConfig
  • ClickStackHeatmapSelectItem
  • ClickStackLogSourceMetadataMaterializedViews
  • ClickStackOnClick
  • ClickStackOnClickDashboard
  • ClickStackOnClickFilterTemplate
  • ClickStackOnClickSearch
  • ClickStackOnClickTarget
  • ClickStackOnClickTargetIdVariant
  • ClickStackOnClickTargetTemplateVariant
  • ClickStackTraceSourceMetadataMaterializedViews
  • UpgradeWindow
  • UpgradeWindowPutRequest

Implementation Guide

  1. Update the checked-in spec: 
    curl -s https://api.clickhouse.cloud/v1 -o crates/clickhouse-cloud-api/clickhouse_cloud_openapi.json
  2. Add missing types to crates/clickhouse-cloud-api/src/models.rs
    • Use #[serde(rename_all = "camelCase")] on structs
    • Use #[serde(skip_serializing_if = "Option::is_none")] for optional fields
    • Enums should derive Default and include an #[serde(other)] Unknown variant
  3. Add missing methods to crates/clickhouse-cloud-api/src/client.rs
  4. Fix field optionality: 
    python scripts/update-models-optionality.py
  5. Verify: cargo test -p clickhouse-cloud-api

Metadata

Metadata

Assignees

Labels

openapi-driftAutomated: live OpenAPI spec has operations/schemas not covered by the Rust library

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions