Skip to content

Search & Vector Stores - #107

Open
mikeee wants to merge 5 commits into
dapr:mainfrom
mikeee:searchvectorstores
Open

mikeee wants to merge 5 commits into
dapr:mainfrom
mikeee:searchvectorstores

Conversation

@mikeee

@mikeee mikeee commented Apr 28, 2026 •

Copy link
Copy Markdown
Member

Purely a building block implementation of the search and vector stores

Co-authored-by: Copilot <copilot@github.com>
Signed-off-by: Mike Nguyen <hey@mike.ee>
@mikeee mikeee mentioned this pull request Apr 28, 2026
4 tasks
Signed-off-by: Mike Nguyen <hey@mike.ee>

This is a proposal surrounding the implementation of two new specialised state stores without bringing into
scope the deep integrations planned on implementation of these building blocks. Whilst the two building
blocks share almost the same envelope, the method of requesting the records can vary significantly and should

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm wondering if it'd make sense to ship a single building block with both of the APIs combined into one. With a single component, we get a unified API for index/upsert/delete documents, and different endpoints for fetching, one for lexical search and one for vector search.
This would be beneficial if a user needs to use both APIs at the same time.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unless there's some scenario you can think of where a query to a provider might do some sort of join operation between lexical and vector searches (e.g. we can offload that heavy lifting to the provider - we absolutely should not do any manipulation of this data in the runtime), I would vote they remain separate.

This obviates the need for another (and differing) capabilities functionality at the building block level, it keeps the APIs for each building block simple and focused and it potentially improves the rate at which provider implementations can be developed and added (e.g. they need only implement the API associated with one block at a time, not have to implement a broader set just for v1.0).

Especially if the results from either are instead used alongside local logic in the app, that's the domain of the SDK to offer a usage smooth experience where it's the domain of the runtime to establish connectivity, issue commands and perform data transfer. I think runtime's role is better suited to small, lean building block APIs going forward.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was considering this too - I can make it clearer in the proposal but I share the same sentiment as Whit.

The two building blocks can be objectively very different. I feel like it may be running the risk of becoming a feature flag mess/very confusing for implementation where providers have differing feature sets that fall distinctly within the lexical or vector search buckets.

We should focus on having distinct building blocks, if you need to use both APIs at the same time then you'd just need to register another component type with the same provider.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing I'd love to see explicitly spelled out is the story for someone who wants to use both search & vector against the same provider. From ^ it sounds like the answer is to register 2 components pointing to the same server.

When that happens, is the underlying data shared - so an item indexed for search and its vector can be tied together by a common ID or are they independent? I think that matters with AI use cases where you might want to store something once and both search it by keyword && find it by similarity.

And is there a scenario where a single query should do both at once - keyword & similarity combined by the provider itself?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rather than trying to design a feature like @cicoyle is describing as a one-off feature for this, I'd much rather take that idea back to the drawing board and figure out if the idea is applicable across more components and design that as a separate runtime feature than necessarily jam in something that potentially complex as a one-off here. Seems like that would dramatically increase the complexity of what's otherwise a pretty straightforward proposal here.

}

