Skip to main content
Filters allow you to narrow down search results based on payload conditions. They are combined with vector similarity search to find the most relevant points that match specific criteria.

​
Filter Structure

Filters use a boolean logic structure with three main clauses:
​
must
array
All conditions in this array must be satisfied (AND logic).
​
should
array
At least one condition in this array must be satisfied (OR logic).
​
must_not
array
None of the conditions in this array should be satisfied (NOT logic).

​
Basic Field Matching

​
Match Single Value

Filter points where a field matches a specific value. 
curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "key": "city",
          "match": {
            "value": "Berlin"
          }
        }
      ]
    },
    "limit": 10
  }'

​
Match Any of Multiple Values

Filter points where a field matches any value from a list. 
curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "key": "country",
          "match": {
            "any": ["Germany", "France", "UK"]
          }
        }
      ]
    },
    "limit": 10
  }'

​
Range Filters

Filter numeric fields using range conditions.

​
Greater Than / Less Than

curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "key": "population",
          "range": {
            "gte": 1000000,
            "lt": 5000000
          }
        }
      ]
    },
    "limit": 10
  }'
​
range.gt
number
Greater than (exclusive).
​
range.gte
number
Greater than or equal to (inclusive).
​
range.lt
number
Less than (exclusive).
​
range.lte
number
Less than or equal to (inclusive).

​
Geo Filters

Filter points based on geographic location.

​
Geo Radius Filter

Find points within a radius of a geographic coordinate. 
curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "key": "location",
          "geo_radius": {
            "center": {
              "lon": 13.4050,
              "lat": 52.5200
            },
            "radius": 10000
          }
        }
      ]
    },
    "limit": 10
  }'
The radius is specified in meters. The location field must be stored as a geo point with lon and lat values.

​
Geo Bounding Box Filter

Find points within a rectangular geographic area. 
curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "key": "location",
          "geo_bounding_box": {
            "top_left": {
              "lon": 13.0,
              "lat": 53.0
            },
            "bottom_right": {
              "lon": 14.0,
              "lat": 52.0
            }
          }
        }
      ]
    },
    "limit": 10
  }'

​
Combining Multiple Conditions

​
AND Logic (must)

All conditions must be satisfied. 
curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "key": "country",
          "match": {"value": "Germany"}
        },
        {
          "key": "population",
          "range": {"gte": 1000000}
        }
      ]
    },
    "limit": 10
  }'

​
OR Logic (should)

At least one condition must be satisfied. 
curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "should": [
        {
          "key": "city",
          "match": {"value": "Berlin"}
        },
        {
          "key": "city",
          "match": {"value": "Munich"}
        }
      ]
    },
    "limit": 10
  }'

​
NOT Logic (must_not)

Exclude points that match these conditions. 
curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must_not": [
        {
          "key": "country",
          "match": {"value": "Germany"}
        }
      ]
    },
    "limit": 10
  }'

​
Advanced Filter Conditions

​
Check if Field is Empty

curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "is_empty": {
            "key": "tags"
          }
        }
      ]
    },
    "limit": 10
  }'

​
Check if Field is Null

curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "is_null": {
            "key": "description"
          }
        }
      ]
    },
    "limit": 10
  }'

​
Filter by Point IDs

curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "has_id": [1, 2, 3, 5, 8]
        }
      ]
    },
    "limit": 10
  }'

​
Nested Filters

Filter on nested object properties using dot notation. 
curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "key": "metadata.author.name",
          "match": {"value": "John Doe"}
        }
      ]
    },
    "limit": 10
  }'

​
Complex Filter Example

Combine multiple filter types for complex queries. 
curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "key": "country",
          "match": {"any": ["Germany", "France"]}
        },
        {
          "key": "population",
          "range": {"gte": 500000, "lt": 2000000}
        }
      ],
      "must_not": [
        {
          "key": "city",
          "match": {"value": "Frankfurt"}
        }
      ]
    },
    "limit": 10,
    "score_threshold": 0.7
  }'
Filters are applied before vector search. Complex filters with many conditions may impact performance on large collections.

​
Best Practices

  1. Index Payload Fields: Create payload indexes for fields used frequently in filters
  2. Simple Conditions: Use simple conditions when possible for better performance
  3. Field Types: Match filter types with payload field types (string, integer, geo, etc.)
  4. Combine Wisely: Balance between filter specificity and search performance
  5. Test Performance: Profile complex filters on your dataset to ensure acceptable performance