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.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client v2
- Go
- GraphQL
from weaviate.classes.query import Filter
jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
filters=Filter.by_property("round").equal("Double Jeopardy!"),
limit=3
)
for o in response.objects:
print(o.properties)
response = (
client.query
.get("JeopardyQuestion", ["question", "answer", "round"])
.with_where({
"path": ["round"],
"operator": "Equal",
"valueText": "Double Jeopardy!"
})
.with_limit(3)
.do()
)
print(json.dumps(response, indent=2))
const jeopardy = client.collections.get('JeopardyQuestion');
const result = await jeopardy.query.fetchObjects({
filters: jeopardy.filter.byProperty('round').equal('Double Jeopardy!'),
limit: 3,
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
result = await client.graphql
.get()
.withClassName('JeopardyQuestion')
.withWhere({
path: ['round'],
operator: 'Equal',
valueText: 'Double Jeopardy!',
})
.withLimit(3)
.withFields('question answer round')
.do();
console.log(JSON.stringify(result, null, 2));
response, err := client.GraphQL().Get().
WithClassName("JeopardyQuestion").
WithFields(graphql.Field{Name: "question"}, graphql.Field{Name: "answer"}, graphql.Field{Name: "round"}).
WithWhere(filters.Where().
WithPath([]string{"round"}).
WithOperator(filters.Equal).
WithValueString("Double Jeopardy!")).
WithLimit(3).
Do(ctx)
{
Get {
JeopardyQuestion(
limit: 3
where: {
path: ["round"],
operator: Equal,
valueText: "Double Jeopardy!"
}
) {
question
answer
round
}
}
}
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.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client v2
- Go
- GraphQL
The v4
Python client API provides filtering by any_of
, or all_of
, as well as using &
or |
operators.
- Use
any_of
orall_of
for filtering by any, or all of a list of provided filters. - Use
&
or|
for filtering by pairs of provided filters.
Filter with &
or |
from weaviate.classes.query import Filter
jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
# Use & as AND
# | as OR
filters=(
Filter.by_property("round").equal("Double Jeopardy!") &
Filter.by_property("points").less_than(600)
),
limit=3
)
for o in response.objects:
print(o.properties)
Filter with any of
from weaviate.classes.query import Filter
jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
filters=(
Filter.all_of([ # Combines the below with `&`
Filter.by_property("points").greater_than(300),
Filter.by_property("points").less_than(700),
Filter.by_property("round").equal("Double Jeopardy!"),
])
),
limit=5
)
for o in response.objects:
print(o.properties)
Filter with all of
from weaviate.classes.query import Filter
jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
filters=(
Filter.all_of([ # Combines the below with `&`
Filter.by_property("points").greater_than(300),
Filter.by_property("points").less_than(700),
Filter.by_property("round").equal("Double Jeopardy!"),
])
),
limit=5
)
for o in response.objects:
print(o.properties)
response = (
client.query
.get("JeopardyQuestion", ["question", "answer", "round", "points"])
.with_where({
"operator": "And",
"operands": [
{
"path": ["round"],
"operator": "Equal",
"valueText": "Double Jeopardy!",
},
{
"path": ["points"],
"operator": "LessThan",
"valueInt": 600,
},
]
})
.with_limit(3)
.do()
)
print(json.dumps(response, indent=2))
Use Filters.and
and Filters.or
methods to combine filters in the JS/TS v3
API.
These methods take variadic arguments (e.g. Filters.and(f1, f2, f3, ...)
). To pass an array (e.g. fs
) as an argument, provide it like so: Filters.and(...fs)
which will spread the array into its elements.
import weaviate, { Filters } from 'weaviate-client';
const jeopardy = client.collections.get('JeopardyQuestion');
const result = await jeopardy.query.fetchObjects({
filters: Filters.and(
jeopardy.filter.byProperty('round').equal('Double Jeopardy!'),
jeopardy.filter.byProperty('points').lessThan(600)
),
limit: 3,
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
result = await client.graphql
.get()
.withClassName('JeopardyQuestion')
.withWhere({
operator: 'And',
operands: [
{
path: ['round'],
operator: 'Equal',
valueText: 'Double Jeopardy!',
},
{
path: ['points'],
operator: 'LessThan',
valueInt: 600,
},
],
})
.withLimit(3)
.withFields('question answer round points')
.do();
console.log(JSON.stringify(result, null, 2));
response, err := client.GraphQL().Get().
WithClassName("JeopardyQuestion").
WithFields(graphql.Field{Name: "question"}, graphql.Field{Name: "answer"}, graphql.Field{Name: "round"}, graphql.Field{Name: "points"}).
WithWhere(filters.Where().
WithOperator(filters.And).
WithOperands([]*filters.WhereBuilder{
filters.Where().WithPath([]string{"round"}).WithOperator(filters.Equal).WithValueString("Double Jeopardy!"),
filters.Where().WithPath([]string{"points"}).WithOperator(filters.LessThan).WithValueInt(600),
},
)).
WithLimit(3).
Do(ctx)
{
Get {
JeopardyQuestion(
limit: 3
where: {
operator: And,
operands: [
{
path: ["round"],
operator: Equal,
valueText: "Double Jeopardy!",
},
{
path: ["points"],
operator: LessThan,
valueInt: 600,
},
]
}
) {
question
answer
round
points
}
}
}
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!"
}
]
}
}
}
Nested filters
You can group and nest filters.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client v2
- Go
- GraphQL
from weaviate.classes.query import Filter
jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
filters=Filter.by_property("answer").like("*bird*") &
(Filter.by_property("points").greater_than(700) | Filter.by_property("points").less_than(300)),
limit=3
)
for o in response.objects:
print(o.properties)
response = (
client.query
.get("JeopardyQuestion", ["question", "answer", "round", "points"])
.with_where({
"operator": "And",
"operands": [
{
"path": ["answer"],
"operator": "Like",
"valueText": "*bird*",
},
{
"operator": "Or",
"operands": [
{
"path": ["points"],
"operator": "GreaterThan",
"valueInt": 700,
},
{
"path": ["points"],
"operator": "LessThan",
"valueInt": 300,
},
]
}
]
})
.with_limit(3)
.do()
)
print(json.dumps(response, indent=2))
import weaviate, { Filters } from 'weaviate-client';
const jeopardy = client.collections.get('JeopardyQuestion');
const result = await jeopardy.query.fetchObjects({
filters: Filters.and(
jeopardy.filter.byProperty('answer').like('*bird*'),
Filters.or(
jeopardy.filter.byProperty('points').greaterThan(700),
jeopardy.filter.byProperty('points').lessThan(300)
)
),
limit: 3
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
result = await client.graphql
.get()
.withClassName('JeopardyQuestion')
.withWhere({
operator: 'And',
operands: [
{
path: ['answer'],
operator: 'Like',
valueText: '*bird*',
},
{
operator: 'Or',
operands: [
{
path: ['points'],
operator: 'GreaterThan',
valueInt: 700,
},
{
path: ['points'],
operator: 'LessThan',
valueInt: 300,
},
],
},
],
})
.withLimit(3)
.withFields('question answer round points')
.do();
console.log(JSON.stringify(result, null, 2));
operands := []*filters.WhereBuilder{
filters.Where().WithPath([]string{"points"}).WithOperator(filters.GreaterThan).WithValueInt(300),
filters.Where().WithPath([]string{"points"}).WithOperator(filters.LessThan).WithValueInt(700),
}
response, err := client.GraphQL().Get().
WithClassName("JeopardyQuestion").
WithFields(graphql.Field{Name: "question"}, graphql.Field{Name: "answer"}, graphql.Field{Name: "round"}, graphql.Field{Name: "points"}).
WithWhere(filters.Where().
WithOperator(filters.And).
WithOperands(operands)).
WithLimit(3).
Do(ctx)
{
Get {
JeopardyQuestion(
limit: 3
where: {
operator: And,
operands: [
{
path: ["answer"],
operator: Like,
valueText: "*bird*",
},
{
operator: Or,
operands: [
{
path: ["points"],
operator: GreaterThan,
valueInt: 700,
},
{
path: ["points"],
operator: LessThan,
valueInt: 300,
},
]
}
]
}
) {
question
answer
round
points
}
}
}
Example response
The output is like this:
{
"data": {
"Get": {
"JeopardyQuestion": [
{
"answer": "The Firebird",
"points": 1000,
"question": "This title character has the face & arms of a woman & a body of feathers that tapers off in flames",
"round": "Double Jeopardy!"
},
{
"answer": "the Firebird",
"points": 800,
"question": "This Stravinsky character first played by Tamara Karsavina has the face & arms of a girl & a body of feathers",
"round": "Double Jeopardy!"
}
]
}
}
}
Additional information
To create a nested filter, follow these steps.
- Set the outer
operator
equal toAnd
orOr
. - Add
operands
. - Inside an
operand
expression, setoperator
equal toAnd
orOr
to add the nested group. - Add
operands
to the nested group as needed.
Combine filters and search operators
Filters work with search operators like nearXXX
, hybrid
, and bm25
.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client v2
- Go
- GraphQL
from weaviate.classes.query import Filter
jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.near_text(
query="fashion icons",
filters=Filter.by_property("points").greater_than(200),
limit=3
)
for o in response.objects:
print(o.properties)
response = (
client.query
.get("JeopardyQuestion", ["question", "answer", "round", "points"])
.with_where({
"path": ["points"],
"operator": "GreaterThan",
"valueInt": 200
})
.with_near_text({
"concepts": ["fashion icons"]
})
.with_limit(3)
.do()
)
print(json.dumps(response, indent=2))
const jeopardy = client.collections.get('JeopardyQuestion');
const result = await jeopardy.query.nearText('fashion icons', {
filters: jeopardy.filter.byProperty('points').greaterThan(200),
limit: 3,
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
result = await client.graphql
.get()
.withClassName('JeopardyQuestion')
.withWhere({
path: ['points'],
operator: 'GreaterThan',
valueInt: 200,
})
.withNearText({
concepts: ['fashion icons'],
})
.withLimit(3)
.withFields('question answer round points')
.do();
console.log(JSON.stringify(result, null, 2));
response, err := client.GraphQL().Get().
WithClassName("JeopardyQuestion").
WithFields(graphql.Field{Name: "question"}, graphql.Field{Name: "answer"}, graphql.Field{Name: "round"}, graphql.Field{Name: "points"}).
WithWhere(filters.Where().
WithPath([]string{"points"}).
WithOperator(filters.GreaterThan).
WithValueInt(200)).
WithNearText(client.GraphQL().NearTextArgBuilder().
WithConcepts([]string{"fashion icons"})).
WithLimit(3).
Do(ctx)
{
Get {
JeopardyQuestion(
limit: 3
where: {
path: ["points"],
operator: GreaterThan,
valueInt: 200
}
nearText: {
concepts: ["fashion icons"]
}
) {
question
answer
round
points
}
}
}
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.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client v2
- Go
- GraphQL
from weaviate.classes.query import Filter
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=Filter.by_property("answer").contains_any(token_list),
limit=3
)
for o in response.objects:
print(o.properties)
token_list = ["australia", "india"]
response = (
client.query
.get("JeopardyQuestion", ["question", "answer", "round", "points"])
# Find objects where the `answer` property contains any of the strings in `token_list`
.with_where({
"path": ["answer"],
"operator": "ContainsAny",
"valueText": token_list
})
.with_limit(3)
.do()
)
print(json.dumps(response, indent=2))
const jeopardy = client.collections.get('JeopardyQuestion');
const tokenList = ['australia', 'india']
const result = await jeopardy.query.fetchObjects({
// Find objects where the `answer` property contains any of the strings in `tokenList`
filters: jeopardy.filter.byProperty('answer').containsAny(tokenList),
limit: 3,
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
let token_list
token_list = ['australia', 'india']
result = await client.graphql
.get()
.withClassName('JeopardyQuestion')
// Find objects where the `answer` property contains any of the strings in `token_list`
.withWhere({
path: ['answer'],
operator: 'ContainsAny',
valueTextArray: token_list,
})
.withLimit(3)
.withFields('question answer round')
.do();
console.log(JSON.stringify(result, null, 2));
tokenList := []string{"australia", "india"}
response, err := client.GraphQL().Get().
WithClassName("JeopardyQuestion").
WithFields(graphql.Field{Name: "question"}, graphql.Field{Name: "answer"}, graphql.Field{Name: "round"}, graphql.Field{Name: "points"}).
WithWhere(filters.Where().
WithPath([]string{"answer"}).
WithOperator(filters.ContainsAny).
WithValueText(tokenList...)).
WithLimit(3).
Do(ctx)
{
Get {
JeopardyQuestion(
limit: 3
where: {
path: ["answer"],
operator: ContainsAny,
valueText: ["australia", "india"]
}
) {
question
answer
round
points
}
}
}
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.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client v2
- Go
- GraphQL
from weaviate.classes.query import Filter
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=Filter.by_property("question").contains_all(token_list),
limit=3
)
for o in response.objects:
print(o.properties)
token_list = ["blue", "red"]
response = (
client.query
.get("JeopardyQuestion", ["question", "answer", "round", "points"])
.with_where({
"path": ["question"],
"operator": "ContainsAll",
"valueText": token_list
})
.with_limit(3)
.do()
)
print(json.dumps(response, indent=2))
const jeopardy = client.collections.get('JeopardyQuestion');
const tokenList = ['australia', 'india']
const result = await jeopardy.query.fetchObjects({
// Find objects where the `question` property contains all of the strings in `tokenList`
filters: jeopardy.filter.byProperty('question').containsAll(tokenList),
limit: 3,
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
let token_list
token_list = ['blue', 'red']
result = await client.graphql
.get()
.withClassName('JeopardyQuestion')
// Find objects where the `question` property contains all of the strings in `token_list`
.withWhere({
path: ['question'],
operator: 'ContainsAll',
valueTextArray: token_list,
})
.withLimit(3)
.withFields('question answer round')
.do();
console.log(JSON.stringify(result, null, 2));
tokenList := []string{"blue", "red"}
response, err := client.GraphQL().Get().
WithClassName("JeopardyQuestion").
WithFields(graphql.Field{Name: "question"}, graphql.Field{Name: "answer"}, graphql.Field{Name: "round"}, graphql.Field{Name: "points"}).
WithWhere(filters.Where().
WithPath([]string{"question"}).
WithOperator(filters.ContainsAll).
WithValueText(tokenList...)).
WithLimit(3).
Do(ctx)
{
Get {
JeopardyQuestion(
limit: 3
where: {
path: ["question"],
operator: ContainsAll,
valueText: ["blue", "red"]
}
) {
question
answer
round
points
}
}
}
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.
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.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client v2
- Go
- GraphQL
from weaviate.classes.query import Filter
jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
filters=Filter.by_property("answer").like("*inter*"),
limit=3
)
for o in response.objects:
print(o.properties)
response = (
client.query
.get("JeopardyQuestion", ["question", "answer", "round"])
.with_where({
"path": ["answer"],
"operator": "Like",
"valueText": "*inter*"
})
.with_limit(3)
.do()
)
print(json.dumps(response, indent=2))
const jeopardy = client.collections.get('JeopardyQuestion');
const result = await jeopardy.query.fetchObjects({
filters: jeopardy.filter.byProperty('answer').like('*inter*'),
limit: 3,
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
result = await client.graphql
.get()
.withClassName('JeopardyQuestion')
.withWhere({
path: ['answer'],
operator: 'Like',
valueText: '*inter*',
})
.withLimit(3)
.withFields('question answer round')
.do();
console.log(JSON.stringify(result, null, 2));
response, err := client.GraphQL().Get().
WithClassName("JeopardyQuestion").
WithFields(graphql.Field{Name: "question"}, graphql.Field{Name: "answer"}, graphql.Field{Name: "round"}).
WithWhere(filters.Where().
WithPath([]string{"answer"}).
WithOperator(filters.Like).
WithValueText("*inter*")).
WithLimit(3).
Do(ctx)
{
Get {
JeopardyQuestion(
limit: 3
where: {
path: ["answer"],
operator: Like,
valueText: "*inter*"
}
) {
question
answer
round
}
}
}
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.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client v2
- Go
- GraphQL
from weaviate.classes.query import Filter, QueryReference
jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
filters=Filter.by_ref(link_on="hasCategory").by_property("title").like("*Sport*"),
return_references=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"])
response = (
client.query
.get("JeopardyQuestion", ["question", "answer", "round", "hasCategory {... on JeopardyCategory { title } }"])
.with_where({
"path": ["hasCategory", "JeopardyCategory", "title"],
"operator": "Like",
"valueText": "*Sport*"
})
.with_limit(3)
.do()
)
print(json.dumps(response, indent=2))
const jeopardy = client.collections.get('JeopardyQuestion');
const result = await jeopardy.query.fetchObjects({
filters: jeopardy.filter.byRef('hasCategory').byProperty('title').like('*Sport*'),
returnReferences: [{
linkOn: 'hasCategory',
returnProperties: ['title'],
}],
limit: 3
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
result = await client.graphql
.get()
.withClassName('JeopardyQuestion')
.withWhere({
path: ['round'],
operator: 'Equal',
valueText: 'Double Jeopardy!',
})
.withLimit(3)
.withFields('question answer round')
.do();
console.log(JSON.stringify(result, null, 2));
response, err := client.GraphQL().Get().
WithClassName("JeopardyQuestion").
WithFields(
graphql.Field{Name: "question"},
graphql.Field{Name: "answer"},
graphql.Field{Name: "round"},
graphql.Field{
Name: "hasCategory",
Fields: []graphql.Field{
{Name: "... on JeopardyCategory", Fields: []graphql.Field{{Name: "title"}}},
},
},
).
WithWhere(filters.Where().
WithPath([]string{"hasCategory", "JeopardyCategory", "title"}).
WithOperator(filters.Like).
WithValueText("*Sport*")).
WithLimit(3).
Do(ctx)
{
Get {
JeopardyQuestion(
limit: 3
where: {
path: ["hasCategory", "JeopardyCategory", "title"],
operator: Like,
valueText: "*Sport*"
}
) {
question
answer
round
hasCategory {... on JeopardyCategory { 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
Currently, geo-coordinate filtering is limited to the nearest 800 results from the source location, which will be further reduced by any other filter conditions and search parameters.
If you plan on a densely populated dataset, consider using another strategy such as geo-hashing into a text
datatype, and filtering further, such as with a ContainsAny
filter.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client v2
- Go
- GraphQL
from weaviate.classes.query import Filter
from weaviate.classes.query import GeoCoordinate
response = publications.query.fetch_objects(
filters=(
Filter
.by_property("headquartersGeoLocation")
.within_geo_range(
coordinate=GeoCoordinate(
latitude=52.39,
longitude=4.84
),
distance=1000 # In meters
)
)
)
for o in response.objects:
print(o.properties) # Inspect returned objects
get_publications_where = """
{
Get {
Publication(where: {
operator: WithinGeoRange,
valueGeoRange: {
geoCoordinates: {
latitude: 52.3932696, # latitude
longitude: 4.8374263 # longitude
},
distance: {
max: 1000 # distance in meters
}
},
path: ["headquartersGeoLocation"] # property needs to be a geoLocation data type.
}) {
name
headquartersGeoLocation {
latitude
longitude
}
}
}
}
"""
query_result = client.query.raw(get_publications_where)
print(query_result)
const publications = client.collections.get('Publication');
const geoResult = await publications.query.fetchObjects({
filters: publications.filter.byProperty('headquartersGeoLocation').withinGeoRange({
latitude: 52.39,
longitude: 4.84,
distance: 1000
}),
})
console.log(JSON.stringify(geoResult.objects, null, 2));
const publications = client.collections.get('Publication');
const geoResult = await publications.query.fetchObjects({
filters: publications.filter.byProperty('headquartersGeoLocation').withinGeoRange({
latitude: 52.39,
longitude: 4.84,
distance: 1000
}),
})
console.log(JSON.stringify(geoResult.objects, null, 2));
geoFilter := filters.Where().
WithPath([]string{"headquartersGeoLocation"}).
WithOperator(filters.WithinGeoRange).
WithValueGeoRange(&filters.GeoCoordinatesParameter{
Latitude: 52.39,
Longitude: 4.84,
MaxDistance: 1000,
})
response, err := client.GraphQL().Get().
WithClassName("Publication").
WithWhere(geoFilter).
WithFields(graphql.Field{Name: "name"}).
WithFields(graphql.Field{
Name: "headquartersGeoLocation",
Fields: []graphql.Field{
{Name: "latitude"},
{Name: "longitude"},
},
}).
Do(ctx)
{
Get {
Publication(where: {
operator: WithinGeoRange,
valueGeoRange: {
geoCoordinates: {
latitude: 52.3932696, # latitude
longitude: 4.8374263 # longitude
},
distance: {
max: 1000 # distance in meters
}
},
path: ["headquartersGeoLocation"] # property needs to be a geoLocation data type.
}) {
name
headquartersGeoLocation {
latitude
longitude
}
}
}
}
By DATE
datatype
To filter by a DATE
datatype property, specify the date/time as an RFC 3339 timestamp, or a client library-compatible type such as a Python datetime
object.
- Python Client v4
- JS/TS Client v3
- Go
from datetime import datetime, timezone
from weaviate.classes.query import Filter, MetadataQuery
# Set the timezone for avoidance of doubt
filter_time = datetime(2022, 6, 10).replace(tzinfo=timezone.utc)
# The filter threshold could also be an RFC 3339 timestamp, e.g.:
# filter_time = "2022-06-10T00:00:00.00Z"
response = collection.query.fetch_objects(
limit=3,
# This property (`some_date`) is a `DATE` datatype
filters=Filter.by_property("some_date").greater_than(filter_time),
)
for o in response.objects:
print(o.properties) # Inspect returned objects
const filterTime = new Date(2020, 5, 10) // Note that the month is 0-indexed
// The filter threshold could also be an RFC 3339 timestamp, e.g.:
// filterTime = '2022-06-10T00:00:00.00Z'
result = await collectionWithDate.query.fetchObjects({
limit: 3,
filters: jeopardy.filter.byProperty('some_date').greaterThan(filterTime),
})
result.objects.forEach((object) =>
console.log(JSON.stringify(object.properties, null, 2))
);
// Note: In Go, months are 1-indexed
filterTime := time.Date(2020, 6, 10, 0, 0, 0, 0, time.UTC)
// Alternatively, you can use an RFC 3339 timestamp:
// filterTime, _ := time.Parse(time.RFC3339, "2022-06-10T00:00:00Z")
response, err := client.GraphQL().Get().
WithClassName("Article").
WithLimit(3).
WithFields(graphql.Field{Name: "publicationDate"}).
WithWhere(filters.Where().
WithPath([]string{"publicationDate"}).
WithOperator(filters.GreaterThan).
WithValueDate(filterTime)).
Do(ctx)
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.
By object id
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client v2
- Go
- GraphQL
from weaviate.classes.query import Filter
collection = client.collections.get("Article")
target_id = "00037775-1432-35e5-bc59-443baaef7d80"
response = collection.query.fetch_objects(
filters=Filter.by_id().equal(target_id)
)
for o in response.objects:
print(o.properties) # Inspect returned objects
print(o.uuid)
target_id = "00037775-1432-35e5-bc59-443baaef7d80"
response = (
client.query
.get("Article", ["title"])
.with_where({
"path": "id",
"operator": "Equal",
"valueText": target_id
})
.with_additional("id")
.do()
)
print(response)
const myArticleCollection = client.collections.get('Article');
const targetId = '00037775-1432-35e5-bc59-443baaef7d80'
result = await article.query.fetchObjects({
filters: article.filter.byId().equal(targetId),
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
let target_id = '00037775-1432-35e5-bc59-443baaef7d80'
result = await client.graphql
.get()
.withClassName('Article')
.withWhere({
path: ['id'],
operator: 'Equal',
valueText: target_id,
})
.withFields('title _additional { id }')
.do();
console.log(JSON.stringify(result, null, 2));
targetID := "00037775-1432-35e5-bc59-443baaef7d80"
response, err := client.GraphQL().Get().
WithClassName("Article").
WithFields(graphql.Field{Name: "title"}).
WithWhere(filters.Where().
WithPath([]string{"id"}).
WithOperator(filters.Equal).
WithValueString(targetID)).
WithFields(
graphql.Field{Name: "title"},
graphql.Field{
Name: "_additional",
Fields: []graphql.Field{
{Name: "id"},
},
},
).
Do(ctx)
{
Get {
Article(
where: {
path: ["id"],
operator: Equal,
valueText: "00037775-1432-35e5-bc59-443baaef7d80"
}
) {
title
_additional { id }
}
}
}
By object timestamp
This filter requires the property timestamp to be indexed.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client
- Go
- GraphQL
from datetime import datetime, timezone
from weaviate.classes.query import Filter, MetadataQuery
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=Filter.by_creation_time().greater_than(filter_time),
return_metadata=MetadataQuery(creation_time=True)
)
for o in response.objects:
print(o.properties) # Inspect returned objects
print(o.metadata.creation_time) # Inspect object creation time
timestamp_str = "2020-01-01T00:00:00+00:00"
response = (
client.query
.get("Article", ["title"])
.with_where({
"path": ["_creationTimeUnix"],
"operator": "GreaterThan",
"valueDate": timestamp_str # Can use either `valueDate` with a `RFC3339` datetime or `valueText` as Unix epoch milliseconds
})
.with_additional("creationTimeUnix")
.with_limit(3)
.do()
)
print(response)
const myArticleCollection = client.collections.get('Article');
const creationTime = '2020-01-01T00:00:00+00:00'
result = await myArticleCollection.query.fetchObjects({
filters: jeopardy.filter.byCreationTime().greaterOrEqual(creationTime),
returnMetadata: ['creationTime']
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
result = await client.graphql
.get()
.withClassName('Article')
.withFields('title _additional { creationTimeUnix }')
.withWhere({
operator: 'GreaterThan',
path: ['_creationTimeUnix'],
valueDate: '2020-01-01T00:00:00+00:00',
// Can use either `valueDate` with a `RFC3339` datetime or `valueText` as Unix epoch milliseconds
// valueText: '1577836800',
})
.withLimit(3)
.do();
console.log(JSON.stringify(result, null, 2));
timestampStr := "2020-01-01T00:00:00+00:00"
layout := "2006-01-02T15:04:05Z07:00"
timestamp, err := time.Parse(layout, timestampStr)
if err != nil {
fmt.Println("Error parsing time:", err)
return
}
response, err := client.GraphQL().Get().
WithClassName("Article").
WithFields(graphql.Field{Name: "title"}).
WithWhere(filters.Where().
WithPath([]string{"_creationTimeUnix"}).
WithOperator(filters.GreaterThan).
WithValueDate(timestamp)).
WithFields(
graphql.Field{Name: "title"},
graphql.Field{
Name: "_additional",
Fields: []graphql.Field{
{Name: "creationTimeUnix"},
},
},
).
WithLimit(3).
Do(ctx)
{
Get {
Article(
limit: 3
where: {
path: ["_creationTimeUnix"],
operator: GreaterThan,
valueDate: "2020-01-01T00:00:00+00:00"
}
) {
title
_additional { creationTimeUnix }
}
}
}
By object property length
This filter requires the property length to be indexed.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- JS/TS Client v2
- Go
- GraphQL
from weaviate.classes.query import Filter
collection = client.collections.get("JeopardyQuestion")
response = collection.query.fetch_objects(
limit=3,
filters=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
response = (
client.query
.get("JeopardyQuestion", ["answer"])
.with_where({
"path": ["len(answer)"],
"operator": "GreaterThan",
"valueInt": 20
})
.with_limit(3)
.do()
)
print(response)
const jeopardy = client.collections.get('JeopardyQuestion');
const result = await jeopardy.query.fetchObjects({
filters: jeopardy.filter.byProperty('answer', true).greaterThan(20),
limit: 3
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
result = await client.graphql
.get()
.withClassName('JeopardyQuestion')
.withFields('answer')
.withWhere({
operator: 'GreaterThan',
path: ['len(answer)'],
valueInt: 20,
})
.withLimit(3)
.do();
console.log(JSON.stringify(result, null, 2));
response, err := client.GraphQL().Get().
WithClassName("JeopardyQuestion").
WithFields(graphql.Field{Name: "answer"}).
WithWhere(filters.Where().
WithPath([]string{"len(answer)"}).
WithOperator(filters.GreaterThan).
WithValueInt(20)).
WithLimit(3).
Do(ctx)
{
Get {
JeopardyQuestion(
limit: 3
where: {
path: ["len(answer)"],
operator: GreaterThan,
valueInt: 20
}
) {
answer
}
}
}
By object null state
This filter requires the property null state to be indexed.
- Python Client v4
- Python Client v3
- JS/TS Client v3
- Go
- GraphQL
from weaviate.classes.query import Filter
collection = client.collections.get("WineReview")
response = collection.query.fetch_objects(
limit=3,
# This requires the `country` property to be configured with `index_null_state=True``
filters=Filter.by_property("country").is_none(True) # Find objects where the `country` property is null
)
for o in response.objects:
print(o.properties) # Inspect returned objects
response = (
client.query
.get("JeopardyQuestion", ["points"])
.with_where({
"path": ["points"],
"operator": "IsNull",
"valueBoolean": True
})
.with_limit(3)
.do()
)
print(response)
const result = await jeopardy.query.fetchObjects({
// This requires the `points` property to be configured with `index_null_state=True``
filters: jeopardy.filter.byProperty('points').isNull(true),
limit: 3
})
for (let object of result.objects) {
console.log(JSON.stringify(object.properties, null, 2));
}
response, err := client.GraphQL().Get().
WithClassName("JeopardyQuestion").
WithFields(graphql.Field{Name: "points"}).
WithWhere(filters.Where().
WithPath([]string{"points"}).
WithOperator(filters.IsNull).
WithValueBoolean(true)).
WithLimit(3).
Do(ctx)
{
Get {
JeopardyQuestion(
limit: 3
where: {
path: ["points"],
operator: IsNull,
valueBoolean: true
}
) {
points
}
}
}
Filter considerations
Tokenization
Weaviate converts filter terms into tokens. The default tokenization is word
. The word
tokenizer keeps alphanumeric characters, lowercase them 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.
Related pages
Questions and feedback
If you have any questions or feedback, let us know in the user forum.