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.

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)

API docs

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))

API docs Deprecated (v3)

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));
}

API docs

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)

API docs

{
  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.

The v4 Python client API provides filtering by any_of, or all_of, as well as using & or | operators.

Use any_of or all_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)

API docs

Filter with `any of`

from weaviate.classes.query import Filter

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
    filters=(
        Filter.any_of([  # Combines the below with `|`
            Filter.by_property("points").greater_or_equal(700),
            Filter.by_property("points").less_than(500),
            Filter.by_property("round").equal("Double Jeopardy!"),
        ])
    ),
    limit=5
)

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

API docs

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)

API docs

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))

API docs Deprecated (v3)

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));
}

API docs

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)

API docs

{
  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.

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)

API docs

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))

API docs Deprecated (v3)

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));
}

API docs

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)

API docs

{
  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 to And or Or.
Add operands.
Inside an operand expression, set operator equal to And or Or 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.

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)

API docs

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))

API docs Deprecated (v3)

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));
}

API docs

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)

API docs

{
  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.

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)

API docs

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))

API docs Deprecated (v3)

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));
}

API docs

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)

API docs

{
  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.

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)

API docs

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))

API docs Deprecated (v3)

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));
}

API docs

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)

API docs

{
  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.

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)

API docs

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))

API docs Deprecated (v3)

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));
}

API docs

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)

API docs

{
  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

Cross-references and query performance

Queries involving cross-references can be slower than queries that do not involve cross-references, especially at scale such as for multiple objects or complex queries.

At the first instance, we strongly encourage you to consider whether you can avoid using cross-references in your data schema. As a scalable AI-native database, Weaviate is well-placed to perform complex queries with vector, keyword and hybrid searches involving filters. You may benefit from rethinking your data schema to avoid cross-references where possible.

For example, instead of creating separate "Author" and "Book" collections with cross-references, consider embedding author information directly in Book objects and using searches and filters to find books by author characteristics.

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

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"])

API docs

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))

API docs Deprecated (v3)

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));
}

API docs

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)

API docs

{
  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

Limitations

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.

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

API docs

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)

API docs Deprecated (v3)

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));

API docs

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)

API docs

  {
    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

API docs

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))
);

API docs

// 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)

API docs

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`

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)

API docs

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)

API docs Deprecated (v3)

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));
}

API docs

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)

API docs

{
  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.

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

API docs

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)

API docs Deprecated (v3)

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));
}

API docs

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));

API docs

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)

API docs

{
  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.

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

API docs

response = (
    client.query
    .get("JeopardyQuestion", ["answer"])
    .with_where({
        "path": ["len(answer)"],
        "operator": "GreaterThan",
        "valueInt": 20
    })
    .with_limit(3)
    .do()
)

print(response)

API docs Deprecated (v3)

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));
}

API docs

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)

API docs

{
  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

API docs

response = (
    client.query
    .get("JeopardyQuestion", ["points"])
    .with_where({
        "path": ["points"],
        "operator": "IsNull",
        "valueBoolean": True
    })
    .with_limit(3)
    .do()
)

print(response)

API docs Deprecated (v3)

  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));
  }

API docs

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)

API docs

{
  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.

Questions and feedback

If you have any questions or feedback, let us know in the user forum.

Filter with one condition​

Filter with multiple conditions​

Filter with & or |​

Filter with any of​

Filter with all of​

Nested filters​

Combine filters and search operators​

ContainsAny Filter​

ContainsAll Filter​

ContainsAny and ContainsAll with batch delete​

Filter text on partial matches​

Filter using cross-references​

By geo-coordinates​

By DATE datatype​

Filter by metadata​

By object id​

By object timestamp​

By object property length​

By object null state​

Filter considerations​

Tokenization​

Improve filter performance​

List of filter operators​

Related pages​

Questions and feedback​

Filter with one condition

Filter with multiple conditions

Filter with `&` or `|`

Filter with `any of`

Filter with `all of`

Nested filters

Combine filters and search operators

`ContainsAny` Filter

`ContainsAll` Filter

`ContainsAny` and `ContainsAll` with batch delete

Filter text on partial matches

Filter using cross-references

By geo-coordinates

By `DATE` datatype

Filter by metadata

By object `id`

By object timestamp

By object property length

By object null state

Filter considerations

Tokenization

Improve filter performance

List of filter operators

Related pages

Questions and feedback