Table of documentation contents

Filters

Filters can be set to order or sort your dataset or to find specific data objects. Some filters are available in multiple functions where others are only available in specific ones. Some filters are only available when specific modules are activated. Check the modules pages, like text2vec-contextionary or text2vec-transformers for a nearText filter or qna-transformers for the question answering filter.

Where filter

Filter structure

Supported by the Get{} and Aggregate{} function.

The where filter is an algebraic object, which takes the following arguments:

  • Operator (which takes one of the following values)
    • And
    • Or
    • Not
    • Equal
    • NotEqual
    • GreaterThan
    • GreaterThanEqual
    • LessThan
    • LessThanEqual
    • Like
    • WithinGeoRange
  • Operands: Is a list of Operator objects of this same structure, only used if the parent Operator is set to And or Or.
  • Path: Is a list of strings indicating the property name of the class. If the property is a beacon (i.e., cross-reference), the path should be followed to the property of the beacon which should be specified as a list of strings.
  • valueInt: The integer value where the Path’s last property name should be compared to.
  • valueBoolean: The boolean value that the Path’s last property name should be compared to.
  • valueString: The string value that the Path’s last property name should be compared to.
  • valueText: The text value that the Path’s last property name should be compared to.
  • valueNumber: The number (float) value that the Path’s last property name should be compared to.
  • valueDate: The date (ISO 8601 timestamp, formatted as RFC3339) value that the Path’s last property name should be compared to.
{
  Get {
    <Class>(where: {
        operator: <operator>,
        operands: [{
          path: [path],
          operator: <operator>
          <valueType>: <value>
        }, {
          path: [<matchPath>],
          operator: <operator>,
          <valueType>: <value>
        }]
      }) {
      <propertyWithBeacon> {
        <property>
        ... on <ClassOfWhereBeaconGoesTo> {
          <propertyOfClass>
        }
      }
    }
  }
}

Filter behavior of multi-word queries in Equal operator

The behavior for the Equal operator on multi-word string and text properties in where filters is as follows. Multi-word queries are broken up into single word segments. An object must contain all segments. How words are broken up depends on the datatype. For string properties only spaces defined word boundaries. For text properties all non-alphanumeric properties are considered word boundaries. E.g. for text: my email is alice@example.com is split into ["my", "email", "is", "alice" "example", "com"], whereas the same query string on a string property would be broken into ["my", "email", "is", "alice@example.com"].

Single operand

You can create operator filters by setting the where key. You always need to include the GraphQL property path, the operator type, and the valueType plus a value.

