POST
/
query-data
/
{namespace}
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "data": "What is Upstash?", "topK": 2, "includeMetadata": true }'

{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}
To use this endpoint, the index must be created with an embedding model.
Query will run against the default namespace by default. You can use a different namespace by specifying it in the request path.

​
Request

It is also possible to send a batch query request by providing an array of fields below.
​
data
string
required
The raw text data to embed and query.
​
topK
number
default:"10"
required
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.
​
includeData
boolean
default:"false"
Whether to include the data of the vectors in the response. When set to true, data will contain the raw text data used while upserting.
​
filter
string
default:""
Metadata filter to apply.
​
weightingStrategy
string
For sparse vectors of sparse and hybrid indexes, specifies what kind of weighting strategy should be used while querying the matching non-zero dimension values of the query vector with the documents.If not provided, no weighting will be used.Only possible value is IDF (inverse document frequency).
​
fusionAlgorithm
string
Fusion algorithm to use while fusing scores from dense and sparse components of a hybrid index.If not provided, defaults to RRF (Reciprocal Rank Fusion).Other possible value is DBSF (Distribution-Based Score Fusion).
​
queryMode
string
Query mode for hybrid indexes with Upstash-hosted embedding models.Specifies whether to run the query in only the dense index, only the sparse index, or in both.If not provided, defaults to HYBRID.Possible values are HYBRID, DENSE, and SPARSE.

​
Path

​
namespace
string
default:""
The namespace to use. When no namespace is specified, the default namespace will be used.

​
Response

If the request was an array of a single element, or a JSON object, an object with the following fields is returned. If the request was an array of more than one items, an array of objects below is returned, one for each query item.
For dense indexes, 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.For sparse and hybrid indexes, scores can be arbitrary values, but the score will be higher for more similar vectors.
​
Scores
Object[]
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "data": "What is Upstash?", "topK": 2, "includeMetadata": true }'

{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}