Skip to content

Azure Search DP 2026-11-01-Preview Release - #47300

Merged
Yangyang Lu (yangylu91) merged 60 commits into
mainfrom
search/dp-2026-11-01-preview
Nov 5, 2026
Merged

Yangyang Lu (yangylu91) merged 60 commits into
mainfrom
search/dp-2026-11-01-preview

Conversation

@yangylu91

@yangylu91 Yangyang Lu (yangylu91) commented Oct 14, 2026 •

Copy link
Copy Markdown
Member

Data Plane API Specification Update Pull Request

PR review workflow diagram

Please understand this diagram before proceeding. It explains how to get your PR approved & merged.
spec_pr_review_workflow_diagram

API Info: The Basics

Most of the information about your service should be captured in the issue that serves as your API Spec engagement record.

  • Link to API Spec engagement record issue:

Is this review for (select one):

  • a private preview
  • a public preview
  • GA release

Change Scope

This section will help us focus on the specific parts of your API that are new or have been modified.
Please share a link to the design document for the new APIs, a link to the previous API Spec document (if applicable), and the root paths that have been updated.

  • Design Document:
  • Previous API Spec Doc:
  • Updated paths:

Viewing API changes

For convenient view of the API changes made by this PR, refer to the URLs provided in the table
in the Generated ApiView comment added to this PR. You can use ApiView to show API versions diff.

Suppressing failures

If one or multiple validation error/warning suppression(s) is detected in your PR, please follow the
Swagger-Suppression-Process
to get approval.

Release planner

A release plan should have been created. If not, please create one as it will help guide you through the REST API and SDK creation process.

❔Got questions? Need additional info?? We are here to help!

Contact us!

The Azure API Review Board is dedicated to helping you create amazing APIs. You can read about our mission and learn more about our process on our wiki.

Click here for links to tools, specs, guidelines & other good stuff

Tooling

Guidelines & Specifications

Helpful Links

Getting help

  • First, please carefully read through this PR description, from top to bottom.
  • If you don't have permissions to remove or add labels to the PR, request write access per aka.ms/azsdk/access#request-access-to-rest-api-or-sdk-repositories
  • To understand what you must do next to merge this PR, see the Next Steps to Merge comment. It will appear within few minutes of submitting this PR and will continue to be up-to-date with current PR state.
  • For guidance on fixing this PR CI check failures, see the hyperlinks provided in given failure
    and https://aka.ms/ci-fix.
  • If the PR CI checks appear to be stuck in queued state, please add a comment with contents /azp run.
    This should result in a new comment denoting a PR validation pipeline has started and the checks should be updated after few minutes.
  • If the help provided by the previous points is not enough, post to https://aka.ms/azsdk/support/specreview-channel and link to this PR.

Breaking Changes

Breaking Change CI reports:

Summary of Breaking Changes

  1. Move fieldName and boost from ScoringFunction to child models:
    Shows in: both cross-version comparisons.
    Justification: supports random scoring, which does not use these fields. Only the polymorphic base-model contract changes. Clients use concrete child models, which retain both fields with no wire-level changes.

  2. Mark x-ms-query-source-authorization as secret:
    Shows in: both cross-version comparisons and same-version checks.
    Justification: fixes the bot's [SEC-SECRET-DETECT] finding. Adds format: password and x-ms-secret: true without changing the header name, string type, or optional status.

  3. Swap the primary and alternate Swagger entries for file upload:
    Shows in: 2026-08-01-preview → 2026-11-01-preview ; same-version 2026-08-01-preview .
    Justification: makes multipart upload the primary Swagger entry while retaining raw upload as the alternate. Both formats remain available. CI treats the swapped entries as operation-ID, path, required-parameter, and content-type changes.

  4. Make filter-hint fieldValues optional and remove minItems: 1 :
    Shows in: 2026-08-01-preview → 2026-11-01-preview ; same-version 2026-08-01-preview .
    Justification: the new preview supports autoConfiguration instead of explicit values. Optional status is versioned to the new preview. Removing the shared minItems decorator also relaxes the constraint in the previous preview.

  5. Remove query-hint properties from non-search-index knowledge sources:
    Shows in: 2026-08-01-preview → 2026-11-01-preview .
    Justification: query hints are supported only for searchIndex and remoteSearchIndex ; other source types already reject these settings. The new preview removes the unsupported queryHints , queryHintOverrides , and queryHintProcessing properties while preserving previous-version contracts.

  6. Add back knowledgeBasesCount and knowledgeSourcesCount properties :
    Shows in: 2026-10-01 → 2026-11-01-preview .
    Justification: restores preview-only service-statistics counters excluded from GA. These are response properties, not new request requirements.

  7. Make SearchIndexerStatus.runtime and SearchServiceStatistics.indexersRuntime optional:
    Shows in: 2026-08-01-preview → 2026-11-01-preview .
    Justification: inherits the optional status already introduced in 2026-10-01 ; this PR does not introduce any new relaxation.

  8. Shift existing parameter positions:
    Shows in: both cross-version comparisons.
    Justification: new or restored preview-only optional parameters shift existing Swagger parameter positions. HTTP parameters remain name-based, though generated SDK signatures may change.

  9. Add operations and read-only response fields:
    Shows in: both cross-version comparisons; added-path warnings appear in 2026-10-01 → 2026-11-01-preview .
    Justification: exposes new or restored preview capabilities. Warnings cover counts, facet statistics, search and document diagnostics, indexer state and execution details, data-source subtype, graph statistics, agentic diagnostics, and file capacity. These are additive operations and response fields.

Co-authored-by: yangylu91 <53235012+yangylu91@users.noreply.github.com>
# Conflicts:
#	specification/search/data-plane/Search/CHANGELOG.md
… params

The \list\ and \listWithSelectedProperties\ operations are already
fully removed at v2026_08_01_preview, so the same decorator on their
\\\/\\\/\\\ parameters is dead weight. Found by the
local Data-Plane API Reviewer agent; verified no-op via tsp compile
(no swagger diff).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This SearchServiceCreateOrUpdateIndexer.json change is a cosmetic
example rename unrelated to the GA (2026-10-01) work; removing it
keeps this PR scoped to GA-only changes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…l false breaking-change flags on param position
* Add SearchField.organizationAccessExpiration for SharePoint Org-wide Link

* Promote runtime and indexersRuntime to GA as optional properties

* Update example files for runtime/indexersRuntime
Port of AzureSearch ADO PR 2343313: removes/version-gates several
preview-only API elements that had accidentally leaked into GA swagger
for the 2026-04-01 (shipped) and/or 2026-10-01 (unshipped) API versions.

- KnowledgeBaseAgenticReasoningActivityRecord.retrievalReasoningEffort:
  removed from both 2026-04-01 and 2026-10-01 (never legitimate on this record)
- KnowledgeRetrievalReasoningEffort / KnowledgeRetrievalMinimalReasoningEffort:
  gated out of 2026-04-01 only; remain legit GA in 2026-10-01
- maxCumulativeIndexerRuntimeSeconds: removed from 2026-04-01 only;
  remains legit GA in 2026-10-01
- VectorFilterMode.strictPostFilter: removed from both versions
- VectorizableImageUrlQuery / VectorizableImageBinaryQuery (and their
  VectorQueryKind enum members): removed from both versions, gated at
  model level
- AMLVectorizer / AMLParameters: removed from both versions, gated at
  model level

Cleaned up 2026-04-01 example JSON files referencing removed fields
and regenerated stable/2026-04-01 and stable/2026-10-01 search.json via
tsp compile.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add none, diverse, and balanced query variants, profile defaults, and candidate-pool settings.
- Share VectorSearchTopicGraphKind across index profiles and per-query options while preserving distinct model names.
- Add facet-based filter-hint auto-configuration with cache TTL and facet-count limits
- Update client.tsp, examples and swagger

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@yangylu91

Yangyang Lu (yangylu91) commented Oct 22, 2026 •

Copy link
Copy Markdown
Member Author

Hi Heath Stewart (@heaths), we have a few late changes since your last approval, mainly in this commit:

  • Refined topic-graph search models and added profile defaults and candidate-pool controls.
  • Added filter-hint autoConfiguration, making fieldValues optional in the new preview. Removing its shared minItems constraint also affects 2026-08-01-preview.
  • Cleaned up duplicate SDK namespace mappings and refreshed Swagger and examples.

Could you please help take another look and re-approve if everything looks good? Thank you very much for your time and guidance!

FYI, I've also emailed to request for the breaking change review and approval.

@github-actions

This comment has been minimized.

@github-actions

Copy link
Copy Markdown

Data-Plane API Review

Automated advisory review by Copilot. This is one non-deterministic pass over a
narrow semantic scope and does not replace complete human API review.

Findings: 🔴 0 Blocking · 🟡 2 Warning · 💡 0 Suggestion

  • DP-PAGE-01 — Graph query results are unpaged (models-index.tsp:126)
  • DP-MODEL-01 — File replacement duplicates PUT as a POST action (routes-service.tsp:1113)

Not reviewed: deterministic compiler/linter concerns, naming and
documentation quality, grey-area design questions, runtime behavior, SDK
customizations, and unchanged API surface.

🔍 Automated data-plane API review by Data-Plane API Review. Advisory only.

@heaths Heath Stewart (heaths) added the data-plane-review-signoff Data-plane API review sign-off/approved: Azure API Stewardship team has signed off and approved. label Oct 23, 2026
@yangylu91
Yangyang Lu (yangylu91) merged commit e5e59f7 into main Nov 5, 2026
108 of 112 checks passed
@yangylu91
Yangyang Lu (yangylu91) deleted the search/dp-2026-11-01-preview branch November 5, 2026 19:14
Yangyang Lu (yangylu91) added a commit to Azure/azure-sdk-for-js that referenced this pull request Nov 16, 2026
<!-- Give your Pull Request a brief description, and answer the
following questions. This helps us find the best reviewers for the PR.
-->

