# Turbopuffer Quickstart
```elixir
Mix.install([
{:turbopuffer, "~> 0.1"},
{:req, "~> 0.4"},
{:kino, "~> 0.12"}
])
```
## Setup
Configure your Turbopuffer API key and create a client.
```elixir
# API tokens are created in the dashboard: https://turbopuffer.com/dashboard
api_key_input = Kino.Input.password("Turbopuffer API Key")
```
```elixir
api_key = Kino.Input.read(api_key_input)
# Pick the right region: https://turbopuffer.com/docs/regions
client =
Turbopuffer.new(
api_key: api_key,
region: :gcp_us_central1
)
namespace = Turbopuffer.namespace(client, "quickstart-example-ex")
```
## Embedding Generation
We'll create a helper function to generate embeddings using OpenAI or random vectors as fallback.
```elixir
openai_key_input = Kino.Input.password("OpenAI API Key (optional)")
```
```elixir
openai_api_key = Kino.Input.read(openai_key_input)
# Helper function to create embeddings with OpenAI, or use random vectors as fallback
create_embedding = fn text ->
if openai_api_key && openai_api_key != "" do
# Use OpenAI API to generate embeddings
case Req.post(
"https://api.openai.com/v1/embeddings",
json: %{
model: "text-embedding-3-small",
input: text
},
headers: [
{"authorization", "Bearer #{openai_api_key}"},
{"content-type", "application/json"}
]
) do
{:ok, %{status: 200, body: body}} ->
body["data"] |> List.first() |> Map.get("embedding")
_ ->
IO.puts("Failed to get OpenAI embedding, using random vectors")
# Generate random vector of dimension 1536 (text-embedding-3-small dimension)
for _ <- 1..1536, do: :rand.uniform()
end
else
IO.puts("OpenAI API key not set, using random vectors")
# For demo purposes, using smaller dimension when no API key
for _ <- 1..128, do: :rand.uniform()
end
end
```
## Write Documents with Schema Configuration
Insert documents with vectors and attributes, configuring the schema on first write.
```elixir
rows = [
%{
id: 1,
vector: create_embedding.("walrus narwhal"),
name: "foo",
public: 1,
text: "walrus narwhal"
},
%{
id: 2,
vector: create_embedding.("elephant walrus rhino"),
name: "foo",
public: 0,
text: "elephant walrus rhino"
},
%{
id: 3,
vector: create_embedding.("quick brown fox"),
name: "bar",
public: 1,
text: "quick brown fox"
}
]
```
```elixir
# Write documents with vectors and attributes
# Attributes can be provided either nested under "attributes" key or directly in the row
{:ok, _} =
Turbopuffer.write(
namespace,
upsert_rows: rows,
distance_metric: "cosine_distance",
schema: %{
"text" => %{
"type" => "string",
"full_text_search" => true
}
}
)
IO.puts("Documents written successfully with schema configuration!")
```
## Query Vectors
Query nearest neighbors with filters.
```elixir
query_vector = create_embedding.("walrus narwhal")
```
```elixir
# Query nearest neighbors with filter
{:ok, results} =
Turbopuffer.query(
namespace,
vector: query_vector,
top_k: 10,
filters: %{
"name" => "foo",
"public" => 1
},
include_attributes: ["name", "text"]
)
IO.puts("Vector search results:")
for result <- results do
dist = if result.dist, do: Float.round(result.dist, 4), else: "N/A"
IO.puts("ID: #{result.id}, Distance: #{dist}, Name: #{result.attributes["name"]}")
end
results
```
## Full-Text Search
Perform full-text search on the text attribute.
```elixir
# Full-text search on an attribute
{:ok, text_results} =
Turbopuffer.text_search(
namespace,
query: "quick walrus",
attribute: "text",
top_k: 10,
filters: %{"name" => "foo"}
)
IO.puts("Full-text search results:")
for result <- text_results do
score = if result.dist, do: Float.round(result.dist, 4), else: "N/A"
IO.puts("ID: #{result.id}, Score: #{score}, Text: #{result.attributes["text"]}")
end
text_results
```
## Hybrid Search
Combine vector and text search for better results.
```elixir
query_vector = create_embedding.("walrus")
```
```elixir
# Hybrid search combining vector and text
{:ok, hybrid_results} =
Turbopuffer.hybrid_search(
namespace,
vector: query_vector,
text_query: "walrus",
text_attribute: "text",
top_k: 10
)
IO.puts("Hybrid search results:")
for result <- hybrid_results do
score = if result.dist, do: Float.round(result.dist, 4), else: "N/A"
IO.puts("ID: #{result.id}, Score: #{score}")
end
hybrid_results
```
## Update Vectors
Update existing vectors by providing new data for existing IDs.
```elixir
rows = [
%{
id: 1,
vector: create_embedding.("updated content"),
name: "updated",
public: 1
}
]
```
```elixir
# Vectors can be updated by passing new data for an existing ID
# Attributes can be provided directly in the row
{:ok, _} =
Turbopuffer.write(namespace,
upsert_rows: rows,
distance_metric: "cosine_distance"
)
IO.puts("Vector 1 updated successfully!")
```
```elixir
query_vector = create_embedding.("updated")
```
```elixir
# Verify the update
{:ok, updated_results} =
Turbopuffer.query(
namespace,
vector: query_vector,
top_k: 10,
include_attributes: ["name", "text"]
)
IO.puts("\nVectors after update:")
for result <- updated_results do
name = result.attributes["name"] || "N/A"
IO.puts("ID: #{result.id}, Name: #{name}")
end
```
## Delete Vectors
Delete vectors by their IDs using the write function.
```elixir
# Vectors are deleted by ID
{:ok, _} = Turbopuffer.write(namespace,
deletes: [1, 3]
)
IO.puts("Vectors 1 and 3 deleted successfully!")
# Verify deletion
{:ok, remaining} = Turbopuffer.query(namespace,
vector: create_embedding.("test"),
top_k: 10,
include_attributes: ["name"]
)
if Enum.empty?(remaining) do
IO.puts("No vectors remaining")
else
remaining =
for vec <- remaining do
"ID: #{vec.id}, Name: #{vec.attributes["name"] || "N/A"}"
end
IO.puts("Remaining vectors: #{Enum.join(remaining, "\n")}")
end
```
## Clean Up
Optionally delete the namespace when done.
```elixir
# Uncomment to delete the namespace
{:ok, _} = Turbopuffer.delete_namespace(namespace)
IO.puts("Namespace deleted")
```
## Summary
This Livebook demonstrates:
1. **Vector Operations**: Writing and querying vectors with the Turbopuffer API
2. **Full-Text Search**: Using BM25 ranking for text search
3. **Hybrid Search**: Combining vector and text search using multi-query
4. **Filtering**: Applying metadata filters to queries
5. **Updates and Deletes**: Managing vector lifecycle with the write function
Key differences from the Python version:
* Uses Elixir's pattern matching and functional approach
* Results are returned as `Result` structs with fields: `id`, `dist`, `attributes`, `vector`
* All operations return `{:ok, result}` or `{:error, reason}` tuples
* Uses Kino for interactive inputs in Livebook
* Attributes can be provided either nested under an `attributes` key or directly in the row map
* Filters use simple map syntax: `%{"name" => "foo", "public" => 1}`
For more information, see:
* [Turbopuffer Documentation](https://turbopuffer.com/docs)
* [Hybrid Search Guide](https://turbopuffer.com/docs/hybrid-search)
* [API Reference](https://turbopuffer.com/docs/reference)
