Query: Adds Query Advisor SDK capabilities

[aayush3011]

Description

This PR adds the capability to request and receive Query Advice in QueryRequests. The response from BE is an URL-encoded JSON string that will get decoded to UTF8 text.

When populate_query_advice=True is passed to query_items(), the backend analyzes the query and returns optimization hints (e.g., replace CONTAINS with STARTSWITH, use computed properties, prefer static datetime functions). The formatted advice is surfaced in response headers under HttpHeaders.QueryAdvice, following the same pattern as populate_index_metrics.

.NET SDK (PR #4714)

Note: Emulator-based integration tests are marked @pytest.mark.skip until the emulator supports Query Advisor.

Usage

results = container.query_items(
    query='SELECT * FROM c WHERE CONTAINS(c.name, "test")',
    partition_key="pk",
    populate_query_advice=True
)
list(results)  # consume iterator

advice = results.get_response_headers()[http_constants.HttpHeaders.QueryAdvice]
# QA1002: Instead of CONTAINS, consider using STARTSWITH or computed properties...

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 Python SDK by letting callers request query advice via query_items(..., populate_query_advice=True) and surfacing formatted advice from the x-ms-cosmos-query-advice response header.

Changes:

• Adds new request/response headers (PopulateQueryAdvice, QueryAdvice) and plumbs populate_query_advice through sync/async query_items.
• Introduces a _query_advisor helper module to decode URL-encoded JSON advice and format it using a local rules catalog.
• Adds unit/integration tests and extends existing “None options” tests to cover the new parameter.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
sdk/cosmos/azure-cosmos/azure/cosmos/http_constants.py	Adds header constants for Query Advice request/response.
sdk/cosmos/azure-cosmos/azure/cosmos/container.py	Adds populate_query_advice kwarg + docstrings and maps it into feed options.
sdk/cosmos/azure-cosmos/azure/cosmos/aio/_container.py	Async query_items support for populate_query_advice.
sdk/cosmos/azure-cosmos/azure/cosmos/_base.py	Emits the x-ms-cosmos-populatequeryadvice request header when enabled.
sdk/cosmos/azure-cosmos/azure/cosmos/_cosmos_client_connection.py	Decodes and formats x-ms-cosmos-query-advice in last response headers (sync).
sdk/cosmos/azure-cosmos/azure/cosmos/aio/_cosmos_client_connection_async.py	Decodes and formats x-ms-cosmos-query-advice in last response headers (async).
sdk/cosmos/azure-cosmos/azure/cosmos/_query_advisor/init.py	Exposes internal Query Advisor helpers.
sdk/cosmos/azure-cosmos/azure/cosmos/_query_advisor/_get_query_advice_info.py	Entry point for turning the header value into a formatted string.
sdk/cosmos/azure-cosmos/azure/cosmos/_query_advisor/_query_advice.py	Implements parsing/formatting for advice entries and collections.
sdk/cosmos/azure-cosmos/azure/cosmos/_query_advisor/_rule_directory.py	Loads the local rules catalog and provides message lookup.
sdk/cosmos/azure-cosmos/azure/cosmos/_query_advisor/query_advice_rules.json	Adds the local rule message catalog + documentation URL prefix.
sdk/cosmos/azure-cosmos/tests/test_query_advisor.py	Adds unit tests for parsing/formatting Query Advisor data.
sdk/cosmos/azure-cosmos/tests/test_query.py	Adds (currently skipped) emulator integration coverage for Query Advice (sync).
sdk/cosmos/azure-cosmos/tests/test_query_async.py	Adds (currently skipped) emulator integration coverage for Query Advice (async).
sdk/cosmos/azure-cosmos/tests/test_query_cross_partition.py	Adds (currently skipped) cross-partition integration coverage for Query Advice (sync).
sdk/cosmos/azure-cosmos/tests/test_query_cross_partition_async.py	Adds live cross-partition async integration coverage for Query Advice.
sdk/cosmos/azure-cosmos/tests/test_none_options.py	Ensures populate_query_advice=None is accepted in sync query paths.
sdk/cosmos/azure-cosmos/tests/test_none_options_async.py	Ensures populate_query_advice=None is accepted in async query paths.

[aayush3011]

/azp run python - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[tvaron3]

PR Deep Review — Query Advisor SDK Capabilities

Overall: Well-structured PR that correctly mirrors the established populate_index_metrics pattern across sync/async code paths. The new _query_advisor module has clean separation of concerns and good docstrings. One CI-blocking issue (missing test skip decorator) and several recommendations below.

#	Severity	Summary
1	🔴 Blocking	Missing @pytest.mark.skip on async cross-partition test
2	🟡 Recommendation	Duplicate import in async client connection
3	🟡 Recommendation	Query advice not decoded in prefix partition path
4	🟡 Recommendation	Broad except Exception silently swallows errors
5	🟡 Recommendation	Spurious cspell:ignore with typo
6	🟢 Suggestion	_rule_directory.py missing logger

---

_{⚠️ AI-generated review — may be incorrect. Agree? → resolve the conversation. Disagree? → reply with your reasoning.}

[simorenoh]

LGTM - just one change requested based on Pythonic practices, and Tomas caught several duplications/ bits that could be added to prefix queries