versions

Creates, updates, deletes, gets or lists a versions resource.

Overview

Name	versions
Type	Resource
Id	confluent.schema_registry.versions

Fields

The following fields are returned by SELECT queries:

get_schema_by_version

The schema.

Name	Datatype	Description
id	integer (int32)	Globally unique identifier of the schema
metadata	object	User-defined metadata
references	array	References to other schemas
ruleSet	object	Schema rule set
schema	string	Schema definition string (example: {"schema": "{"type": "string"}"})
schemaTags	array	Schema tags
schemaType	string	Schema type (example: AVRO)
subject	string	Name of the subject (example: User)
version	integer (int32)	Version number

get_versions

List of subject versions matching the specified parameters.

Name	Datatype	Description
subject	string	Name of the subject (example: User)
version	integer (int32)	Version number

list_versions

List of version numbers matching the specified parameters.

Name	Datatype	Description
version	integer

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_schema_by_version	select	subject, version	format, deleted	Retrieves a specific version of the schema registered under this subject.
get_versions	select	id	subject, deleted, offset, limit	Get all the subject-version pairs associated with the input ID.
list_versions	select	subject	deleted, deletedOnly, offset, limit	Retrieves a list of versions registered under the specified subject.
register	insert	subject	normalize, format	Register a new schema under the specified subject. If successfully registered, this returns the unique identifier of this schema in the registry. The returned identifier should be used to retrieve this schema from the schemas resource and is different from the schema's version which is associated with the subject. If the same schema is registered under a different subject, the same identifier will be returned. However, the version of the schema may be different under different subjects. A schema should be compatible with the previously registered schema or schemas (if there are any) as per the configured compatibility level. The configured compatibility level can be obtained by issuing a GET http:get:: /config/(string: subject). If that returns null, then GET http:get:: /config When there are multiple instances of Schema Registry running in the same cluster, the schema registration request will be forwarded to one of the instances designated as the primary. If the primary is not available, the client will get an error code indicating that the forwarding has failed.
delete_schema_version	delete	subject, version	permanent	Deletes a specific version of the schema registered under this subject. This only deletes the version and the schema ID remains intact making it still possible to decode data using the schema ID. This API is recommended to be used only in development environments or under extreme circumstances where-in, its required to delete a previously registered schema for compatibility purposes or re-register previously registered schema.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
id	integer (int32)	Globally unique identifier of the schema
subject	string	Name of the subject
version	string	Version of the schema to be returned. Valid values for versionId are between [1,2^31-1] or the string "latest". "latest" returns the last registered schema under the specified subject. Note that there may be a new latest schema that gets registered right after this request is served.
deleted	boolean	Whether to include deleted schemas
deletedOnly	boolean	Whether to return deleted schemas only
format	string	Desired output format, dependent on schema type. For AVRO schemas, valid values are: " " (default) or "resolved". For PROTOBUF schemas, valid values are: " " (default), "ignore_extensions", or "serialized" (The parameter does not apply to JSON schemas.)
limit	integer (int32)	Pagination size for results. Ignored if negative
normalize	boolean	Whether to register the normalized schema
offset	integer (int32)	Pagination offset for results
permanent	boolean	Whether to perform a permanent delete
subject	string	Filters results by the respective subject

SELECT examples

get_schema_by_version

Retrieves a specific version of the schema registered under this subject.

SELECT
id,
metadata,
references,
ruleSet,
schema,
schemaTags,
schemaType,
subject,
version
FROM confluent.schema_registry.versions
WHERE subject = '{{ subject }}' -- required
AND version = '{{ version }}' -- required
AND format = '{{ format }}'
AND deleted = '{{ deleted }}'
;

get_versions

Get all the subject-version pairs associated with the input ID.

SELECT
subject,
version
FROM confluent.schema_registry.versions
WHERE id = '{{ id }}' -- required
AND subject = '{{ subject }}'
AND deleted = '{{ deleted }}'
AND offset = '{{ offset }}'
AND limit = '{{ limit }}'
;

list_versions

Retrieves a list of versions registered under the specified subject.

SELECT
version
FROM confluent.schema_registry.versions
WHERE subject = '{{ subject }}' -- required
AND deleted = '{{ deleted }}'
AND deletedOnly = '{{ deletedOnly }}'
AND offset = '{{ offset }}'
AND limit = '{{ limit }}'
;

INSERT examples

register

