Filter policy constraints

When you create a filter policy for an Amazon SNS subscription, it's important to understand how the keys in the policy are counted. The key aspects to keep in mind are:

1. Parent Keys – The parent keys are the top-level keys in the filter policy. These are the keys for which you specify values or constraints.

2. Attribute Names – The parent keys are considered the attribute names in the filter policy. The values or constraints you specify for these keys will be applied to the corresponding attributes in the message payload.

3. Valid Values – The values specified for the parent keys must be either a string, an array of strings, or a number. If the value is an object (for example, a JSON object), it will not be counted as a valid key in the filter policy.

Let's consider the following example filter policy:

{
  "state": ["SUCCESS"],
  "severity": [{ "exists": true }],
  "message": [{ "exists": true }],
  "finding": {
    "standard_control": [{ "exists": true }],
    "region": [{ "exists": true }],
    "account": [{ "exists": true }]
  }
}

In this example, the following keys are counted as part of the filter policy:

• state

• severity

• message

• standard_control

• region

• account

The key finding is not counted, as it contains a JSON object as its value, rather than a string, array of strings, or a number.

Another example:

{
  "key_a": {
    "key_b": {
      "key_c": {
        "key_d": ["value_one", "value_two", "value_three", "value_four"]
      }
    },
    "key_e": {
      "key_f": ["value_one", "value_two", "value_three"]
    }
  }
}        

In this case, only the keys key_d and key_f are counted as part of the filter policy, as they have values assigned to them that are either a string or an array of strings. The parent keys key_a, key_b, and key_c are not counted, as they contain nested JSON objects as their values.

Common policy constraints

• String Matching – For string matching in the filter policy, the comparison is case-sensitive.

• Numeric Matching – For numeric matching, the value can range from -10⁹ to 10⁹ (-1 billion to 1 billion), with five digits of accuracy after the decimal point.

• Filter Policy Complexity – For the complexity of the filter policy, the total combination of values must not exceed 150. To calculate the total combination, multiply the number of values in each array in the filter policy.

Consider the following example policy:

{
   "key_a": ["value_one", "value_two", "value_three"],
   "key_b": ["value_one"],
   "key_c": ["value_one", "value_two"]
}            

In this policy:

• The first array has 3 values

• The second array has 1 value

• The third array has 2 values

The total combination is calculated as follows:

• 3 x 1 x 2 = 6

Filter policy syntax

The JSON of the filter policy can contain the following:

• Strings enclosed in quotation marks

• Numbers

• The keywords true, false, and null, without quotation marks

When using the Amazon SNS API, you must pass the JSON of the filter policy as a valid UTF-8 string.

Filter policy limits

• The maximum size of a filter policy is 256 KB.

• By default, you can have up to 200 filter policies per topic, and 10,000 filter policies per AWS account.

• This policy limit would not stop Amazon SQS queue subscriptions from being created with the Subscribe API. However, it will fail when you attach the filter policy in the Subscribe API call (or the SetSubscriptionAttributes API call).

• To increase this quota, you can use AWS Service Quotas.

Policy constraints for attribute-based filtering

• Attribute-based filtering is the default option. FilterPolicyScope is set to MessageAttributes in the subscription.

• Amazon SNS doesn't accept a nested filter policy for attribute-based filtering.

• Amazon SNS compares policy properties only to message attributes that have the following data types:

  • String

  • String.Array

    Important

    Passing objects in arrays is not recommended because it may yield unexpected results due to the nesting, which is not supported by attribute-based filtering. Use payload-based filtering for nested policies.

  • Number

• Amazon SNS ignores message attributes with the Binary data type.

• A filter policy can have a maximum of five attribute names.

Policy constraints for payload-based filtering

Amazon SNS aaccepts a nested filter policy for payload-based filtering. To calculate the total combination of values in the filter policy, multiply the number of values in each nested array.

Consider the following example policy:

{
"key_a": {
    "key_b": {
        "key_c": ["value_one", "value_two", "value_three", "value_four"]
        }
    },
"key_d": {
    "key_e": ["value_one", "value_two", "value_three"]
    }
}

In this policy:

• The first array has four values in a three-level nested key.

• The second has three values in a two-level nested key.

The total combination is calculated as follows:

• 4 x 3 x 3 x 2 = 72

Policy limits

A filter policy can have a maximum of five parent keys (top-level keys). For a nested policy, only the parent keys are counted towards the five key limit.

Numeric range

For numeric matching in the filter policy, the value can range from -10⁹ to 10⁹ (-1 billion to 1 billion), with five digits of accuracy after the decimal point.

Switching to payload-based filtering

To switch from attribute-based (default) to payload-based filtering, you must set the FilterPolicyScope to MessageBody in the subscription.