Skip to main content

Filters

Filters let you include, or exclude, particular objects from your result set based on provided conditions.
For a list of filter operators, see the API reference page.

Filter with one condition

Add a filter to your query, to limit the result set.

    jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
filters=wvc.query.Filter.by_property("round").equal("Double Jeopardy!"),
limit=3
)

for o in response.objects:
print(o.properties)
Example response

The output is like this:

{
"data": {
"Get": {
"JeopardyQuestion": [
{
"answer": "garage",
"question": "This French word originally meant \"a place where one docks\" a boat, not a car",
"round": "Double Jeopardy!"
},
{
"answer": "Mexico",
"question": "The Colorado River provides much of the border between this country's Baja California Norte & Sonora",
"round": "Double Jeopardy!"
},
{
"answer": "Amy Carter",
"question": "On September 1, 1996 this former first daughter married Jim Wentzel at the Pond House near Plains",
"round": "Double Jeopardy!"
}
]
}
}
}

Filter with multiple conditions

To filter with two or more conditions, use And or Or to define the relationship between the conditions.

    jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
# Use & as AND
# | as OR
filters=wvc.query.Filter.by_property("round").equal("Double Jeopardy!") &
wvc.query.Filter.by_property("points").less_than(600),
limit=3
)

for o in response.objects:
print(o.properties)
Example response

The output is like this:

{
"data": {
"Get": {
"JeopardyQuestion": [
{
"answer": "Mexico",
"points": 200,
"question": "The Colorado River provides much of the border between this country's Baja California Norte & Sonora",
"round": "Double Jeopardy!"
},
{
"answer": "Amy Carter",
"points": 200,
"question": "On September 1, 1996 this former first daughter married Jim Wentzel at the Pond House near Plains",
"round": "Double Jeopardy!"
},
{
"answer": "Greek",
"points": 400,
"question": "Athenians speak the Attic dialect of this language",
"round": "Double Jeopardy!"
}
]
}
}
}

Nest filters

You can group and nest filters.

    jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
filters=wvc.query.Filter.by_property("question").like("*nest*") &
(wvc.query.Filter.by_property("points").greater_than(700) | wvc.query.Filter.by_property("points").less_than(300)),
limit=3
)

for o in response.objects:
print(o.properties)
Example response

The output is like this:

{
"data": {
"Get": {
"JeopardyQuestion": [
{
"answer": "rhinestones",
"points": 100,
"question": "Imitation diamonds, they were originally gems obtained from a certain German river",
"round": "Jeopardy!"
},
{
"answer": "Clytemnestra",
"points": 1000,
"question": "In \"Absalom! Absalom!\", it's the \"mythological\" name of Thomas Stupen's daughter, known as Clytie for short",
"round": "Double Jeopardy!"
},
{
"answer": "Ernest Hemingway",
"points": 200,
"question": "His 1926 novel \"The Sun Also Rises\" has been published in England as \"Fiesta\"",
"round": "Jeopardy!"
}
]
}
}
}
Additional information

To create a nested filter, follow these steps.

  • Set the outer operator equal to And or Or.
  • Add operands.
  • Within an operand, set operator equal to And or Or to nest a group.
  • Add operands to the nested group.

Combine filters and search operators

Filters work with search operators like nearXXX, hybrid, and bm25.

    jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.near_text(
query="fashion icons",
filters=wvc.query.Filter.by_property("points").greater_than(200),
limit=3
)

for o in response.objects:
print(o.properties)
Example response

The output is like this:

{
"data": {
"Get": {
"JeopardyQuestion": [
{
"answer": "fashion designers",
"points": 400,
"question": "Ted Lapidus, Guy Laroche, Christian Lacroix",
"round": "Jeopardy!"
},
{
"answer": "Dapper Flapper",
"points": 400,
"question": "A stylish young woman of the 1920s",
"round": "Double Jeopardy!"
},
{
"answer": "Women's Wear Daily",
"points": 800,
"question": "This daily chronicler of the fashion industry launched \"W\", a bi-weekly, in 1972",
"round": "Jeopardy!"
}
]
}
}
}

ContainsAny Filter

The ContainsAny operator works on text properties and take an array of values as input. It will match objects where the property contains any (i.e. one or more) of the values in the array.

    jeopardy = client.collections.get("JeopardyQuestion")

token_list = ["australia", "india"]
response = jeopardy.query.fetch_objects(
# Find objects where the `answer` property contains any of the strings in `token_list`
filters=wvc.query.Filter.by_property("answer").contains_any(token_list),
limit=3
)

for o in response.objects:
print(o.properties)
Example response

The output is like this:

{
"data": {
"Get": {
"JeopardyQuestion": [
{
"answer": "India",
"points": 100,
"question": "Country that is home to Parsis & Sikhs",
"round": "Jeopardy!"
},
{
"answer": "Australia",
"points": 400,
"question": "The redundant-sounding Townsville, in this country's Queensland state, was named for Robert Towns",
"round": "Double Jeopardy!"
},
{
"answer": "Australia",
"points": 100,
"question": "Broken Hill, this country's largest company, took its name from a small town in New South Wales",
"round": "Jeopardy!"
}
]
}
}
}

ContainsAll Filter

The ContainsAll operator works on text properties and take an array of values as input. It will match objects where the property contains all of the values in the array.

    jeopardy = client.collections.get("JeopardyQuestion")

token_list = ["blue", "red"]

response = jeopardy.query.fetch_objects(
# Find objects where the `question` property contains all of the strings in `token_list`
filters=wvc.query.Filter.by_property("question").contains_all(token_list),
limit=3
)

for o in response.objects:
print(o.properties)
Example response

The output is like this:

