Vector API reference

Dapr provides an API to manage collections and to upsert, retrieve, delete, and run similarity queries over dense vectors in vector databases. For an overview of concepts and features, see the vector API overview.

All HTTP request and response bodies use the JSON mapping of the vector protobuf definitions:

• Field names are in lowerCamelCase.
• bytes fields, such as record payload, are base64-encoded strings.
• Enum values are sent and returned as their names, for example DISTANCE_METRIC_COSINE.
• 64-bit integers, such as recordCount, are returned as strings.
• Durations, such as waitTimeout, are strings with an s suffix, for example "10s".
• Responses include fields that hold their default value, for example "recordCount": "0", "score": 0, or an empty values array. Fields declared optional, such as record payload and metadata, are omitted when unset.
• Unknown request fields are ignored.

Routes without a request body (get collection, list collections, and delete collection) take component-specific metadata as metadata.<key>=<value> query parameters.

Create collection

Creates a collection in the vector store.

POST http://localhost:<daprPort>/v1.0-alpha1/vector/<storeName>/collections/<collection>

URL parameters

Request body

Distance metrics

HTTP response codes

Example

curl -X POST http://localhost:3500/v1.0-alpha1/vector/myvectors/collections/cars \
  -H "Content-Type: application/json" \
  -d '{
        "dimensions": 4,
        "metric": "DISTANCE_METRIC_COSINE"
      }'

Get collection

Gets information about a collection.

GET http://localhost:<daprPort>/v1.0-alpha1/vector/<storeName>/collections/<collection>

URL parameters

Query parameters

Response content

HTTP response codes

Example

curl http://localhost:3500/v1.0-alpha1/vector/myvectors/collections/cars

{
  "collection": "cars",
  "recordCount": "3",
  "properties": {
    "filterableAttributes": "daprMetadata",
    "primaryKey": "id"
  },
  "dimensions": 4,
  "metric": "DISTANCE_METRIC_COSINE"
}

List collections

Lists the collections in the vector store.

GET http://localhost:<daprPort>/v1.0-alpha1/vector/<storeName>/collections

URL parameters

Query parameters

Response content

HTTP response codes

Example

curl http://localhost:3500/v1.0-alpha1/vector/myvectors/collections

{
  "collections": ["cars", "products"]
}

Delete collection

Deletes a collection and all the records in it.

DELETE http://localhost:<daprPort>/v1.0-alpha1/vector/<storeName>/collections/<collection>

URL parameters

Query parameters

HTTP response codes

When a resiliency retry policy retries the delete and a later attempt finds that the collection no longer exists, the delete succeeds, because an earlier attempt most likely deleted it. A NOT_FOUND on the first attempt is returned as is.

Example

curl -X DELETE http://localhost:3500/v1.0-alpha1/vector/myvectors/collections/cars

Upsert vectors

Writes records with a keyed upsert. A record with an ID that already exists in the collection is replaced.

POST http://localhost:<daprPort>/v1.0-alpha1/vector/<storeName>/collections/<collection>/vectors

URL parameters

Request body

Record

Response content

An upsert with no records returns INDEX_ACK_COMPLETED without calling the vector store.

HTTP response codes

Example

curl -X POST http://localhost:3500/v1.0-alpha1/vector/myvectors/collections/cars/vectors \
  -H "Content-Type: application/json" \
  -d '{
        "records": [
          {
            "id": "car-1",
            "values": [1, 0, 0, 0],
            "metadata": { "make": "tesla", "year": 2023, "dealer": { "city": "Seattle" } },
            "payload": "eyJuYW1lIjoiTW9kZWwgMyJ9"
          }
        ],
        "options": {
          "mode": "INDEXING_MODE_WAIT_FOR_COMPLETION",
          "waitTimeout": "10s",
          "onWaitTimeout": "INDEXING_WAIT_TIMEOUT_ACTION_FAIL_REQUEST"
        }
      }'

{
  "failedItems": [],
  "ack": "INDEX_ACK_COMPLETED"
}

Get vectors

Gets records by ID.

POST http://localhost:<daprPort>/v1.0-alpha1/vector/<storeName>/collections/<collection>/vectors/get

URL parameters

Request body

Response content

HTTP response codes

Example

curl -X POST http://localhost:3500/v1.0-alpha1/vector/myvectors/collections/cars/vectors/get \
  -H "Content-Type: application/json" \
  -d '{
        "ids": ["car-1", "car-42"],
        "includeValues": true
      }'

{
  "records": [
    {
      "id": "car-1",
      "values": [1, 0, 0, 0],
      "payload": "eyJuYW1lIjoiTW9kZWwgMyJ9",
      "metadata": { "dealer": { "city": "Seattle" }, "make": "tesla", "year": 2023 }
    }
  ]
}

Delete vectors

Deletes records by ID. Deleting is a write and shares the acknowledgement model of upsert vectors. IDs that don’t exist are not an error.

POST http://localhost:<daprPort>/v1.0-alpha1/vector/<storeName>/collections/<collection>/vectors/delete

URL parameters

Request body

Response content

HTTP response codes

Example

curl -X POST http://localhost:3500/v1.0-alpha1/vector/myvectors/collections/cars/vectors/delete \
  -H "Content-Type: application/json" \
  -d '{
        "ids": ["car-1", "car-2"]
      }'

{
  "ack": "INDEX_ACK_QUEUED"
}

Query vectors

Finds the records closest to a query vector or to an existing record.

POST http://localhost:<daprPort>/v1.0-alpha1/vector/<storeName>/collections/<collection>/query

URL parameters

Request body

Vector query

All query fields go inside query; because unknown fields are ignored, a field such as vector placed at the top level of the request body has no effect and the request is rejected for a missing query.

Filter language

