Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
6d31609
Add Azure AI Search 2026-11-01-preview SDK support
yangylu91 Oct 23, 2026
cf06e53
Complete Search preview field annotations and align spec documentation
yangylu91 Oct 23, 2026
26cb65d
Address Search November preview SDK review feedback
yangylu91 Oct 27, 2026
e466a0a
Deprecate ignored Search field annotation and fix version guidance
yangylu91 Oct 27, 2026
ad5f060
Align Search preview with October GA and validated recordings
hillarykhuu Nov 10, 2026
cbe57f7
Remove unverified Search preview live tests
hillarykhuu Nov 10, 2026
055a418
Restore Search GA test authentication and regression coverage
hillarykhuu Nov 10, 2026
285f7b7
Preserve Search preview integration when rebasing onto GA main
hillarykhuu Nov 11, 2026
95776c7
Preserve Search release-history ordering from main
hillarykhuu Nov 11, 2026
f1c7feb
Fix Search preview coverage documentation spelling
hillarykhuu Nov 11, 2026
3d5d1a1
Update explain stage to use LOGICAL_PLAN constant
hillarykhuu Nov 11, 2026
413fde9
Change listIndexers to block until completion
hillarykhuu Nov 11, 2026
56afc42
Merge branch 'main' into yangylu/dp-2026-11-01-preview
hillarykhuu Nov 11, 2026
0fdf45a
Expose Search listing metadata and typed graph errors
hillarykhuu Nov 11, 2026
5dc0cd2
Fix Search listing metadata paging contract test
hillarykhuu Nov 11, 2026
c5028b7
Fix file knowledge source preview sample argument order
hillarykhuu Nov 11, 2026
90658d2
Make preview retrieval response sample non-destructive
hillarykhuu Nov 11, 2026
f80cd6d
Preserve HTTP errors while polling preview file ingestion
hillarykhuu Nov 11, 2026
2608cd7
Address Search preview review feedback
hillarykhuu Nov 13, 2026
89c8cee
Include October GA in Search version fallback
hillarykhuu Nov 14, 2026
ead432d
Remove custom graph response overloads
hillarykhuu Nov 14, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,11 @@ Categorize each compilation error:
`SearchServiceVersion.java` is generated but customized by `SearchCustomizations.java`.

1. Check `getLatest()` returns the new version
2. In `includeOldApiVersions()`:
- **Remove** any version the generator now produces (prevents duplicates)
- **Add** the previous latest version if not already produced by the generator
3. Verify all expected old versions are present
2. Retain supported GA versions and only the latest preview:
- In `includeOldApiVersions()`, add supported GA versions missing from generated output; do not re-add older previews.
- Remove any version the generator now produces from that list (prevents duplicates).
- Remove obsolete preview constants through `removeOldPreviewApiVersions()`.
3. Regenerate and verify supported GA constants remain, only the latest preview is present, and the latest-preview-only regression test passes.

## Detect Breaking Changes

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,9 @@ Generated methods have `@Generated` annotation. Some generated files contain BOT

## Service Version

`SearchServiceVersion.java` is generated but customized. The generator produces only the latest version constant. Older versions are added by `includeOldApiVersions()` in `SearchCustomizations.java`.
`SearchServiceVersion.java` is generated but customized. Supported GA versions missing from generated output are added by `includeOldApiVersions()` in `SearchCustomizations.java`.

When a new API version is released, the generator produces a new constant and updates `getLatest()`. The previous latest must be added to the customization list -- but only if the generator does NOT also produce it (otherwise you get duplicate enum constants).
Retain supported GA versions and only the latest preview. When a new API version is generated, verify `getLatest()` returns it. Do not re-add obsolete previews in `includeOldApiVersions()`; remove obsolete preview constants through `removeOldPreviewApiVersions()`. Do not add a GA constant already produced by the generator. Regenerate and run the latest-preview-only regression test.

## Key Hand-Written Files

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,11 @@ Note: The `azsdk_customized_code_update` MCP tool can apply many customization f

### 3. includeOldApiVersions

**What**: Prepends older version constants to the SearchServiceVersion enum.
**What**: Prepends supported GA version constants missing from the generated SearchServiceVersion enum.

**Current list**: See `includeOldApiVersions()` in `SearchCustomizations.java` for the authoritative version list. When a new API version is released, add the previous latest to this list -- but only if the generator does not already produce it.
**Current list**: See `includeOldApiVersions()` in `SearchCustomizations.java` for the authoritative GA version list. Do not add a version already produced by the generator or re-add an obsolete preview.

**When to update**: When a new API version is released -- add the previous latest to this list. **Critical**: check if the generator now produces a version that's in this list. If so, remove it to avoid duplicate enum constants.
**When to update**: Retain supported GA versions and only the latest preview. Add supported GA versions missing from generated output, and remove obsolete preview constants through `removeOldPreviewApiVersions()`. If the generator now produces a GA version in the inclusion list, remove it from the list to avoid duplicates. Regenerate and verify the latest-preview-only regression test passes.

### 4. removeGetApis

Expand Down Expand Up @@ -59,7 +59,9 @@ Note: The `azsdk_customized_code_update` MCP tool can apply many customization f
(silently does nothing -- no error, no warning)
[ ] If new API version:
[ ] Check includeOldApiVersions() list for duplicates with generator
[ ] Retain supported GA versions and remove obsolete previews through removeOldPreviewApiVersions()
[ ] Verify getLatest() returns the new version
[ ] Run the latest-preview-only regression test
[ ] If new client classes generated:
[ ] Add hideWithResponseBinaryDataApis() call
[ ] Add addSearchAudienceScopeHandling() call for builder
Expand Down
33 changes: 33 additions & 0 deletions sdk/search/azure-search-documents/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,45 @@

### Features Added

- Added support for `2026-11-01-preview`, now the default service version. Previously supported GA service versions remain available.
- Added synchronous and asynchronous graph queries, typed results, query planning, diagnostics, statistics, and provenance models.
- Added `GraphQueryError` for opt-in typed parsing of graph error bodies without changing existing exceptions.
- Added `listIndexesWithMetadata` and `listIndexStatsSummaryWithMetadata` to read optional service-supplied total counts while preserving existing listing APIs. The preview contract does not define a count-request parameter.
- Added graph extraction, enrichment cache, graph retrieval activities and references, and updated knowledge source and model options.
- Added `none`, `diverse`, and `balanced` vector topic graph retrieval, facet-backed filter hint auto-configuration, and random scoring.
- Restored preview search options, including more-like-this and agentic search, and exposed query diagnostics on paged responses.
- Carried forward the October GA knowledge base retrieval APIs: closeable synchronous and direct typed asynchronous event streams, query-source authorization options and overloads, and nullable numeric completion status codes. Work IQ authorization remains available in the November preview.
- Added typed `RequestOptions` listing overloads and aligned `KnowledgeBaseIndexedSqlReference` with the GA `getDocumentUrl()` getter.
- Carried forward the final October GA `GetDocumentOptions` and synchronous/asynchronous document lookup overloads, including authorization headers, elevated read, selected fields, and caller `RequestOptions` precedence.

### Breaking Changes

