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

# Filter Syntax

> Filter real-time data streams with flexible JSON-based conditions.

Filters allow you to receive only messages that match specific criteria. This reduces bandwidth and allows you to focus on relevant data.

## Filter Structure

Filters are JSON objects with the following structure:

```json theme={null}
{
  "field": "status",
  "operator": "=",
  "value": "active"
}
```

## Field Paths

Use dot notation to access nested fields in your data:

```json theme={null}
{
  "field": "user.profile.age",
  "operator": ">=",
  "value": 18
}
```

Examples of field paths:

* `status` - Top-level field
* `user.email` - Nested field
* `transaction.from_address` - Blockchain transaction field
* `payload.metadata.timestamp` - Deeply nested field

## Comparison Operators

### Equals (`=`)

Match exact values.

```json theme={null}
{
  "field": "blockchain",
  "operator": "=",
  "value": "ethereum"
}
```

**Use cases:**

* Filter by specific blockchain
* Match exact addresses
* Filter by transaction type

**Example:** Only Ethereum transactions

```json theme={null}
{
  "field": "blockchain",
  "operator": "=",
  "value": "ethereum"
}
```

### Not Equals (`!=`)

Exclude specific values.

```json theme={null}
{
  "field": "status",
  "operator": "!=",
  "value": "pending"
}
```

**Use cases:**

* Exclude failed transactions
* Filter out specific addresses
* Remove test data

**Example:** Exclude zero-value transfers

```json theme={null}
{
  "field": "value",
  "operator": "!=",
  "value": "0"
}
```

### Greater Than (`>`)

Match values greater than the specified value.

```json theme={null}
{
  "field": "block_number",
  "operator": ">",
  "value": 18000000
}
```

**Use cases:**

* Filter by block number ranges
* Minimum transaction values
* Time-based filtering

**Example:** Large transactions only (> 1 ETH in wei)

```json theme={null}
{
  "field": "value",
  "operator": ">",
  "value": "1000000000000000000"
}
```

### Greater Than or Equal (`>=`)

Match values greater than or equal to the specified value.

```json theme={null}
{
  "field": "gas_price",
  "operator": ">=",
  "value": 30
}
```

**Use cases:**

* Minimum thresholds
* Starting from a specific block
* Value ranges (inclusive)

**Example:** Transactions from block 18M onwards

```json theme={null}
{
  "field": "block_number",
  "operator": ">=",
  "value": 18000000
}
```

### Less Than (`<`)

Match values less than the specified value.

```json theme={null}
{
  "field": "gas_used",
  "operator": "<",
  "value": 21000
}
```

**Use cases:**

* Maximum thresholds
* Filter small transactions
* Gas optimization analysis

**Example:** Low gas transactions

```json theme={null}
{
  "field": "gas_used",
  "operator": "<",
  "value": 50000
}
```

### Less Than or Equal (`<=`)

Match values less than or equal to the specified value.

```json theme={null}
{
  "field": "confirmations",
  "operator": "<=",
  "value": 6
}
```

**Use cases:**

* Maximum thresholds (inclusive)
* Confirmation tracking
* Value caps

**Example:** Recent blocks (last 100)

```json theme={null}
{
  "field": "block_number",
  "operator": "<=",
  "value": 18000100
}
```

## Special Operators

### Exists

Check if a field exists or doesn't exist in the data.

**Check if field exists:**

```json theme={null}
{
  "field": "to_address",
  "operator": "exists",
  "value": true
}
```

**Check if field doesn't exist:**

```json theme={null}
{
  "field": "error",
  "operator": "exists",
  "value": false
}
```

**Use cases:**

* Filter contract creations (no `to_address`)
* Exclude failed transactions (no `error` field)
* Find records with optional fields

**Example:** Only contract deployments

```json theme={null}
{
  "field": "to_address",
  "operator": "exists",
  "value": false
}
```

**Example:** Only successful transactions

```json theme={null}
{
  "field": "error",
  "operator": "exists",
  "value": false
}
```

### In

Check if a value matches any value in an array or data source.

**Using an array of values:**

```json theme={null}
{
  "field": "blockchain",
  "operator": "in",
  "value": ["ethereum", "polygon", "arbitrum"]
}
```

**Using a data source (not supported in websockets):**

```json theme={null}
{
  "field": "contract_address",
  "operator": "in",
  "data_source_id": "whitelisted_addresses"
}
```

<Warning>
  The `data_source_id` parameter is not currently supported for websocket streams. Use the `value` array instead.
</Warning>

**Use cases:**

* Filter multiple blockchains
* Whitelist addresses
* Match multiple statuses
* Check against large lists (with data sources)

**Example:** EVM L2 chains only

```json theme={null}
{
  "field": "blockchain",
  "operator": "in",
  "value": ["arbitrum", "optimism", "base", "polygon"]
}
```

**Example:** Specific DEX contracts

```json theme={null}
{
  "field": "contract_address",
  "operator": "in",
  "value": [
    "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
    "0xd9e1ce17f2641f24ae83637ab66a2cca9c378b9f",
    "0x1111111254fb6c44bac0bed2854e76f90643097d"
  ]
}
```

## Compound Filters

Combine multiple conditions with AND/OR logic.

### AND Logic

All conditions must be true.

```json theme={null}
{
  "op": "AND",
  "conditions": [
    {
      "field": "blockchain",
      "operator": "=",
      "value": "ethereum"
    },
    {
      "field": "value",
      "operator": ">",
      "value": "1000000000000000000"
    }
  ]
}
```

