Search API reference

Dapr provides an API to manage indexes and to index, retrieve, delete, and query documents in lexical (full-text) search engines. For an overview of concepts and features, see the search API overview.

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

• Field names are in lowerCamelCase.
• bytes fields, such as document content, are base64-encoded strings.
• Enum values are sent and returned as their names, for example INDEX_ACK_COMPLETED.
• 64-bit integers, such as documentCount and totalHits, are returned as strings.
• Durations, such as waitTimeout, are strings with an s suffix, for example "10s" or "1.5s".
• Responses include fields that hold their default value, for example "documentCount": "0", "score": 0, or an empty failedItems array. Fields declared optional are omitted when unset, for example continuationToken on the last page and totalHits when the search store can’t supply one.
• Unknown request fields are ignored.

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

Create index

Creates an index in the search store.

POST http://localhost:<daprPort>/v1.0-alpha1/search/<storeName>/indexes/<index>

URL parameters

Request body

HTTP response codes

Example

curl -X POST http://localhost:3500/v1.0-alpha1/search/mysearch/indexes/articles \
  -H "Content-Type: application/json" \
  -d '{
        "metadata": {
          "filterableAttributes": "category,price",
          "sortableAttributes": "price"
        }
      }'

Get index

Gets information about an index.

GET http://localhost:<daprPort>/v1.0-alpha1/search/<storeName>/indexes/<index>

URL parameters

Query parameters

Response content

HTTP response codes

Example

curl http://localhost:3500/v1.0-alpha1/search/mysearch/indexes/articles

{
  "index": "articles",
  "documentCount": "3",
  "properties": {
    "filterableAttributes": "category,price",
    "primaryKey": "id",
    "sortableAttributes": "id,price"
  }
}

List indexes

Lists the indexes in the search store.

GET http://localhost:<daprPort>/v1.0-alpha1/search/<storeName>/indexes

URL parameters

Query parameters

Response content

HTTP response codes

Example

curl http://localhost:3500/v1.0-alpha1/search/mysearch/indexes

{
  "indexes": ["articles", "products"]
}

Delete index

Deletes an index and all the documents in it.

DELETE http://localhost:<daprPort>/v1.0-alpha1/search/<storeName>/indexes/<index>

URL parameters

Query parameters

HTTP response codes

When a resiliency retry policy retries the delete and a later attempt finds that the index 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/search/mysearch/indexes/articles

Index documents

Indexes documents with a keyed upsert. A document with an ID that already exists in the index is replaced.

POST http://localhost:<daprPort>/v1.0-alpha1/search/<storeName>/indexes/<index>/documents

URL parameters

Request body

Document

Indexing options

The same options apply to every write: index documents, delete documents, and the vector API’s upsert and delete operations.

Indexing options that break these rules are rejected before the write reaches the store, with INVALID_ARGUMENT, the ERR_SEARCH_INVALID_REQUEST error code (ERR_VECTOR_INVALID_REQUEST for the vector API), and a google.rpc.BadRequest field violation on options or options.wait_timeout.

Response content

When no document is left to write, because the request has no documents or every document was rejected, the search store isn’t called and ack is INDEX_ACK_COMPLETED.

HTTP response codes

Example

curl -X POST http://localhost:3500/v1.0-alpha1/search/mysearch/indexes/articles/documents \
  -H "Content-Type: application/json" \
  -d '{
        "documents": [
          {
            "id": "doc-1",
            "content": "eyJ0aXRsZSI6IkdldHRpbmcgc3RhcnRlZCB3aXRoIERhcHIiLCJjYXRlZ29yeSI6Imd1aWRlIiwicHJpY2UiOjEwfQ==",
            "metadata": { "author": "alice" }
          },
          {
            "id": "doc-2",
            "content": "WyJub3QiLCAiYW4iLCAib2JqZWN0Il0="
          }
        ],
        "options": {
          "mode": "INDEXING_MODE_WAIT_FOR_COMPLETION",
          "waitTimeout": "10s",
          "onWaitTimeout": "INDEXING_WAIT_TIMEOUT_ACTION_FAIL_REQUEST"
        }
      }'

In this example, the content of doc-2 is a JSON array rather than an object, so it is rejected while doc-1 is indexed:

{
  "failedItems": [
    {
      "id": "doc-2",
      "error": {
        "code": 3,
        "message": "content must be a JSON object",
        "details": []
      }
    }
  ],
  "ack": "INDEX_ACK_COMPLETED"
}

