Filter policies

A subscription filter selects which published messages produce a delivery for that subscription. Put routing values in the publication’s attributes map. Putting an event field inside the JSON text of message does not make it a filterable attribute.

A complete example

This subscription policy accepts production orders worth at least 100 and less than 1,000, unless the publication carries a test attribute:

{
  "event": ["order.created", "order.paid"],
  "environment": ["production"],
  "amount": [{ "numeric": [">=", 100, "<", 1000] }],
  "test": [{ "exists": false }]
}

These publication attributes match:

{
  "event": { "type": "String", "value": "order.paid" },
  "environment": { "type": "String", "value": "production" },
  "amount": { "type": "Number", "value": "149.50" }
}

Attribute values are strings even when their type is Number. Numeric matcher operands are JSON numbers. Keep those two representations distinct.

Change to the example attributes	Result	Reason
No change	Match	Every named attribute condition succeeds.
`event` becomes `order.refunded`	No match	Neither event alternative matches.
`amount` becomes `1000`	No match	The upper bound is exclusive.
Remove `amount`	No match	Numeric comparisons require a present attribute.
Add `test` with value `false`	No match	`exists: false` tests absence, not the value.
Add an unrelated `customer` attribute	Match	Extra attributes are ignored.

How conditions combine

Every attribute named by a policy must match: AND across attribute names. Within one attribute’s array, any alternative can match: OR across alternatives. Inside a single numeric operator, every comparison must succeed. Names and string matches are case-sensitive. An empty policy {} matches all messages, including messages with no attributes. Every matcher except exists: false requires that the attribute be present. A missing attribute therefore does not match an exclusion such as anything-but.

Supported matchers

The examples below show the alternatives array for one attribute.

Matcher	Example	Behavior
Exact string	`["critical", "error"]`	Value equals either string.
Prefix	`[{"prefix": "order."}]`	Value starts with `order.`.
Suffix	`[{"suffix": ".failed"}]`	Value ends with `.failed`.
Exclusion	`[{"anything-but": ["debug", "trace"]}]`	Present value equals neither item. A single string or number is also accepted.
Presence	`[{"exists": true}]`	Attribute exists, including an empty string value.
Absence	`[{"exists": false}]`	Attribute is absent.
Numeric range	`[{"numeric": [">=", 100, "<", 1000]}]`	Value parses as a number and satisfies both comparisons.
Numeric equality	`[{"numeric": ["=", 100]}]`	Compares numerically, so `100` and `100.0` both match.

Supported numeric operators are =, <, <=, >, and >=. Write an operator followed by its numeric operand; repeat pairs to form a range. A value that cannot be parsed as a number does not match numeric conditions. The current evaluator parses the value for numeric comparisons regardless of its declared attribute type; use Number for numeric data for clarity. Bare JSON numbers are also accepted as exact alternatives, but they compare their string representation. [100] matches the attribute value "100", not "100.0". Use numeric for mathematical equality. A prefix or suffix matches literal text. There are no wildcards, regular expressions, nested body matching, array-valued message attributes, or case-insensitive operators. Do not assume every SNS filter operator is supported.

Combining presence and exclusion

To accept a value other than test, including publications where the attribute is absent, include both alternatives:

{
  "environment": [
    { "anything-but": "test" },
    { "exists": false }
  ]
}

To require a prefix and a suffix on the same value, two entries in the array will not work: they mean OR. Publish a separate routing attribute with the combined classification if your application needs that condition.

Set or clear a policy

Console
API
CLI
Go

Open a topic’s Subscriptions tab and select Subscribe. Paste a JSON object into Filter policy on the creation page. Leave it empty to receive every message. The form checks JSON syntax; the API validates operators and limits.Open an existing subscription’s Filter policy tab to inspect its policy; use the API to replace or clear it.

Set filter_policy when creating a subscription, or replace it with PATCH:

PATCH /v1/topics/{topic_id}/subscriptions/{subscription_id}
Content-Type: application/json

{
  "filter_policy": {
    "severity": ["critical", "error"]
  }
}

PATCH replaces the complete policy; it does not merge attribute names. Send {"filter_policy": {}} to remove filtering. Omitting the field preserves the existing policy.

Save the JSON request from the API tab as request-1.json. Set SUBSCRIPTION_ID, TOPIC_ID to the resource UUIDs. Use your configured account and region.

basaltic notifications subscription update "$TOPIC_ID" "$SUBSCRIPTION_ID" --from-file request-1.json

Save the JSON request from the API tab as request-1.json. Set SUBSCRIPTION_ID, TOPIC_ID to the resource UUIDs. Configure credentials, account, and region through the SDK environment variables.

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	basaltic "github.com/basaltic-sh/sdk-go"
	"github.com/basaltic-sh/sdk-go/notifications"
)

func readJSON(path string, value any) error {
	data, err := os.ReadFile(path)
	if err != nil {
		return err
	}
	return json.Unmarshal(data, value)
}

func run() error {
	ctx := context.Background()
	cfg, err := basaltic.NewConfig(ctx)
	if err != nil {
		return err
	}
	client := notifications.New(cfg)
	var request1 notifications.UpdateSubscriptionRequest
	if err := readJSON("request-1.json", &request1); err != nil {
		return err
	}
	result1, err := client.UpdateSubscription(ctx, os.Getenv("TOPIC_ID"), os.Getenv("SUBSCRIPTION_ID"), &request1)
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", result1)
	return nil
}

func main() {
	if err := run(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

Limits and validation

Item	Limit
Attribute names in one filter	20
Alternatives per attribute	1–50
Values in an `anything-but` list	1–50
Attributes on a published message	20
Published attribute name	1–256 bytes
Published attribute value	At most 1,024 bytes
Published attribute types	`String` or `Number`

Each operator object must have exactly one operator. Prefix and suffix strings must be nonempty. Numeric lists must contain complete operator/number pairs. Empty alternatives arrays and unknown operators are invalid. Malformed policies return HTTP 400 with NOTIFICATION_INVALID_FILTER_POLICY. A filtered-out subscription has no delivery record and is not a failed attempt. If a publication reports fewer deliveries than expected, check the subscription confirmation status, exact attribute names and values, and every condition in the policy. A policy change affects fan-out decisions made after the change; it does not retroactively create or remove existing delivery records.

Get started

Products

Platform

Help

A complete example

How conditions combine

Supported matchers

Combining presence and exclusion

Set or clear a policy

Limits and validation

​A complete example

​How conditions combine

​Supported matchers

​Combining presence and exclusion

​Set or clear a policy

​Limits and validation

A complete example

How conditions combine

Supported matchers

Combining presence and exclusion

Set or clear a policy

Limits and validation