{namespace}`¶

Performs fuzzy semantic graph traversal starting from a value in a given slot, following a sequence of predicate/edge values hop by hop. Unlike exact graph traversal, each hop uses vector similarity — enabling semantic path following across loosely structured data.

Request¶

Content-Type: application/json

URL Parameters:

Parameter	Description
`db_name`	Name of the database
`namespace`	Namespace within the database

Body:

Parameter	Type	Required	Default	Description
`start_value`	string	✅	—	Starting node value (e.g. `"Alice"`)
`start_slot`	string	✅	—	Slot to search `start_value` in (e.g. `"subject"`)
`path`	list of string	✅	—	Ordered list of predicate/edge values to follow (e.g. `["works_at", "located_in"]`)
`hop_threshold`	float	❌	`0.5`	Minimum similarity score required to follow an edge at each hop
`max_candidates`	int	❌	`100`	Maximum candidates to carry forward at each hop
`top_k`	int	❌	`10`	Number of final results to return
`schema_json_data`	string	❌	`null`	JSON string of the schema. Required if not stored in metadata

Behavior¶

Hop-by-hop traversal — Starting from rows where start_slot is similar to start_value, the traversal follows each entry in path as a predicate. At each hop, only candidates above hop_threshold are carried forward, up to max_candidates.

Semantic edges — Because similarity rather than exact matching is used, edges like "works_at" will also match "employed_by" or "works_for" if they are semantically close — a capability not possible in traditional graph databases.

A schema is required — either stored in metadata from ingest, or provided via schema_json_data.

Responses¶

200 OK¶

{
  "status": "success",
  "query_type": "fuzzy_traverse",
  "start_value": "Alice",
  "start_slot": "subject",
  "path": ["works_at", "located_in"],
  "count": 2,
  "results": [
    {
      "_id": 42,
      "_score": 0.831,
      "data": {
        "subject":   "Acme Corp",
        "predicate": "located_in",
        "object":    "New York"
      }
    }
  ]
}

Field	Description
`start_value`	The starting node value
`start_slot`	The slot searched at the start
`path`	The edge sequence followed
`count`	Number of results returned
`results`	Final nodes reached, with `_id`, `_score`, and `data`

Error Responses¶

Status	Condition
`400`	No schema found, none provided, or invalid path
`404`	Collection not found
`500`	Unexpected internal error

Notes¶

Raise hop_threshold to require more confident edge matches at each hop; lower it to allow looser semantic traversal.
If traversal returns 0 results, try lowering hop_threshold or verifying the path values exist in the data.
Schema must be available — either stored from ingest or passed in schema_json_data.

Example¶

import requests

SERVER_URL = "http://18.220.128.24:8000"
API_KEY    = "yourapitoken"

def traverse_fuzzy(db_name: str, namespace: str, start_value: str, start_slot: str, path: list, top_k: int = 10) -> dict:
    response = requests.post(
        f"{SERVER_URL}/compose/traverse_fuzzy/{db_name}/{namespace}",
        headers={"X-API-Key": API_KEY},
        json={
            "start_value":    start_value,
            "start_slot":     start_slot,
            "path":           path,
            "hop_threshold":  0.5,
            "max_candidates": 100,
            "top_k":          top_k,
        },
    )
    response.raise_for_status()
    return response.json()


result = traverse_fuzzy(
    db_name="my_db",
    namespace="triples",
    start_value="Alice",
    start_slot="subject",
    path=["works_at", "located_in"],
    top_k=5,
)
print(result)

Expected output:

{
  "status": "success",
  "query_type": "fuzzy_traverse",
  "start_value": "Alice",
  "start_slot": "subject",
  "path": ["works_at", "located_in"],
  "count": 1,
  "results": [
    { "_id": 42, "_score": 0.831, "data": { "subject": "Acme Corp", "predicate": "located_in", "object": "New York" } }
  ]
}

POST /compose/traverse_fuzzy/{db_name}/{namespace}¶