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 = container.client_connection.last_response_headers.get(
    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.