message BatchQueryVectorsRequestAlpha1 {
string store_name = 1;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see store_name && collection here and inside QueryVectorsRequestAlpha1 - shall we trim the inner msg?

The current implementations of state stores do not accomodate the necessity to access data not only by
key-value but an extended querying layer. New 'specialised' building blocks facilitate rapid development.

There is a specific need from AI workloads to not only query by key but also by 'relevant' records returned

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add a Use Cases section? I believe it would help ground the separate vs combined API decision - might be good to note under an Alternatives Considered section or similar. There are RAG/agent retrieval patterns where lexical & vector results get fused together. I believe its a first class AI usecase that should be considered, rather than it being an edge case. Its worth deciding if we should have the APIs separate and/or have a hybrid, even if the hybrid API is out of scope for now - it should be thought thru ahead of implementation to prevent breaking changes later on.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One of the key ideas of my proposal to split out into discrete building blocks is to explicitly pivot away from what the key/value state store turned into: a far more use-case governed platform with runtime shims holding together what providers failed to provide.

I would dramatically prefer that if there's an AI use-case, it be proposed as a separate block - more of a composite component that's able to express the individual functionality but which only applies to those providers that can do both operations. This is a central tenant of my handily rejected planes proposal, but is exactly along the lines of what I was thinking.

Some people will just need a vector store. Some people will just need a search store. For those that need both, build something that specifically speaks to that use-case but atop far more generic basic components.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in the scope boundary


This is a proposal surrounding the implementation of two new specialised state stores without bringing into
scope the deep integrations planned on implementation of these building blocks. Whilst the two building
blocks share almost the same envelope, the method of requesting the records can vary significantly and should

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One thing I'd love to see explicitly spelled out is the story for someone who wants to use both search & vector against the same provider. From ^ it sounds like the answer is to register 2 components pointing to the same server.

When that happens, is the underlying data shared - so an item indexed for search and its vector can be tied together by a common ID or are they independent? I think that matters with AI use cases where you might want to store something once and both search it by keyword && find it by similarity.

And is there a scenario where a single query should do both at once - keyword & similarity combined by the provider itself?

mikeee added 3 commits August 9, 2026 13:16
Signed-off-by: Mike Nguyen <hey@mike.ee>
Signed-off-by: Mike Nguyen <hey@mike.ee>
Signed-off-by: Mike Nguyen <hey@mike.ee>

@nelson-parente nelson-parente left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reviewed the implementation in dapr/components-contrib#4613 and dapr/dapr#9974 against this text at 4339cda. The code follows the proposal closely, and the protos and HTTP routes match it one for one. The open threads are further along than the PR page shows.

Five threads are answered in the text but still open. @mikeee, resolve them with a pointer to the line, then @cicoyle can re-review against a short list.

  • Score direction: the VectorMatch.score comment and the vector score table.
    #### Vector score semantics
    `VectorMatch.score` and `score_threshold` use the metric's unnormalized value rather than a provider-specific ranking
    score or a value normalized onto a common range. Components translate their provider's native score representation to
    the following contract:
    | Metric | Score | Better match | Inclusive threshold |
    |--------|-------|--------------|---------------------|
    | Cosine | `dot(a, b) / (norm(a) * norm(b))`, in `[-1, 1]` | Higher | `score >= score_threshold` |
    | Dot product | `dot(a, b)`, unbounded | Higher | `score >= score_threshold` |
    | Euclidean | `sqrt(sum((a_i - b_i)^2))`, in `[0, +inf)` | Lower | `score <= score_threshold` |
    Scores are only comparable when they use the same metric and embedding model. If `metric` is
    `DISTANCE_METRIC_UNSPECIFIED`, the collection's configured metric determines these semantics and the response's
    `metric` field reports that effective metric.
  • A reason code on failed items: FailedItem.error is a google.rpc.Status.
    // FailedItem is shared by document indexing and vector upserts.
    message FailedItem {
    string id = 1;
    // error.code uses a canonical google.rpc.Code and must not be OK.
    // Provider-specific codes may be included in google.rpc.ErrorInfo details.
    google.rpc.Status error = 2;
    }
  • Offset or cursor: opaque continuation tokens.
    #### Search pagination semantics
    The first search request omits `continuation_token`. When more results are available, the response returns an opaque
    token that the caller supplies unchanged in the next request. An empty response token means that the provider
    definitively reports no further results. Callers must not parse, construct, or modify tokens and must tolerate a
    non-empty token leading to a final empty page when provider exhaustion can only be detected by reading the next page.
    The component translates the token to the provider's strongest resumable pagination primitive, such as
    `search_after`, a point-in-time handle, a provider-managed cursor, or an encoded offset for providers that expose only
    offset pagination.
    A continuation token is bound to the component, store, index, query, filter, sort, page size, projection, highlighting,
    and component-declared result-affecting metadata. Transport metadata such as trace or request IDs is not bound. A
    subsequent request repeats those fields unchanged and sets the token from the previous response. A malformed or
    mismatched token returns `INVALID_ARGUMENT`. An expired provider cursor returns `FAILED_PRECONDITION` with
    `google.rpc.ErrorInfo.reason` set to `SEARCH_CONTINUATION_EXPIRED`; callers restart pagination from the first page.
    Pagination requires deterministic ordering. Components append the document ID as a stable tie-breaker when the
    requested sort or provider relevance order is not unique. Providers that only sort on declared attributes (for
    example Meilisearch's `sortableAttributes`) declare the document ID sortable when the index is created, so that the
    tie-breaker is always available. A provider-native query must not embed its own offset, cursor, page size, or
    conflicting sort; such a request returns `INVALID_ARGUMENT`.
    `total_hits` is best-effort and may be omitted. `total_hits_relation` distinguishes an exact total, a lower bound, and
    an estimate. Providers may return it only on the first page, and concurrent writes can change a total reported on
    later pages.
  • Inner store_name and collection on batch queries: the text says they are ignored.
    authentication, transport) fail the RPC as a whole. A query's `store_name` and `collection` are taken from the batch
    request; values set on individual queries are ignored.
  • One block or two: the opening paragraph keeps them separate.
    This is a proposal surrounding the implementation of two new specialised state stores without bringing into
    scope the deep integrations planned on implementation of these building blocks. Whilst the two building
    blocks share almost the same envelope, the method of requesting the records can vary significantly and should
    be kept distinct shapes.

What the text still needs. Each item below is something the code already decided and the proposal does not say.

  1. Use Cases, and whether one index can back both blocks. Cassie's follow-up on the one-or-two thread asked whether the two components can share data. The code answers it by accident: point the vector component at an index the search component created and GetCollection reports Dimensions: 0 as if it were a valid collection. Hybrid retrieval is the main RAG pattern, and today the text only lists it as deferred. A short Use Cases section settles both threads. It needs to say what a user who wants lexical and vector results over the same documents does in alpha.
  2. An empty search query. The oneof allows neither text nor native. The runtime forwards that to the component, Meilisearch treats it as match-all, and its conformance suite depends on that. The contrib doc comment says "exactly one", and the runtime validation list covers the vector oneof but not this one. Write the rule down.
    ### Validation performed by the runtime
    The runtime rejects the following before invoking the component, with `INVALID_ARGUMENT`, HTTP 400, a
    `google.rpc.BadRequest` field violation naming the offending field, and the Dapr error code
    `ERR_SEARCH_INVALID_REQUEST` or `ERR_VECTOR_INVALID_REQUEST`:
    - an empty or duplicated ID in a keyed upsert (`documents.id`, `records.id`);
    - an `IndexingOptionsAlpha1` combination that this proposal forbids (`options`, `options.wait_timeout`);
    - a vector query that does not set exactly one of `vector` / `by_id` (`query`) — inside a batch this is a per-query
    `error` result rather than an RPC failure;
    - a collection created without `dimensions` (`dimensions`).
  3. Inner batch fields. Ignoring them means a caller who sets a different collection on one query gets results from another collection without an error. Alpha is the time to remove the two fields, which is what Cassie asked. The other option is to reject a value that differs from the batch.
  4. The HTTP error body. The runtime renders a component status error with the google.rpc.Code name as errorCode, for example NOT_FOUND, next to the existing ERR_* codes. The component error contract section covers gRPC only. This is a new HTTP contract, so it belongs here.
    ### Component error contract
    Components return errors created with `google.golang.org/grpc/status` carrying a canonical `codes.Code`. The runtime
    passes a status error through unchanged, including any `google.rpc.ErrorInfo` details such as the
    `SEARCH_CONTINUATION_EXPIRED` and `INDEXING_OUTCOME_UNKNOWN` reasons (domain `dapr.io`). An error that is not a status
    error is reported as `INTERNAL`. The runtime never re-wraps a component error with a Dapr error code, so that the
    canonical code and details the caller relies on survive.
    The `search` package in components-contrib provides the shared validators (`ValidateWriteIDs`,
    `ValidateIndexingOptions`) and error helpers (`ContinuationExpiredError`, `IndexingOutcomeUnknownError`) so that
    components and the runtime enforce identical rules.
  5. Token binding. The text binds a continuation token to "component-declared result-affecting metadata", but nothing defines how a component declares it, and the Meilisearch fingerprint leaves metadata out. Define the mechanism or drop the clause.
    A continuation token is bound to the component, store, index, query, filter, sort, page size, projection, highlighting,
    and component-declared result-affecting metadata. Transport metadata such as trace or request IDs is not bound. A

Observability is deferred to beta, which is fine, and the code matches that. The code-level findings are on #4613 and #9974.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants