Migrate azure-search-documents to TypeSpec #47819

alzimmermsft · 2026-01-27T19:08:21Z

Description

Initial work to migrate azure-search-documents to TypeSpec.

Further work is needed for the following:

Artifact version updates to new major version
Updates to Java TypeSpec generator to support typed WithResponse APIs rather than using BinaryData
Rerecording of tests
Capturing all the breaking changes and how to migrate to the new version

All SDK Contribution checklist:

The pull request does not introduce [breaking changes]
CHANGELOG is updated for new features, bug fixes or other significant changes.
I have read the contribution guidelines.

General Guidelines and Best Practices

Title of the pull request is clear and informative.
There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

Pull request includes test coverage for the included changes.

…ng kept

github-actions · 2026-02-02T17:36:04Z

API Change Check

APIView identified API level changes in this PR and created the following API reviews

com.azure:azure-search-documents

Copilot

Pull request overview

Migrates azure-search-documents from AutoRest-generated code to TypeSpec-generated code as initial groundwork for the next major version.

Changes:

Replace large portions of AutoRest-generated implementation and model surface with TypeSpec-generated equivalents.
Update field-builder annotations and rework field building logic for the new model shape.
Refactor buffered indexing senders/publishers to use RequestOptions and the new untyped/document-map representation.

Reviewed changes

Copilot reviewed 71 out of 710 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/indexes/implementation/SearchServiceClientImpl.java	Removes legacy AutoRest-generated service client implementation.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/indexes/SimpleField.java	Removes old annotation-based field builder API surface.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/indexes/SearchIndexerDataSources.java	Removes legacy convenience factory utilities.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/indexes/FieldBuilderIgnore.java	Removes old ignore marker annotation used by the previous field builder.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/indexes/ComplexField.java	Adds new field-builder annotation aligned with the new FieldBuilder implementation.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/indexes/BasicField.java	Replaces `SearchableField` semantics with the new `BasicField` annotation and nullable-boolean semantics.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/util/package-info.java	Removes legacy internal util package docs (package appears removed).
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/util/Utility.java	Removes legacy internal utility helpers used by AutoRest-era implementation.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/util/SpatialFormatter.java	Removes spatial OData encoding helper (previously used by `SearchFilter`).
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/util/SemanticSearchResultsAccessHelper.java	Removes internal accessor helper for semantic results.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/util/MappingUtils.java	Removes mapping helpers tied to deleted generated models.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/util/FieldBuilder.java	Removes old util FieldBuilder implementation in favor of new location/behavior.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/util/Constants.java	Removes internal logging constants helper.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/package-info.java	Updates package docs header to TypeSpec generator and broadens package description.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/package-info.java	Updates models package docs header to TypeSpec generator and broadens description.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/SuggestResult.java	Removes legacy generated SuggestResult model (now handled differently).
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/SuggestPostRequest.java	Updates generated request model shape (string lists → `List<String>`) and TypeSpec header.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/Speller.java	Removes legacy generated Speller model.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/SearchResult.java	Removes legacy generated SearchResult model.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/SearchFirstPageResponseWrapper.java	Removes legacy wrapper model.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/SearchError.java	Removes legacy error model.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/SearchContinuationToken.java	Removes legacy continuation token handling.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/RequestOptions.java	Removes legacy generated RequestOptions model.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/IndexAction.java	Removes legacy generated IndexAction model.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/ErrorResponseException.java	Removes legacy generated error exception model.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/ErrorResponse.java	Removes legacy generated error response model.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/ErrorDetail.java	Removes legacy generated error detail model.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/ErrorAdditionalInfo.java	Removes legacy generated error additional info model.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/models/AutocompletePostRequest.java	Updates generated request model shape (string lists → `List<String>`) and TypeSpec header.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/converters/package-info.java	Removes converter package docs (converters appear removed).
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/converters/SuggestResultHelper.java	Removes legacy model-to-public converter helper.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/converters/SuggestResultConverter.java	Removes legacy converter implementation.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/converters/SearchResultHelper.java	Removes legacy converter helper.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/converters/SearchResultConverter.java	Removes legacy converter implementation.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/converters/IndexActionHelper.java	Removes legacy converter helper.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/converters/IndexActionConverter.java	Removes legacy converter implementation.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/converters/AnalyzeRequestConverter.java	Removes legacy request converter.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/batching/TryTrackingIndexAction.java	Refactors batching tracking to new untyped `IndexAction` usage.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/batching/SearchIndexingPublisher.java	Refactors sync batching publisher to use `SearchClient`, `RequestOptions`, and untyped document shape.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/batching/SearchIndexingAsyncPublisher.java	Refactors async batching publisher to use `SearchAsyncClient`, `RequestOptions`, and untyped document shape.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/batching/IndexingDocumentManager.java	Refactors document manager to support untyped map-based key retrieval.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/SearchUtils.java	Adds new helpers to map public `SearchOptions` to generated `SearchRequest` and apply request headers.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/KnowledgeBaseRetrievalClientImpl.java	Adds TypeSpec-generated implementation client for knowledge base retrieval.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/implementation/FieldBuilder.java	Adds new FieldBuilder implementation compatible with `BasicField`/`ComplexField`.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/SearchServiceVersion.java	Updates service version enum to TypeSpec header and changes supported versions list.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/SearchIndexingBufferedSender.java	Refactors buffered sender to use `RequestOptions` and map-based IndexAction payloads.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/SearchIndexingBufferedAsyncSender.java	Refactors buffered async sender similarly and reworks API shapes around `RequestOptions`.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/SearchFilter.java	Removes legacy OData filter builder API.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/SearchDocument.java	Removes legacy untyped document container type.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/SearchAudience.java	Moves SearchAudience into the root package.
sdk/search/azure-search-documents/spotbugs-exclude.xml	Updates SpotBugs suppressions (adds FieldBuilder suppression and adjusts test suppressions).
sdk/search/azure-search-documents/pom.xml	Bumps package version to `12.0.0-beta.1` and adjusts test module opens and dependencies.
sdk/search/azure-search-documents/customizations/src/main/java/SearchCustomizations.java	Adds generator customizations (hide APIs and patch SearchAudience scopes handling).
sdk/search/azure-search-documents/checkstyle-suppressions.xml	Updates suppressions to match renamed/moved testing models.
sdk/search/azure-search-documents/assets.json	Updates assets tag reference.
sdk/search/azure-search-documents/README.md	Updates samples and snippets to match new APIs and model shapes.
sdk/search/azure-search-documents/CHANGELOG.md	Updates unreleased version header to `12.0.0-beta.1`.
eng/versioning/version_client.txt	Updates tracked version for `azure-search-documents` to `12.0.0-beta.1`.
.vscode/cspell.json	Removes stray whitespace line and updates dictionary list for the package scope.

