Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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

Copy link
Copy Markdown
Contributor

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 on ontogeny, so this PR carries #391's 68 commits and 383 extra files and merging it lands them without that PR's review. Rebase the two llm commits onto ontogeny so the diff holds only graph_query_node.py and its test.

Copy link
Copy Markdown
Author

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 llm commits onto ontogeny and force-pushed perf/gremlin-neighbor-batching. The PR diff now contains only those 2 commits and graph_query_node.py + its test (test_graph_query_node.py).


PROPERTY_QUERY_NEIGHBOR_TPL = """\
g.V().has('{prop}', within({keywords}))
.repeat(
Expand Down Expand Up @@ -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),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: bothE().limit({edge_limit}), dedup() and .limit({max_items}) in VID_QUERY_NEIGHBOR_TPL are global steps, so the vids in one batch share a single edge budget and dedup set; on TinkerGraph 3.5.1 with one edge label, 10 vids with 8 neighbours each return 8 paths, all from the first vid, instead of 80. Wrap the traversal after g.V(...) in local(...) so each vid keeps its own limits and dedup, and add a test that checks the generated query keeps that per-vid scope.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The 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 g.V(...) is now wrapped in local(__. ...), so each matched vid runs the inner repeat ... path ... limit(max_items) in its own scope. bothE().limit(edge_limit), dedup() and .limit(max_items) are now per vid instead of sharing one edge budget / dedup set / cap across the batch, while the query count is still 1 + ceil(N / 10) (N=25: 4 execs, unchanged).

Generated query shape:

g.V('v1', ..., 'v10')
.local(
   __.repeat(
      bothE('edge').limit(edge_limit).otherV().dedup()
   ).times(max_deep).emit()
   .simplePath()
   .path()
   .by(project('label', 'id', 'props')...)
   .by(project('label', 'inV', 'outV', 'props')...)
   .limit(max_items)
)
.toList()

Semantics are back to the old per-vid loop: each vid contributes its own paths, capped independently by max_items, with no cross-vid contamination of the edge limit or dedup() set.

Tests added in src/tests/nodes/test_graph_query_node.py, both asserting the generated query keeps the per-vid scope:

  • test_neighbor_query_wraps_per_vid_traversal_in_local_scope — bothE(, dedup() and both .limit( steps are inside local(...), with the global .toList() outside.
  • test_neighbor_query_keeps_limits_inside_local_not_global — no limit( / dedup() leaks ahead of .local(, and both limits are scoped inside it.

Verification:

ruff check <both files>            -> All checks passed
ruff format --check <both files>   -> 2 files already formatted
PYTHONPATH=src pytest src/tests/nodes -q -> 11 passed

Branch was also rebased onto current upstream/ontogeny, so the diff is now just the two files above.

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,
Expand Down
165 changes: 165 additions & 0 deletions hugegraph-llm/src/tests/nodes/test_graph_query_node.py
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
Loading