POST
/
query
/
{namespace}
curl $UPSTASH_VECTOR_REST_URL/query \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "vector": [0.1, 0.2], "topK": 2, "includeMetadata": true }'
{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}

Query will run against the default namespace by default. You can use a different namespace by specifying it in the request path.

Request

vector
number[]
required

The query vector

The query vector should have the same dimensions as your index.

topK
number
default: "10"

The total number of the vectors that you want to receive as a query result. The response will be sorted based on the distance metric score, and at most topK many vectors will be returned.

includeMetadata
boolean
default: "false"

Whether to include the metadata of the vectors in the response, if any. It is recommended to set this to true to easily identify vectors.

includeVectors
boolean
default: "false"

Whether to include the vector values in the response. It is recommended to set this to false as the vector values can be quite big, and not needed most of the time.

filter
string
default: ""

Metadata filter to apply.

Path

namespace
string
default: ""

The namespace to use. When no namespace is specified, the default namespace will be used.

Response

The score is normalized to always be between 0 and 1. The closer the score is to 1, the more similar the vector is to the query vector. This does not depend on the distance metric you use.

Scores
Object[]
id
string
required

The id of the vector.

score
number
required

The similarity score of the vector, calculated based on the distance metric of your index.

vector
number[]

The vector value.

metadata
Object

The metadata of the vector, if any.

curl $UPSTASH_VECTOR_REST_URL/query \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "vector": [0.1, 0.2], "topK": 2, "includeMetadata": true }'
{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}