**Example:** Large Ethereum transactions to specific address

```json theme={null}
{
  "op": "AND",
  "conditions": [
    {
      "field": "blockchain",
      "operator": "=",
      "value": "ethereum"
    },
    {
      "field": "to_address",
      "operator": "=",
      "value": "0x..."
    },
    {
      "field": "value",
      "operator": ">=",
      "value": "1000000000000000000"
    }
  ]
}
```

### OR Logic

At least one condition must be true.

```json theme={null}
{
  "op": "OR",
  "conditions": [
    {
      "field": "type",
      "operator": "=",
      "value": "swap"
    },
    {
      "field": "type",
      "operator": "=",
      "value": "transfer"
    }
  ]
}
```

**Example:** Multiple transaction types

```json theme={null}
{
  "op": "OR",
  "conditions": [
    {
      "field": "method",
      "operator": "=",
      "value": "transfer"
    },
    {
      "field": "method",
      "operator": "=",
      "value": "transferFrom"
    },
    {
      "field": "method",
      "operator": "=",
      "value": "mint"
    }
  ]
}
```

### Nested AND/OR

Combine AND and OR logic for complex queries.

```json theme={null}
{
  "op": "AND",
  "conditions": [
    {
      "field": "blockchain",
      "operator": "in",
      "value": ["ethereum", "polygon"]
    },
    {
      "op": "OR",
      "conditions": [
        {
          "field": "value",
          "operator": ">",
          "value": "1000000000000000000"
        },
        {
          "field": "gas_price",
          "operator": ">=",
          "value": 100
        }
      ]
    }
  ]
}
```

**Example:** High-value OR high-gas transactions on specific chains

```json theme={null}
{
  "op": "AND",
  "conditions": [
    {
      "field": "blockchain",
      "operator": "in",
      "value": ["ethereum", "base", "arbitrum"]
    },
    {
      "field": "to_address",
      "operator": "exists",
      "value": true
    },
    {
      "op": "OR",
      "conditions": [
        {
          "field": "value",
          "operator": ">",
          "value": "5000000000000000000"
        },
        {
          "field": "gas_price",
          "operator": ">=",
          "value": 50
        }
      ]
    }
  ]
}
```

## Complete Examples

### Example 1: DeFi Swap Monitoring

Monitor large swaps on Uniswap V3:

```json theme={null}
{
  "op": "AND",
  "conditions": [
    {
      "field": "contract_address",
      "operator": "=",
      "value": "0x68b3465833fb72a70ecdf485e0e4c7bd8665fc45"
    },
    {
      "field": "value",
      "operator": ">",
      "value": "10000000000000000000"
    },
    {
      "field": "status",
      "operator": "=",
      "value": "success"
    }
  ]
}
```

### Example 2: NFT Transfer Tracking

Track NFT transfers for specific collections:

```json theme={null}
{
  "op": "AND",
  "conditions": [
    {
      "field": "token_standard",
      "operator": "in",
      "value": ["ERC721", "ERC1155"]
    },
    {
      "field": "contract_address",
      "operator": "in",
      "value": [
        "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
        "0x60e4d786628fea6478f785a6d7e704777c86a7c6"
      ]
    },
    {
      "field": "from_address",
      "operator": "!=",
      "value": "0x0000000000000000000000000000000000000000"
    }
  ]
}
```

### Example 3: Multi-Chain Whale Watching

Monitor large transactions across multiple chains:

```json theme={null}
{
  "op": "AND",
  "conditions": [
    {
      "field": "blockchain",
      "operator": "in",
      "value": ["ethereum", "bsc", "polygon", "arbitrum", "optimism"]
    },
    {
      "op": "OR",
      "conditions": [
        {
          "field": "value_usd",
          "operator": ">=",
          "value": 1000000
        },
        {
          "op": "AND",
          "conditions": [
            {
              "field": "token_type",
              "operator": "=",
              "value": "ERC20"
            },
            {
              "field": "amount_usd",
              "operator": ">=",
              "value": 500000
            }
          ]
        }
      ]
    }
  ]
}
```

### Example 4: Failed Transaction Analysis

Find failed transactions with high gas:

```json theme={null}
{
  "op": "AND",
  "conditions": [
    {
      "op": "OR",
      "conditions": [
        {
          "field": "status",
          "operator": "=",
          "value": "failed"
        },
        {
          "field": "error",
          "operator": "exists",
          "value": true
        }
      ]
    },
    {
      "field": "gas_used",
      "operator": ">",
      "value": 100000
    },
    {
      "field": "gas_price",
      "operator": ">=",
      "value": 30
    }
  ]
}
```

## Best Practices

1. **Be specific**: Use the most restrictive filters possible to reduce data transfer
2. **Use IN for multiple values**: More efficient than multiple OR conditions for the same field
3. **Combine with EXISTS**: Check field existence before comparing values
4. **Test incrementally**: Start with simple filters and add complexity gradually
5. **Monitor performance**: Complex nested filters may impact latency

## Related Documentation

<CardGroup cols={2}>
  <Card title="Websocket Streams" icon="bolt" href="/datastreams/websockets">
    Use filters with websocket streams
  </Card>

  <Card title="Stream Transformations" icon="bullseye" href="/datastreams/transformations">
    Use filters with stream transformations
  </Card>
</CardGroup>