> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Políticas de filtro

> Selecione notificações por igualdade, prefixo, sufixo, exclusão, presença e comparação numérica.

O filtro escolhe quais mensagens publicadas geram uma entrega para a assinatura. Coloque valores de roteamento no mapa `attributes`. Um campo `event` dentro do texto JSON de `message` não se torna um atributo filtrável.

<span id="a-complete-example" />

## Um exemplo completo

Esta política aceita pedidos de produção de valor mínimo 100 e menor que 1.000, salvo quando há um atributo `test`:

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

Estes atributos de publicação correspondem:

```json theme={null}
{
  "event": { "type": "String", "value": "order.paid" },
  "environment": { "type": "String", "value": "production" },
  "amount": { "type": "Number", "value": "149.50" }
}
```

Valores de atributos são strings mesmo com tipo `Number`. Operandos numéricos do filtro são números JSON. Mantenha as representações distintas.

| Alteração nos atributos | Resultado | Motivo |
| - | - | - |
| Nenhuma | Corresponde | Todas as condições são satisfeitas. |
| `event` vira `order.refunded` | Não corresponde | Nenhuma alternativa de evento corresponde. |
| `amount` vira `1000` | Não corresponde | O limite superior é exclusivo. |
| Remover `amount` | Não corresponde | Comparações numéricas exigem presença. |
| Adicionar `test` com valor `false` | Não corresponde | `exists: false` verifica ausência, não valor. |
| Adicionar atributo `customer` não relacionado | Corresponde | Atributos extras são ignorados. |

<span id="how-conditions-combine" />

## Como combinar condições

Todos os atributos nomeados devem corresponder: **AND entre nomes de atributos**. Na lista de um atributo, basta uma alternativa: **OR entre alternativas**. Dentro de um único operador `numeric`, todas as comparações devem ser satisfeitas.

Nomes e comparações textuais distinguem maiúsculas. Uma política vazia `{}` aceita todas as mensagens, inclusive sem atributos. Todos os operadores exceto `exists: false` exigem presença. Atributos ausentes não correspondem a exclusões como `anything-but`.

<span id="supported-matchers" />

## Comparações disponíveis

Os exemplos mostram a lista de alternativas de um atributo.

| Comparação | Exemplo | Comportamento |
| - | - | - |
| String exata | `["critical", "error"]` | Valor igual a uma das strings. |
| Prefixo | `[{"prefix": "order."}]` | Começa com `order.`. |
| Sufixo | `[{"suffix": ".failed"}]` | Termina com `.failed`. |
| Exclusão | `[{"anything-but": ["debug", "trace"]}]` | Valor presente diferente dos itens. Também aceita uma string ou número. |
| Presença | `[{"exists": true}]` | Atributo existe, inclusive com string vazia. |
| Ausência | `[{"exists": false}]` | Atributo ausente. |
| Intervalo numérico | `[{"numeric": [">=", 100, "<", 1000]}]` | Valor numérico que satisfaz ambas as comparações. |
| Igualdade numérica | `[{"numeric": ["=", 100]}]` | Compara números: `100` e `100.0` correspondem. |

Operadores numéricos: `=`, `<`, `<=`, `>` e `>=`. Escreva operador e operando; repita pares para um intervalo. Valores que não podem ser interpretados como números não correspondem. O avaliador atual interpreta o valor independentemente do tipo declarado; use `Number` em dados numéricos para clareza.

Números JSON simples também são alternativas exatas, mas comparam a representação textual. `[100]` corresponde a `"100"`, não a `"100.0"`. Use `numeric` para igualdade matemática.

Prefixos e sufixos comparam texto literal. Não há curingas, expressões regulares, filtros aninhados do corpo, atributos com arrays ou operadores que ignorem maiúsculas. Não presuma suporte a todos os operadores SNS.

<span id="combining-presence-and-exclusion" />

## Combinar presença e exclusão

Para aceitar um valor diferente de `test`, inclusive quando o atributo estiver ausente, inclua ambas as alternativas:

```json theme={null}
{
  "environment": [
    { "anything-but": "test" },
    { "exists": false }
  ]
}
```

Dois itens na lista não exigem prefixo e sufixo ao mesmo tempo: significam OR. Publique um atributo de roteamento separado com a classificação combinada quando precisar dessa condição.

<span id="set-or-clear-a-policy" />

## Definir ou limpar uma política

<Tabs>
  <Tab title="Console">
    Abra **Subscriptions** no tópico e selecione **Subscribe**. Cole um objeto JSON em **Filter policy** na criação. Deixe vazio para receber tudo. O formulário verifica sintaxe; a API valida operadores e limites.

    Abra **Filter policy** na assinatura existente para inspecionar; use a API para substituir ou limpar.
  </Tab>

  <Tab title="API">
    Defina `filter_policy` ao criar ou substitua com PATCH:

    ```http theme={null}
    PATCH /v1/topics/{topic_id}/subscriptions/{subscription_id}
    Content-Type: application/json
    ```

    ```json theme={null}
    {
      "filter_policy": {
        "severity": ["critical", "error"]
      }
    }
    ```

    PATCH substitui a política inteira, sem mesclar nomes de atributos. Envie `{"filter_policy": {}}` para remover o filtro. Omitir o campo preserva a política.
  </Tab>

  <Tab title="CLI">
    Salve a solicitação JSON da aba API como `request-1.json`. Defina `SUBSCRIPTION_ID`, `TOPIC_ID` com os UUIDs dos recursos. Use sua conta e região configuradas.

    ```bash theme={null}
    basaltic notifications subscription update "$TOPIC_ID" "$SUBSCRIPTION_ID" --from-file request-1.json
    ```
  </Tab>

  <Tab title="Go">
    Salve a solicitação JSON da aba API como `request-1.json`. Defina `SUBSCRIPTION_ID`, `TOPIC_ID` com os UUIDs dos recursos. Configure credenciais, conta e região pelas variáveis de ambiente do SDK.

    ```go theme={null}
    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)
    	}
    }
    ```
  </Tab>
</Tabs>

<span id="limits-and-validation" />

## Limites e validação

| Item | Limite |
| - | - |
| Nomes de atributos por filtro | 20 |
| Alternativas por atributo | 1–50 |
| Valores em `anything-but` | 1–50 |
| Atributos por mensagem publicada | 20 |
| Nome do atributo publicado | 1–256 bytes |
| Valor do atributo publicado | Até 1.024 bytes |
| Tipos de atributo publicado | `String` ou `Number` |

Cada objeto deve ter exatamente um operador. Prefixos e sufixos não podem ser vazios. Listas numéricas precisam de pares completos operador/número. Alternativas vazias e operadores desconhecidos são inválidos. Políticas malformadas retornam HTTP `400` com `NOTIFICATION_INVALID_FILTER_POLICY`.

Uma assinatura filtrada não tem registro de entrega nem tentativa com falha. Se houver menos entregas que o esperado, verifique confirmação, nomes e valores exatos e todas as condições. Mudanças afetam decisões de distribuição posteriores; não criam nem removem registros existentes retroativamente.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.