Copilot · 2026-02-02T19:39:52Z

...ments/src/main/java/com/azure/search/documents/implementation/models/SuggestPostRequest.java

+            SuggestPostRequest deserializedSuggestPostRequest = new SuggestPostRequest(searchText, suggesterName);
+            deserializedSuggestPostRequest.filter = filter;
+            deserializedSuggestPostRequest.useFuzzyMatching = useFuzzyMatching;
+            deserializedSuggestPostRequest.highlightPostTag = highlightPostTag;
+            deserializedSuggestPostRequest.highlightPreTag = highlightPreTag;
+            deserializedSuggestPostRequest.minimumCoverage = minimumCoverage;
+            deserializedSuggestPostRequest.orderBy = orderBy;
+            deserializedSuggestPostRequest.searchFields = searchFields;
+            deserializedSuggestPostRequest.select = select;
+            deserializedSuggestPostRequest.top = top;
+            return deserializedSuggestPostRequest;


The previous implementation validated required JSON properties (e.g., search and suggesterName) and threw an IllegalStateException when missing. The updated fromJson now always constructs SuggestPostRequest even when required fields are absent, which can result in null required fields and harder-to-diagnose failures later. Restore the required-property tracking and throw a clear IllegalStateException listing missing required properties when they’re not found.

Copilot · 2026-02-02T19:39:52Z

.../src/main/java/com/azure/search/documents/implementation/models/AutocompletePostRequest.java

+            AutocompletePostRequest deserializedAutocompletePostRequest
+                = new AutocompletePostRequest(searchText, suggesterName);
+            deserializedAutocompletePostRequest.autocompleteMode = autocompleteMode;
+            deserializedAutocompletePostRequest.filter = filter;
+            deserializedAutocompletePostRequest.useFuzzyMatching = useFuzzyMatching;
+            deserializedAutocompletePostRequest.highlightPostTag = highlightPostTag;
+            deserializedAutocompletePostRequest.highlightPreTag = highlightPreTag;
+            deserializedAutocompletePostRequest.minimumCoverage = minimumCoverage;
+            deserializedAutocompletePostRequest.searchFields = searchFields;
+            deserializedAutocompletePostRequest.top = top;
+            return deserializedAutocompletePostRequest;


