Arcana.Graph.GraphQuery (Arcana v1.3.3)

View Source

Queries the knowledge graph for entities, relationships, and community summaries.

This module provides efficient graph traversal and lookup operations for GraphRAG workflows. It works with in-memory graph structures built from entities, relationships, chunks, and community summaries.

Graph Structure

The graph is represented as a map with indexed lookups for efficient querying:

%{
  entities: %{id => entity},
  relationships: [relationship],
  chunks: [chunk],
  communities: [community],
  adjacency: %{entity_id => [neighbor_ids]},
  entity_chunks: %{entity_id => [chunk_ids]}
}

Example

graph = GraphQuery.build_graph(entities, relationships, chunks, communities)

# Find entities by name
GraphQuery.find_entities_by_name(graph, "OpenAI")

# Traverse the graph
GraphQuery.traverse(graph, "entity_id", depth: 2)

# Get relevant chunks
GraphQuery.get_chunks_for_entities(graph, ["id1", "id2"])

Summary

Functions

build_graph(entities, relationships, chunks, communities)

Builds a graph structure from entities, relationships, chunks, and communities.

find_entities_by_embedding(graph, query_embedding, opts \\ [])

Finds entities similar to a query embedding using cosine similarity.

find_entities_by_name(graph, query, opts \\ [])

Finds entities by name with optional fuzzy matching.

get_chunks_for_entities(graph, entity_ids)

Gets all chunks connected to a set of entities.

get_community_summaries(graph, opts \\ [])

Gets community summaries with optional filtering.

traverse(graph, entity_id, opts \\ [])

Traverses the graph from a starting entity up to the specified depth.

Functions

build_graph(entities, relationships, chunks, communities)

Builds a graph structure from entities, relationships, chunks, and communities.

Creates indexed lookups for efficient querying:

  • Entity lookup by ID
  • Adjacency list for graph traversal
  • Entity-to-chunk mapping for retrieval

find_entities_by_embedding(graph, query_embedding, opts \\ [])

Finds entities similar to a query embedding using cosine similarity.

Options

  • :top_k - Maximum number of results to return (default: 10)
  • :min_similarity - Minimum cosine similarity threshold (default: 0.0)

find_entities_by_name(graph, query, opts \\ [])

Finds entities by name with optional fuzzy matching.

Options

  • :fuzzy - When true, matches if entity name contains the query (default: false)

Examples

# Exact match (case-insensitive)
GraphQuery.find_entities_by_name(graph, "OpenAI")

# Fuzzy match
GraphQuery.find_entities_by_name(graph, "Open", fuzzy: true)

get_chunks_for_entities(graph, entity_ids)

Gets all chunks connected to a set of entities.

Returns unique chunks that contain at least one of the specified entities.

get_community_summaries(graph, opts \\ [])

Gets community summaries with optional filtering.

Options

  • :level - Filter by hierarchy level
  • :entity_id - Filter by communities containing a specific entity

traverse(graph, entity_id, opts \\ [])

Traverses the graph from a starting entity up to the specified depth.

Returns all entities reachable within the given number of hops. Does not include the starting entity in results.

Options

  • :depth - Maximum traversal depth (default: 1)