Filtering

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:

array

All conditions in this array must be satisfied (AND logic).

array

At least one condition in this array must be satisfied (OR logic).

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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchValue

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            FieldCondition(
                key="city",
                match=MatchValue(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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchAny

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            FieldCondition(
                key="country",
                match=MatchAny(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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, Range

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            FieldCondition(
                key="population",
                range=Range(
                    gte=1000000,
                    lt=5000000
                )
            )
        ]
    ),
    limit=10
)

number

Greater than (exclusive).

number

Greater than or equal to (inclusive).

number

Less than (exclusive).

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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, GeoRadius, GeoPoint

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            FieldCondition(
                key="location",
                geo_radius=GeoRadius(
                    center=GeoPoint(lon=13.4050, lat=52.5200),
                    radius=10000.0  # in meters
                )
            )
        ]
    ),
    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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, GeoBoundingBox, GeoPoint

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            FieldCondition(
                key="location",
                geo_bounding_box=GeoBoundingBox(
                    top_left=GeoPoint(lon=13.0, lat=53.0),
                    bottom_right=GeoPoint(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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchValue, Range

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            FieldCondition(key="country", match=MatchValue(value="Germany")),
            FieldCondition(key="population", range=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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchValue

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        should=[
            FieldCondition(key="city", match=MatchValue(value="Berlin")),
            FieldCondition(key="city", match=MatchValue(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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchValue

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must_not=[
            FieldCondition(key="country", match=MatchValue(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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, IsEmptyCondition

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            IsEmptyCondition(is_empty=PayloadField(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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, IsNullCondition

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            IsNullCondition(is_null=PayloadField(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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, HasIdCondition

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            HasIdCondition(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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchValue

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            FieldCondition(
                key="metadata.author.name",
                match=MatchValue(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
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchAny, MatchValue, Range

client = QdrantClient(url="http://localhost:6333")

results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[
            FieldCondition(
                key="country",
                match=MatchAny(any=["Germany", "France"])
            ),
            FieldCondition(
                key="population",
                range=Range(gte=500000, lt=2000000)
            )
        ],
        must_not=[
            FieldCondition(
                key="city",
                match=MatchValue(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

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

Getting Started

Core Concepts

Working with Data

Advanced Features

Deployment

Operations

Filter Structure

Basic Field Matching

Match Single Value

Match Any of Multiple Values

Range Filters

Greater Than / Less Than

Geo Filters

Geo Radius Filter

Geo Bounding Box Filter

Combining Multiple Conditions

AND Logic (must)

OR Logic (should)

NOT Logic (must_not)

Advanced Filter Conditions

Check if Field is Empty

Check if Field is Null

Filter by Point IDs

Nested Filters

Complex Filter Example

Best Practices

​Filter Structure

​Basic Field Matching

​Match Single Value

​Match Any of Multiple Values

​Range Filters

​Greater Than / Less Than

​Geo Filters

​Geo Radius Filter

​Geo Bounding Box Filter

​Combining Multiple Conditions

​AND Logic (must)

​OR Logic (should)

​NOT Logic (must_not)

​Advanced Filter Conditions

​Check if Field is Empty

​Check if Field is Null

​Filter by Point IDs

​Nested Filters

​Complex Filter Example

​Best Practices

Filter Structure

Basic Field Matching

Match Single Value

Match Any of Multiple Values

Range Filters

Greater Than / Less Than

Geo Filters

Geo Radius Filter

Geo Bounding Box Filter

Combining Multiple Conditions

AND Logic (must)

OR Logic (should)

NOT Logic (must_not)

Advanced Filter Conditions

Check if Field is Empty

Check if Field is Null

Filter by Point IDs

Nested Filters

Complex Filter Example

Best Practices