Confluent Materialized Table Versions (sql/v1) API

openapi: 3.2.0
info:
  title: Confluent Cloud Materialized Table Versions (sql/v1) API
  version: ''
  x-api-id: 46234552-5833-42eb-ba0f-883ad3f70d2b
  x-audience: external-public
  x-logo:
    url: https://assets.confluent.io/m/1661ef5e4ff82d3d/
  description: '# Introduction


    Note


    This documents the collection of Confluent Cloud APIs.'
servers:
- url: https://api.confluent.cloud
  description: Confluent Cloud API
tags:
- name: Materialized Table Versions (sql/v1)
  description: '![General Availability](#section/Versioning/API-Lifecycle-Policy)


    `MaterializedTableVersion` represents a specific version of a Materialized Table, capturing the state and changes at that point in time.

    The API allows you to list and read versions of your materialized tables.

    ## The Materialized Table Version Model'
paths:
  ? /sql/v1/organizations/{organization_id}/environments/{environment_id}/databases/{kafka_cluster_id}/materialized-tables/{table_name}/versions
  : servers:
    - url: https://flink.region.provider.confluent.cloud
      description: Flink Compute Pool Endpoint
    get:
      x-lifecycle-stage: General Availability
      x-self-access: true
      x-request-access-name: SQL API v1
      operationId: listSqlv1MaterializedTableVersions
      summary: List all the versions of a materialized table
      description: '![General Availability](#section/Versioning/API-Lifecycle-Policy)


        Retrieve a sorted and paginated list of all versions for a specific Materialized Table.'
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
          format: uuid
        description: The unique identifier for the organization.
      - in: path
        name: environment_id
        required: true
        schema:
          type: string
        description: The unique identifier for the environment.
      - in: path
        name: kafka_cluster_id
        required: true
        schema:
          type: string
        description: The unique identifier for the database.
      - in: path
        name: table_name
        required: true
        schema:
          type: string
        description: The unique identifier for the Materialized Table.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          format: int32
          default: 10
          maximum: 100
        description: A pagination size for collection requests.
      - name: page_token
        in: query
        required: false
        schema:
          type: string
          maxLength: 255
        description: An opaque pagination token for collection requests.
      tags:
      - Materialized Table Versions (sql/v1)
      security:
      - resource-api-key: []
      - global-api-key: []
      - external-access-token: []
      responses:
        '200':
          description: A list of Materialized Table Versions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sql.v1.MaterializedTableVersionList'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: The unique identifier for the API request.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/DefaultSystemError'
  ? /sql/v1/organizations/{organization_id}/environments/{environment_id}/databases/{kafka_cluster_id}/materialized-tables/{table_name}/versions/{version}
  : servers:
    - url: https://flink.region.provider.confluent.cloud
      description: Flink Compute Pool Endpoint
    get:
      x-lifecycle-stage: General Availability
      x-self-access: true
      x-request-access-name: SQL API v1
      operationId: getSqlv1MaterializedTableVersion
      summary: Read a materialized table version
      description: '![General Availability](#section/Versioning/API-Lifecycle-Policy)


        Retrieve a specific version of a Materialized Table.'
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
          format: uuid
        description: The unique identifier for the organization.
      - in: path
        name: environment_id
        required: true
        schema:
          type: string
        description: The unique identifier for the environment.
      - in: path
        name: kafka_cluster_id
        required: true
        schema:
          type: string
        description: The unique identifier for the database.
      - in: path
        name: table_name
        required: true
        schema:
          type: string
        description: The unique identifier for the Materialized Table.
      - in: path
        name: version
        required: true
        schema:
          type: integer
          format: int32
          minimum: 1
        description: The version number of the Materialized Table.
      tags:
      - Materialized Table Versions (sql/v1)
      security:
      - resource-api-key: []
      - global-api-key: []
      - external-access-token: []
      responses:
        '200':
          description: The requested Materialized Table Version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sql.v1.MaterializedTableVersion'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: The unique identifier for the API request.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthenticatedError'
        '403':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/DefaultSystemError'
