Repository navigation
perf(llm): batch gremlin neighbour queries #430
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: ontogeny
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -30,26 +30,33 @@ | |
| # 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())) | ||
| .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}) | ||
| ) | ||
| .by(project('label', 'inV', 'outV', 'props') | ||
| .by(label()) | ||
| .by(inV().id()) | ||
| .by(outV().id()) | ||
| .by(valueMap().by(unfold())) | ||
| ) | ||
| .limit({max_items}) | ||
| .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 +368,26 @@ 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. 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] | ||
| gremlin_query = VID_QUERY_NEIGHBOR_TPL.format( | ||
| keywords=f"'{matched_vid}'", | ||
| keywords=", ".join(f"'{vid}'" for vid in batch), | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Important:
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks for catching this — it was a real behaviour regression, not just an edge case. Fixed in e3409f6. The traversal after Generated query shape: Semantics are back to the old per-vid loop: each vid contributes its own paths, capped independently by Tests added in
Verification: Branch was also rebased onto current |
||
| 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, | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,165 @@ | ||
| # 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"]] | ||
|
|
||
|
|
||
| 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Important: the head is based on #391's head
d97afa1, not onontogeny, so this PR carries #391's 68 commits and 383 extra files and merging it lands them without that PR's review. Rebase the twollmcommits ontoontogenyso the diff holds onlygraph_query_node.pyand its test.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@bitflicker64 Done — rebased the two
llmcommits ontoontogenyand force-pushedperf/gremlin-neighbor-batching. The PR diff now contains only those 2 commits andgraph_query_node.py+ its test (test_graph_query_node.py).