ExTypesense

Typesense client for Elixir. Collections, documents, search, bulk import, multi-search, and synonyms.

Built for and extracted from Shiko, where we use Typesense to power instant search across patients, owners, inventory, and clinics.

Installation

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

Configuration

# config/config.exs
config :ex_typesense,
  url: "http://localhost:8108",
  api_key: "your-api-key"

# If you already have a Finch instance, pass its name:
config :ex_typesense,
  url: "http://localhost:8108",
  api_key: "your-api-key",
  finch_name: MyApp.Finch

If you don't set :finch_name, the client expects ExTypesense.Finch to be started in your supervision tree:

# application.ex
children = [
  {Finch, name: ExTypesense.Finch}
]

Usage

Collections

# Create
ExTypesense.create_collection(%{
  "name" => "products",
  "fields" => [
    %{"name" => "name", "type" => "string", "sort" => true},
    %{"name" => "price", "type" => "float"},
    %{"name" => "category", "type" => "string", "facet" => true}
  ],
  "default_sorting_field" => "price"
})

# Ensure exists (idempotent)
ExTypesense.ensure_collection(schema)

# Drop and recreate
ExTypesense.recreate_collection(schema)

# List all
ExTypesense.list_collections()

Documents

# Upsert (create or update)
ExTypesense.upsert_document("products", %{"id" => "1", "name" => "Widget", "price" => 9.99})

# Get by ID
ExTypesense.get_document("products", "1")

# Delete
ExTypesense.delete_document("products", "1")

# Bulk import (JSONL, fast)
docs = [%{"id" => "1", "name" => "A"}, %{"id" => "2", "name" => "B"}]
ExTypesense.bulk_import("products", docs, action: "upsert")

Search

# Basic search
ExTypesense.search("products", "widget", query_by: "name")

# With filters and pagination
ExTypesense.search("products", "widget",
  query_by: "name,description",
  filter_by: "category:=electronics",
  sort_by: "price:asc",
  per_page: 10,
  num_typos: 2
)

# Multi-search (one HTTP call, multiple collections)
ExTypesense.multi_search([
  %{collection: "products", q: "widget", query_by: "name"},
  %{collection: "users", q: "john", query_by: "name,email"}
])

Synonyms

ExTypesense.upsert_synonym("products", "color-synonyms", ["red", "crimson", "scarlet"])
ExTypesense.list_synonyms("products")
ExTypesense.delete_synonym("products", "color-synonyms")

Health check

ExTypesense.health()
#=> {:ok, %{"ok" => true}}

License

MIT