Skip to content

fix(llm): escape edge labels and property key in Gremlin queries - #385

Open
atharrva01 wants to merge 6 commits into
apache:mainfrom
atharrva01:fix/llm-escape-gremlin-labels-and-prop
Open

atharrva01 wants to merge 6 commits into
apache:mainfrom
atharrva01:fix/llm-escape-gremlin-labels-and-prop

Conversation

@atharrva01

Copy link
Copy Markdown

Follow-up to #383, as suggested in the review there.

The graph query templates still quoted edge labels and the prop_to_match key by hand. HugeGraph accepts names with apostrophes, so a schema with an edge label like author's friend (easy to get from LLM extraction) made every GraphRAG neighbor query fail with unexpected token: s. Same for a property key like owner's name in the property query path.

This passes both through gremlin_literal, so all values in these templates are now escaped the same way.

  • Edge labels: graph_query_node.py, edge_labels_str
  • Property key: the three '{prop}' spots in PROPERTY_QUERY_NEIGHBOR_TPL

I checked the queries against a real HugeGraph 1.7.0 server: the hand-quoted versions fail to parse, and the escaped ones run. Added two regression tests for the label and the key; both fail without the fix. The llm unit suite and Ruff pass.

Note: this branch is on top of #383 because it uses gremlin_literal from there. Only the last commit is new. I'll rebase once #383 is merged.

@atharrva01

Copy link
Copy Markdown
Author

hi @imbajin @bitflicker64, this is the follow-up we talked about in #383. It runs the edge labels and the prop_to_match key through gremlin_literal too, so labels like author's friend no longer break the neighbor queries. It's stacked on #383, so only the last commit (c38ff3a) is new here. Would appreciate a look when you have time.

@atharrva01
atharrva01 force-pushed the fix/llm-escape-gremlin-labels-and-prop branch from c38ff3a to f341f83 Compare November 9, 2026 17:07
lplalbert pushed a commit to lplalbert/hugegraph-ai that referenced this pull request Nov 10, 2026
pytest's default prepend import mode collides when two test modules
share a basename in directories without __init__.py. The in-flight
Gremlin-escaping work (apache#383/apache#385) adds its own test_graph_query_node.py,
so rename this module to test_graph_query_vertex_knowledge.py (the
behavior it covers) instead of keeping a duplicate name.

Co-Authored-By: Claude Code <noreply@anthropic.com>

@bitflicker64 bitflicker64 left a comment

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.

Blocking: no. Score: 9/10. Summary: Edge labels and the prop_to_match key now go through gremlin_literal, which closes the last hand-quoted values in the _subgraph_query templates, and both new regression tests fail without the fix and pass with it. The rest of the diff is the stacked #383 change, unchanged from that PR's head 9c94f31.

@imbajin imbajin left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Score: 8.0/10 · Confidence: medium

Blocking: no

Summary

The updated query paths consistently render IDs, edge labels and property keys as Gremlin literals. Approval is deferred pending independent live traversal validation.

Evidence

Reviewed query templates, callers, literal handling and existing discussion. Local Groovy parser checks sampled control escapes and literal backslash sequences; current-head LLM and quality CI passed. The author reports a HugeGraph 1.7.0 check.

Validation notes

No independent real HugeGraph traversal was run; fake endpoint tests do not establish server compatibility across versions. The Pull Request Labeler workflow has a startup failure; product CI passed.

lplalbert pushed a commit to lplalbert/hugegraph-ai that referenced this pull request Nov 15, 2026
pytest's default prepend import mode collides when two test modules
share a basename in directories without __init__.py. The in-flight
Gremlin-escaping work (apache#383/apache#385) adds its own test_graph_query_node.py,
so rename this module to test_graph_query_vertex_knowledge.py (the
behavior it covers) instead of keeping a duplicate name.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@atharrva01

Copy link
Copy Markdown
Author

Live validation against a real HugeGraph 1.7.0 server, as requested in the review.

Setup

  • HugeGraph Server 1.7.0, the official binary release from downloads.apache.org (SHA-512 checked), RocksDB backend, auth off. It runs on OpenJDK 11. On JDK 21 the server's Groovy engine fails to start (Unsupported class file major version 65).
  • Schema: vertex label person, edge label author's friend, property key owner's name with a secondary index (HugeGraph only accepts has() on indexed properties). Two vertices 1:alice --[author's friend]--> 1:bob.
  • Each run calls the real GraphQueryNode._subgraph_query through the real PyHugeClient, with no fake endpoint. Edge labels come from the live schema (_schema left empty). The same script runs on main (1a1e269) and on this branch (f341f83).

Results

Path main this PR
Vertex-ID path, edge label author's friend server rejects: unexpected token: s runs, returns 1:alice{...}--[author's friend]-->1:bob{...}
Property path, prop_to_match = "owner's name" server rejects: unexpected token: s server accepts and returns 1 path

On main the server rejects both queries before running them:

bothE('author's friend').limit(8).otherV().dedup()
                    ^  unexpected token: s
g.V().has('owner's name', within('Alice'))
                    ^  unexpected token: s

On this branch the server runs both queries as sent:

bothE('author\'s friend').limit(8).otherV().dedup()          -> server OK, 1 result
g.V().has('owner\'s name', within('Alice')) ... values('owner\'s name') -> server OK, 1 result

Separate, older issue (out of scope here): in the property path the query now runs, but _process_vertex then raises KeyError: 'id'. PROPERTY_QUERY_NEIGHBOR_TPL projects vertices as ('label', 'props') with no id, but _process_vertex reads item['id']. It also happens on main with plain names (indexed property genre, edge cites), so this PR didn't cause it. On main the parse error simply hid it. I'll open a separate PR for it.

Validation script
"""Live validation for apache/hugegraph-ai#385 against a real HugeGraph server.

Runs the real GraphQueryNode._subgraph_query (no fake endpoint) through the real
PyHugeClient, on whatever checkout is on sys.path, and prints every Gremlin script
sent to the server plus the server's answer or error.

Usage (from <checkout>/hugegraph-llm/src):
    uv run python live_validate_385.py setup   # create schema + data (once)
    uv run python live_validate_385.py run
"""

import json
import sys

from pyhugegraph.client import PyHugeClient

from hugegraph_llm.nodes.hugegraph_node.graph_query_node import GraphQueryNode

URL, GRAPH, USER, PWD = "http://127.0.0.1:8080", "hugegraph", "admin", "admin"
EDGE_LABEL = "author's friend"
PROP_KEY = "owner's name"


def client():
    return PyHugeClient(url=URL, graph=GRAPH, user=USER, pwd=PWD)


def setup():
    c = client()
    s = c.schema()
    s.propertyKey("name").asText().ifNotExist().create()
    s.propertyKey(PROP_KEY).asText().ifNotExist().create()
    s.vertexLabel("person").properties("name", PROP_KEY).primaryKeys("name").ifNotExist().create()
    s.edgeLabel(EDGE_LABEL).sourceLabel("person").targetLabel("person").ifNotExist().create()
    # HugeGraph only allows has() on indexed properties, so prop_to_match needs an index.
    s.indexLabel("personByOwnersName").onV("person").by(PROP_KEY).secondary().ifNotExist().create()
    g = c.graph()
    alice = g.addVertex("person", {"name": "alice", PROP_KEY: "Alice"})
    bob = g.addVertex("person", {"name": "bob", PROP_KEY: "Bob"})
    g.addEdge(EDGE_LABEL, alice.id, bob.id, {})
    print("schema edge labels:", [e.name for e in s.getEdgeLabels()])
    print("schema property keys:", [p.name for p in s.getPropertyKeys()])
    print("vertices:", alice.id, bob.id)


class LoggingGremlin:
    def __init__(self, inner):
        self._inner = inner

    def exec(self, gremlin):
        print("----- Gremlin sent to server -----")
        print(gremlin.strip())
        try:
            res = self._inner.exec(gremlin=gremlin)
        except Exception as e:  # report the server's own error verbatim
            print(f"----- SERVER ERROR: {type(e).__name__}: {e}")
            raise
        print(f"----- server OK, {len(res['data'])} result(s)")
        return res


def node_with_live_client():
    real = client()
    node = GraphQueryNode()
    node._client = real
    gremlin_factory = real.gremlin
    real.gremlin = lambda: LoggingGremlin(gremlin_factory())
    node._schema = ""  # force the real schema read from the server
    node._prop_to_match = None
    node._max_deep = 2
    node._max_items = 30
    return node


def run_case(title, fn):
    print(f"\n========== {title} ==========")
    try:
        ctx = fn()
        print("RESULT graph_result:", json.dumps(sorted(ctx.get("graph_result", [])), ensure_ascii=False))
    except Exception as e:
        print(f"RESULT FAILED: {type(e).__name__}")


def run():
    run_case(
        f"vertex-id path, edge label {EDGE_LABEL!r}",
        lambda: node_with_live_client()._subgraph_query({"match_vids": ["1:alice"]}),
    )

    def prop_path():
        node = node_with_live_client()
        node._prop_to_match = PROP_KEY
        return node._subgraph_query({"keywords": ["Alice"]})

    run_case(f"property path, prop_to_match {PROP_KEY!r}", prop_path)


if __name__ == "__main__":
    {"setup": setup, "run": run}[sys.argv[1]]()

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants