[Cosmos] Use deterministic ordinal ranks for hybrid-search RRF by Maya-Painter · Pull Request #49623 · Azure/azure-sdk-for-python

Maya Painter (Maya-Painter) · 2026-10-20T17:39:21Z

Description

Fixes Cosmos hybrid-search reciprocal rank fusion (RRF) results being ranked incorrectly when component scores are tied. Both synchronous and asynchronous Python clients now use deterministic ordinal ranks, matching Azure/azure-cosmos-dotnet-v3#6188.

Previously, Python used dense ranking: tied component scores shared a rank, and the next distinct score received the next consecutive rank. Every result now receives its 1-based position in the sorted component results, including ties. There is no environment-variable switch or competition-ranking fallback. The RRF formula and component weights are unchanged.

Example

For a descending component with scores 10, 5, 5, 5, 0:

Component score	Previous dense rank	New ordinal rank
10	1	1
5	2	2
5	2	3
5	2	4
0	3	5

With weight 1, the last document contributes 1 / 65 instead of 1 / 63; the three documents scoring 5 also receive distinct contributions.

Equal component scores use the numeric document portion of _rid as a deterministic client-side tie-breaker, in the component query's sort direction. Equal final RRF scores use numeric document RID descending. Each retained document's numeric RID is decoded once.

Both clients share the ranking implementation. Full-RID deduplication, returned payloads, skip/take behavior, query-plan sort directions, and component weights are preserved. Component-score arrays are sized from the query plan so empty-score rows retain the existing fallback regardless of arrival order. No public API signatures or SDK versions change.

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.

Port Azure/azure-cosmos-dotnet-v3#6130 with shared sync/async fusion, numeric document RID ordering, and an internal per-query competition-ranking fallback. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 68efd20b-2c16-45ea-9e93-ecbd62e4e352

azure-pipelines · 2026-10-20T17:40:34Z

Azure Pipelines: Successfully started running 3 pipeline(s). 7 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 68efd20b-2c16-45ea-9e93-ecbd62e4e352

Copilot

🟡 Changes recommended

A verified empty-score ordering regression can raise IndexError in both clients.

1 open issue

Prevent IndexError when empty-score rows precede populated rows · New

What changed in this PR

Updates Cosmos hybrid-search reciprocal rank fusion to use deterministic ordinal ranks in both synchronous and asynchronous clients.

Changes:

Shares ranking logic with numeric document-RID tie-breaking and optional competition ranking.
Adds tests for ranking modes, weights, deterministic ordering, and preserved query behavior.
Documents the behavior change and compatibility setting in release notes.

File	Description
`sdk/cosmos/azure-cosmos/tests/test_hybrid_search_aggregator.py`	Adds ranking and sync/async regression coverage.
`sdk/cosmos/azure-cosmos/CHANGELOG.md`	Documents ordinal ranking and the competition option.
`sdk/cosmos/azure-cosmos/azure/cosmos/_execution_context/hybrid_search_aggregator.py`	Implements shared ranking and numeric RID tie-breaking.
`sdk/cosmos/azure-cosmos/azure/cosmos/_execution_context/aio/hybrid_search_aggregator.py`	Uses shared ranking and snapshots the ranking mode.
`.chronus/changes/cosmos-ordinal-rrf-ranking.md`	Adds release metadata describing the ranking fix.

_{Review effort: Balanced}

Size score arrays from the query plan and cover empty-first and all-empty rows in sync and async queries. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 68efd20b-2c16-45ea-9e93-ecbd62e4e352

Copilot

🟢 Approval recommended

No active review issues remain to block the hybrid-search ranking update.

No open issues 🎉

1 resolved since last review

Prevent IndexError when empty-score rows precede populated rows

_{Review effort: Balanced}

Remove the options override, centralize environment constants, update regression coverage, apply the suggested changelog wording, and remove the Chronus fragment. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 68efd20b-2c16-45ea-9e93-ecbd62e4e352

Copilot

🟢 Approval recommended

No active review issues remain for the hybrid-search ranking changes.

No open issues 🎉

_{Review effort: Balanced}

Simon Moreno (simorenoh) · 2026-10-28T22:14:20Z

/azp run python - cosmos - tests

azure-pipelines · 2026-10-28T22:14:41Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Remove the competition-ranking environment switch and update the changelog and tests to match the .NET ranking fix. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 68efd20b-2c16-45ea-9e93-ecbd62e4e352

Copilot

🟢 Approval recommended

No active review issues were identified for the deterministic hybrid-search ranking changes.

No open issues 🎉

_{Review effort: Balanced}

Simon Moreno (simorenoh) · 2026-11-05T15:10:11Z

/azp run python - cosmos - tests

azure-pipelines · 2026-11-05T15:10:36Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Copilot

