Run a Vector Search with the REST API and curl/HTTP

  • how-to
    You can use the REST API and a curl command to run a search against a Vector Search index and return similar vectors.

    For more information about how the Search Service scores documents in search results, see Scoring for Search Queries.



    To run 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. Enter your username, password, and the Search Service endpoint on port 8094 with the name of the Vector Search index you want to query:

      curl -s -XPUT -H "Content-Type: application/json" \
      -u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME}/query -d \

      To use SSL, use the https protocol in the Search Service endpoint URL and port 18094.

    4. Enter the JSON payload for your query.

      You can copy the JSON for a Query Request from the Couchbase Server Web Console to use in your REST API call. For more information about how to perform a search with the UI, see Run A Simple Search with the Web Console.


    In the following example, the JSON payload uses both a query and knn object to run both a Vector Search and traditional Search query on an index named color-index.

    The query searches for a specified Euclidean distance color vector, but uses the query object to search for a color with a brightness value in the range of 70-80:

    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 ]

    The Search Service combines the Vector search results from the knn object with the traditional query object by using an OR function. If the same documents match the knn and query objects, the Search Service ranks those documents higher in search results.

    For a more complex query, you can copy the query object from the example under Example: Running a Semantic Search Query with a Large Embedding Vector to use in your REST API call.

    For more information about the available properties for a Search query JSON payload, see Search Request JSON Properties.

    Next Steps

    If you do not get the search results you were expecting, you can change the JSON definition for your Search index or change the parameters for your Search query.