[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).

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 · 2026-11-06T22:58:03Z

[Pilot] PR Pipeline Failure Analysis

What failed

Azure Pipelines build 7048924 — python - cosmos - ci, job Build Test windows2022___EmulatorTestsPython313Standard:

tests.test_cosmos_http_logging_policy.TestCosmosHttpLogger.test_activity_id_logging_policy

Relevant pipeline output

azure.cosmos.exceptions.CosmosHttpResponseError: (InternalServerError) Unknown server error occurred when processing this request.
ActivityId: e233cbae-87a7-43b2-88f3-2464d60eb5c3, Microsoft.Azure.Documents.Common/2.14.0
Code: InternalServerError
Message: Unknown server error occurred when processing this request.

Failed at: database.create_container(id=container_id, partition_key=PartitionKey(path="/pk"))
File: tests/test_cosmos_http_logging_policy.py:319

Recommended next steps

The failure is a 5xx InternalServerError returned by the Cosmos DB emulator during create_container, before any ranking/RRF logic in this PR would execute. It is not caused by this PR's code changes.
Retry the python - cosmos - ci pipeline.
If it recurs consistently, investigate emulator health/capacity for the windows2022___EmulatorTestsPython313Standard job independent of this PR.
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 · 35.9 AIC · ⌖ 0.61 AIC · ⊞ 9.1K · ◷

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

This comment has been minimized.

Sign in to view

[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

This comment has been minimized.

Sign in to view

Maya Painter (Maya-Painter) enabled auto-merge (squash) November 7, 2026 00:18

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!

This comment has been minimized.

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 comment has been minimized.

github-actions Bot commented Nov 6, 2026

What failed

Recommended next steps

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