Quickstart

Get from zero to a working RAG application with this complete tutorial. You’ll ingest documents, search for relevant content, and ask questions powered by AI.

Prerequisites

Elixir 1.14+ and Phoenix 1.7+
PostgreSQL running with pgvector extension
OpenAI API key (or use local embeddings)

If you haven’t installed Arcana yet, follow the Installation Guide first.

Complete Working Example

This tutorial walks through building a simple RAG system for Elixir documentation. Copy and run each step in your IEx session.

Start your application

Open an IEx session with your Phoenix app:

iex -S mix

Ingest some documents

Add content to your vector store. We’ll ingest a few facts about Elixir:

# Ingest documents about Elixir
{:ok, doc1} = Arcana.ingest(
  "Elixir is a dynamic, functional programming language designed for building scalable and maintainable applications. It runs on the Erlang VM (BEAM), which is known for creating low-latency, distributed, and fault-tolerant systems.",
  repo: MyApp.Repo,
  metadata: %{"topic" => "basics", "source" => "elixir-lang.org"},
  collection: "elixir-docs"
)

{:ok, doc2} = Arcana.ingest(
  "Phoenix is a web framework written in Elixir that enables building rich, interactive web applications with server-side rendering, real-time features using LiveView, and excellent performance.",
  repo: MyApp.Repo,
  metadata: %{"topic" => "phoenix", "source" => "phoenixframework.org"},
  collection: "elixir-docs"
)

{:ok, doc3} = Arcana.ingest(
  "OTP (Open Telecom Platform) is a set of libraries and design principles for building concurrent, distributed systems in Erlang and Elixir. GenServer is the most commonly used OTP behavior for implementing server processes.",
  repo: MyApp.Repo,
  metadata: %{"topic" => "otp", "source" => "elixir-lang.org"},
  collection: "elixir-docs"
)

Behind the scenes, Arcana is chunking the text, generating embeddings, and storing them in PostgreSQL with pgvector.

Search for relevant content

Now search for content using semantic similarity:

# Semantic search - finds content by meaning
{:ok, results} = Arcana.search(
  "What is Phoenix used for?",
  repo: MyApp.Repo,
  limit: 3
)

# Inspect the results
Enum.each(results, fn chunk ->
  IO.puts("Score: #{chunk.similarity}")
  IO.puts("Text: #{chunk.text}\n")
end)

Expected output:

Score: 0.89
Text: Phoenix is a web framework written in Elixir that enables building rich, interactive web applications...

Score: 0.72
Text: Elixir is a dynamic, functional programming language designed for building scalable...

Ask a question

Use RAG to answer questions based on your documents:

# Configure your LLM (requires OPENAI_API_KEY environment variable)
{:ok, answer} = Arcana.ask(
  "What is Phoenix and what can I build with it?",
  repo: MyApp.Repo,
  llm: "openai:gpt-4o-mini"
)

IO.puts(answer)

Expected output:

Phoenix is a web framework written in Elixir that enables you to build rich, 
interactive web applications. You can create applications with server-side 
rendering, add real-time features using LiveView, and benefit from excellent 
performance characteristics.

The ask/2 function retrieves relevant chunks via semantic search, then sends them to the LLM as context for generating the answer.

Try Different Search Modes

Arcana supports multiple search strategies. Here’s how they compare:

Semantic Search
Full-Text Search
Hybrid Search

Best for natural language and conceptual queries:

{:ok, results} = Arcana.search(
  "building fault-tolerant systems",
  repo: MyApp.Repo,
  mode: :semantic  # This is the default
)

Finds content by meaning, not just keywords. Great for “What is X?” or “How do I Y?” questions.

Best for exact keyword matches:

{:ok, results} = Arcana.search(
  "GenServer",
  repo: MyApp.Repo,
  mode: :fulltext
)

Finds exact keyword matches. Perfect for searching specific terms, function names, or code snippets.

Best of both worlds - combines semantic and keyword matching:

{:ok, results} = Arcana.search(
  "Phoenix LiveView real-time",
  repo: MyApp.Repo,
  mode: :hybrid
)

Uses Reciprocal Rank Fusion to combine vector similarity and full-text results. Recommended for general-purpose search.

Add More Advanced Features

Filter by Collection

Organize documents into collections for better routing:

# Search only in specific collection
{:ok, results} = Arcana.search(
  "web framework",
  repo: MyApp.Repo,
  collection: "elixir-docs"
)

Set Similarity Threshold

Filter out low-quality matches:

# Only return results with similarity > 0.7
{:ok, results} = Arcana.search(
  "distributed systems",
  repo: MyApp.Repo,
  threshold: 0.7,
  limit: 5
)

Ingest Files

Load content from text, markdown, or PDF files:

# Supports .txt, .md, .pdf
{:ok, document} = Arcana.ingest_file(
  "path/to/elixir-guide.pdf",
  repo: MyApp.Repo,
  collection: "elixir-docs",
  metadata: %{"type" => "guide"}
)

Complete End-to-End Example

Here’s a complete working script you can save and run:

complete_example.exs