- Removed `SearchServiceVersion.V2026_08_01_PREVIEW`; `V2026_11_01_PREVIEW` is now the only supported preview service version.
- Removed preview `queryHints` from `AzureBlobKnowledgeSourceParameters` and `IndexedSharePointKnowledgeSourceParameters`, and `queryHintOverrides` from their runtime parameter models, to match the November contract in [spec PR #47300](https://github.com/Azure/azure-rest-api-specs/pull/47300). These properties remain supported on `SearchIndexKnowledgeSourceParameters` and `SearchIndexKnowledgeSourceParams`, respectively; `topicGraph` is not a replacement for query hints.
- Removed preview query hints and query hint overrides from other non-SearchIndex knowledge sources, and their query hint processing activity properties, to match the service contract.
- Aligned preview streaming APIs with the October GA signatures: synchronous `retrieveStream` returns a `CloseableIterableStream<KnowledgeBaseRetrievalStreamEvent>` instead of accepting a callback, and asynchronous `retrieveStream` emits typed events directly instead of `ServerSentEvent` envelopes.
- Removed preview-only `ServerSentEvent`, `ServerSentEventListener`, `UnknownKnowledgeBaseRetrievalStreamEvent`, and `KnowledgeBaseRetrievalStatusCode` types. As in GA, stream event wrappers have SDK-only constructors and are not JSON models; unknown events expose only their names. SQL references expose `getDocumentUrl()` instead of `getDocUrl()`.

### Bugs Fixed

- Forwarded topic graph profile and organization access expiration settings from field-builder annotations.
- Added field-builder annotations for sensitivity label IDs and names, source document IDs, and SharePoint site URLs, and forwarded permission filter settings to generated search fields.
- Fixed convenience search requests dropping preview query language, spelling, rewriting, hybrid, semantic field, and authorization options.
- Carried forward SSE decoding, cancellation, backpressure, buffer ownership, and response-cleanup fixes.
- Aligned file delete and update argument order with GA: knowledge source `name` precedes `fileId`.
- Corrected file update and delete argument order in the File knowledge source preview sample, including cleanup.
- Updated the preview retrieval response parsing sample to use an existing knowledge base without modifying or deleting resources.
- Preserved HTTP status, headers, and error bodies when polling preview file ingestion operations fails, instead of throwing an unrelated exception.

### Other Changes

- Restored the opt-in Content Understanding skillset sample and index statistics pagination and indexer-runtime examples.
- Deprecated `BasicField.isSensitivityLabel()`, which has no effect when building search fields. Use `isSensitivityLabelId()` for sensitivity label ID filtering or `isSensitivityLabelName()` for sensitivity label names. The legacy member and its default remain unchanged for compatibility.

#### Dependency Updates

- Carried forward the GA dependency baselines: `azure-core` 1.61.0 and `azure-core-http-netty` 1.17.0.

## 12.2.0 (2026-11-13)

These release notes compare `12.2.0` with the previous GA release, `12.1.1`. Changes that apply only when upgrading
Expand Down
101 changes: 43 additions & 58 deletions sdk/search/azure-search-documents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,43 +33,6 @@ Use the Azure AI Search client library to:

## Getting started

### Service API version

This development version targets the `2026-10-01` GA service API by default.
Use `SearchServiceVersion.V2026_10_01` to select this version explicitly on a client builder.
Preview-only APIs that are not included in this GA service version are not available in this development version.
Previously supported GA service versions remain selectable with `SearchServiceVersion`.

This release also removes public Java APIs for preview-only features accidentally exposed by the previous GA
specification. The corresponding features were not supported by that GA service API, but removing the published Java
APIs is a source and binary compatibility break. Selecting an older service version does not restore removed Java
APIs. See the changelog's [Breaking Changes](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/CHANGELOG.md#breaking-changes)
section and the [specification correction](https://github.com/Azure/azure-rest-api-specs/pull/47112) for details.

Knowledge bases, typed retrieval streaming, and file knowledge sources are included in this GA API.
See the [knowledge base configuration sample](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/KnowledgeBaseConfigurationExample.java),
[retrieval response sample](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/KnowledgeRetrievalResponseExample.java),
[retrieval streaming sample](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/KnowledgeBaseRetrievalStreamExample.java), and
[file knowledge source sample](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/KnowledgeSourceFileExample.java).
See [the changelog](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/CHANGELOG.md) for additions, breaking changes, and fixes relative to the previous GA release,
`12.1.1`. The [sample feature-coverage table](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/src/samples/README.md#new-ga-feature-coverage) maps the new capabilities
to runnable examples and configuration snippets, including document permissions, indexed SQL and SharePoint sources,
and content-understanding chunking.

### Listing and pagination

Listing operations use `list...` names and return typed `PagedIterable<T>` results on synchronous clients and
`PagedFlux<T>` results on asynchronous clients. Pages are fetched lazily, and service-provided continuation links
are followed automatically. Use `iterableByPage()` or `byPage()` to inspect pages, and pass a page's continuation
token to the corresponding overload to resume a listing.

Request-options overloads accept service-supported listing filters such as `search`, `searchType`, `pageSize`,
and `$select` where applicable. A page size limits each service response, not the total number of returned items.
Set `pageSize` explicitly in the request options or the listing overload that accepts it; the current generated
listing APIs do not forward page-size hints from `iterableByPage(int)` or `byPage(int)` to the service.
Use a new `RequestOptions` instance for each independently configured listing. The `list...Names()` methods request
only resource names and retain pagination.

### Include the package

#### Include the BOM file
Expand Down Expand Up @@ -112,7 +75,7 @@ add the direct dependency to your project as follows.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-search-documents</artifactId>
<version>12.2.0</version>
<version>12.3.0-beta.1</version>
</dependency>
```
[//]: # ({x-version-update-end})
Expand Down Expand Up @@ -301,6 +264,7 @@ tables.)_ The `azure-search-documents` client library exposes operations on thes
* `SearchIndexClient` allows you to:
* [Create, delete, update, or configure a search index](https://learn.microsoft.com/rest/api/searchservice/index-operations)
* [Declare custom synonym maps to expand or rewrite queries](https://learn.microsoft.com/rest/api/searchservice/synonym-map-operations)
<!-- * Most of the `SearchServiceClient` functionality is not yet available in our current preview -->

* `SearchIndexerClient` allows you to:
* [Start indexers to automatically crawl data sources](https://learn.microsoft.com/rest/api/searchservice/indexer-operations)
Expand Down Expand Up @@ -413,26 +377,6 @@ SearchPagedIterable searchResultsIterable = SEARCH_CLIENT.search(options);
// ...
```

To find documents similar to an existing document, supply its key with `setMoreLikeThis`.
Do not combine this option with search text.

```java readme-sample-searchMoreLikeThis
SearchOptions options = new SearchOptions().setMoreLikeThis("hotel-1")
.setSearchFields("HotelName", "Description")
.setTop(5);
SEARCH_CLIENT.search(options).forEach(result -> System.out.println(result.getAdditionalProperties()));
```

For permission-filtered search, supply the user's query-source authorization token. These header options are preserved
on continuation pages. Elevated reads bypass document-level permission checks and are disabled in this example.

```java readme-sample-searchWithDocumentPermissions
SearchOptions options = new SearchOptions().setSearchText("hotel")
.setQuerySourceAuthorization(querySourceToken)
.setEnableElevatedRead(false);
SEARCH_CLIENT.search(options).forEach(result -> System.out.println(result.getAdditionalProperties()));
```

### Creating an index

You can use the [`SearchIndexClient`](#create-a-searchindexclient) to create a search index. Indexes can also define
Expand Down Expand Up @@ -509,6 +453,20 @@ Map<String, Object> hotel = SEARCH_CLIENT.getDocument("1").getAdditionalProperti
System.out.printf("This is hotelId %s, and this is hotel name %s.%n", hotel.get("Id"), hotel.get("Name"));
```

Use `GetDocumentOptions` to select fields or supply a query-source authorization token for document-level permissions.
The three-argument `getDocumentWithResponse` overload is available on both synchronous and asynchronous clients.
Explicit headers in `RequestOptions` override the operation options; query parameters in `RequestOptions` are appended.

```java readme-sample-retrieveDocumentWithOptions
GetDocumentOptions options = new GetDocumentOptions()
.setQuerySourceAuthorization(querySourceToken)
.setEnableElevatedRead(false)
.setSelectedFields(Arrays.asList("Id", "Name"));
Map<String, Object> hotel = SEARCH_CLIENT.getDocumentWithResponse("1", options, null)
.getValue().getAdditionalProperties();
System.out.printf("This is hotelId %s, and this is hotel name %s.%n", hotel.get("Id"), hotel.get("Name"));
```

### Adding documents to your index

You can `Upload`, `Merge`, `MergeOrUpload`, and `Delete` multiple documents from an index in a single batched request.
Expand Down Expand Up @@ -609,6 +567,33 @@ provides more information on configuring or changing the HTTP client.

## Next steps

### November 2026 preview

The unreleased beta defaults to `SearchServiceVersion.V2026_11_01_PREVIEW`.
Set `serviceVersion` on a client builder to continue using a previously supported API version.
The preview includes graph querying and diagnostics, knowledge source graph extraction and enrichment caches,
vector topic graph retrieval, automatic facet-backed filter hints, and random scoring.

Use `SearchClient.graph` or `SearchAsyncClient.graph` with `GraphOptions` to query an existing graph index.
A plan-only request must request at least one explain stage.
See the [preview samples](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/PreviewSearchSamples.java).
These APIs require a service that supports the preview; the samples do not provision resources.

The preview preserves the October GA knowledge base streaming APIs. `KnowledgeBaseRetrievalClient.retrieveStream`
returns a `CloseableIterableStream<KnowledgeBaseRetrievalStreamEvent>`; use try-with-resources, especially when stopping
early. `KnowledgeBaseRetrievalAsyncClient.retrieveStream` returns a `Flux<KnowledgeBaseRetrievalStreamEvent>` directly,
without `ServerSentEvent` envelopes. Known events expose typed payloads through `getValue()`; unknown events expose
only their names, not their payloads. Event wrappers are SDK-created envelopes; serialize their typed payloads instead.
Completion status codes remain nullable integers.
See the [streaming sample](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/KnowledgeBaseRetrievalStreamExample.java),
which provisions uniquely named sample resources and removes them afterward.

Set `KnowledgeBaseRetrievalOptions.setQuerySourceAuthorization` to send query-source authorization as a header,
never as JSON. An explicit non-null authorization argument overrides the option; null falls back to it.
The three-argument retrieval and streaming overloads also support November's Work IQ authorization.
Typed listing overloads accept `RequestOptions` and preserve service continuation links. File delete and update APIs
take the knowledge source `name` before `fileId`. SQL references use the GA `getDocumentUrl()` getter.

* Samples are explained in detail [here][samples_readme].
* Read more about the [Azure AI Search service](https://learn.microsoft.com/azure/search/search-what-is-azure-search)

Expand Down
2 changes: 1 addition & 1 deletion sdk/search/azure-search-documents/assets.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@
"AssetsRepo": "Azure/azure-sdk-assets",
"AssetsRepoPrefixPath": "java",
"TagPrefix": "java/search/azure-search-documents",
"Tag": "java/search/azure-search-documents_6b5dc0e6de"
"Tag": "java/search/azure-search-documents_6950366571"
}
9 changes: 9 additions & 0 deletions sdk/search/azure-search-documents/cspell.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"version": "0.2",
"import": [
"../cspell.yml"
],
"words": [
"aicompatible"
]
}
Loading
Loading