Filters are JSON objects that vector components translate into their native query language. Field paths address keys of the record metadata and use dotted notation for nested keys, for example dealer.city. A field set directly to a value is an equality match, and multiple conditions in the same object are combined with a logical AND.

{
  "$or": [
    { "make": "tesla", "year": { "$gte": 2024 } },
    { "dealer.city": { "$in": ["Seattle", "Portland"] } }
  ]
}

Response content

HTTP response codes

Example

curl -X POST http://localhost:3500/v1.0-alpha1/vector/myvectors/collections/cars/query \
  -H "Content-Type: application/json" \
  -d '{
        "query": {
          "vector": { "values": [1, 0, 0, 0] },
          "topK": 2,
          "filter": { "make": "tesla" },
          "includePayload": true,
          "scoreThreshold": 0.5
        }
      }'

{
  "matches": [
    {
      "record": {
        "id": "car-1",
        "values": [],
        "payload": "eyJuYW1lIjoiTW9kZWwgMyJ9",
        "metadata": { "dealer": { "city": "Seattle" }, "make": "tesla", "year": 2023 }
      },
      "score": 1
    }
  ],
  "metric": "DISTANCE_METRIC_COSINE"
}

Batch query vectors

Runs multiple queries against the same collection. Each query is evaluated independently and succeeds or fails on its own.

POST http://localhost:<daprPort>/v1.0-alpha1/vector/<storeName>/collections/<collection>/batch-query

URL parameters

Request body

Response content

A query that fails validation, for example one that sets neither vector nor byId or has an empty query vector, isn’t sent to the vector store. Its slot holds an INVALID_ARGUMENT error with the DAPR_VECTOR_INVALID_REQUEST reason and a google.rpc.BadRequest field violation that names the query by its position, for example queries[1] or queries[1].vector.values. The other queries still run.

Only request-wide failures, such as a missing vector store or collection, invalid credentials, or a transport error, fail the whole request.

HTTP response codes

Example

curl -X POST http://localhost:3500/v1.0-alpha1/vector/myvectors/collections/cars/batch-query \
  -H "Content-Type: application/json" \
  -d '{
        "queries": [
          { "vector": { "values": [1, 0, 0, 0] }, "topK": 1 },
          { "topK": 1 },
          { "byId": "car-1", "topK": 1, "metric": "DISTANCE_METRIC_EUCLIDEAN" }
        ]
      }'

In this example, the second query sets neither vector nor byId, so Dapr rejects it without calling the vector store. The third query asks for a metric that Meilisearch doesn’t support, so the vector store reports an error in its slot. The first query returns matches:

{
  "results": [
    {
      "response": {
        "matches": [
          {
            "record": {
              "id": "car-1",
              "values": [],
              "metadata": { "dealer": { "city": "Seattle" }, "make": "tesla", "year": 2023 }
            },
            "score": 1
          }
        ],
        "metric": "DISTANCE_METRIC_COSINE"
      }
    },
    {
      "error": {
        "code": 3,
        "message": "exactly one of vector or by_id must be set",
        "details": [
          {
            "@type": "type.googleapis.com/google.rpc.BadRequest",
            "fieldViolations": [
              {
                "field": "queries[1]",
                "description": "exactly one of vector or by_id must be set",
                "reason": "",
                "localizedMessage": null
              }
            ]
          },
          {
            "@type": "type.googleapis.com/google.rpc.ResourceInfo",
            "resourceType": "vector",
            "resourceName": "myvectors",
            "owner": "",
            "description": ""
          },
          {
            "@type": "type.googleapis.com/google.rpc.ErrorInfo",
            "reason": "DAPR_VECTOR_INVALID_REQUEST",
            "domain": "dapr.io",
            "metadata": {}
          }
        ]
      }
    },
    {
      "error": {
        "code": 3,
        "message": "meilisearch only supports the cosine distance metric for user-provided embeddings",
        "details": []
      }
    }
  ]
}

Errors

Errors the Dapr runtime detects itself, such as a missing vector store or an invalid request, are returned in the standard Dapr error format with the following error codes:

Errors returned by the vector store, such as a missing collection, are passed through with their canonical gRPC status code and details. Over HTTP, the response body uses the canonical code name as errorCode, carries the status details in details, and the HTTP status is mapped from the code in the same way as for the search API, for example NOT_FOUND to 404, ALREADY_EXISTS to 409, UNAVAILABLE to 503, and DEADLINE_EXCEEDED to 504:

{
  "errorCode": "ALREADY_EXISTS",
  "message": "meilisearch collection \"cars\" already exists"
}

A vector store error that carries no gRPC status is reported as INTERNAL.

A write whose outcome can’t be determined, because the vector store reported a batch-level failure without saying which records were applied, carries a google.rpc.ErrorInfo detail with the INDEXING_OUTCOME_UNKNOWN reason in the dapr.io domain. Retry the request; keyed upserts and deletes are idempotent.

Resiliency

Vector store calls run under the store’s resiliency policy:

• Retry policies can match the vector store’s canonical gRPC code with matching.gRPCStatusCodes.
• A policy timeout is returned as DEADLINE_EXCEEDED, a cancelled request as CANCELLED, and an open circuit breaker as UNAVAILABLE.
• ALREADY_EXISTS on a retried create collection is returned unchanged, because the collection may belong to another caller. NOT_FOUND on a retried delete collection is treated as success.
• A write whose INDEXING_WAIT_TIMEOUT_ACTION_FAIL_REQUEST wait expired isn’t retried.

gRPC API

The vector API is also available over gRPC through the Dapr service in the Dapr runtime protos:

Over gRPC, storeName and collection are fields of the request message and payload is sent as raw bytes.

Next steps

• Vector API overview
• How-To: Store and query vectors
• Vector component specs