Get documents

Gets documents by ID.

POST http://localhost:<daprPort>/v1.0-alpha1/search/<storeName>/indexes/<index>/documents/get

URL parameters

Request body

Response content

HTTP response codes

Example

curl -X POST http://localhost:3500/v1.0-alpha1/search/mysearch/indexes/articles/documents/get \
  -H "Content-Type: application/json" \
  -d '{
        "ids": ["doc-1", "doc-42"],
        "includeContent": true
      }'

{
  "documents": [
    {
      "id": "doc-1",
      "content": "eyJjYXRlZ29yeSI6Imd1aWRlIiwicHJpY2UiOjEwLCJ0aXRsZSI6IkdldHRpbmcgc3RhcnRlZCB3aXRoIERhcHIifQ==",
      "metadata": { "author": "alice" }
    }
  ]
}

Delete documents

Deletes documents by ID. Deleting is a write and shares the acknowledgement model of index documents. IDs that don’t exist are not an error, and deletions never report failed items.

POST http://localhost:<daprPort>/v1.0-alpha1/search/<storeName>/indexes/<index>/documents/delete

URL parameters

Request body

Response content

HTTP response codes

Example

curl -X POST http://localhost:3500/v1.0-alpha1/search/mysearch/indexes/articles/documents/delete \
  -H "Content-Type: application/json" \
  -d '{
        "ids": ["doc-1", "doc-2"]
      }'

{
  "ack": "INDEX_ACK_QUEUED"
}

Search

Queries an index.

POST http://localhost:<daprPort>/v1.0-alpha1/search/<storeName>/indexes/<index>/query

URL parameters

Request body

Search query

A query that sets neither text nor native matches every document in the index, subject to filter. All query fields go inside query; because unknown fields are ignored, a field such as text placed at the top level of the request body has no effect.

Filter language

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

{
  "$and": [
    { "category": { "$in": ["guide", "reference"] } },
    { "price": { "$gte": 10, "$lt": 50 } },
    { "$not": { "author.name": "bob" } }
  ]
}

Response content

A continuation token is bound to the query that produced it. To get the next page, send the same query with query.continuationToken set to the token; changing the query, filter, sort, or field options returns INVALID_ARGUMENT. If the search store’s cursor behind the token has expired, the request fails with FAILED_PRECONDITION and the SEARCH_CONTINUATION_EXPIRED error reason.

HTTP response codes

Example

curl -X POST http://localhost:3500/v1.0-alpha1/search/mysearch/indexes/articles/query \
  -H "Content-Type: application/json" \
  -d '{
        "query": {
          "text": "dapr",
          "filter": { "category": "guide" },
          "sort": [ { "field": "price", "order": "SORT_ORDER_ASC" } ],
          "highlightFields": ["title"],
          "includeContent": true,
          "topK": 10
        }
      }'

{
  "hits": [
    {
      "document": {
        "id": "doc-1",
        "content": "eyJjYXRlZ29yeSI6Imd1aWRlIiwicHJpY2UiOjEwLCJ0aXRsZSI6IkdldHRpbmcgc3RhcnRlZCB3aXRoIERhcHIifQ==",
        "metadata": { "author": "alice" }
      },
      "score": 0.9,
      "highlights": {
        "title": "Getting started with <em>Dapr</em>"
      }
    }
  ],
  "totalHits": "1",
  "totalHitsRelation": "TOTAL_HITS_RELATION_ESTIMATE"
}

Errors

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

Errors returned by the search store, such as a missing index, 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:

{
  "errorCode": "ALREADY_EXISTS",
  "message": "meilisearch index \"articles\" already exists"
}

An error with details, such as an expired continuation token:

{
  "errorCode": "FAILED_PRECONDITION",
  "message": "...",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "SEARCH_CONTINUATION_EXPIRED",
      "domain": "dapr.io"
    }
  ]
}

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

Resiliency

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

• Retry policies can match the search 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 index is returned unchanged, because the index may belong to another caller. NOT_FOUND on a retried delete index is treated as success.
• A write whose INDEXING_WAIT_TIMEOUT_ACTION_FAIL_REQUEST wait expired isn’t retried.

Error reasons

Some errors carry a google.rpc.ErrorInfo detail in the dapr.io domain with one of the following reasons:

gRPC API

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

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

Next steps

• Search API overview
• How-To: Index and search documents
• Search component specs