fix(graph): resolve edge creation failure due to vertex ID mismatch by linmengmeng-1314 · Pull Request #331 · apache/hugegraph-ai

linmengmeng-1314 · 2026-05-18T11:57:01Z

Summary

Fix edge creation failure when loading extracted graph data into HugeGraph
The HugeGraph server assigns vertex IDs (e.g., 1:Sarah) using numeric label IDs, which differ from LLM-predicted IDs (e.g., person:Sarah) that edges reference
Add vid_mapping to track the ID mapping and update edge outV/inV after vertex creation
Normalize extracted graph IDs and edge endpoints after LLM extraction, including missing item type fields and custom string IDs

Problem

When using "Load into GraphDB" to import extracted graph data, edges fail to be created with java.lang.IllegalArgumentException. The root cause is that the LLM generates vertex IDs using label names (e.g., person:Sarah), but the HugeGraph server uses numeric label IDs (e.g., 1:Sarah). Edge references still point to the LLM-predicted IDs, causing vertex lookup failures.

Solution

Save original vertex ID before server creation
Build a mapping from original ID to actual server-assigned ID
Apply the mapping when creating edges (with fallback to original ID for backward compatibility)
Derive PRIMARY_KEY vertex IDs from schema after LLM extraction
Reject edges whose endpoints cannot be resolved to vertices in the same extracted output
Preserve explicit CUSTOMIZE_STRING vertex IDs and pass them to HugeGraph when creating vertices
Align few-shot prompt examples with the current extraction contract

Flow

LLM output
  |
  v
Parse JSON / infer item type
  |
  v
Normalize vertices by schema
  - PRIMARY_KEY: person:Sarah -> 1:Sarah
  - CUSTOMIZE_STRING: keep explicit id
  |
  v
Validate edge endpoints
  - outV/inV must resolve to extracted vertices
  - labels must match source_label/target_label
  |
  v
Commit vertices
  - remember original id -> server id
  |
  v
Commit edges with mapped endpoints

TODO

Handle valid cross-chunk edges without requiring both endpoints to appear in the same chunk output. This likely needs graph extraction normalization after all chunks are merged, or a shared vertex index across chunks.
Preserve or coerce property data types consistently across PropertyGraphExtract.run() and Commit2Graph; filter_item() currently stringifies non-string values while commit-time validation expects typed values.
Consider broader non-PRIMARY_KEY id strategy support beyond the current minimal CUSTOMIZE_STRING path, such as CUSTOMIZE_NUMBER, CUSTOMIZE_UUID, and AUTOMATIC.

Test plan

Extract graph data with an LLM
Load into GraphDB and verify both vertices and edges are created successfully
Verify existing functionality is not broken when LLM predicts correct IDs
Verify LLM outputs without item type fields are accepted from grouped vertices/edges arrays
Verify label-name IDs such as person:Sarah are normalized to schema-derived IDs such as 1:Sarah
Verify explicit CUSTOMIZE_STRING IDs are preserved and committed with addVertex(..., id=...)

🤖 Generated with Claude Code

When loading graph data, the HugeGraph server assigns vertex IDs (e.g., "1:Sarah") that differ from LLM-predicted IDs (e.g., "person:Sarah"). This causes edge creation to fail with IllegalArgumentException because the edge references use the original LLM-predicted IDs which don't match actual vertex IDs in the graph. Add a vid_mapping to track the ID mapping and update edge references after vertex creation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot