[Search] Add knowledge base retrieve stream convenience APIs - #50210
Open
Xiaofei Cao (XiaofeiCao) wants to merge 9 commits into
Open
Conversation
Add regeneration-safe retrieveStream convenience APIs, typed knowledge-base stream events, and Search-local SSE parsing and lifecycle support. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: eecc64df-f690-4410-b68c-b45e323ec918
Remove the generated zero-argument helper that calls an overload no longer present after the synonym-map listing API update. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: eecc64df-f690-4410-b68c-b45e323ec918
|
Azure Pipelines: 34 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run. |
| private static final String RESPONSE_COMPLETED_JSON = "{\"statusCode\":200,\"response\":{}}"; | ||
|
|
||
| @Test | ||
| public void convertsAllStreamEventVariants() { |
Contributor
Author
There was a problem hiding this comment.
event model/wrapper deserialization tests
| */ | ||
| @Generated | ||
| @ServiceMethod(returns = ReturnType.COLLECTION) | ||
| public Flux<ServerSentEvent<KnowledgeBaseRetrievalStreamEvent>> |
Contributor
Author
There was a problem hiding this comment.
async retrieveStream
| */ | ||
| @Generated | ||
| @ServiceMethod(returns = ReturnType.SINGLE) | ||
| public void retrieveStream(KnowledgeBaseRetrievalOptions retrievalRequest, |
Contributor
Author
There was a problem hiding this comment.
sync retrieveStream
Keep knowledge base stream event dispatch and payload decoding in the unexported knowledgebases implementation package while preserving generated client wiring. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: eecc64df-f690-4410-b68c-b45e323ec918
Keep the target branch's repaired synonym-map convenience method and preserve the regeneration-safe knowledge base retrieve stream implementation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: eecc64df-f690-4410-b68c-b45e323ec918
| /** | ||
| * Represents a knowledge base retrieval stream event that is not recognized by this SDK version. | ||
| */ | ||
| public final class UnknownKnowledgeBaseRetrievalStreamEvent extends KnowledgeBaseRetrievalStreamEvent { |
Contributor
Author
There was a problem hiding this comment.
For unknown events, we'll not throw exception, but put them all in this UnknownKnowledgeBaseRetrievalStreamEvent.
Welcome suggestions.
Member
There was a problem hiding this comment.
I think this is fine. I believe the other langs are doing the same
Treat terminal predicates as inclusive early-stop signals while allowing EOF and HTTP 204 responses to complete normally without terminal events. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: eecc64df-f690-4410-b68c-b45e323ec918
Keep Search-specific knowledge base stream coverage while relying on the Azure Core SSE PR for generic parser, Flux, response, and lifecycle tests. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: eecc64df-f690-4410-b68c-b45e323ec918
Xiaofei Cao (XiaofeiCao)
marked this pull request as ready for review
August 24, 2026 07:35
|
Azure Pipelines: 34 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds regeneration-safe, typed server-sent events (SSE) convenience APIs for Knowledge Base retrieveStream in azure-search-documents, including Search-local SSE parsing utilities and typed wrappers for known knowledge-base events with a forward-compatible “unknown event” fallback.
Changes:
- Introduces Search-local SSE public models (
ServerSentEvent,ServerSentEventListener) and internal stream parsing/lifecycle utilities. - Adds typed Knowledge Base retrieval stream event wrappers + converter, and new sync/async
retrieveStreamconvenience APIs that emit/dispatch typed SSE events. - Adds focused tests for stream event conversion and client integration, and updates the changelog.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| sdk/search/azure-search-documents/src/test/java/com/azure/search/documents/knowledgebases/KnowledgeBaseRetrievalStreamTests.java | Adds tests validating typed event conversion and sync/async streaming behavior. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/ServerSentEventListener.java | Adds public sync listener contract for SSE consumption. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/ServerSentEvent.java | Adds public typed SSE event model and internal construction hook. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/implementation/sse/ServerSentEventStreams.java | Adds facade utilities to decode/listen to SSE streams from a single response. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/implementation/sse/ServerSentEventStreamResponse.java | Validates SSE response status/content-type and supports body cancellation. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/implementation/sse/ServerSentEventStream.java | Implements SSE decoding and sync listener processing. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/implementation/sse/ServerSentEventHelper.java | Internal accessor helper for constructing ServerSentEvent. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseRetrievalStreamEvent.java | Adds base type for typed KB retrieval stream events + terminal flag. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/UnknownKnowledgeBaseRetrievalStreamEvent.java | Adds raw-data fallback model for unknown event names. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseRetrievalStartedStreamEvent.java | Adds typed wrapper for retrieval.started. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseActivityStartedStreamEvent.java | Adds typed wrapper for activity.started. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseActivityCompletedStreamEvent.java | Adds typed wrapper for activity.completed. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseAnswerCompletedStreamEvent.java | Adds typed wrapper for answer.completed. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseReferencesCompletedStreamEvent.java | Adds typed wrapper for references.completed. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseErrorStreamEvent.java | Adds typed terminal wrapper for error. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseResponseCompletedStreamEvent.java | Adds typed terminal wrapper for response.completed. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/implementation/KnowledgeBaseRetrievalStreamEventConverter.java | Adds event-name-to-typed-model conversion logic. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/KnowledgeBaseRetrievalClient.java | Adds new public sync retrieveStream(..., listener) convenience API. |
| sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/KnowledgeBaseRetrievalAsyncClient.java | Adds new public async retrieveStream(...) convenience API returning Flux. |
| sdk/search/azure-search-documents/customizations/src/main/java/SearchCustomizations.java | Injects regeneration-safe additions for SSE + KB streaming APIs/models. |
| sdk/search/azure-search-documents/CHANGELOG.md | Documents the newly added typed SSE streaming APIs and models. |
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: eecc64df-f690-4410-b68c-b45e323ec918
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: eecc64df-f690-4410-b68c-b45e323ec918
efrainretana
approved these changes
Aug 24, 2026
There was a problem hiding this comment.
High-level design thought, instead of inlining all the custom code here without IDE capabilities, why not add a utility class in implementation which adds these features and then the customizations here are just having the Knowledge Base clients calling those methods
Alan Zimmer (alzimmermsft)
approved these changes
Aug 25, 2026
Co-authored-by: Alan Zimmer <48699787+alzimmermsft@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds regeneration-safe convenience APIs for knowledge-base
retrieveStreamon top of #49988.Fluxand sync listener-based typed SSE APIs.azure-core.SearchCustomizations.Testing