🟢 Approval recommended

No active review issues are identified for the hybrid-search ranking update.

No open issues 🎉

_{Review effort: Balanced}

Simon Moreno (simorenoh) · 2026-11-06T15:00:51Z

/azp run python - cosmos - tests

azure-pipelines · 2026-11-06T15:01:13Z

Azure Pipelines: Successfully started running 1 pipeline(s).

github-actions · 2026-11-06T17:31:52Z

[Pilot] PR Pipeline Failure Analysis

What failed

python - cosmos - tests (Azure Pipeline build 7047729) on PR #49623, with 4 failing test matrix legs:

Public Test azure-cosmos Ubuntu2404_312_aad_query
Public Test azure-cosmos Ubuntu2404_313_aad_circuit_breaker_MultiMaster
Public Test azure-cosmos Ubuntu2404_313_circuit_breaker_MultiMaster
Public Test azure-cosmos macos311_search_query

Root cause

The automated azsdk ci analyze run returned empty azure_pipeline_analyses and github_workflow_analyses sections, and no failed-test artifact data could be retrieved for any of the four failing jobs (the test-results file produced for this run was empty). This Azure DevOps pipeline (azure-sdk project, build 7047729) is internal and requires an authenticated Azure DevOps identity to pull logs or test-result artifacts — this workflow's GitHub-only credentials cannot reach it. No log excerpts or failing-test messages were obtainable in this environment, so a code-level root cause cannot be determined automatically.

Relevant pipeline output

pipeline-analysis.json:
{
  "azure_pipeline_analyses": [],
  "github_workflow_analyses": [],
  "failing_pull_request_checks": [
    { "name": "python - cosmos - tests", "conclusion": "FAILURE" },
    { "name": "python - cosmos - tests (Public Test azure-cosmos Ubuntu2404_312_aad_query)", "conclusion": "FAILURE" },
    { "name": "python - cosmos - tests (Public Test azure-cosmos Ubuntu2404_313_aad_circuit_breaker_MultiMaster)", "conclusion": "FAILURE" },
    { "name": "python - cosmos - tests (Public Test azure-cosmos Ubuntu2404_313_circuit_breaker_MultiMaster)", "conclusion": "FAILURE" },
    { "name": "python - cosmos - tests (Public Test azure-cosmos macos311_search_query)", "conclusion": "FAILURE" }
  ],
  "operation_status": "Succeeded"
}

pipeline-test-results.txt: (empty — no failed test details were retrievable)

Recommended next steps

