Subscribing to Cloud Pub/Sub topics gives you some control over the types of messages you will receive.  However, there may be times when you are only interested in a small subset of messages in a particular topic.  In these cases, creating a custom subscription filter can be very helpful.

So let’s say you have a topic called “new user accounts”.  And this topic was set up to notify you about registration events.  Now, you want to add a new feature for your premium users.  Unfortunately, most of your signups are for free accounts.  So let’s say that only 10% of the messages in the topic represent premium registrations.  

So now, you have a couple of options.  First, you can read through every single message and then only do something when you find a new premium user.  But that is going to result in a lot of extra, unnecessary calls and processing.  Your second option is to filter out all the free registrations, so that you will only get messages for premium users.

Filtering works by looking at message attributes.  Attributes are key:value pairs designed to hold the message metadata.  So in order to create a filter, your messages will need to have one or more attributes set.  Note: you cannot filter messages based upon the message data, only by attributes.

So in our “new user accounts” example, you could add an attribute to every message where the key was named “type” and the value contained either “free” or “premium”.  Then you could create a subscription with a filter that said only deliver messages where “type=premium”.  Now you will only have to process premium messages.

Both pull and push subscriptions can have filters.  To filter messages, you write an expression that evaluates each message’s attributes. You can either match on key name or value.  So you can do things like filter out all messages missing a “language” attribute.  Or you can filter out messages where the “language” attribute is not set to “english”.

Also you should note that filters are set on the subscription level, not on the topic level.  So creating a filter does not change the content of a topic.  Nor does creating a filter in one subscription affect the others.  You can have many different messages in a single topic, and each subscription can have it’s own unique filter.

Let me give you a quick demonstration of how to set up a subscription filter.  I am going to create a topic that will contain messages in different languages.  Then I will create a subscription with a filter for messages that are written in english.

First, I have to create the topic.  I’ll name this one “topic-1”.  And I don’t have to configure anything special for the topic.

Next, I need to create a subscription.  I’ll name it “subscription-1”.  And then I need to pick the topic I just created.  Now I need to scroll down and specify the filter.

Remember that you can only filter by attributes.  In this case, our messages are going to have an attribute called “language”.  And this is going to contain a standard ISO language code.  For example, “en-US” for US english.  Now, since I only want to only receive messages in US English, then the filter needs to be: attributes.language = "en-US".

And then I can confirm creation by clicking on “create”.

So now, I have a topic and a subscription with a filter.  Let me verify that the filter works by sending two messages.

The first message I am going to send is going to be in English.  And the second message will be in French.

Let me type in an English message.  And I need to be sure to add the language attribute.

For this next one, I’ll type a message in French.

Now if I check my subscription, I should only get the first message and not the second one.  

As you can see, we only received the English message.  If I pull again, I still just see the one message.  

So now you know how to create a filter on your subscriptions.  You can make your filters a lot more complicated if you wish.   For example, you can filter by multiple attributes.  But this demo should be enough to get you started.