Filter messages from a subscription

This page explains how to create Pub/Sub subscriptions with filters.

When you receive messages from a subscription with a filter, you only receive the messages that match the filter. The Pub/Sub service automatically acknowledges the messages that don't match the filter. You can filter messages by their attributes, but not by the data in the message.

You can have multiple subscriptions attached to a topic and each subscription can have a different filter.

For example, if you have a topic that receives news from different parts of the world, you can configure a subscription to filter in news that is published only from a specific region. For this configuration, you must ensure that one of the topic message attributes conveys the region of news publication.

When you receive messages from a subscription with a filter, you don't incur outbound message fees for the messages that Pub/Sub automatically acknowledges. You incur message delivery fees and seek-related storage fees for these messages.

Create a subscription with a filter

Pull and push subscriptions can have filters. All subscribers can receive messages from subscriptions with filters, including subscribers that use the StreamingPull API.

You can create a subscription with a filter using the Google Cloud console, the Google Cloud CLI, the client libraries, or the Pub/Sub API.

Console

To create a pull subscription with a filter, follow these steps:

In the Google Cloud console, go to the Subscriptions page.

Go to the Subscriptions page
Click Create subscription.
Enter the Subscription ID.
Choose or create a topic from the drop-down menu. The subscription receives messages from the topic.
In the Subscription filter section, enter the filter expression.
Click Create.

To create a push subscription with a filter, follow these steps:

In the Google Cloud console, go to the Subscriptions page.

Go to the Subscriptions page
Click Create subscription.
Enter the Subscription ID.
Choose or create a topic from the drop-down menu. The subscription receives messages from the topic.
In the Delivery type section, click Push.
In the Endpoint URL field, enter the URL of the push endpoint.
In the Subscription filter section, enter the filter expression.
Click Create.

gcloud

To create a pull subscription with a filter, use the gcloud pubsub subscriptions create command with the --message-filter flag:

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  --message-filter='FILTER'

Replace the following:

SUBSCRIPTION_ID: the ID of the subscription to create
TOPIC_ID: the ID of the topic to attach to the subscription
FILTER: an expression in the filtering syntax

To create a push subscription with a filter, use the gcloud pubsub subscriptions create command with the --push-endpoint and --message-filter flags:

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  --push-endpoint=PUSH_ENDPOINT \
  --message-filter='FILTER'

Replace the following:

SUBSCRIPTION_ID: the ID of the subscription to create
TOPIC_ID: the ID of the topic to attach to the subscription
PUSH_ENDPOINT: the URL of the server that the push subscriber runs on
FILTER: an expression in the filtering syntax

REST

To create a subscription with a filter, use the projects.subscriptions.create method.

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer $(gcloud auth print-access-token)

Replace the following:

PROJECT_ID: the project ID for the project to create the subscription in
SUBSCRIPTION_ID: the ID of the subscription to create

To create a pull subscription with a filter, specify the filter in the request body:

{
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  "filter": "FILTER"
}

Replace the following:

PROJECT_ID: the project ID for the project with the topic
TOPIC_ID: the ID of the topic to attach to the subscription
FILTER: an expression in the filtering syntax

To create a push subscription with a filter, specify the push endpoint and the filter in the request body:

{
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  "pushConfig": {
    "pushEndpoint": "PUSH_ENDPOINT"
  },
  "filter": "FILTER"
}

Replace the following:

PROJECT_ID: the project ID for the project with the topic
TOPIC_ID: the ID of the topic to attach to the subscription
PUSH_ENDPOINT: the URL of the server that the push subscriber runs on
FILTER: an expression in the filtering syntax

C++

Before trying this sample, follow the C++ setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C++ API reference documentation.

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string topic_id,
   std::string subscription_id) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, std::move(subscription_id))
          .FullName());
  request.set_topic(
      pubsub::Topic(project_id, std::move(topic_id)).FullName());
  request.set_filter(R"""(attributes.is-even = "false")""");
  auto sub = client.CreateSubscription(request);
  if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The subscription already exists\n";
    return;
  }
  if (!sub) throw std::move(sub).status();

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

C#

Before trying this sample, follow the C# setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub C# API reference documentation.


using Google.Cloud.PubSub.V1;
using Grpc.Core;

public class CreateSubscriptionWithFilteringSample
{
    public Subscription CreateSubscriptionWithFiltering(string projectId, string topicId, string subscriptionId, string filter)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);
        Subscription subscription = null;

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            Filter = filter
        };

        try
        {
            subscription = subscriber.CreateSubscription(subscriptionRequest);
        }
        catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
        {
            // Already exists.  That's fine.
        }
        return subscription;
    }
}

Go

The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, see the migration guide to v2. To see a list of v1 code samples, see the deprecated code samples.

Before trying this sample, follow the Go setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Go API reference documentation.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

func createWithFilter(w io.Writer, projectID, topic, subscription, filter string) error {
	// Receive messages with attribute key "author" and value "unknown".
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// filter := "attributes.author=\"unknown\""
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:   subscription,
		Topic:  topic,
		Filter: filter,
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription with filter: %v\n", sub)
	return nil
}

Java

Before trying this sample, follow the Java setup instructions in Quickstart: Using Client Libraries. For more information, see the Pub/Sub Java API reference documentation.

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

public class CreateSubscriptionWithFiltering {
  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";
    String filter = "attributes.author=\"unknown\"";

    createSubscriptionWithFilteringExample(projectId, topicId, subscriptionId, filter);
  }

  public static void createSubscriptionWithFilteringExample(

Filter messages from a subscription Stay organized with collections Save and categorize content based on your preferences.

Create a subscription with a filter

Console

gcloud

REST

C++

C#

Go

Java

Filter messages from a subscription