### Packages impacted by this PR

`@azure/search-documents` **13.2.0-beta.1**

### Issues associated with this PR

Adds support for API version **2026-11-01-preview** as the new default,
carrying forward October GA (`2026-10-01`) contracts unchanged. Older
preview constants (`V20251101Preview`, `V20260501Preview`,
`V20260801Preview`) are removed; only the November preview and GA
constants remain (documented as a breaking change in the changelog).

### Describe the problem that is addressed by this PR

- Graph queries, Topic Graph configuration, knowledge-base
tools/retrieval defaults, query-hint auto-configuration,
OpenAI-compatible/Microsoft Retriever 1 models, agentic diagnostics,
OneLake security fields, and async File ingestion/replacement via core
LRO pollers.
- Preserves all October GA signatures, overloads, exports, and closed
enum/union types (`VectorQueryKind`, `BaseVectorQuery.kind`,
`VectorFilterMode`) unchanged.
- New `KnowledgeBaseModelInput`/`KnowledgeBaseInput` types support
additional model kinds on create/update without altering any response
types.
- Full details of individual review-feedback fixes are available in the
commit history.

### What are the possible designs available to address the problem?

October GA (#40171) is authoritative — contracts are preserved and new
preview capabilities are exposed as additive convenience/protocol
surface rather than replacing GA signatures with raw emitter output.

### Are there test cases added in this PR?

Yes — new/updated unit, playback, and sample-safety tests cover graph
queries, Topic Graph, knowledge-base model inputs, random scoring, File
LRO polling, and MCP/AML/vectorizer auth paths. Current status: **469
Node tests / 95 browser tests passing**, 8 inherited live-only skips
(not new quarantines). Live validation performed against an approved
test resource group for File ingestion/replacement polling and
knowledge-base retrieval.

### Local validation summary

| Check | Result |
| --- | --- |
| Build, lint, format, API extraction | Passed |
| `pnpm exec vitest run` (Node) | 469 passed, 8 live-only skips |
| `pnpm exec vitest run --config=vitest.browser.config.ts` | 95 passed |
| `node eng/tools/ci-runner/index.js check-package-version` | Passed
(`13.2.0-beta.1` not yet published) |
| Strict TS consumer compatibility vs October GA | 23 consumer groups +
29 model pairs, 0 diagnostics |

### Published recording assets

`assets.json` →
[`js/search/search-documents_9d099c8033`](https://github.com/Azure/azure-sdk-assets/tree/js/search/search-documents_9d099c8033)
(commit `9d099c8033d9376b0f10ab933e6f82df22cda3a8`).

### Provide a list of related PRs

- #40171 — October GA baseline (merged)
- #40745 — October GA TypeSpec-pin update on `main` (November pin
preserved here)
- Azure/azure-rest-api-specs#47300 — November API spec (SHA
`b41ba04c0219f6622b7f5214fc020f90bad339ae`)

### Command used to generate this PR

`generate:client` with emitter options
`api-version=2026-11-01-preview;ignore-nullable-on-optional=true;wrap-non-model-return=false`,
then `dev-tool customization apply --skip index.ts`.

### Checklists
- [x] Added impacted package name to the issue description
- [ ] Does this PR need any fixes in the SDK Generator?
- [x] Added a changelog (if necessary)

## Release Plan Details
- Release Plan:
https://azsdk-releaseplan-dashboard-hveph5aqhhcfhtgu.westus-01.azurewebsites.net/?releaseplan=37175
- Work Item Link:
https://dev.azure.com/azure-sdk/fe81d705-3c06-41e5-bf7c-5ebea18efe89/_workitems/edit/37175
- Spec Pull Request:
Azure/azure-rest-api-specs#47300
- Spec API version: 2026-11-01-preview

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: hillarykhuu <86318926+hillarykhuu@users.noreply.github.com>
Copilot-Session: fe2529dc-fd48-4581-9a04-27f63dfe8723
Copilot-Session: cca341f8-fc12-40a1-8e46-370ac3c46d65
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

BreakingChange-Approved-BranchPolicyException Changes violate the branch policy but exception has been granted. aka.ms/azsdk/pr-brch-deep BreakingChangeReviewRequired <valid label in PR review process>add this label when breaking change review is required data-plane data-plane-review-requested Data-plane API review requested/needed: pending Azure API Stewardship + service team review. data-plane-review-signoff Data-plane API review sign-off/approved: Azure API Stewardship team has signed off and approved. new-api-version PublishToCustomers Acknowledgement the changes will be published to Azure customers. Search TypeSpec Authored with TypeSpec

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants