enhance: add query_iterator to AsyncMilvusClient

[csy1204]

related to: #3742

Problem

AsyncMilvusClient has no query_iterator(). Async callers who need a full filtered result set fall back to query(..., limit=N) — which has no ordering guarantee, so which N rows come back is undefined — or hand-roll primary-key cursor pagination plus mvcc-timestamp pinning in application code.

What this does

The sync QueryIterator touches the network in only four places, all through self._handler; everything else is pure logic. So instead of a parallel implementation, this splits the state machine out and drives it from both transports.

• refactor: extract transport-agnostic _QueryIteratorBase from QueryIterator — the base holds cursor bookkeeping, expression assembly, batch/limit accounting, the result cache and the checkpoint file, and exposes _*_kwargs() builders paired with _consume_*() methods. QueryIterator becomes a thin sync driver over it. Two private helpers move to a single underscore (_setup_next_expr, _save_pk_cursor) because the subclass driver calls them and existing tests reference the mangled names.
• enhance: add AsyncQueryIterator on top of the shared iterator base — the async driver. Setup RPCs run in a create() classmethod because __init__ cannot await. await next(), await close(), get_cursor(), and __aiter__/__anext__ for async for.
• enhance: add query_iterator to AsyncMilvusClient — the factory, mirroring the sync one (same parameter names/order/defaults, same filter type check, same schema-cache lookup). AsyncMilvusClientSession delegates it the way the sync session does.
• test: cover AsyncQueryIterator limits, cursors, checkpoint resume and async for

it = await client.query_iterator(collection_name="c", filter="pk > 0", batch_size=1000)
try:
    while True:
        batch = await it.next()
        if not batch:
            break
        handle(batch)
finally:
    await it.close()

# or
async for batch in it:
    handle(batch)

Behavior note

The refactor moves parameter validation ahead of the first RPC, so QueryIterator(batch_size=-1) now raises ParamError without the describe_collection call the old code made first (same for a schema dict with no is_primary field). This is the only intentional behavior difference, and it makes sync and async validate identically. It is stated in the refactor commit's message too.

How the refactor was verified

Commit 1 renames the class at the top of the file and appends a subclass, so GitHub renders it as close to a rewrite — "existing tests pass" is weak evidence for a refactor whose tests were written against the old structure. So I also compared old vs new directly with a throwaway differential harness (not part of this PR), driving both versions against identical recording handlers and diffing the full ordered sequence of describe_collection/query calls with all kwargs, plus returned batches, final cursor and checkpoint-file contents:

• 19 scenarios, old vs new: identical except the validation-ordering difference above. Covered int/varchar/None pk expressions, the cache hit-and-refill path, limit cut-off, offset seek (full / drained-early / partial-loop), element_filter with and without an element cursor, extra rpc_options passthrough, and all six checkpoint branches (fresh, resume, one-line ParamError, unparseable ts, element-cursor resume, resume-with-residual-offset).
• 24 scenarios, new sync vs new async: identical, zero divergence. Also covered limit=0, reduce_stop_for_best=False, the mvccTs fallback when the server returns 0, and the 100-line checkpoint-file truncation path.

Tests

tests/unit/test_async_query_iterator.py (new, no server needed) covers batch exhaustion, int and varchar PK cursor expressions, batch_size validation before any RPC, limit cut-off, checkpoint-file write / resume / removal, describe_collection called exactly once, async for parity with the next() loop, and get_cursor(). tests/unit/test_iterator_ownership.py gains an ownership assertion for the new class, and the session-delegation parametrize list in tests/unit/test_async_milvus_client.py gains a query_iterator row so cluster_id forwarding is pinned the way the sync suite pins it.

Full unit suite: 4553 passed, 3 skipped. black --check and ruff check clean.

Also ran it against a live Milvus deployment: iterating one filtered set returned 4,621 rows over 47 pages, and AsyncMilvusClient.query_iterator, async for, and the sync query_iterator all produced the identical primary-key set with no duplicates.

Scope

Deliberately limited to query_iterator, since #3483 was closed for bundling unrelated changes:

• search_iterator async support is left for a separate PR, which is why AsyncMilvusClientSession delegates only query_iterator where the sync session delegates both.
• __aiter__/__anext__ has no sync counterpart on purpose — it is the idiomatic async consumption protocol and six lines. I did not add __iter__ to the sync iterator.
• Checkpoint-file I/O stays synchronous inside the async coroutines. It lives in the shared base, it is one buffered line plus a flush per batch next to a network round-trip, and moving it off-thread would mean either a thread-pool hop per batch or lifting the checkpoint logic back out of the shared base.
• AsyncQueryIterator is not exported from the top-level pymilvus namespace, matching QueryIterator.

Happy to split, rename or adjust anything here — including the base-class extraction, if you would rather see the async driver built a different way.

[csy1204]

/assign @XuanYang-cn

For context: in #3483 you asked for that PR to be closed and split into one PR per requirement. This is the async-iterator item, on its own, with focused tests — no other changes bundled in.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[sre-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: csy1204
To complete the pull request process, please ask for approval from xuanyang-cn after the PR has been reviewed.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[codecov]

Codecov Report

❌ Patch coverage is 92.96482% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.11%. Comparing base (c5e73a6) to head (5d0fedf).
⚠️ Report is 1 commits behind head on master.

Files with missing lines	Patch %	Lines
pymilvus/client/iterator/async_query_iterator.py	78.43%	11 Missing ⚠️
pymilvus/client/iterator/query_iterator.py	97.76%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3743      +/-   ##
==========================================
- Coverage   94.14%   94.11%   -0.04%     
==========================================
  Files          76       77       +1     
  Lines       15921    16012      +91     
==========================================
+ Hits        14989    15069      +80     
- Misses        932      943      +11     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.