For example, this filter selects articles from the class Article with a wordcount higher than 1000.

  {
  Get {
    Article(where: {
        path: ["wordCount"],    # Path to the property that should be used
        operator: GreaterThan,  # operator
        valueInt: 1000          # value (which is always = to the type of the path property)
      }) {
      title
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Console.

Example response

{
  "data": {
    "Get": {
      "Article": [
        {
          "title": "Opinion | John Lennon Told Them ‘Girls Don’t Play Guitar.’ He Was So Wrong."
        },
      ]
  },
  "errors": null
} 

Filter by id

You can filter object by their unique id or uuid, where you give the id as valueString.

  {
  Get {
    Article(where: {
        path: ["id"],
        operator: Equal,
        valueString: "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf"
      }) {
      title
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Console.

Example response

{
  "data": {
    "Get": {
      "Article": [
        {
          "title": "9 home improvement projects that are easier – and often cheaper – in the winter"
        },
      ]
  },
  "errors": null
} 

Multiple operands

You can set multiple operands by providing an array.

For example, these filters select based on the class Article with a wordCount higher than 1000 and who are published before January 1st 2020. Note that you can filter a date and time just similar to numbers, with the valueDate given as string. Note that the valueDate should be formatted according to standard RFC3339.

  {
  Get {
    Article(where: {
      operator: And,
      operands: [{
          path: ["wordCount"],
          operator: GreaterThan,
          valueInt: 1000
        }, {
          path: ["wordCount"],
          operator: LessThan,
          valueInt: 1500
        }]
      }) {
      title
      wordCount
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Console.

Like operator

Using the Like operator allows you to do string searches based on partial match. The capabilities of this operator are:

  • ? -> exactly one unknown character
    • car? matches cart, care, but not car
  • * -> zero, one or more unknown characters
    • car* matches car, care, carpet, etc
    • *car* matches car, healthcare, etc.
  {
  Get {
    Publication(where: {
          path: ["name"],
          operator: Like,
          valueString: "New *"
      }) {
      name
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Console.

Notes

Each query using the Like operator iterates over the entire inverted index for that property. The search time will go up linearly with the dataset size. Be aware that there might be a point where this query is too expensive and will not work anymore. We will improve this implementation in a future release. You can leave feedback or feature requests in a Github issue.

Example response

{
  "data": {
    "Get": {
      "Publication": [
        {
          "name": "New Yorker"
        },
        {
          "name": "New York Times"
        }
      ]
    }
  },
  "errors": null
}

Beacon (reference) filters

You can also search for the value of the property of a beacon.

For example, these filters select based on the class Article but who have inPublication set to New Yorker.

  {
  Get {
    Article(where: {
        path: ["inPublication", "Publication", "name"],
        operator: Equal,
        valueString: "New Yorker"
      }) {
      title
      inPublication{
        ... on Publication{
          name
        }
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Console.

Filter objects by count of reference

Above example shows how filter by reference can solve straightforward questions like “Find all articles that are published by New Yorker”. But questions like “Find all articles that are written by authors that wrote at least two articles”, cannot be answered by the above query structure. It is however possible to filter by reference count. To do so, simply provide one of the existing compare operators (Equal, LessThan, LessThanEqual, GreaterThan, GreaterThanEqual) and use it directly on the reference element. For example:

  {
  Get {
    Author(
      where:{
        valueInt: 2,
        operator: GreaterThanEqual,
        path: ["WroteArticles"]
      }
    ) {
      name
      wroteArticles {
        ... on Article {
          title
        }
      }
    }
  }
 }

🟢 Click here to try out this graphql example in the Weaviate Console.

GeoCoordinates filter

A special case of the Where filter is with geoCoordinates. This filter is only supported by the Get{} function. If you’ve set the geoCoordinates property type, you can search in an area based on kilometers.

For example, this curious returns all in a radius of 2KM around a specific geo-location:

  {
  Get {
    Publication(where: {
      operator: WithinGeoRange,
      valueGeoRange: {
        geoCoordinates: {
          latitude: 51.51,    # latitude
          longitude: -0.09    # longitude
        },
        distance: {
          max: 2000           # distance in meters
        }
      },
      path: ["headquartersGeoLocation"] # property needs to be of geoLocation type.
    }) {
      name
      headquartersGeoLocation {
        latitude
        longitude 
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Console.

Example response

{
  "data": {
    "Get": {
      "Publication": [
        {
          "headquartersGeoLocation": {
            "latitude": 51.512737,
            "longitude": -0.0962234
          },
          "name": "Financial Times"
        },
        {
          "headquartersGeoLocation": {
            "latitude": 51.512737,
            "longitude": -0.0962234
          },
          "name": "International New York Times"
        }
      ]
    }
  },
  "errors": null
}

Limit filter

Supported by the Get{}, Explore{} and Aggregate{} function.

A limit filter limits the number of results.

An example of a stand-alone limit filter:

  {
  Get {
    Article(limit:5) {
      title
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Console.

Example response

{
  "data": {
    "Get": {
      "Article": [
        {
          "title": "The War Vet, the Dating Site, and the Phone Call From Hell"
        },
        {
          "title": "Opinion | John Lennon Told Them ‘Girls Don’t Play Guitar.’ He Was So Wrong."
        },
        {
          "title": "The press pressed - Brazilian prosecutors go after Glenn Greenwald, an American journalist"
        },
        {
          "title": "Not to Ruin the Super Bowl, but the Sea Is Consuming Miami"
        },
        {
          "title": "Coca-Cola Resurrects Post of Chief Marketing Officer"
        }
      ]
    }
  },
  "errors": null
}

NearVector filter

Supported by the Get{} function. (Note that this filter is different from the GraphQL Explore{} function )

Note: Cannot use multiple 'near' filters, or a 'near' filter along with an 'ask' filter!

You can use an explore filter to find data objects close to a specified vector in your dataset. The nearVector{} filter is structured as follows for the Get{} function:

  {
  Get{
    Publication(
      nearVector: {
        vector: [-0.36840257,0.13973749,-0.28994447,-0.18607682,0.20019795,0.15541431,-0.42353877,0.30262852,0.2724561,0.07069917,0.4877447,0.038771532,0.64523,-0.15907241,-0.3413626,-0.026682584,-0.63310874,-0.33411884,0.082939014,0.30305764,0.045918174,-0.21439327,-0.5005205,0.6210859,-0.2729049,-0.51221114,0.09680918,0.094923325,-0.15688285,-0.07325482,0.6588305,0.0523736,-0.14173415,-0.27428055,0.25526586,0.057506185,-0.3103442,0.028601522,0.124522656,0.66984487,0.12160647,-0.5090515,-0.540393,-0.39546522,-0.2201204,0.34625968,-0.21068871,0.21132985,0.048714135,0.09043683,0.3176081,-0.056684002,-0.12117501,-0.6591976,-0.26731065,0.42615625,0.33333477,-0.3240578,-0.18771006,0.2328068,-0.17239179,-0.33583146,-0.6556605,-0.10608161,-0.5135395,-0.25123677,-0.23004892,0.7036331,0.04456794,0.41253626,0.27872285,-0.28226635,0.11927197,-0.4677766,0.4343466,-0.17538455,0.10621233,0.95815116,0.23587844,-0.006406698,-0.10512518,-1.1125883,-0.37921682,0.040789194,0.676718,0.3369762,0.040712647,0.580487,0.20063736,-0.021220192,-0.09071747,-0.0023735985,0.30007777,-0.039925132,0.4035474,-0.2518212,-0.17846306,0.12371392,-0.0703354,-0.3752431,-0.652917,0.5952828,1.3426708,-0.08167235,-0.38515738,0.058423538,-0.08100355,-0.192886,0.3745164,-0.23291737,0.33326542,-0.6019264,-0.42822492,-0.6524583,-0.15210791,-0.5073593,0.022548754,-0.058033653,-0.47369233,-0.30890635,0.6338296,0.0017854869,0.1954949,0.99348027,-0.26558784,-0.058124136,1.149388,0.02915948,0.013422121,0.25484946,-0.030017598,-0.23879935,0.053123385,-0.36463016,-0.0024245526,0.1202083,-0.45966506,-0.34140104,-0.08484162,-0.03537422,-0.2817959,0.25044164,-0.5060605,0.1252808,-0.032539487,0.110069446,-0.20679846,-0.46421885,-0.4141739,0.26994973,-0.070687145,0.16862138,-0.20162229,0.22199251,-0.2771402,0.23653336,0.16585203,-0.08286354,-0.15343396,0.23893964,-0.7453282,-0.16549355,-0.1947069,0.46136436,0.22064126,0.28654936,-0.038697664,0.037633028,-0.80988157,0.5094175,-0.0920082,0.25405347,-0.64169943,0.43366328,-0.2999211,-0.4090591,0.11957859,0.00803617,-0.0433745,0.12818244,0.28464508,-0.31760025,0.16558012,-0.33553946,-0.3943465,0.59569097,-0.6524206,0.3683173,-0.60456693,0.2046492,0.46010277,0.24695799,0.2946015,0.11376746,-0.027988048,0.03749422,-0.16577742,0.23407385,-0.0231737,-0.023245076,0.08752677,0.2299883,0.35467404,0.046193745,-0.39828986,0.21079691,0.38396686,-0.0018698421,0.16047359,-0.057517264,-0.203534,0.23438136,-0.84250915,0.22371331,0.0058325706,0.30733636,0.19518353,-0.108008966,0.6509316,0.070131645,-0.24023099,0.28779706,0.2326336,0.07004021,-0.45955566,0.20426086,-0.37472793,-0.049604423,0.4537271,0.6133582,-1.0527759,-0.5472505,0.15193434,0.5296606,-0.11560251,0.07279209,0.40557706,0.2505283,0.24490519,0.017602902,-0.004647707,0.16608049,0.12576887,0.118216865,0.4403996,0.39552462,-0.22196701,-0.061155193,0.03693534,-0.4022908,0.3842317,-0.0831345,0.01930883,0.3446575,-0.2167439,-0.23994556,-0.09370326,-0.3671856,0.044011243,0.017895095,-0.019855855,-0.16416992,0.17858285,0.31287143,0.38368022,-0.006513525,0.45780763,-0.23027879,0.108570844,-0.4449492,-0.035763215,0.03818417,0.040017277,-0.17022872,-0.2622464,0.65610534,0.16720143,0.2515769,-0.23535803,0.62484455,0.16771325,-0.62404263,0.19176348,-0.72786695,0.18485649,-0.30914405,-0.3230534,-0.24064465,0.28841522,0.39792386,0.15618932,0.03928854,0.18277727,-0.101632096,0.1868196,-0.33366352,0.086561844,0.48557812,-0.6198209,-0.07978742]
      }
    ){
      name
      _additional {
        certainty
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Console.

Note that the length of the given vector in the filter needs to be of the same length as the data objects in your vector space (300 in case of text2vec-contextionary).

Certainty

You can set a minimum required certainty, which will be used to determine which data results to return. The value is a float between 0.0 (return all data objects, regardless similarity) and 1.0 (only return data objects that are matching completely, without any uncertainty). The certainty of a query result is computed by normalized distance of the fuzzy query and the data object in the vector space.

NearObject filter

Weaviate can search based on a data object. Weaviate will return data objects that are closest to this data object in the semantic space.

Note: Cannot use multiple 'near' filters, or a 'near' filter along with an 'ask' filter!

You can specify an object’s id or beacon in the filter, along with a desired certainty:

  {
  Get{
    Publication(
      nearObject: {
        id: "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", # or weaviate://localhost/e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf
        certainty: 0.7
      }
    ){
      name
      _additional {
        certainty
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Console.

Note that the first result will always be the object in the filter itself.

Near object search can also be combined with the text2vec-contextionary module as movement.

Group filter (entity merging)

Supported by the Get{} function.

You can use a group filter to combine similar concepts (aka entity merging). There are two ways of grouping objects with a semantic similarity together.

  • closest, which shows the one result closest to the others.
  • merge, which merges all results into one.

The group{} filter is structured as follows for the Get{} function:

{
  Get{
    <Class>(
      group: {
        type: <String>  # "closest" or "merge"
        force: <Number> # percentage as float (0.75 = 75%) how closely merge items should be related       
      }
    ){
      <property>
    }
  }
}

Note that all words in the concepts argument array should be present in the Contextionary.

An example query:

  {
  Get {
    Publication(
      group:{
        type: merge,
        force:0.05
      }
    ) {
      name
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Console.

This results in the following. Note that publications International New York Times, The New York Times Company and New York Times are merged. The property values that do not have an exact overlap will all be shown, with the value of the most central concept before the brackets.

{
  "data": {
    "Get": {
      "Publication": [
        {
          "name": "Vogue"
        },
        {
          "name": "Wired"
        },
        {
          "name": "Financial Times"
        },
        {
          "name": "New Yorker"
        },
        {
          "name": "The Economist"
        },
        {
          "name": "International New York Times (The New York Times Company, New York Times)"
        },
        {
          "name": "Wall Street Journal"
        },
        {
          "name": "CNN"
        },
        {
          "name": "Game Informer"
        },
        {
          "name": "The Guardian"
        },
        {
          "name": "Fox News"
        }
      ]
    }
  },
  "errors": null
}

More Resources

If you can’t find the answer to your question here, please look at the:

  1. Frequently Asked Questions. Or,
  2. Knowledge base of old issues. Or,
  3. For questions: Stackoverflow. Or,
  4. For issues: Github. Or,
  5. Ask your question in the Slack channel: Slack.
Tags
  • graphql
  • filters