Getting Started

This guide walks you through setting up Milvex and performing basic vector operations.

Prerequisites

Elixir 1.19 or later
A running Milvus instance (local or cloud)

Installation

Add milvex to your dependencies in mix.exs:

def deps do
  [
    {:milvex, "~> 0.1.0"}
  ]
end

Then fetch dependencies:

mix deps.get

Connecting to Milvus

Basic Connection

{:ok, conn} = Milvex.Connection.start_link(host: "localhost", port: 19530)

Named Connection

For use throughout your application, start a named connection:

{:ok, _} = Milvex.Connection.start_link([host: "localhost"], name: :milvus)

# Use the named connection
Milvex.search(:milvus, "collection", vectors, vector_field: "embedding")

Under a Supervisor

The recommended approach for production:

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      {Milvex.Connection, [host: "localhost", port: 19530, name: MyApp.Milvus]}
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

Connection Options

Milvex.Connection.start_link(
  host: "localhost",        # Milvus server hostname
  port: 19530,              # gRPC port (default: 19530, or 443 for SSL)
  database: "default",      # Database name
  user: "root",             # Username (optional)
  password: "milvus",       # Password (optional)
  token: "api_token",       # API token (alternative to user/password)
  ssl: true,                # Enable SSL/TLS
  ssl_options: [],          # SSL options for transport
  timeout: 30_000           # Connection timeout in ms
)

You can also use a URI:

{:ok, config} = Milvex.Config.parse_uri("https://user:pass@milvus.example.com:443/mydb")
{:ok, conn} = Milvex.Connection.start_link(config)

Creating a Collection

Define the Schema

Use the fluent builder API to define your collection schema:

alias Milvex.Schema
alias Milvex.Schema.Field

schema = Schema.build!(
  name: "movies",
  fields: [
    Field.primary_key("id", :int64, auto_id: true),
    Field.varchar("title", 512),
    Field.vector("embedding", 128)
  ],
  enable_dynamic_field: true
)

Create Collection and Index

alias Milvex.Index

# Create the collection
:ok = Milvex.create_collection(conn, "movies", schema)

# Create an HNSW index for vector search
index = Index.hnsw("embedding", :cosine, m: 16, ef_construction: 256)
:ok = Milvex.create_index(conn, "movies", index)

# Load collection into memory for searching
:ok = Milvex.load_collection(conn, "movies")

Inserting Data

Insert data as a list of maps:

{:ok, result} = Milvex.insert(conn, "movies", [
  %{title: "The Matrix", embedding: generate_embedding("The Matrix")},
  %{title: "Inception", embedding: generate_embedding("Inception")}
])

# result.ids contains the auto-generated IDs
IO.inspect(result.ids)

Searching Vectors

Perform similarity search:

query_vector = generate_embedding("science fiction action")

{:ok, results} = Milvex.search(conn, "movies", [query_vector],
  vector_field: "embedding",
  top_k: 10,
  output_fields: ["title"],
  filter: "title like \"The%\""
)

# Access results
for hit <- results.hits do
  IO.puts("#{hit.id}: #{hit.fields["title"]} (score: #{hit.score})")
end

Querying by Expression

Query records using filter expressions:

{:ok, results} = Milvex.query(conn, "movies", "id > 0",
  output_fields: ["id", "title"],
  limit: 100
)

Index Types

Choose the right index for your use case:

# HNSW - best for high recall with good performance
Index.hnsw("field", :cosine, m: 16, ef_construction: 256)

# IVF_FLAT - good balance for medium datasets
Index.ivf_flat("field", :l2, nlist: 1024)

# AUTOINDEX - let Milvus choose optimal settings
Index.autoindex("field", :ip)

# IVF_PQ - memory efficient for large datasets
Index.ivf_pq("field", :l2, nlist: 1024, m: 8, nbits: 8)

# DiskANN - for datasets that don't fit in memory
Index.diskann("field", :l2)

Supported metric types: :l2, :ip, :cosine, :hamming, :jaccard

Using Partitions

Organize data into partitions for efficient querying:

# Create partition
:ok = Milvex.create_partition(conn, "movies", "movies_2024")

# Insert into partition
{:ok, _} = Milvex.insert(conn, "movies", data, partition_name: "movies_2024")

# Search specific partitions
{:ok, _} = Milvex.search(conn, "movies", vectors,
  vector_field: "embedding",
  partition_names: ["movies_2024", "movies_2023"]
)

# Load/release partitions
:ok = Milvex.load_partitions(conn, "movies", ["movies_2024"])
:ok = Milvex.release_partitions(conn, "movies", ["movies_2024"])

Next Steps

Read the Architecture guide to understand how Milvex works internally
Learn about Error Handling patterns
Explore the Milvex module documentation for all available operations

Next Page → Architecture