---
source_url: https://www.pubnub.com/docs/pub-sub/subscribe/filter-received-messages
title: Filter received messages
updated_at: 2026-09-30T07:20:08.000Z
---

# Filter received messages

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

This guide shows you how to set a [subscribe filter](https://www.pubnub.com/docs/pub-sub/subscribe/overview.md#filter-on-the-server) expression on a PubNub client. The server then discards a non-matching message before it reaches that client.

* Set a filter expression when you create a client.
* Put a value the filter can read into the message payload or into `meta`.
* Exclude the messages your own client published.
* Sample a percentage of a high-volume stream.

Every call on this page needs an SDK instance initialized with your subscribe key, and the Stream Controller add-on enabled on your keyset in the [Admin Portal](https://admin.pubnub.com/). If you don't have a keyset yet, start with [Set up your account](https://www.pubnub.com/docs/architecture/authentication/set-up-your-account.md). This page covers the calls that set an expression. For the expression language itself, the operators, data types, and precedence, refer to [Subscribe filter expressions](https://www.pubnub.com/docs/pub-sub/subscribe/subscribe-filter-expressions.md).

## Set a filter expression

A subscribe filter is a property of the client, not of one subscription or channel, so it applies to every channel and channel group that client subscribes to. Set it before your first subscribe call.

### JavaScript

```javascript
const pubnub = new PubNub({
  subscribeKey: 'mySubscribeKey',
  userId: 'myUserId',
});

pubnub.setFilterExpression('meta.priority == "high"');
```

### Swift

```swift
let config = PubNubConfiguration(
  subscribeKey: "mySubscribeKey",
  userId: "myUserId",
  filterExpression: "meta.priority == \"high\""
)
let pubnub = PubNub(configuration: config)
```

### Java

```java
PNConfiguration pnConfiguration = PNConfiguration.builder(new UserId("myUserId"), "mySubscribeKey").build();
pnConfiguration.setFilterExpression("meta.priority == \"high\"");

PubNub pubnub = PubNub.create(pnConfiguration);
```

### Kotlin

```kotlin
val pnConfiguration = PNConfiguration.builder(UserId("myUserId"), "mySubscribeKey").build()
pnConfiguration.filterExpression = "meta.priority == \"high\""

val pubnub = PubNub.create(pnConfiguration)
```

### Python

```python
pnconfig = PNConfiguration()
pnconfig.subscribe_key = "mySubscribeKey"
pnconfig.user_id = "myUserId"
pnconfig.filter_expression = 'meta.priority == "high"'

pubnub = PubNub(pnconfig)
```

### C#

```csharp
PNConfiguration pnConfiguration = new PNConfiguration(new UserId("myUserId"));
pnConfiguration.SubscribeKey = "mySubscribeKey";
pnConfiguration.FilterExpression = "meta.priority == \"high\"";

Pubnub pubnub = new Pubnub(pnConfiguration);
```

### PHP

```php
$pnconfig = new PNConfiguration();
$pnconfig->setSubscribeKey("mySubscribeKey");
$pnconfig->setUserId("myUserId");
$pnconfig->setFilterExpression('meta.priority == "high"');

$pubnub = new PubNub($pnconfig);
```

### Objective-C

```objectivec
PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@"myPublishKey"
                                                                 subscribeKey:@"mySubscribeKey"
                                                                       userID:@"myUserId"];
self.client = [PubNub clientWithConfiguration:configuration];
self.client.filterExpression = @"meta.priority == \"high\"";
```

Whether you can change the expression again on a client that's already subscribing depends on the SDK. JavaScript's `setFilterExpression()` and Objective-C's `filterExpression` property both work on an already-created client and take effect on its next subscribe request. Java, Kotlin, PHP, and Swift fix the filter at configuration time. Their configuration becomes immutable once it creates a client, so changing the filter means building a new client with a new expression. Swift's legacy `subscribe(filterOverride:)` call is the one exception, overriding the filter for a single subscribe request. Check your SDK's configuration reference before assuming either behavior.

## Make a value filterable

A filter expression can read only two places: the message payload, as `data.*`, and the metadata attached with [meta](https://www.pubnub.com/docs/pub-sub/publish/send-different-message-types.md#attach-metadata-to-a-message) at publish time, as `meta.*`. It can't read envelope fields such as the publisher's [User ID](https://www.pubnub.com/docs/architecture/core-concepts.md#user-id), the channel name, the timetoken, or the message type. To filter on any of those, decide at publish time and put the value in `meta` or the payload yourself.

When message encryption is enabled, a subscribe filter cannot read `data.*`. `meta.*` remains unencrypted and filterable, so never put a secret in `meta`.

For the full syntax, every operator, and the data types each one accepts, refer to [Subscribe filter expressions](https://www.pubnub.com/docs/pub-sub/subscribe/subscribe-filter-expressions.md).

## Exclude your own published messages

A client's own [User ID](https://www.pubnub.com/docs/architecture/core-concepts.md#user-id) isn't addressable in a filter expression, because it's an envelope field, not part of `data.*` or `meta.*`. Publish it into `meta` yourself, then filter it out:

```javascript
await pubnub.publish({
  channel: 'updates',
  message: { text: 'Hello world' },
  meta: { publisher: pubnub.getUserId() },
});

pubnub.setFilterExpression(`meta.publisher != "${pubnub.getUserId()}"`);
```

Only the client that set this filter drops its own messages. Every other client subscribed to `updates` still receives them, because the filter is a property of the filtering client, not a rule attached to the message.

## Sample a percentage of a stream

Modulo arithmetic on a numeric field keeps roughly one message in every *N*. That cuts a high-volume stream down before it reaches the client, instead of discarding the extra messages after they arrive:

```text
meta.eventId % 10 == 0
```

This keeps about 10% of messages. The sample is only as even as `eventId`'s distribution. A sequential counter gives you exactly one in ten. A hashed or random ID only approximates it. Publish the field you intend to sample on into `meta` or the payload the same way you would any other filterable value.

## Related tasks

* [Subscribe filter expressions](https://www.pubnub.com/docs/pub-sub/subscribe/subscribe-filter-expressions.md). The full expression syntax, operators, data types, and precedence.
* [Filter on the server](https://www.pubnub.com/docs/pub-sub/subscribe/overview.md#filter-on-the-server). What a subscribe filter is, where it runs, and its design constraints.
* [Send different message types](https://www.pubnub.com/docs/pub-sub/publish/send-different-message-types.md). Attach the `meta` a filter reads.
* [Receive messages](https://www.pubnub.com/docs/pub-sub/subscribe/receive-messages.md). Create a subscription and register handlers on it.
* [Subscribe](https://www.pubnub.com/docs/pub-sub/subscribe/overview.md). The subscribe model a filter narrows.

Last updated at: 2026-09-30T07:20:08.000Z