`nexyron.semantic.search`

Generic Description

nexyron.semantic.search is the canonical semantic search procedure. It searches one unified semantic ANN index containing graph-node embeddings, graph-edge embeddings, abstractions, and abstraction artifacts in one call.

Simple example:

CALL nexyron.semantic.search({query: 'churn', k: 10, ef: 200})
YIELD result_kind, item_id, node_id, edge_id, source, name, score, text, metadata_json
RETURN result_kind, item_id, node_id, edge_id, source, name, score, text, metadata_json
ORDER BY score DESC

Consumer-Level Explanation

Use this procedure when a person searches for a concept in ordinary language.

The result can be a graph node, a graph edge, an abstraction-backed semantic item, or an artifact-backed semantic item. Callers do not need to guess which kind contains the answer before searching.

Assistant, Client semantic-search, wiki, and report surfaces use this procedure through the service-owned graph context retriever. That layer preserves the canonical procedure and cluster-routed read path, then adds bounded graph expansion, source references, observed-data snippets, score components, provenance, and temporal hints for UI and assistant evidence.

Conceptual Explanation

nexyron.semantic.search should be read as one named procedure contract in the broader Nexyron Cypher surface. The procedure call is not only a syntax hook: it defines what runtime state, projection, registry entry, or graph algorithm is being asked to operate, and it determines which output columns downstream YIELD, WITH, and RETURN stages can safely use.

More Detailed Explanation

The procedure embeds the query text once, searches the unified typed semantic index, and returns the best owner-level matches across all semantic item kinds. k is applied to the combined ranking, not independently per type.

The search step is ANN-backed. Nexyron does not treat a cold ANN index as an acceptable degraded mode: if semantic vectors are present but the HNSW structure is not hot, the procedure fails with a semantic ANN error rather than silently scanning vectors by brute force.

Output columns:

• result_kind: node, edge, abstract, or artifact
• item_id: stable semantic item id for abstraction and artifact results
• node_id: internal node id for node results
• edge_id: internal edge id for edge results
• source: source family such as graph_node, graph_edge, knowledge_abstraction, knowledge_assertion, knowledge_analysis_run, or knowledge_report
• name: display name when available
• score: cosine-similarity relevance score; higher is better
• text: indexed semantic text
• metadata_json: JSON metadata for the hit

Advanced Example

CALL nexyron.semantic.search({query: 'early churn risk', k: 20, ef: 200})
YIELD result_kind, item_id, node_id, edge_id, source, name, score, text, metadata_json
RETURN result_kind,
       name,
       score,
       text,
       node_id,
       edge_id,
       item_id,
       source,
       metadata_json
ORDER BY score DESC
LIMIT 20

Real Use Cases

• Search a knowledge-heavy database where useful content may be stored as abstractions, knowledge assertions, reports, analysis runs, or ordinary graph rows.
• Search an operational graph without knowing whether the best match is a node description, an edge description, or an extracted knowledge claim.
• Give assistants one retrieval tool that can cover graph context and source-grounded knowledge without branching across several procedure calls.
• Feed graph context retrieval for assistant, Client, wiki, and report evidence without introducing a separate vector database or a separate query language.

Real Limitations And Tradeoffs

• node_id is only populated for node hits, edge_id only for edge hits, and item_id only for abstraction or artifact hits. Query logic should branch on result_kind.
• Abstraction and artifact hits are registry-backed semantic items, not concrete LPG nodes. Use their metadata_json, item_id, and source fields rather than trying to MATCH them as graph nodes.
• Filtered procedures still exist for debugging specific slices, but normal UI, assistant, and documentation examples should use this unified procedure.
• If you need to join node and edge hits back to LPG entities in one Cypher query, branch the query explicitly. Do not chain separate OPTIONAL MATCH ... WHERE result_kind = ... clauses over the same row stream because each optional predicate can eliminate rows meant for the other kind.