kafka_topics

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

Overview

Name	kafka_topics
Type	Resource
Id	ovh.public_cloud_analytics.kafka_topics

Fields

The following fields are returned by SELECT queries:

get

successful operation

Name	Datatype	Description
id	string (uuid)	Unique identifier of the topic
name	string	Name of the Kafka topic
checksum	string	Hash of the resource used for concurrency control
created_at	string (date-time)	Date at which the resource was created (wire: createdAt)
minimum_in_sync_replicas	integer	Minimum number of in-sync replicas required before a write is acknowledged (wire: minimumInSyncReplicas)
partitions	integer	Number of partitions for this topic
replication	integer	Replication factor for this topic
retention_bytes	integer	Maximum size in bytes retained per partition. -1 means unlimited. (wire: retentionBytes)
retention_hours	integer	Maximum time in hours that messages are retained. -1 means unlimited. (wire: retentionHours)
updated_at	string (date-time)	Date of the last update to the resource (wire: updatedAt)

list

A Kafka topic on a managed Kafka service

Name	Datatype	Description
id	string (uuid)	Unique identifier of the topic
name	string	Name of the Kafka topic
checksum	string	Hash of the resource used for concurrency control
created_at	string (date-time)	Date at which the resource was created (wire: createdAt)
minimum_in_sync_replicas	integer	Minimum number of in-sync replicas required before a write is acknowledged (wire: minimumInSyncReplicas)
partitions	integer	Number of partitions for this topic
replication	integer	Replication factor for this topic
retention_bytes	integer	Maximum size in bytes retained per partition. -1 means unlimited. (wire: retentionBytes)
retention_hours	integer	Maximum time in hours that messages are retained. -1 means unlimited. (wire: retentionHours)
updated_at	string (date-time)	Date of the last update to the resource (wire: updatedAt)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	service_id, topic_id, project_id		Returns the partitions, replication factor, minimum in-sync replicas and retention settings of the topic. (Beta version)
list	select	service_id, project_id	x_pagination_cursor, x_pagination_size	Returns the topics of the service with their partitions, replication and retention settings. (Beta version)
create	insert	service_id, project_id, name		Creates a topic. By default it has 1 partition, a replication factor of 1 and a retention of 168 hours (7 days). The replication factor must not exceed the number of brokers. (Beta version)
update	update	service_id, topic_id, project_id		Partially updates the partitions, replication, minimum in-sync replicas or retention of the topic. The number of partitions can only be increased. (Beta version)
delete	delete	service_id, topic_id, project_id		Permanently deletes the topic and its messages. (Beta version)
replace	exec	serviceId, topicId, project_id, minimumInSyncReplicas, partitions, replication, retentionBytes, retentionHours		Updates the partitions, replication, minimum in-sync replicas and retention of the topic. Every field is required. The number of partitions can only be increased. (Beta version)

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
api_host	string	The OVHcloud API host. Selected by OVH_ENDPOINT (ovh-eu, ovh-ca or ovh-us; default ovh-eu). (default: api.eu.ovhcloud.com, x-stackQL-envVarSelector: {"envVar":"OVH_ENDPOINT","default":"ovh-eu","values":{"ovh-eu":"api.eu.ovhcloud.com","ovh-ca":"api.ca.ovhcloud.com","ovh-us":"api.us.ovhcloud.com"}})
project_id	string	The Public Cloud project ID. Resolved from OVH_CLOUD_PROJECT_SERVICE when set.
serviceId	string (uuid)	Service ID
service_id	string (uuid)	Service ID (wire: serviceId)
topicId	string (uuid)	Topic ID
topic_id	string (uuid)	Topic ID (wire: topicId)
x_pagination_cursor	string	Pagination cursor (wire: X-Pagination-Cursor)
x_pagination_size	integer	Pagination size (wire: X-Pagination-Size)

SELECT examples

get

Returns the partitions, replication factor, minimum in-sync replicas and retention settings of the topic. (Beta version)

SELECT
id,
name,
checksum,
created_at,
minimum_in_sync_replicas,
partitions,
replication,
retention_bytes,
retention_hours,
updated_at
FROM ovh.public_cloud_analytics.kafka_topics
WHERE service_id = '{{ service_id }}' -- required
AND topic_id = '{{ topic_id }}' -- required
AND project_id = '{{ project_id }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
;

