Create a subscription with SMTs

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

Console

1. In the Google Cloud console, go to the Pub/Sub Subscriptions page.

   Go to Subscriptions

2. Click Create subscription.

   The Create subscription page opens.

3. In the Subscription ID field, enter an ID for your subscription. For more information about naming subscriptions, see the naming guidelines.

4. Under Transforms, click Add a transform.

5. Enter a function name. For example: redactSSN.

6. If you don't want to use the SMT with your subscription immediately, click the Disable transform option. This will still save the SMT, but it will not be executed as messages flow through your subscription.

7. Enter a new transform. For example:

   function redactSSN(message, metadata) {
     const data = JSON.parse(message.data);
     delete data['ssn'];
     message.data = JSON.stringify(data);
     return message;
   }

8. Pub/Sub provides a validate function that lets you validate an SMT. Click Validate to validate the transform.

9. If you want to add another transform, click Add a transform.

10. To arrange all the SMTs in a specific order, you can use the up and down arrows. To remove an SMT, click the delete button.

11. Pub/Sub provides a test function that lets you check the result of running the SMT on a sample message. To test the SMTs, click Test transform.

12. In the Test transform window, select the function that you want to test.

13. In the Input message window, enter a sample message.

14. If you want to add message attributes, click Add an attribute and enter one or more key-value pairs.

15. Click Test. The result of applying the SMTs on the message is displayed.

16. Close the window to stop testing SMTs on sample messages.

17. Click Create to create the subscription.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Pub/Sub provides a validate function that lets you validate an SMT. Run the gcloud pubsub message-transforms validate command:

   gcloud pubsub message-transforms validate --message-transform-file=TRANSFORM_FILE

   Replace the following:

   • TRANSFORM_FILE: The path to the YAML or JSON file containing a single SMT.

     Here is an example of a YAML transform file:

     javascriptUdf:
         code: >
             function redactSSN(message, metadata) {
               const data = JSON.parse(message.data);
               delete data['ssn'];
               message.data = JSON.stringify(data);
               return message;
             }
         functionName: redactSSN

3. Pub/Sub provides a test function that lets you check the result of running one or more SMTs on a sample message. Run the gcloud pubsub message-transforms test command:

   gcloud pubsub message-transforms test --message-transforms-file=TRANSFORMS_FILE

   Replace the following:

   • TRANSFORMS_FILE: The path to the YAML or JSON file containing one or more SMTs.

     Here is an example of a YAML transforms file:

     - javascriptUdf:
         code: >
             function redactSSN(message, metadata) {
               const data = JSON.parse(message.data);
               delete data['ssn'];
               message.data = JSON.stringify(data);
               return message;
             }
         functionName: redactSSN

4. To create the subscription, run the gcloud pubsub subscriptions create command:

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_NAME \
       --message-transforms-file=TRANSFORMS_FILE

   Replace the following:

   • SUBSCRIPTION_ID: The ID or name of the subscription you want to create. For guidelines on how to name a subscription, see Resource names. The name of a subscription is immutable.

   • TOPIC_NAME: The name of the topic to subscribe to, in the format projects/PROJECT_ID/topics/TOPIC_ID.

   • TRANSFORMS_FILE: The path to the YAML or JSON file containing one or more SMTs.

     Here is an example of a YAML transforms file:

     - javascriptUdf:
         code: >
             function redactSSN(message, metadata) {
               const data = JSON.parse(message.data);
               delete data['ssn'];
               message.data = JSON.stringify(data);
               return message;
             }
         functionName: redactSSN

Java

Before trying this sample, follow the Java setup instructions in the Pub/Sub quickstart using client libraries. For more information, see the Pub/Sub Java API reference documentation.

To authenticate to Pub/Sub, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.JavaScriptUDF;
import com.google.pubsub.v1.MessageTransform;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateSubscriptionWithSmtExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";

    createSubscriptionWithSmtExample(projectId, topicId, subscriptionId);
  }

  public static void createSubscriptionWithSmtExample(
      String projectId, String topicId, String subscriptionId) throws IOException {

    // UDF that removes the 'ssn' field, if present
    String code =
        "function redactSSN(message, metadata) {"
            + "  const data = JSON.parse(message.data);"
            + "  delete data['ssn'];"
            + "  message.data = JSON.stringify(data);"
            + "  return message;"
            + "}";
    String functionName = "redactSSN";

    JavaScriptUDF udf =
        JavaScriptUDF.newBuilder().setCode(code).setFunctionName(functionName).build();
    MessageTransform transform = MessageTransform.newBuilder().setJavascriptUdf(udf).build();

    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  // Add the UDF message transform
                  .addMessageTransforms(transform)
                  .build());

      System.out.println("Created subscription with SMT: " + subscription.getAllFields());
    }
  }
}

Python

Before trying this sample, follow the Python setup instructions in the Pub/Sub quickstart using client libraries. For more information, see the Pub/Sub Python API reference documentation.

To authenticate to Pub/Sub, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

from google.cloud import pubsub_v1
from google.pubsub_v1.types import JavaScriptUDF, MessageTransform

# TODO(developer): Choose an existing topic.
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

code = """function redactSSN(message, metadata) {
            const data = JSON.parse(message.data);
            delete data['ssn'];
            message.data = JSON.stringify(data);
            return message;
            }"""
udf = JavaScriptUDF(code=code, function_name="redactSSN")
transforms = [MessageTransform(javascript_udf=udf)]

with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "message_transforms": transforms,
        }
    )
    print(f"Created subscription with SMT: {subscription}")

Go

Before trying this sample, follow the Go setup instructions in the Pub/Sub quickstart using client libraries. For more information, see the Pub/Sub Go API reference documentation.

To authenticate to Pub/Sub, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package subscriptions

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub"
)

// createSubscriptionWithSMT creates a subscription with a single message transform function applied.
func createSubscriptionWithSMT(w io.Writer, projectID, subID string, topic *pubsub.Topic) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	code := `function redactSSN(message, metadata) {
			const data = JSON.parse(message.data);
			delete data['ssn'];
			message.data = JSON.stringify(data);
			return message;
		}`
	transform := pubsub.MessageTransform{
		Transform: pubsub.JavaScriptUDF{
			FunctionName: "redactSSN",
			Code:         code,
		},
	}
	cfg := pubsub.SubscriptionConfig{
		Topic:             topic,
		MessageTransforms: []pubsub.MessageTransform{transform},
	}
	sub, err := client.CreateSubscription(ctx, subID, cfg)
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription with message transform: %v\n", sub)
	return nil
}