The workflow does not have the user's Azure DevOps identity and cannot download logs/test artifacts for this internal pipeline. Analyze it locally while authenticated to Azure DevOps (e.g., after az login) with:
```
azsdk ci analyze https://github.com/Azure/azure-sdk-for-python/pull/49623 --output json
```
Alternatively, inspect the failing jobs' logs/test results directly in the Azure DevOps UI: https://dev.azure.com/azure-sdk/590cfd2a-581c-4dcb-a12e-6568ce786175/_build/results?buildId=7047729
Given this PR changes Cosmos hybrid-search RRF ranking/tie-breaking logic, pay particular attention to the *_circuit_breaker_MultiMaster and *_aad_query/*_search_query legs — these most likely exercise the query/ranking and multi-master failover paths touched by this change. Confirm whether failures are assertion mismatches from the ranking change (fixable) or environment/circuit-breaker timing flakiness (infrastructure) once logs are available.
See https://aka.ms/ci-fix

Copilot detected the failing pipeline and generated the analysis above. To have it attempt a
fix automatically, reply with @copilot please fix the failing pipeline on this PR.

Generated by Pipeline Analysis Next Steps · copilot · sonnet50 · 42.8 AIC · ⌖ 0.567 AIC · ⊞ 9.1K · ◷

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 68efd20b-2c16-45ea-9e93-ecbd62e4e352

Copilot

🟢 Approval recommended

No active review issues remain for the deterministic hybrid-search ranking update.

No open issues 🎉

_{Review effort: Balanced}

Simon Moreno (simorenoh) · 2026-11-06T19:07:23Z

/azp run python - cosmos - tests

azure-pipelines · 2026-11-06T19:07:44Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 68efd20b-2c16-45ea-9e93-ecbd62e4e352

github-actions Bot added the Cosmos label Oct 20, 2026

github-project-automation Bot added this to CosmosDB Python Eco-System Oct 20, 2026

Clarify hybrid ranking stages with comments and spacing

e49c312

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 68efd20b-2c16-45ea-9e93-ecbd62e4e352

This comment has been minimized.

Sign in to view

Maya Painter (Maya-Painter) mentioned this pull request Oct 22, 2026

[Cosmos] Use deterministic ordinal ranks for hybrid-search RRF Azure/azure-sdk-for-js#40450

Open

1 of 3 tasks

Merge branch 'main' into maya-painter-cosmos-rrf-ordinal-ranking

6bd33f3

This comment has been minimized.

Sign in to view

Maya Painter (Maya-Painter) marked this pull request as ready for review October 26, 2026 22:18

Maya Painter (Maya-Painter) requested a review from a team as a code owner October 26, 2026 22:18

Copilot AI balanced review requested due to automatic review settings October 26, 2026 22:18

Merge branch 'main' into maya-painter-cosmos-rrf-ordinal-ranking

eb9863b

Copilot started reviewing on behalf of Maya Painter (Maya-Painter) October 26, 2026 22:18

View session

Copilot AI reviewed Oct 26, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos/azure/cosmos/_execution_context/hybrid_search_aggregator.py Resolved

This comment has been minimized.

Sign in to view

Fix hybrid ranking for empty component scores

cda2b7b

Size score arrays from the query plan and cover empty-first and all-empty rows in sync and async queries. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 68efd20b-2c16-45ea-9e93-ecbd62e4e352

Copilot AI balanced review requested due to automatic review settings October 27, 2026 21:08

Copilot started reviewing on behalf of Maya Painter (Maya-Painter) October 27, 2026 21:08

View session

Copilot AI reviewed Oct 27, 2026

View reviewed changes

Simon Moreno (simorenoh) requested changes Oct 27, 2026

View reviewed changes

Comment thread sdk/cosmos/azure-cosmos/CHANGELOG.md Resolved

Comment thread sdk/cosmos/azure-cosmos/azure/cosmos/_execution_context/hybrid_search_aggregator.py Resolved

Comment thread .chronus/changes/cosmos-ordinal-rrf-ranking.md Resolved

This comment has been minimized.

Sign in to view

Copilot AI balanced review requested due to automatic review settings October 27, 2026 23:49

Copilot started reviewing on behalf of Maya Painter (Maya-Painter) October 27, 2026 23:49

View session

Merge branch 'main' into maya-painter-cosmos-rrf-ordinal-ranking

7c3e599

Copilot AI reviewed Oct 27, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

Copilot AI balanced review requested due to automatic review settings November 4, 2026 19:38

Copilot started reviewing on behalf of Maya Painter (Maya-Painter) November 4, 2026 19:38

View session

Copilot AI reviewed Nov 4, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

Merge branch 'main' into maya-painter-cosmos-rrf-ordinal-ranking

381ffe6

Copilot AI balanced review requested due to automatic review settings November 5, 2026 17:08

Copilot started reviewing on behalf of Maya Painter (Maya-Painter) November 5, 2026 17:09

View session

Copilot AI reviewed Nov 5, 2026

View reviewed changes

[Cosmos] Update live hybrid search expectations for ordinal ranking

bb97ff1

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 68efd20b-2c16-45ea-9e93-ecbd62e4e352

Copilot AI balanced review requested due to automatic review settings November 6, 2026 18:15

Copilot started reviewing on behalf of Maya Painter (Maya-Painter) November 6, 2026 18:15

View session

Copilot AI reviewed Nov 6, 2026

View reviewed changes

Simon Moreno (simorenoh) approved these changes Nov 6, 2026

View reviewed changes

Maya Painter (Maya-Painter) and others added 2 commits November 6, 2026 12:31

[Cosmos] Correct unfiltered hybrid search test expectations

4258c99

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 68efd20b-2c16-45ea-9e93-ecbd62e4e352

Merge branch 'main' into maya-painter-cosmos-rrf-ordinal-ranking

9e42726

Conversation

Maya Painter (Maya-Painter) commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Example

All SDK Contribution checklist:

General Guidelines and Best Practices

Testing Guidelines

Uh oh!

azure-pipelines Bot commented Oct 20, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

This comment has been minimized.

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

This comment has been minimized.

Simon Moreno (simorenoh) commented Oct 28, 2026

Uh oh!

azure-pipelines Bot commented Oct 28, 2026

Uh oh!

This comment has been minimized.

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

This comment has been minimized.

Simon Moreno (simorenoh) commented Nov 5, 2026

Uh oh!

azure-pipelines Bot commented Nov 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Simon Moreno (simorenoh) commented Nov 6, 2026

Uh oh!

azure-pipelines Bot commented Nov 6, 2026

Uh oh!

github-actions Bot commented Nov 6, 2026

What failed

Root cause

Recommended next steps

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Simon Moreno (simorenoh) commented Nov 6, 2026

Uh oh!

azure-pipelines Bot commented Nov 6, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Maya Painter (Maya-Painter) commented Oct 20, 2026 •

edited

Loading