From beeaf2d1f66dca63169784ed9387acf239e23162 Mon Sep 17 00:00:00 2001 From: z <3042372703@qq.com> Date: Fri, 13 Nov 2026 00:37:35 +0800 Subject: [PATCH 1/2] perf(llm): batch neighbour gremlin queries by matched vid --- .../nodes/hugegraph_node/graph_query_node.py | 20 +++- .../src/tests/nodes/test_graph_query_node.py | 103 ++++++++++++++++++ 2 files changed, 119 insertions(+), 4 deletions(-) create mode 100644 hugegraph-llm/src/tests/nodes/test_graph_query_node.py diff --git a/hugegraph-llm/src/hugegraph_llm/nodes/hugegraph_node/graph_query_node.py b/hugegraph-llm/src/hugegraph_llm/nodes/hugegraph_node/graph_query_node.py index 1b5a1b368..6c084bc81 100644 --- a/hugegraph-llm/src/hugegraph_llm/nodes/hugegraph_node/graph_query_node.py +++ b/hugegraph-llm/src/hugegraph_llm/nodes/hugegraph_node/graph_query_node.py @@ -50,6 +50,11 @@ .toList() """ +# Number of matched vids grouped per single gremlin ``exec`` for the neighbour +# traversal. One round-trip per group instead of one per matched vid; the batch +# stays small to keep each query's work bounded. +NEIGHBOR_QUERY_BATCH_SIZE = 10 + PROPERTY_QUERY_NEIGHBOR_TPL = """\ g.V().has('{prop}', within({keywords})) .repeat( @@ -361,17 +366,24 @@ def _subgraph_query(self, context: Dict[str, Any]) -> Dict[str, Any]: vertex_knowledge = self._format_graph_from_vertex(query_result=vertexes) paths: List[Any] = [] - # TODO: use generator or asyncio to speed up the query logic - for matched_vid in matched_vids: + # Batch the per-vid neighbour traversals: one gremlin exec per + # group instead of one per matched vid, so a large id set no longer + # triggers one server round-trip per id. Batch data is concatenated + # in matched_vids order, so the path list keeps the per-vid order. + batch_size = min(NEIGHBOR_QUERY_BATCH_SIZE, len(matched_vids)) + for start in range(0, len(matched_vids), batch_size): + batch = matched_vids[start : start + batch_size] gremlin_query = VID_QUERY_NEIGHBOR_TPL.format( - keywords=f"'{matched_vid}'", + keywords=", ".join(f"'{vid}'" for vid in batch), max_deep=self._max_deep, edge_labels=edge_labels_str, edge_limit=edge_limit_amount, max_items=self._max_items, ) log.debug("Kneighbor gremlin query: %s", gremlin_query) - paths.extend(self._client.gremlin().exec(gremlin=gremlin_query)["data"]) + batch_paths = self._client.gremlin().exec(gremlin=gremlin_query)["data"] + if batch_paths: + paths.extend(batch_paths) ( graph_chain_knowledge, diff --git a/hugegraph-llm/src/tests/nodes/test_graph_query_node.py b/hugegraph-llm/src/tests/nodes/test_graph_query_node.py new file mode 100644 index 000000000..d59507805 --- /dev/null +++ b/hugegraph-llm/src/tests/nodes/test_graph_query_node.py @@ -0,0 +1,103 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +"""Unit tests for the batched neighbour-traversal gremlin exec in GraphQueryNode.""" + +import math +from unittest.mock import Mock + +from hugegraph_llm.nodes.hugegraph_node.graph_query_node import ( + NEIGHBOR_QUERY_BATCH_SIZE, + GraphQueryNode, +) + +# A parseable schema so _extract_labels_from_schema does not hit the client. +_SCHEMA = "Vertex properties: label: name, id: uuid\nEdge properties: edge: source, target\nRelationships: []\n" + + +def _node(match_vids: list[str], exec_result: dict | None = None, exec_side_effect=None) -> GraphQueryNode: + node = GraphQueryNode() + node._client = Mock() + if exec_side_effect is not None: + node._client.gremlin.return_value.exec.side_effect = exec_side_effect + else: + node._client.gremlin.return_value.exec.return_value = exec_result or {"data": []} + node._schema = _SCHEMA + node._max_deep = 1 + node._max_items = 10 + node._prop_to_match = None # id-to-match subgraph branch (per-vid loop) + data_json = {"query": "some query", "match_vids": match_vids, "max_deep": 1, "max_items": 10} + node.operator_schedule(data_json) + return node + + +def test_neighbor_queries_are_batched_across_matched_vids(): + node = _node(["v1", "v2", "v3", "v4", "v5"]) + # vertex full-match exec (1) + one neighbour batch for 5 vids (1) = 2, + # instead of 1 + 5 per-vid execs. + assert node._client.gremlin().exec.call_count == 2 + + +def test_neighbor_queries_batch_large_vid_set(): + vids = [f"v{i}" for i in range(1, 26)] + node = _node(vids) + # 1 vertex exec + one exec per batch, instead of 1 + 25 executions. + expected = 1 + math.ceil(len(vids) / NEIGHBOR_QUERY_BATCH_SIZE) + assert node._client.gremlin().exec.call_count == expected + + +def test_single_vid_keeps_one_vertex_and_one_neighbor_query(): + node = _node(["only-vid"]) + assert node._client.gremlin().exec.call_count == 2 + + +def test_empty_match_vids_skips_query(): + node = _node([]) + assert node._client.gremlin().exec.call_count == 0 + + +def test_batch_queries_split_vids_in_order(): + vids = [f"v{i}" for i in range(1, 13)] # 12 vids -> batches of 10 + 2 + first_batch, second_batch = vids[:NEIGHBOR_QUERY_BATCH_SIZE], vids[NEIGHBOR_QUERY_BATCH_SIZE:] + exec_calls: list[str] = [] + + def exec_side_effect(gremlin): + exec_calls.append(gremlin) + return {"data": []} + + _node(vids, exec_side_effect=exec_side_effect) + assert len(exec_calls) == 1 + math.ceil(len(vids) / NEIGHBOR_QUERY_BATCH_SIZE) + # the full-vertex query is kept as-is, then one query per vid batch + assert exec_calls[0].startswith(f"g.V({vids}).limit(8)") + assert all(f"'{vid}'" in exec_calls[1] for vid in first_batch) + assert all(f"'{vid}'" not in exec_calls[1] for vid in second_batch) + assert all(f"'{vid}'" in exec_calls[2] for vid in second_batch) + + +def test_batches_concatenate_paths_in_vid_order(monkeypatch): + vids = [f"v{i}" for i in range(1, 13)] + captured_paths: list[list[str]] = [] + + def fake_format(self, query_paths): + captured_paths.append(list(query_paths)) + return set(), [], set() + + monkeypatch.setattr(GraphQueryNode, "_format_graph_query_result", fake_format) + batches = iter([{"data": []}, {"data": ["p1", "p2"]}, {"data": ["p3"]}]) + _node(vids, exec_side_effect=lambda gremlin: next(batches)) + # batch results are appended in matched_vids order, so ordering is preserved + assert captured_paths == [["p1", "p2", "p3"]] From fb2dee7a0f168b7b140579fc41782441c4f2d358 Mon Sep 17 00:00:00 2001 From: z <3042372703@qq.com> Date: Fri, 13 Nov 2026 13:11:40 +0800 Subject: [PATCH 2/2] fix(llm): scope batched neighbour traversal per vid with local() The batched neighbour query ran repeat/bothE().limit()/dedup()/limit(max_items) as global steps, so all vids in a batch shared one edge budget, one dedup set and one result cap; on a batch of 10 vids only the first vid's neighbours survived. Wrap the traversal after g.V(...) in local(__. ...) so each vid keeps its own limits and dedup while still issuing one exec per batch. Add tests asserting the generated query keeps those steps inside the local() scope. --- .../nodes/hugegraph_node/graph_query_node.py | 40 ++++++------ .../src/tests/nodes/test_graph_query_node.py | 62 +++++++++++++++++++ 2 files changed, 84 insertions(+), 18 deletions(-) diff --git a/hugegraph-llm/src/hugegraph_llm/nodes/hugegraph_node/graph_query_node.py b/hugegraph-llm/src/hugegraph_llm/nodes/hugegraph_node/graph_query_node.py index 6c084bc81..b4791f749 100644 --- a/hugegraph-llm/src/hugegraph_llm/nodes/hugegraph_node/graph_query_node.py +++ b/hugegraph-llm/src/hugegraph_llm/nodes/hugegraph_node/graph_query_node.py @@ -30,23 +30,25 @@ # TODO: test with profile()/explain() to speed up the query VID_QUERY_NEIGHBOR_TPL = """\ g.V({keywords}) -.repeat( - bothE({edge_labels}).limit({edge_limit}).otherV().dedup() -).times({max_deep}).emit() -.simplePath() -.path() -.by(project('label', 'id', 'props') - .by(label()) - .by(id()) - .by(valueMap().by(unfold())) -) -.by(project('label', 'inV', 'outV', 'props') - .by(label()) - .by(inV().id()) - .by(outV().id()) - .by(valueMap().by(unfold())) +.local( + __.repeat( + bothE({edge_labels}).limit({edge_limit}).otherV().dedup() + ).times({max_deep}).emit() + .simplePath() + .path() + .by(project('label', 'id', 'props') + .by(label()) + .by(id()) + .by(valueMap().by(unfold())) + ) + .by(project('label', 'inV', 'outV', 'props') + .by(label()) + .by(inV().id()) + .by(outV().id()) + .by(valueMap().by(unfold())) + ) + .limit({max_items}) ) -.limit({max_items}) .toList() """ @@ -368,8 +370,10 @@ def _subgraph_query(self, context: Dict[str, Any]) -> Dict[str, Any]: paths: List[Any] = [] # Batch the per-vid neighbour traversals: one gremlin exec per # group instead of one per matched vid, so a large id set no longer - # triggers one server round-trip per id. Batch data is concatenated - # in matched_vids order, so the path list keeps the per-vid order. + # triggers one server round-trip per id. The traversal is wrapped in + # local(...) so each vid keeps its own edge_limit, dedup and + # max_items budget; batch data is concatenated in matched_vids + # order, so the path list keeps the per-vid order. batch_size = min(NEIGHBOR_QUERY_BATCH_SIZE, len(matched_vids)) for start in range(0, len(matched_vids), batch_size): batch = matched_vids[start : start + batch_size] diff --git a/hugegraph-llm/src/tests/nodes/test_graph_query_node.py b/hugegraph-llm/src/tests/nodes/test_graph_query_node.py index d59507805..4983b3a9d 100644 --- a/hugegraph-llm/src/tests/nodes/test_graph_query_node.py +++ b/hugegraph-llm/src/tests/nodes/test_graph_query_node.py @@ -101,3 +101,65 @@ def fake_format(self, query_paths): _node(vids, exec_side_effect=lambda gremlin: next(batches)) # batch results are appended in matched_vids order, so ordering is preserved assert captured_paths == [["p1", "p2", "p3"]] + + +def test_neighbor_query_wraps_per_vid_traversal_in_local_scope(): + """The batched neighbour query must keep edge_limit / dedup / max_items per vid. + + Without local(...) the bothE().limit(), dedup() and .limit(max_items) steps + are global across the whole batch, so a batch of N vids shares one edge + budget and returns neighbours almost only from the first vid. Wrapping the + traversal after g.V(...) in local(__. ...) runs the inner traversal + independently per vid, restoring the per-vid limits. + """ + vids = [f"v{i}" for i in range(1, 6)] + exec_calls: list[str] = [] + + def exec_side_effect(gremlin): + exec_calls.append(gremlin) + return {"data": []} + + _node(vids, exec_side_effect=exec_side_effect) + # exec_calls[0] is the full-vertex query; exec_calls[1] is the neighbour batch + neighbor_query = exec_calls[1] + + # the per-vid traversal (repeat ... path ... limit) is wrapped in local(...) + assert ".local(" in neighbor_query + # the anonymous traversal starts right after local(, so limits are per-vid + local_idx = neighbor_query.index(".local(") + inner = neighbor_query[local_idx:] + assert "bothE(" in inner + assert ".limit(" in inner # edge_limit is inside local scope + assert "dedup()" in inner + assert ".limit(" in inner # max_items is inside local scope + # the global .toList() sits outside local(...): local's closing ')' + # precedes the final .toList() step + stripped = neighbor_query.rstrip() + assert stripped.endswith(".toList()") + to_list_idx = stripped.rindex(".toList()") + local_close_idx = stripped[:to_list_idx].rindex(")") + assert local_close_idx < to_list_idx + + +def test_neighbor_query_keeps_limits_inside_local_not_global(): + """edge_limit / dedup / max_items must appear after local(, not before it.""" + vids = ["v1", "v2", "v3"] + exec_calls: list[str] = [] + + def exec_side_effect(gremlin): + exec_calls.append(gremlin) + return {"data": []} + + _node(vids, exec_side_effect=exec_side_effect) + neighbor_query = exec_calls[1] + local_idx = neighbor_query.index(".local(") + before_local = neighbor_query[:local_idx] + after_local = neighbor_query[local_idx:] + + # g.V(...) precedes local(); no limit/dedup step leaks ahead of it + assert "limit(" not in before_local + assert "dedup()" not in before_local + # the per-vid edge budget and result cap are scoped inside local(...) + assert "bothE(" in after_local + assert "dedup()" in after_local + assert after_local.count(".limit(") >= 2