Delete a subject

This document describes how to delete a subject from a schema registry. There are two ways to delete a subject:

Soft-delete. Marks the subject as deleted, but its information is retained and can be recovered. All versions for the subject are also soft-deleted.
Hard-delete. Permanently removes the subject and its associated data.

You can also delete a specific schema version from a subject. For more information, see Delete a schema subject version .

Required roles and permissions

To get the permissions that you need to delete a subject, ask your administrator to grant you the Managed Kafka Schema Registry Editor ( roles/managedkafka.schemaRegistryEditor ) IAM role on your subject. For more information about granting roles, see Manage access to projects, folders, and organizations .

This predefined role contains the permissions required to delete a subject. To see the exact permissions that are required, expand the Required permissionssection:

Required permissions

The following permissions are required to delete a subject:

Grant the following permission on the subject to be deleted: managedkafka.subjects.delete
If deleting in the console, grant the following permission to view the subject: managedkafka.subjects.list

You might also be able to get these permissions with custom roles or other predefined roles .

The Managed Kafka Schema Registry Admin( roles/managedkafka.schemaRegistryAdmin ) role also let you delete subjects.

For more information about predefined roles, see the Managed Service for Apache Kafka predefined roles .

Soft-delete a subject

Make sure the following conditions are met:

The subject that you are going to delete is not referenced by other schemas. A request for deletion fails if any version in the subject is referenced by other schemas.
The schema registry to which the subject belongs or the subject itself must not be in the Read-only mode.

To soft-delete a subject, follow these steps.

Console

In the Google Cloud console, go to the Schema registriespage.

Go to Schema registries
Click the name of the schema registry that contains the subject to delete.
Under Subjects in this schema registry, click the name of the subject.
In the Subject detailspage, click Delete.
Select Soft Delete.
In the Delete schema subjectdialog, type delete into the field.
Click Delete. This action soft-deletes the subject before permanently deleting it.

REST

The request must be authenticated with an access token in the Authorization header. To obtain an access token for the current Application Default Credentials: gcloud auth application-default print-access-token .

To soft-delete a subject using the REST API, make a DELETE request to the appropriate URI using the projects.locations.schemaRegistries.contexts.subjects.delete method.

 DELETE https://managedkafka.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ LOCATION 
/schemaRegistries/ REGISTRY_ID 
/subjects/ SUBJECT_ID 
Authorization: Bearer $(gcloud auth application-default print-access-token)

To soft-delete a subject under a specific context by using the REST API, make a DELETE request to the appropriate URI using the projects.locations.schemaRegistries.contexts.subjects.delete method.

 DELETE https://managedkafka.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ LOCATION 
/schemaRegistries/ REGISTRY_ID 
/contexts/ CONTEXT_ID 
/subjects/ SUBJECT_ID 
Authorization: Bearer $(gcloud auth application-default print-access-token)

Replace the following:

PROJECT_ID (required): your Google Cloud project ID.
LOCATION (required): the Google Cloud region where the schema registry is located.
REGISTRY_ID (required): the ID of your schema registry.
CONTEXT_ID (optional): the ID or name of the context, if deleting a subject within a specific context.
SUBJECT_ID (optional): the ID or name of the subject you want to delete.

For example, to soft-delete orders-topic-value from schema registry test_registry in project test-gcp-project and location us-central1 , make the following request:

 DELETE  
https://managedkafka.googleapis.com/v1/projects/test-gcp-project/locations/us-central1/schemaRegistries/test_registry/subjects/orders-topic-value
Authorization:  
Bearer  
 $( 
gcloud  
auth  
application-default  
print-access-token )

If the request is successful, the API returns a 200 OK status code. The response body contains a JSON array of the version numbers of the schemas that belonged to the deleted subject.

Hard-delete a subject

Hard-deleting a subject is irreversible and also deletes all associated schema versions.

Make sure the following conditions are met:

The subject that you are going to delete is not referenced by other schemas. A request for deletion fails if any version in the subject is referenced by other schemas.
The schema registry to which the subject belongs or the subject itself must not be in the Read-only mode.
Back up any necessary schema information before proceeding with the deletion.
No active producers or consumers must rely on the schemas within this subject, as deleting it can cause disruptions.

Console

In the Google Cloud console, go to the Schema registriespage.

Go to Schema registries
Click the name of the schema registry that contains the subject to delete.
Under Subjects in this schema registry, click the name of the subject.
In the Subject detailspage, click Delete.
Select Hard Delete.
In the Delete schema subjectdialog, type delete into the field.
Click Delete. This action soft-deletes the subject before permanently deleting it.

