---
title: `nexyron.semantic.search`
url: https://nexyron.tech/docs/cypher/procedures/semantic/nexyron-semantic-search
description: nexyron.semantic.search is the canonical semantic search procedure. It searches one unified semantic ANN index containing graph node embeddings, graph edge embeddings, abstraction
---

# `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:

```cypher
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

```cypher
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.