Same issue as SuggestPostRequest.fromJson: required-property validation was removed (search and suggesterName). Please reintroduce the required-property checks and throw IllegalStateException when missing, to preserve previous behavior and fail fast on malformed payloads.

sdk/search/azure-search-documents/customizations/src/main/java/SearchCustomizations.java

...e-search-documents/src/main/java/com/azure/search/documents/implementation/FieldBuilder.java

Copilot · 2026-02-02T19:39:54Z

...rc/main/java/com/azure/search/documents/implementation/batching/SearchIndexingPublisher.java

@@ -54,40 +53,38 @@
 public final class SearchIndexingPublisher<T> {


The class still declares a generic type parameter <T>, but the refactoring in this diff switches the internal flow to untyped IndexAction and Map<String, Object> key extraction. If <T> is no longer used in the remainder of the file, consider removing the generic parameter to avoid confusion and reduce type-noise for maintainers.

Copilot · 2026-02-02T19:39:54Z

...ch/azure-search-documents/src/main/java/com/azure/search/documents/SearchServiceVersion.java

 public enum SearchServiceVersion implements ServiceVersion {
    /**
-     * {@code 2020-06-30} service version.
-     */
-    V2020_06_30("2020-06-30"),
-
-    /**
-     * {@code 2023-11-01} service version.
-     */
-    V2023_11_01("2023-11-01"),
-
-    /**
-     * {@code 2024-07-01} service version.
-     */
-    V2024_07_01("2024-07-01"),
-
-    /**
-     * {@code 2025-09-01} service version.
-     */
-    V2025_09_01("2025-09-01"),
-
-    /**
-     * {@code 2025-11-01-preview} service version.
+     * Enum value 2025-11-01-preview.
     */
    V2025_11_01_PREVIEW("2025-11-01-preview");


This change removes all previously supported GA service versions and leaves only a preview version. If the intent is still to support earlier stable service API versions (especially for migration scenarios), consider reintroducing the prior GA enum constants and keeping getLatest() pointed at the newest supported version.

alzimmermsft added 6 commits January 16, 2026 15:41

Initial regeneration using TypeSpec

70f686a

Working on migrating tests, adding back convenience APIs that are bei…

9a50ce8

…ng kept

Complete most of the migration

2f8bd79

Additional work

9b6af1c

Stable point before tests

38aa0ac

Newer TypeSpec SHA

0f0bace

alzimmermsft self-assigned this Jan 27, 2026

alzimmermsft added the Search label Jan 27, 2026

github-project-automation bot added this to Azure SDK for Search Jan 27, 2026

github-project-automation bot moved this to Untriaged in Azure SDK for Search Jan 27, 2026

alzimmermsft added 7 commits January 28, 2026 09:47

Add back SearchAudience support

e8f3086

Last changes before testing

b5e89a5

Merge branch 'main' into AzSearch_MigrateToTypeSpec

81d11ed

Rerecord tests and misc fixes along the way

70b62b3

Fix a few recordings and stress tests

b72b976

Merge in main

5faebbb

Fix a few recordings and linting

75e6ac1

alzimmermsft added 4 commits February 2, 2026 12:53

Few more fixes

540e39d

Another round of recording

9fbda57

Rerun TypeSpec codegen

00735e9

Remove errant import

c0bc08b

alzimmermsft marked this pull request as ready for review February 2, 2026 19:35

Copilot AI review requested due to automatic review settings February 2, 2026 19:35

alzimmermsft requested review from Netyyyy, conniey, g2vinay, rujche, saragluna and srnagar as code owners February 2, 2026 19:35

alzimmermsft requested review from a team, moarychan and raych1 as code owners February 2, 2026 19:35

Copilot AI reviewed Feb 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate azure-search-documents to TypeSpec #47819

Migrate azure-search-documents to TypeSpec #47819

Uh oh!

alzimmermsft commented Jan 27, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Copilot AI Feb 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		@@ -54,40 +53,38 @@
		public final class SearchIndexingPublisher<T> {

Migrate azure-search-documents to TypeSpec #47819

Are you sure you want to change the base?

Migrate azure-search-documents to TypeSpec #47819

Uh oh!

Conversation

alzimmermsft commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

All SDK Contribution checklist:

General Guidelines and Best Practices

Testing Guidelines

Uh oh!

github-actions bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Change Check

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

alzimmermsft commented Jan 27, 2026 •

edited

Loading

github-actions bot commented Feb 2, 2026 •

edited

Loading