Filter operators for collections

Many Data API commands, like Find documents, accept a filter parameter to determine which documents to return or update. The filter parameter uses one or more filter operators.

Operators

You can use the following operators in a filter. All operators are case-sensitive.

Equal (default)

The $eq operator matches documents where the specified field is equal to the specified value.

This is the default when you do not specify an operator.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"number_of_pages": {"$eq": 300}})

print(result)

Not equal

The $ne operator matches documents where the specified field is not equal to the specified value.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"number_of_pages": {"$ne": 300}})

print(result)

Greater than

The $gt operator matches documents where the specified field is greater than the specified value.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"number_of_pages": {"$gt": 300}})

print(result)

Greater than or equal

The $gte operator matches documents where the specified field is greater than or equal to the specified value.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"number_of_pages": {"$gte": 300}})

print(result)

Less than

The $lt operator matches documents where the specified field is less than the specified value.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"number_of_pages": {"$lt": 300}})

print(result)

Less than or equal

The $lte operator matches documents where the specified field is less than or equal to the specified value.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"number_of_pages": {"$lte": 300}})

print(result)

In

The $in operator matches documents where the field contains any of the specified values. For fields that store an array, the operator matches documents where the array contains any of the specified values.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"genres": {"$in": ["Fantasy", "Romance"]}})

print(result)

If you have only one value to match, you can use the single value instead of an array, like { "$in": "VALUE" }.

Not in

The $nin operator matches documents where the field doesn’t contain any of the specified values.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"genres": {"$nin": ["Fantasy", "Romance"]}})

print(result)

Exists

The $exists operator matches documents that have the specified field, even if the field value is null.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"borrower": {"$exists": True}})

print(result)

All

For fields that store an array, the $all operator matches documents where the array contains all of the specified values.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"genres": {"$all": ["Fantasy", "Romance"]}})

print(result)

Size

For fields that store an array, the $size operator matches documents where the array has the specified number of elements.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"genres": {"$size": 3}})

print(result)

Not

The $not operator returns documents that don’t match the condition of the clause.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"$not": {"is_checked_out": False}})

print(result)

Combine operators (And, Or)

The $and operator joins clauses with a logical AND. Only documents that match the conditions of all clauses are returned.

The $or operator joins clauses with a logical OR. Documents that match the condition of any of the clauses are returned.

You can use $and and $or separately or together. If you want to match multiple flexible conditions, use $and and $or to together in the same filter:

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one(
    {
        "$and": [
            {"$or": [{"is_checked_out": False}, {"number_of_pages": {"$lt": 300}}]},
            {
                "$or": [
                    {"genres": {"$in": ["Fantasy", "Romance"]}},
                    {"publication_year": {"$gte": 2002}},
                ]
            },
        ]
    }
)

print(result)

To filter on a range of values, use $and with $lt/$lte and $gt/$gte:

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one(
    {
        "$and": [
            {"number_of_pages": {"$lt": 300}},
            {"number_of_pages": {"$gte": 200}},
        ]
    }
)

print(result)

Filter nested fields

Use dot notation to filter nested fields. For example, field.subfield.subsubfield.

python
from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Find a document
result = collection.find_one({"metadata.language": {"$eq": "French"}})

print(result)

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com