{
"data": {
"Get": {
"JeopardyQuestion": [
{
"answer": "James Patterson",
"points": 1000,
"question": "His Alex Cross thrillers include \"Roses are Red\" & \"Violets are Blue\"",
"round": "Jeopardy!"
},
{
"answer": "a chevron",
"points": 800,
"question": "Chevron's red & blue logo is this heraldic shape, meant to convey rank & service",
"round": "Jeopardy!"
},
{
"answer": "litmus",
"points": 400,
"question": "Vegetable dye that turns red in acid solutions & blue in alkaline solutions",
"round": "Double Jeopardy!"
}
]
}
}
}

ContainsAny and ContainsAll with batch delete

If you want to do a batch delete, see Delete objects. ContainsAny and ContainsAll have different behavior in batch deletion operations than they do in queries.

Filter text on partial matches

If the object property is a text, or text-like data type such as object ID, use Like to filter on partial text matches.

    jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
filters=wvc.query.Filter.by_property("answer").like("*inter*"),
limit=3
)

for o in response.objects:
print(o.properties)
Example response

The output is like this:

{
"data": {
"Get": {
"JeopardyQuestion": [
{
"answer": "interglacial",
"question": "This term refers to the warm periods within ice ages; we're in one of those periods now",
"round": "Jeopardy!"
},
{
"answer": "the Interior",
"question": "In 1849, Thomas Ewing, \"The Logician of the West\", became the USA's first Secy. of this Cabinet Dept.",
"round": "Jeopardy!"
},
{
"answer": "Interlaken, Switzerland",
"question": "You can view the Jungfrau Peak from the main street of this town between the Brienz & Thun Lakes",
"round": "Final Jeopardy!"
}
]
}
}
}
Additional information

The * wildcard operator matches zero or more characters. The ? operator matches exactly one character.


Currently, the Like filter is not able to match wildcard characters (? and *) as literal characters (read more).

Filter using cross-references

To filter on properties from a cross-referenced object, add the collection name to the filter.

    jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
filters=wvc.query.Filter.by_ref(link_on="hasCategory").by_property("title").like("*Sport*"),
return_references=wvc.query.QueryReference(link_on="hasCategory", return_properties=["title"]),
limit=3
)

for o in response.objects:
print(o.properties)
print(o.references["hasCategory"].objects[0].properties["title"])
Example response

The output is like this:

{
"data": {
"Get": {
"JeopardyQuestion": [
{
"answer": "Sampan",
"hasCategory": [
{
"title": "TRANSPORTATION"
}
],
"question": "Smaller than a junk, this Oriental boat usually has a cabin with a roof made of mats",
"round": "Jeopardy!"
},
{
"answer": "Emmitt Smith",
"hasCategory": [
{
"title": "SPORTS"
}
],
"question": "In 1994 this Dallas Cowboy scored 22 touchdowns; in 1995 he topped that with 25",
"round": "Jeopardy!"
},
{
"answer": "Lee Iacocca",
"hasCategory": [
{
"title": "TRANSPORTATION"
}
],
"question": "Chrysler executive who developed the Ford Mustang",
"round": "Jeopardy!"
}
]
}
}
}

By geo-coordinates

    response = publications.query.fetch_objects(
filters=(
wvc.query.Filter
.by_property("headquartersGeoLocation")
.within_geo_range(
coordinate=wvc.data.GeoCoordinate(
latitude=52.39,
longitude=4.84
),
distance=1000 # In meters
)
)
)

for o in response.objects:
print(o.properties) # Inspect returned objects

Filter by metadata

Filters also work with metadata properties such as object id, property length, and timestamp.

For the full list, see API references: Filters.

Metadata filter - by object id

    collection = client.collections.get("Article")

target_id = "00037775-1432-35e5-bc59-443baaef7d80"
response = collection.query.fetch_objects(
filters=wvc.query.Filter.by_id().equal(target_id)
)

for o in response.objects:
print(o.properties) # Inspect returned objects
print(o.uuid)
collection = client.collections.get("Article")

target_id = "00037775-1432-35e5-bc59-443baaef7d80"
response = collection.query.fetch_objects(
filters=wvc.query.Filter.by_id().equal(target_id)
)

for o in response.objects:
print(o.properties) # Inspect returned objects
print(o.uuid)

Metadata filter - by object timestamp

    from datetime import datetime, timezone

collection = client.collections.get("Article")

# Set the timezone for avoidance of doubt (otherwise the client will emit a warning)
filter_time = datetime(2020, 1, 1).replace(tzinfo=timezone.utc)

response = collection.query.fetch_objects(
limit=3,
filters=wvc.query.Filter.by_creation_time().greater_than(filter_time),
return_metadata=wvc.query.MetadataQuery(creation_time=True)
)

for o in response.objects:
print(o.properties) # Inspect returned objects
print(o.metadata.creation_time) # Inspect object creation time

Metadata filter - by object property length

    collection = client.collections.get("JeopardyQuestion")

length_threshold = 20

response = collection.query.fetch_objects(
limit=3,
filters=wvc.query.Filter.by_property("answer", length=True).greater_than(length_threshold),
)

for o in response.objects:
print(o.properties) # Inspect returned objects
print(len(o.properties["answer"])) # Inspect property length

Filter considerations

Tokenization

Weaviate converts filter terms into tokens. The default tokenization is word. The word tokenizer keeps alphanumeric characters and splits on whitespace. It converts a string like "test_domain_weaviate" into "test", "domain", and "weaviate".

For details and additional tokenization methods, see Tokenization.

Improve filter performance

If you encounter slow filter performance, consider adding a limit parameter or additional where operators to restrict the size of your data set.

List of filter operators

For a list of filter operators, see the reference page.