list

Returns the topics of the service with their partitions, replication and retention settings. (Beta version)

SELECT
id,
name,
checksum,
created_at,
minimum_in_sync_replicas,
partitions,
replication,
retention_bytes,
retention_hours,
updated_at
FROM ovh.public_cloud_analytics.kafka_topics
WHERE service_id = '{{ service_id }}' -- required
AND project_id = '{{ project_id }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
AND x_pagination_cursor = '{{ x_pagination_cursor }}'
AND x_pagination_size = '{{ x_pagination_size }}'
;

INSERT examples

create

Creates a topic. By default it has 1 partition, a replication factor of 1 and a retention of 168 hours (7 days). The replication factor must not exceed the number of brokers. (Beta version)

INSERT INTO ovh.public_cloud_analytics.kafka_topics (
minimum_in_sync_replicas,
name,
partitions,
replication,
retention_bytes,
retention_hours,
service_id,
project_id
)
SELECT 
{{ minimum_in_sync_replicas }},
'{{ name }}' /* required */,
{{ partitions }},
{{ replication }},
{{ retention_bytes }},
{{ retention_hours }},
'{{ service_id }}',
'{{ project_id }}'
RETURNING
id,
name,
checksum,
created_at,
minimum_in_sync_replicas,
partitions,
replication,
retention_bytes,
retention_hours,
updated_at
;

Manifest

# Description fields are for documentation purposes
- name: kafka_topics
props:
  - name: service_id
    value: "{{ service_id }}"
    description: Required parameter for the kafka_topics resource.
  - name: project_id
    value: "{{ project_id }}"
    description: Required parameter for the kafka_topics resource.
  - name: minimum_in_sync_replicas
    value: {{ minimum_in_sync_replicas }}
    description: |
      Minimum number of in-sync replicas. Defaults to 1 when null.
  - name: name
    value: "{{ name }}"
    description: |
      Name of the Kafka topic
  - name: partitions
    value: {{ partitions }}
    description: |
      Number of partitions. Defaults to 1 when null.
  - name: replication
    value: {{ replication }}
    description: |
      Replication factor. Must not exceed the number of brokers. Defaults to 1 when null.
  - name: retention_bytes
    value: {{ retention_bytes }}
    description: |
      Maximum size in bytes retained per partition. -1 means unlimited. Defaults to -1 when null.
  - name: retention_hours
    value: {{ retention_hours }}
    description: |
      Maximum time in hours that messages are retained. -1 means unlimited. Defaults to 168 (7 days) when null.

UPDATE examples

update

Partially updates the partitions, replication, minimum in-sync replicas or retention of the topic. The number of partitions can only be increased. (Beta version)

UPDATE ovh.public_cloud_analytics.kafka_topics
SET 
minimum_in_sync_replicas = {{ minimum_in_sync_replicas }},
partitions = {{ partitions }},
replication = {{ replication }},
retention_bytes = {{ retention_bytes }},
retention_hours = {{ retention_hours }}
WHERE 
service_id = '{{ service_id }}' --required
AND topic_id = '{{ topic_id }}' --required
AND project_id = '{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
RETURNING
id,
name,
checksum,
created_at,
minimum_in_sync_replicas,
partitions,
replication,
retention_bytes,
retention_hours,
updated_at;

DELETE examples

delete

Permanently deletes the topic and its messages. (Beta version)

DELETE FROM ovh.public_cloud_analytics.kafka_topics
WHERE service_id = '{{ service_id }}' --required
AND topic_id = '{{ topic_id }}' --required
AND project_id = '{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
;

Lifecycle Methods

EXEC variables use wire (API) names.

replace

Updates the partitions, replication, minimum in-sync replicas and retention of the topic. Every field is required. The number of partitions can only be increased. (Beta version)

EXEC ovh.public_cloud_analytics.kafka_topics.replace 
@serviceId='{{ serviceId }}' --required, 
@topicId='{{ topicId }}' --required, 
@project_id='{{ project_id }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"minimumInSyncReplicas": {{ minimumInSyncReplicas }}, 
"partitions": {{ partitions }}, 
"replication": {{ replication }}, 
"retentionBytes": {{ retentionBytes }}, 
"retentionHours": {{ retentionHours }}
}'
;