Query: Adds Query Advisor SDK capabilities

[aayush3011]

Description

This PR adds support for the Query Advisor feature in the Azure Cosmos DB Java SDK. Query Advisor provides actionable optimization recommendations for Cosmos DB queries at query execution time, returned inline via response headers.

When enabled, the service analyzes queries and returns advice such as suggesting STARTSWITH instead of CONTAINS for prefix matching, or GetCurrentDateTimeStatic instead of GetCurrentDateTime for deterministic results.

Changes

New public API surface (azure-cosmos):

• CosmosQueryRequestOptions.setQueryAdviceEnabled(boolean) / isQueryAdviceEnabled() — opt-in flag to request query advice from the service (default: false)
• FeedResponse.getQueryAdvice() — returns a human-readable string with optimization recommendations, or null if no advice is available

Usage Example:

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
options.setQueryAdviceEnabled(true);

CosmosPagedIterable<MyItem> results = container.queryItems(
   "SELECT * FROM c WHERE CONTAINS(c.name, 'test')",
   options,
   MyItem.class);

for (FeedResponse<MyItem> page : results.iterableByPage()) {
   String advice = page.getQueryAdvice();
   if (advice != null) {
       System.out.println("Query Advisor recommendations:\n" + advice);
       // Example output:
       // QA1002: If you are matching on a string prefix, consider using STARTSWITH
       // instead of CONTAINS. For more information, please visit
       // https://aka.ms/CosmosDB/QueryAdvisor/QA1002
   }
}

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.

[Copilot]

Pull request overview

Adds Query Advisor support to the Azure Cosmos DB Java SDK by enabling an opt-in request header and surfacing any returned query recommendations via a new FeedResponse accessor.

Changes:

• Introduces a new opt-in flag (setQueryAdviceEnabled) on query/read-many request options and propagates it to the service via request headers (including RNTBD).
• Adds FeedResponse.getQueryAdvice() to parse the x-ms-cosmos-query-advice response header into a human-readable, multi-line string.
• Bundles a local rule/message directory (query_advice_rules.json) used to render advice messages and documentation links; adds (currently ignored) tests plus validator helpers.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
sdk/cosmos/azure-cosmos/src/main/resources/query/queryadvisor/query_advice_rules.json	Adds the bundled rule/message mapping and URL prefix for rendering advice.
sdk/cosmos/azure-cosmos/src/main/java/module-info.java	Opens/exports the new query advisor implementation package for Jackson/reflection needs.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/FeedResponse.java	Adds getQueryAdvice() to surface parsed advice from response headers.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosRequestOptions.java	Adds a common request option flag for enabling query advice.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosReadManyRequestOptions.java	Adds set/isQueryAdviceEnabled pass-throughs to the internal impl.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosQueryRequestOptions.java	Adds set/isQueryAdviceEnabled pass-throughs to the internal impl.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/query/queryadvisor/QueryAdviceRuleDirectory.java	Implements lazy-loading of the bundled rules/messages from resources.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/query/queryadvisor/QueryAdviceEntry.java	Represents a single advice entry and formats it with rule text + URL.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/query/queryadvisor/QueryAdvice.java	Parses the URL-encoded JSON header and renders formatted multi-line output.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/query/DocumentQueryExecutionContextBase.java	Adds request header population (x-ms-cosmos-populatequeryadvice) when enabled.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/rntbd/RntbdResponseHeaders.java	Captures/mappings for the x-ms-cosmos-query-advice response header in RNTBD.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/rntbd/RntbdRequestHeaders.java	Propagates the populate-query-advice request header into RNTBD tokens.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/rntbd/RntbdConstants.java	Defines RNTBD header IDs for populate-query-advice and query-advice.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/directconnectivity/WFConstants.java	Adds backend header constant for x-ms-cosmos-query-advice.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RequestOptions.java	Extends the request-options interface surface with isQueryAdviceEnabled() (null default).
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/ReadOnlyRequestOptions.java	Adds isQueryAdviceEnabled() to the shared options interface.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/HttpConstants.java	Adds HTTP header constants for populate/query advice.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/CosmosTransactionalBulkExecutionOptionsImpl.java	Implements isQueryAdviceEnabled() (null default for non-query operations).
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/CosmosQueryRequestOptionsBase.java	Stores/overrides the query advice enabled flag and participates in overrides.
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/CosmosChangeFeedRequestOptionsImpl.java	Implements isQueryAdviceEnabled() (null default for non-query operations).
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/CosmosBulkExecutionOptionsImpl.java	Implements isQueryAdviceEnabled() (null default for non-query operations).
sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/CosmosRequestContext.java	Surfaces isQueryAdviceEnabled() from request context.
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/rx/QueryAdviceTest.java	Adds end-to-end style tests for advice (currently disabled via @Ignore).
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/implementation/FeedResponseValidator.java	Adds per-page validator helpers for query advice.
sdk/cosmos/azure-cosmos-tests/src/test/java/com/azure/cosmos/implementation/FeedResponseListValidator.java	Adds list/page-set validator helpers for query advice.