[Question]: OpenSearch not support "_shard_doc", but "opensearch_impl.py " has it

[guangdalin-ship-it]

Do you need to ask a question?

• I have searched the existing question and discussions and this question is not already answered.
• I believe this is a legitimate question, not just a bug or feature request.

Your Question

OpenSearch not support "_shard_doc", but "opensearch_impl.py " has it

is it a bug ?

Additional Context

No response

[danielaskdd]

Confirmed — this is a real bug for users running OpenSearch < 3.3.0.

Root cause

_shard_doc is an Elasticsearch 7.12+ implicit tiebreaker for PIT + search_after. OpenSearch only added an equivalent in 3.3.0 (PR opensearch-project/OpenSearch#18924, merged 2025-09-30 via issue #17064).

lightrag/kg/opensearch_impl.py uses {"_shard_doc": "asc"} in 10 PIT pagination paths (lines 273, 692, 790, 1318, 1450, 1794, 1849, 1919, 2306, 2350), so any OpenSearch 2.x or 3.0–3.2 cluster will fail with No mapping found for [_shard_doc] in order to sort on.

The file header only says OpenSearch 3.x or higher, which is misleading.

Workarounds

Pick whichever fits your environment:

1. Upgrade your cluster to OpenSearch 3.3.0+ — fastest fix if you control the deployment.
2. Patch locally: replace every {"_shard_doc": "asc"} with {"_id": "asc"}, or append {"_id": "asc"} after the existing primary sort (e.g. in get_docs_paginated at line 790). _id works as a tiebreaker on all OpenSearch 2.x/3.x versions with effectively the same correctness guarantees for search_after.

Question

Could you share which OpenSearch version you are running (GET / response) so we can scope the fix?

A proper upstream fix would prefer option 2, since AWS OpenSearch Service and most managed offerings still trail the 3.3 release.

[danielaskdd]

@LantaoJin Could you please share your thoughts on the best approach to resolving this issue?

[danielaskdd]

PR #2991 resoled this issue. Pls pull the latest code and check if it works as expected.