REST

To hard-delete a subject using the REST API, you must first soft-delete it. Once soft-deleted, you can proceed with the hard-deletion.

To hard-delete a subject using the REST API, make a DELETE request to the appropriate URI, including the permanent=true query parameter and using the projects.locations.schemaRegistries.subjects.delete method.

 DELETE https://managedkafka.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ LOCATION 
/schemaRegistries/ REGISTRY_ID 
/subjects/ SUBJECT_ID 
?permanent=true
Authorization: Bearer $(gcloud auth application-default print-access-token)

To hard-delete a subject under a specific context by using the REST API, make a DELETE request to the appropriate URI, including the permanent=true query parameter and using the projects.locations.schemaRegistries.contexts.subjects.delete method.

 DELETE https://managedkafka.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ LOCATION 
/schemaRegistries/ REGISTRY_ID 
/contexts/ CONTEXT_ID 
/subjects/ SUBJECT_ID 
?permanent=true
Authorization: Bearer $(gcloud auth application-default print-access-token)

Replace the following:

PROJECT_ID (required): your Google Cloud project ID.
LOCATION (required): the Google Cloud region where the schema registry is located.
REGISTRY_ID (required): the ID of your schema registry.
CONTEXT_ID (optional): the ID of the context, if deleting a subject within a specific context.
SUBJECT_ID (optional): the ID or name of the subject you want to delete.

For example, to hard-delete the previously soft-deleted subject orders-topic-value from schema registry test_registry in project test-gcp-project and location us-central1 , make the following request:

 DELETE https://managedkafka.googleapis.com/v1/projects/test-gcp-project/locations/us-central1/schemaRegistries/test_registry/subjects/orders-topic-value?permanent=true
Authorization: Bearer $(gcloud auth application-default print-access-token)

If the request is successful, the API returns a 200 OK status code. The response body contains a JSON array of the version numbers of the schemas that belonged to the deleted subject.

For more information, see projects.locations.schemaRegistries.contexts.subjects.delete .

Restore a soft-deleted subject

To restore a soft-deleted subject, perform the following steps.

Console

In the Google Cloud console, go to the Schema registriespage.

Go to Schema registries
Click the name of the schema registry that contains the soft-deleted subject.
For Filter, click Cancelto clear the Soft-deleted: Nofilter.
Click the name of the subject to restore.
In the Subject detailspage, click Create version to restore.
For Schema type, select Avroor Protocol Buffer.
In the Schema definitionfield, enter the definition of the schema. Don't include sensitive information such as personally identifiable information (PII) or security data in your schema field names.
If your schema uses or depends on data structures defined in other schemas in the schema registry, perform the following steps:
1. Click Add Schema reference.
2. In the Reference namefield, enter the reference name of the referenced schema.
3. In the Subjectlist, select the subject that contains the referenced schema.
4. In the Versionlist, select the version number of the referenced schema.
5. Click OK.
Repeat these steps for each referenced schema.
Click Create.

REST

To restore a soft-deleted subject, use the schemaRegistries.subjects.versions.create method.

Before using any of the request data, make the following replacements:

PROJECT_ID : your Google Cloud project ID
LOCATION : the location of the schema registry
REGISTRY_ID : the ID of the schema registry
SUBJECT : the subject name
SCHEMA_DEFINITION : a string that contains the schema definition

HTTP method and URL:

POST https://managedkafka.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ LOCATION 
/schemaRegistries/ REGISTRY_ID 
/subjects/ SUBJECT 
/versions

Request JSON body:

{
  "schema": " SCHEMA_DEFINITION 
"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell , which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list .

Save the request body in a file named request.json , and execute the following command:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://managedkafka.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ LOCATION 
/schemaRegistries/ REGISTRY_ID 
/subjects/ SUBJECT 
/versions"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list .

Save the request body in a file named request.json , and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://managedkafka.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ LOCATION 
/schemaRegistries/ REGISTRY_ID 
/subjects/ SUBJECT 
/versions" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "id": SCHEMA_ID 
}

What's next

Apache Kafka® is a registered trademark of The Apache Software Foundation or its affiliates in the United States and/or other countries.

Delete a subject Stay organized with collections Save and categorize content based on your preferences.

Required roles and permissions

Required permissions

Soft-delete a subject

Console

REST

Hard-delete a subject

Console

REST

Restore a soft-deleted subject

Console

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

What's next

Delete a subject