Register a new schema under the specified subject. If successfully registered, this returns the unique identifier of this schema in the registry. The returned identifier should be used to retrieve this schema from the schemas resource and is different from the schema's version which is associated with the subject. If the same schema is registered under a different subject, the same identifier will be returned. However, the version of the schema may be different under different subjects.
A schema should be compatible with the previously registered schema or schemas (if there are any) as per the configured compatibility level. The configured compatibility level can be obtained by issuing a GET http:get:: /config/(string: subject). If that returns null, then GET http:get:: /config
When there are multiple instances of Schema Registry running in the same cluster, the schema registration request will be forwarded to one of the instances designated as the primary. If the primary is not available, the client will get an error code indicating that the forwarding has failed.

INSERT INTO confluent.schema_registry.versions (
version,
id,
schemaType,
references,
schema,
metadata,
ruleSet,
schemaTagsToAdd,
schemaTagsToRemove,
propagateSchemaTags,
subject,
normalize,
format
)
SELECT 
{{ version }},
{{ id }},
'{{ schemaType }}',
'{{ references }}',
'{{ schema }}',
'{{ metadata }}',
'{{ ruleSet }}',
'{{ schemaTagsToAdd }}',
'{{ schemaTagsToRemove }}',
{{ propagateSchemaTags }},
'{{ subject }}',
'{{ normalize }}',
'{{ format }}'
RETURNING
id
;

Manifest

# Description fields are for documentation purposes
- name: versions
props:
  - name: subject
    value: "{{ subject }}"
    description: Required parameter for the versions resource.
  - name: version
    value: {{ version }}
    description: |
      Version number
  - name: id
    value: {{ id }}
    description: |
      Globally unique identifier of the schema
  - name: schemaType
    value: "{{ schemaType }}"
    description: |
      Schema type
  - name: references
    description: |
      References to other schemas
    value:
      - name: "{{ name }}"
        subject: "{{ subject }}"
        version: {{ version }}
  - name: schema
    value: "{{ schema }}"
    description: |
      Schema definition string
  - name: metadata
    description: |
      User-defined metadata
    value:
      tags: "{{ tags }}"
      properties: "{{ properties }}"
      sensitive:
        - "{{ sensitive }}"
  - name: ruleSet
    description: |
      Schema rule set
    value:
      migrationRules:
        - name: "{{ name }}"
          doc: "{{ doc }}"
          kind: "{{ kind }}"
          mode: "{{ mode }}"
          type: "{{ type }}"
          tags: "{{ tags }}"
          params: "{{ params }}"
          expr: "{{ expr }}"
          onSuccess: "{{ onSuccess }}"
          onFailure: "{{ onFailure }}"
          disabled: {{ disabled }}
      domainRules:
        - name: "{{ name }}"
          doc: "{{ doc }}"
          kind: "{{ kind }}"
          mode: "{{ mode }}"
          type: "{{ type }}"
          tags: "{{ tags }}"
          params: "{{ params }}"
          expr: "{{ expr }}"
          onSuccess: "{{ onSuccess }}"
          onFailure: "{{ onFailure }}"
          disabled: {{ disabled }}
  - name: schemaTagsToAdd
    value:
      - schemaEntity:
          entityPath: "{{ entityPath }}"
          entityType: "{{ entityType }}"
        tags: "{{ tags }}"
  - name: schemaTagsToRemove
    value:
      - schemaEntity:
          entityPath: "{{ entityPath }}"
          entityType: "{{ entityType }}"
        tags: "{{ tags }}"
  - name: propagateSchemaTags
    value: {{ propagateSchemaTags }}
  - name: normalize
    value: {{ normalize }}
    description: Whether to register the normalized schema
    description: Whether to register the normalized schema
  - name: format
    value: "{{ format }}"
    description: Desired output format, dependent on schema type. For AVRO schemas, valid values are: " " (default) or "resolved". For PROTOBUF schemas, valid values are: " " (default), "ignore_extensions", or "serialized" (The parameter does not apply to JSON schemas.)
    description: Desired output format, dependent on schema type. For AVRO schemas, valid values are: " " (default) or "resolved". For PROTOBUF schemas, valid values are: " " (default), "ignore_extensions", or "serialized" (The parameter does not apply to JSON schemas.)

DELETE examples

delete_schema_version

Deletes a specific version of the schema registered under this subject. This only deletes the version and the schema ID remains intact making it still possible to decode data using the schema ID. This API is recommended to be used only in development environments or under extreme circumstances where-in, its required to delete a previously registered schema for compatibility purposes or re-register previously registered schema.

DELETE FROM confluent.schema_registry.versions
WHERE subject = '{{ subject }}' --required
AND version = '{{ version }}' --required
AND permanent = '{{ permanent }}'
;