# `Arcana.Graph.GraphQuery`
[🔗](https://github.com/georgeguimaraes/arcana/blob/main/lib/arcana/graph/graph_query.ex#L1)

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"])

# `build_graph`

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`

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`

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`

Gets all chunks connected to a set of entities.

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

# `get_community_summaries`

Gets community summaries with optional filtering.

## Options

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

# `traverse`

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)

---

*Consult [api-reference.md](api-reference.md) for complete listing*