# Start with a clean slate (optional - deletes existing documents)
# Arcana.Document |> MyApp.Repo.delete_all()

# Ingest a small knowledge base
documents = [
  {"Elixir is a functional language that runs on the BEAM VM, known for concurrency and fault tolerance.", "elixir-basics"},
  {"Phoenix Framework enables building real-time web applications with LiveView and channels.", "phoenix-intro"},
  {"GenServer is an OTP behavior for implementing server processes that maintain state.", "otp-genserver"},
  {"Ecto is the database wrapper for Elixir, providing schemas, queries, and migrations.", "ecto-intro"}
]

Enum.each(documents, fn {text, source} ->
  {:ok, _doc} = Arcana.ingest(
    text,
    repo: MyApp.Repo,
    collection: "elixir-docs",
    metadata: %{"source" => source}
  )
  IO.puts("✓ Ingested: #{source}")
end)

# Search for relevant content
IO.puts("\n=== Semantic Search Results ===")
{:ok, search_results} = Arcana.search(
  "How do I build real-time web apps?",
  repo: MyApp.Repo,
  limit: 2
)

Enum.each(search_results, fn chunk ->
  IO.puts("Score: #{Float.round(chunk.similarity, 2)} | #{String.slice(chunk.text, 0..80)}...")
end)

# Ask a question with RAG
IO.puts("\n=== RAG Answer ===")
{:ok, answer} = Arcana.ask(
  "What is Phoenix Framework and what are its main features?",
  repo: MyApp.Repo,
  llm: "openai:gpt-4o-mini"
)

IO.puts(answer)

Run it with:

mix run complete_example.exs

Using Local Embeddings

Don’t want to use OpenAI? Use local embeddings instead:

Configure local embeddings

config/config.exs

# Use local Bumblebee embeddings (no API keys needed)
config :arcana, embedder: :local

# Configure Nx backend
config :nx,
  default_backend: EXLA.Backend,
  default_defn_options: [compiler: EXLA]

Add to supervision tree

lib/my_app/application.ex

def start(_type, _args) do
  children = [
    MyApp.Repo,
    Arcana.Embedder.Local  # Start local embedder
  ]
  
  opts = [strategy: :one_for_one, name: MyApp.Supervisor]
  Supervisor.start_link(children, opts)
end

Use local LLM (optional)

For a completely local setup, use a local LLM:

# With Ollama running locally
local_llm = fn prompt ->
  case Req.post("http://localhost:11434/api/generate",
    json: %{model: "llama2", prompt: prompt}) do
    {:ok, %{body: %{"response" => response}}} ->
      {:ok, response}
    error ->
      error
  end
end

{:ok, answer} = Arcana.ask(
  "What is Elixir?",
  repo: MyApp.Repo,
  llm: local_llm
)

Next Steps

Agentic RAG

Build multi-step RAG pipelines with query expansion and re-ranking

GraphRAG

Extract entities and relationships for knowledge graph search

Search Algorithms

Deep dive into semantic, full-text, and hybrid search

Dashboard

Use the LiveView UI to manage documents and test queries

Common Issues

Search returns no results

Check that documents were ingested successfully:

# Count documents
MyApp.Repo.aggregate(Arcana.Document, :count)

# Count chunks
MyApp.Repo.aggregate(Arcana.Chunk, :count)

Lower the similarity threshold:

{:ok, results} = Arcana.search(
  "your query",
  repo: MyApp.Repo,
  threshold: 0.5  # Lower threshold
)

OpenAI API errors

Make sure your API key is set:

export OPENAI_API_KEY="sk-..."

Verify it’s accessible:

System.get_env("OPENAI_API_KEY")

Or pass the LLM configuration explicitly:

{:ok, answer} = Arcana.ask(
  "question",
  repo: MyApp.Repo,
  llm: "openai:gpt-4o-mini"
)

Slow first-time embedding

Local embeddings download models on first use (~133MB for default model). This is a one-time download:

Default (BGE Small): 133MB
BGE Base: 438MB
BGE Large: 1.3GB

Subsequent runs use cached models.For faster startup, use OpenAI embeddings instead:

config :arcana, embedder: :openai

Getting Started

Core Concepts

Guides

Configuration

Prerequisites

Complete Working Example

Try Different Search Modes

Add More Advanced Features

Filter by Collection

Set Similarity Threshold

Ingest Files

Complete End-to-End Example

Using Local Embeddings

Next Steps

Agentic RAG

GraphRAG

Search Algorithms

Dashboard

Common Issues

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Configuration

​Prerequisites

​Complete Working Example

​Try Different Search Modes

​Add More Advanced Features

​Filter by Collection

​Set Similarity Threshold

​Ingest Files

​Complete End-to-End Example

​Using Local Embeddings

​Next Steps

Agentic RAG

GraphRAG

Search Algorithms

Dashboard

​Common Issues

Build docs developers (and LLMs) love

Prerequisites

Complete Working Example

Try Different Search Modes

Add More Advanced Features

Filter by Collection

Set Similarity Threshold

Ingest Files

Complete End-to-End Example

Using Local Embeddings

Next Steps

Common Issues