Pre-filtering Vector Searches

  • how-to
    +
    You can specify filters as part of a Vector Search query object to restrict the documents searched in a Search index.

    About Pre-filtering

    The Search Service supports pre-filtering on Vector Search queries. Pre-filtering allows you to execute vector searches over a subset of the vector index, via the means of a filter request that qualifies the subset.

    You cannot use Vector Search on Windows platforms. You can use Vector Search on Linux from Couchbase {page-product-name} version 7.6.0 and MacOS from version 7.6.2.

    You can still use other features of the Search Service.

    Prerequisites

    Procedure

    To add pre-filtering to a Vector Search with the REST API:

    1. In your command-line tool, enter a curl command with the XPOST verb.

    2. Set your header content to include "Content-Type: application/json".

    3. Add your username, password, and the Search Service endpoint on port 8094.

    4. Add the index name you want to query to the endpoint.

      curl -XPOST -H "Content-Type: application/json" \
        -u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/bucket/vector-sample/scope/color/index/{INDEX_NAME}/query \
      -d \
    5. Enter a search query that includes a filter object with your knn object.

      For more information about the filter object, see filter.

    Example: Pre-Filter A Vector Search Query For The Color "Navy"

    For example, the following Vector Search query tries to find matches to a color with an RGB value of [176, 0, 176] with a minimum brightness of 70 and a maximum of 80. A pre-filter on the query will narrow the documents searched inside the Vector Search index to documents that have a color field value that closely matches navy:

    curl -XPOST -H "Content-Type: application/json" \
      -u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/bucket/vector-sample/scope/color/index/color-index/query \
    -d '{
          "fields": ["*"],
          "query": {
            "min": 70,
            "max": 80,
            "inclusive_min": false,
            "inclusive_max": true,
            "field": "brightness"
          },
          "knn": [
            {
              "k": 10,
              "field": "colorvect_l2",
              "vector": [ 176, 0, 176 ],
              "filter": {
                "field":  "color",
                "match": "navy"
              }
            }
          ]
        }'