HyperspaceDB Graph Operations

HyperspaceDB's HNSW index is a navigable graph — you can traverse it directly for knowledge graph exploration, ontology navigation, and multi-hop reasoning.

The Lorentz metric is specifically designed for hierarchical data: taxonomies, organizational charts, biological hierarchies, and knowledge bases.

1. Get Neighbors (Local Graph Connectivity)

Returns the nearest neighbors of a point in the HNSW graph — its direct connections.

const neighbors = await client.getNeighbors(
  pointId,      // number
  16,           // k — number of neighbors
  0,            // layer — HNSW layer (0 = most connected base layer)
  "my_collection"
);
// returns: Array<{ id: number, distance: number }>

Use case: Explore direct semantic relationships without doing a full ANN search.

2. Graph Traversal (Multi-hop BFS/DFS)

Traverse the knowledge graph starting from a node, following edges for N hops.

const result = await client.traverse(
  startId,    // starting node
  3,          // max hops
  "my_collection"
);
// returns visited node IDs and traversal paths

Use case: "What concepts are reachable from 'quantum entanglement' within 2 hops?"

3. Explore Graph (Visualization-ready)

Returns nodes and edges in a structured format ready for graph visualization (D3, Cytoscape, etc.).

const graph = await client.exploreGraph(
  startId,   // number
  2,         // max_depth
  256,       // max_nodes
  "my_collection"
);
// returns: { nodes: [{id, metadata}], edges: [{source, target, weight}] }

4. Subsumption Tree (Lorentz Hierarchy)

Retrieves the full hierarchical tree of concepts rooted at a given ID. Only meaningful for collections using the Lorentz metric.

const tree = await client.getSubsumptionTree(
  rootId,      // root concept ID
  3,           // max_depth
  "ontology_collection"
);

Use case: "Show me the complete taxonomy under the concept 'Mammal'."

5. Concept Parents

Retrieve the parent concepts of a node in the hierarchy.

const parents = await client.getConceptParents(
  conceptId,   // number
  0,           // HNSW layer
  32,          // max parents to return
  "ontology_collection"
);

Use case: "What is the parent category of 'Golden Retriever'?" → Dog → Canine → Mammal

6. Semantic Clusters

Detects emergent thematic regions within the vector space — unsupervised conceptual grouping.

const clusters = await client.findSemanticClusters(
  "my_collection",
  8           // number of clusters
);
// returns: Array<{ centroid: number[], member_ids: number[], label?: string }>

Use case: "What are the main topic clusters in this document corpus?"

Best Practices for Hierarchical Data

Setting Up a Lorentz Collection

import { CollectionSchema } from 'hyperspace-sdk-ts';

const schema: CollectionSchema = {
  components: [
    { name: "ontology", metric: "lorentz", fullDimension: 128, weight: 1.0 }
  ],
  cascadePipeline: [
    { componentName: "ontology", cutoffDimension: 128, storeInRam: true, rerankTopK: 64 }
  ]
};
await client.createCollection("knowledge_graph", schema);

Setting Up a Hybrid Collection (Hierarchy + Semantics)

Use hybrid when your data has both hierarchical structure and dense semantic content. The fixed layout is: 33 Lorentz dims (hierarchy) + N Euclidean dims (semantics).

// 33 Lorentz + 768 Euclidean = 801 total dimensions
const hybridSchema: CollectionSchema = {
  components: [
    { name: "hybrid", metric: "hybrid", fullDimension: 801, weight: 1.0 }
  ],
  cascadePipeline: [
    { componentName: "hybrid", cutoffDimension: 801, storeInRam: false, rerankTopK: 200 }
  ]
};
await client.createCollection("knowledge_with_semantics", hybridSchema);

Embedding Hierarchical Data

When inserting hierarchical data, use embeddings that preserve hyperbolic distance:

• Poincaré embeddings
• Lorentzian embeddings (e.g., from hyperspace-sdk-ts math utilities)
• Standard embeddings from models fine-tuned on ontological data

import { HyperbolicMath } from 'hyperspace-sdk-ts';

// Project a Euclidean embedding onto the Lorentz hyperboloid
const lorentzVector = HyperbolicMath.toLorentz(euclideanEmbedding);

// For hybrid: concatenate Lorentz (33d) + Euclidean (Nd)
const hybridVector = [...lorentzVector.slice(0, 33), ...semanticEmbedding];

Traversal vs. ANN Search

See Also

• hyperspacedb-core — CRUD and search operations
• hyperspacedb-cognitive — reasoning stability and momentum