components:
  schemas:
    ListMeta:
      type: object
      description: ListMeta describes metadata that resource collections may have
      properties:
        first:
          description: A link to the first page of results. If a response does not contain a first link, then direct navigation to the first page is not supported.
          type:
          - string
          - 'null'
          format: uri
          example: https://api.confluent.cloud/v2/resourcekinds
        last:
          description: A link to the last page of results. If a response does not contain a last link, then direct navigation to the last page is not supported.
          type:
          - string
          - 'null'
          format: uri
          example: https://api.confluent.cloud/v2/resourcekinds?page_token=bcAOehAY8F16YD84Z1wT
        prev:
          description: A link to the previous page of results. If a response does not contain a prev link, then either there is no previous data or backwards traversal through the result set is not supported.
          type:
          - string
          - 'null'
          format: uri
          example: https://api.confluent.cloud/v2/resourcekinds?page_token=YIXRY97wWYmwzrax4dld
        next:
          description: A link to the next page of results. If a response does not contain a next link, then there is no more data available.
          type:
          - string
          - 'null'
          format: uri
          example: https://api.confluent.cloud/v2/resourcekinds?page_token=UvmDWOB1iwfAIBPj6EYb
        total_size:
          description: Number of records in the full result set. This response may be paginated and have a smaller number of records.
          type: integer
          format: int32
          minimum: 0
          example: 123
    Failure:
      type: object
      description: Provides information about problems encountered while performing an operation.
      required:
      - errors
      properties:
        errors:
          description: List of errors which caused this operation to fail
          type: array
          items:
            $ref: '#/components/schemas/Error'
          uniqueItems: true
    sql.v1.MaterializedTableVersion:
      type: object
      description: Represents a specific version of a Materialized Table resource.
      required:
      - api_version
      - kind
      - metadata
      - name
      - organization_id
      - environment_id
      - spec
      properties:
        api_version:
          type: string
          enum:
          - sql/v1
          description: APIVersion defines the schema version of this representation of a resource.
          example: sql/v1
          readOnly: true
        kind:
          type: string
          description: Kind defines the object this REST resource represents.
          enum:
          - MaterializedTableVersion
          readOnly: true
        metadata:
          allOf:
          - $ref: '#/components/schemas/ObjectMeta'
          - type: object
            properties:
              self:
                example: https://flink.us-west1.aws.confluent.cloud/sql/v1/organizations/org-123/environments/env-123/databases/lkc-123/materialized-tables/high-value-orders/versions/4
        name:
          type: string
          description: 'The resource version name, unique within the Kafka cluster.

            Name conforms to DNS Subdomain (RFC 1123).

            '
          pattern: '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*'
          maxLength: 100
          example: mt-123-v4
          readOnly: true
        organization_id:
          type: string
          format: uuid
          description: The unique identifier for the organization.
          x-immutable: true
          readOnly: true
        environment_id:
          type: string
          description: The unique identifier for the environment.
          x-immutable: true
          readOnly: true
        spec:
          $ref: '#/components/schemas/sql.v1.MaterializedTableVersionSpec'
    sql.v1.MaterializedTableVersionSpec:
      type: object
      description: The specifications of the Materialized Table Version.
      required:
      - version
      - statement
      properties:
        version:
          type: integer
          format: int32
          minimum: 1
          description: The version number of the Materialized Table.
          example: 4
          readOnly: true
        statement:
          type: string
          description: 'The full SQL statement for the materialized table as generated by SHOW CREATE MATERIALIZED TABLE at the time of the evolution.

            '
          example: CREATE OR ALTER MATERIALIZED TABLE orders AS SELECT user_id, product_id, price FROM orders;
          readOnly: true
          maxLength: 131072
        changes:
          type: array
          description: Changes affecting resources since the previous version.
          items:
            $ref: '#/components/schemas/sql.v1.ResourceChange'
          readOnly: true
    sql.v1.MaterializedTableVersionList:
      type: object
      description: A list of Materialized Table Version resources.
      required:
      - api_version
      - kind
      - metadata
      - data
      properties:
        api_version:
          type: string
          enum:
          - sql/v1
          readOnly: true
        kind:
          type: string
          enum:
          - MaterializedTableVersionList
          readOnly: true
        metadata:
          $ref: '#/components/schemas/ListMeta'
        data:
          type: array
          description: A data property that contains an array of resource items. Each entry in the array is a separate resource.
          items:
            $ref: '#/components/schemas/sql.v1.MaterializedTableVersion'
          uniqueItems: true
    sql.v1.ResourceChange:
      type: object
      description: Details of a change to a specific resource.
      required:
      - kind
      - environment_locator
      - database_locator
      - name
      - details
      properties:
        kind:
          type: string
          x-extensible-enum:
          - MATERIALIZED_TABLE
          - TABLE
          - VIEW
          - FUNCTION
          description: The type of resource that was changed.
          example: MATERIALIZED_TABLE
        environment_locator:
          type: string
          description: The environment containing the resource. Can be either the environment name or ID, depending on how it is referenced in the SQL statement text.
          example: env-abc
        database_locator:
          type: string
          description: The database containing the resource. Can be either the database name or ID, depending on how it is referenced in the SQL statement text.
          example: lkc-123
        name:
          type: string
          description: The name of the resource, unique within its scope (environment and database).
          example: orders
        details:
          type: array
          description: Human-readable descriptions of the changes made to this resource.
          items:
            type: string
          example:
          - 'Column ''product_name: VARCHAR'' added'
          - 'Column ''product_id: BIGINT'' added'
      readOnly: true
    ObjectMeta:
      description: ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.
      required:
      - self
      properties:
        self:
          description: Self is a Uniform Resource Locator (URL) at which an object can be addressed. This URL encodes the service location, API version, and other particulars necessary to locate the resource at a point in time
          type: string
          format: uri
          readOnly: true
          example: https://api.confluent.cloud/v2/kafka-clusters/lkc-f3a90de
        resource_name:
          description: Resource Name is a Uniform Resource Identifier (URI) that is globally unique across space and time. It is represented as a Confluent Resource Name
          type: string
          format: uri
          readOnly: true
          example: crn://confluent.cloud/kafka=lkc-f3a90de
        created_at:
          type: string
          format: date-time
          example: '2006-01-02T15:04:05-07:00'
          readOnly: true
          description: The date and time at which this object was created. It is represented in RFC3339 format and is in UTC.
        updated_at:
          type: string
          format: date-time
          example: '2006-01-02T15:04:05-07:00'
          readOnly: true
          description: The date and time at which this object was last updated. It is represented in RFC3339 format and is in UTC.
        deleted_at:
          type: string
          format: date-time
          example: '2006-01-02T15:04:05-07:00'
          readOnly: true
          description: The date and time at which this object was (or will be) deleted. It is represented in RFC3339 format and is in UTC.
      readOnly: true
    Error:
      type: object
      description: Describes a particular error encountered while performing an operation.
      properties:
        id:
          description: A unique identifier for this particular occurrence of the problem.
          type: string
          maxLength: 255
        status:
          description: The HTTP status code applicable to this problem, expressed as a string value.
          type: string
        code:
          description: An application-specific error code, expressed as a string value.
          type: string
        title:
          description: A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization.
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        source:
          type: object
          description: If this error was caused by a particular part of the API request, the source will point to the query string parameter or request body property that caused it.
          properties:
            pointer:
              description: A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/spec" for a spec object, or "/spec/title" for a specific field].
              type: string
            parameter:
              description: A string indicating which query parameter caused the error.
              type: string
        error_code:
          type: integer
          format: int32
        message:
          type:
          - string
          - 'null'
      additionalProperties: false
  responses:
    RateLimitError:
      description: Rate Limit Exceeded
      headers:
        X-Request-Id:
          schema:
            type: string
          description: The unique identifier for the API request.
        X-RateLimit-Limit:
          schema:
            type: integer
          description: The maximum number of requests you're permitted to make per time period.
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: The number of requests remaining in the current rate limit window.
        X-RateLimit-Reset:
          schema:
            type: integer
          description: "The relative time in seconds until the current rate-limit window resets.  \n  \n**Important:** This differs from Github and Twitter's same-named header which uses UTC epoch seconds. We use relative time to avoid client/server time synchronization issues."
        Retry-After:
          schema:
            type: integer
          description: The number of seconds to wait until the rate limit window resets. Only sent when the rate limit is reached.
    UnauthenticatedError:
      x-summary: Unauthorized
      description: The request lacks valid authentication credentials for this resource.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: The unique identifier for the API request.
        WWW-Authenticate:
          schema:
            type: string
          description: The unique identifier for the API request.
          example: Basic error="invalid_key", error_description="The API Key is invalid"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          example:
            errors:
            - id: ed42afdc-f0d5-4c0d-b428-9fc6ed6e279d
              status: '401'
              code: user_unauthenticated
              title: Authentication Required
              detail: Valid authentication credentials must be provided
    BadRequestError:
      description: Bad Request
      headers:
        X-Request-Id:
          schema:
            type: string
          description: The unique identifier for the API request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          example:
            errors:
            - id: ed42afdc-f0d5-4c0d-b428-9fc6ed6e279d
              status: '400'
              code: invalid_filter
              title: Invalid Filter
              detail: The 'delorean' resource can't be filtered by 'num_doors'
              source:
                parameter: num_doors
    DefaultSystemError:
      description: Oops, something went wrong!
      headers:
        X-Request-Id:
          schema:
            type: string
          description: The unique identifier for the API request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          example:
            errors:
            - id: ed42afdc-f0d5-4c0d-b428-9fc6ed6e279d
              status: '500'
              code: out_of_gas
              title: DeLorean Out Of Gas
              detail: The DeLorean has run out of gas, but Doc Brown will fill 'er up for you asap
    NotFoundError:
      description: Not Found
      headers:
        X-Request-Id:
          schema:
            type: string
          description: The unique identifier for the API request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          example:
            errors:
            - id: ed42afdc-f0d5-4c0d-b428-9fc6ed6e279d
              status: '404'
              title: Not Found
    UnauthorizedError:
      x-summary: Forbidden
      description: The access credentials were considered insufficient to grant access
      headers:
        X-Request-Id:
          schema:
            type: string
          description: The unique identifier for the API request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Failure'
          example:
            errors:
            - id: ed42afdc-f0d5-4c0d-b428-9fc6ed6e279d
              status: '403'
              code: user_unauthorized
              title: User Access Unauthorized
              detail: The user 'mcfly' is not allowed to access the 'delorean' resource without the 'plutonium' role.
  securitySchemes:
    cloud-api-key:
      type: http
      scheme: basic
      description: Authenticate with Cloud API Keys using HTTP Basic Auth. Treat the Cloud API Key ID as the username and Cloud API Key Secret as the password.
    confluent-sts-access-token:
      type: oauth2
      description: Authenticate with Confluent API using this credentials (JSON Web Tokens) following OAuth 2.0.
      flows:
        clientCredentials:
          tokenUrl: https://api.confluent.cloud/sts/v1/oauth2/token
          scopes: {}
    global-api-key:
      type: http
      scheme: basic
      description: Authenticate with Global API Keys using HTTP Basic Auth. Treat the Global API Key ID as the username and Global API Key Secret as the password.
    resource-api-key:
      type: http
      scheme: basic
      description: Authenticate with resource-specific API Keys using HTTP Basic Auth. Treat the resource-specific API Key ID as the username and resource-specific API Key Secret as the password.
    external-access-token:
      type: oauth2
      description: Authenticate with Confluent API using this credentials (JSON Web Tokens) following OAuth 2.0.
      flows:
        clientCredentials:
          tokenUrl: https://api.confluent.cloud/sts/v1/oauth2/token
          scopes: {}
    oauth:
      type: oauth2
      description: Authenticate with OAuth 2.0. Currently this is only supported for partner APIs.
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes:
            partner:alter: enables partners to alter entitlements
            partner:create: enables partners to create entitlements and signup on behalf of customers
            partner:delete: enables partners to delete entitlements and organizations
            partner:describe: enables partners to read and list entitlements and organizations
x-tagGroups:
- name: Identity Access Management (v2)
  tags:
  - API Keys (iam/v2)
  - Users (iam/v2)
  - Service Accounts (iam/v2)
  - Invitations (iam/v2)
  - IP Groups (iam/v2)
  - IP Filters (iam/v2)
  - IP Filter Summaries (iam/v2)
  - Role Bindings (iam/v2)
  - Identity Providers (iam/v2)
  - Jwks (iam/v2)
  - Identity Pools (iam/v2)
  - Group Mappings (iam/v2/sso)
  - Certificate Authorities (iam/v2)
  - Certificate Identity Pools (iam/v2)
- name: Org API (v2)
  tags:
  - Environments (org/v2)
  - Organizations (org/v2)
- name: Notifications API (v1)
  tags:
  - Subscriptions (notifications/v1)
  - Integrations (notifications/v1)
  - Notification Types (notifications/v1)
  - Resource Preferences (notifications/v1)
  - Resource Subscriptions (notifications/v1)
  - User Notifications (notifications/v1)
- name: Cluster Mgmt for Kafka (v2)
  tags:
  - Clusters (cmk/v2)
- name: Cluster Mgmt for ksqlDB (v2)
  tags:
  - Clusters (ksqldbcm/v2)
- name: Connect API (v1)
  tags:
  - Connectors (connect/v1)
  - Lifecycle (connect/v1)
  - Status (connect/v1)
  - Managed Connector Plugins (connect/v1)
  - Offsets (connect/v1)
  - Custom Connector Plugins (connect/v1)
  - Presigned Urls (connect/v1)
  - Custom Connector Runtimes (connect/v1)
- name: Connect Artifact Management (v1)
  tags:
  - Connect Artifacts (cam/v1)
  - Presigned Urls (cam/v1)
- name: Kafka API (v3)
  tags:
  - Cluster (v3)
  - Configs (v3)
  - ACL (v3)
  - Consumer Group (v3)
  - Partition (v3)
  - Topic (v3)
  - Records (v3)
  - Cluster Linking (v3)
  - Share Group (v3)
  - Streams Group (v3)
- name: Service Quota API (v1)
  tags:
  - Applied Quotas (service-quota/v1)
  - Scopes (service-quota/v1)
- name: Partner API (v2)
  tags:
  - Entitlements (partner/v2)
  - Organizations (partner/v2)
  - Signup (partner/v2)
- name: Cluster Mgmt for Schema Registry (v2)
  tags:
  - Regions (srcm/v2)
  - Clusters (srcm/v2)
- name: Cluster Mgmt for Schema Registry (v3)
  tags:
  - Clusters (srcm/v3)
- name: Schema Registry API (v1)
  tags:
  - Compatibility (v1)
  - Config (v1)
  - Contexts (v1)
  - Exporters (v1)
  - Modes (v1)
  - Schemas (v1)
  - Subjects (v1)
  - Key Encryption Keys (v1)
  - Data Encryption Keys (v1)
- name: Catalog API (v1)
  tags:
  - Entity (v1)
  - Search (v1)
  - Types (v1)
- name: Stream Sharing API (v1)
  tags:
  - Provider Shared Resources (cdx/v1)
  - Provider Shares (cdx/v1)
  - Consumer Shared Resources (cdx/v1)
  - Consumer Shares (cdx/v1)
  - Shared Tokens (cdx/v1)
  - Opt Ins (cdx/v1)
- name: Networking (v1)
  tags:
  - Networks (networking/v1)
  - Peerings (networking/v1)
  - Transit Gateway Attachments (networking/v1)
  - Private Link Accesses (networking/v1)
  - Network Link Services (networking/v1)
  - Network Link Endpoints (networking/v1)
  - Network Link Service Associations (networking/v1)
  - IP Addresses (networking/v1)
  - Private Link Attachments (networking/v1)
  - Private Link Attachment Connections (networking/v1)
  - DNS Forwarders (networking/v1)
  - Access Points (networking/v1)
  - DNS Records (networking/v1)
  - Gateways (networking/v1)
- name: Security Token Service (v1)
  tags:
  - OAuth Tokens (sts/v1)
- name: Kafka Quota (v1)
  tags:
  - Client Quotas (kafka-quotas/v1)
- name: Bring Your Own Key (BYOK) Management (v1)
  tags:
  - Keys (byok/v1)
- name: Billing API (v1)
  tags:
  - Costs (billing/v1)
- name: Compute Pool Mgmt for Flink (v2)
  tags:
  - Compute Pools (fcpm/v2)
  - Regions (fcpm/v2)
  - Org Compute Pool Configs (fcpm/v2)
- name: SQL API (v1)
  tags:
  - Statements (sql/v1)
  - Statement Results (sql/v1)
  - Statement Exceptions (sql/v1)
  - Connections (sql/v1)
  - Agents (sql/v1)
  - Tools (sql/v1)
  - Materialized Tables (sql/v1)
  - Materialized Table Versions (sql/v1)
- name: Provider Integration Management (v1)
  tags:
  - Integrations (pim/v1)
- name: Provider Integration Management (v2)
  tags:
  - Integrations (pim/v2)
- name: Artifact API (v1)
  tags:
  - Flink Artifacts (artifact/v1)
  - Presigned Urls (artifact/v1)
  - Flink Artifact Versions (artifact/v1)
- name: Custom Code Logging API (v1)
  tags:
  - Custom Code Loggings (ccl/v1)
- name: Tableflow (v1)
  tags:
  - Regions (tableflow/v1)
  - Tableflow Topics (tableflow/v1)
  - Catalog Integrations (tableflow/v1)
- name: Custom Connect Plugin Management (v1)
  tags:
  - Custom Connect Plugins (ccpm/v1)
  - Presigned Urls (ccpm/v1)
  - Custom Connect Plugin Versions (ccpm/v1)
- name: Unified Stream Manager (v1)
  tags:
  - Kafka Clusters (usm/v1)
  - Connect Clusters (usm/v1)
- name: Endpoint (v1)
  tags:
  - Endpoints (endpoint/v1)
- name: Real Time Context Engine (v1)
  tags:
  - Rtce Topics (rtce/v1)
  - Regions (rtce/v1)
- name: Analytics (v1alpha1)
  tags:
  - Statements (query/v1alpha1)