Get started

This guide walks through adding a vector index, storing embeddings, and searching by similarity.

1. Declare an Index

Import vector from @layeron/modules and declare an index with a name and vector dimensions:

import { backend } from "@layeron/core"
import { vector } from "@layeron/modules"

const app = backend()

const docs = vector({
  name: "docs",
  dimensions: 768,
  metric: "cosine",
})

app.use(docs)

dimensions must match the embedding model that creates your vectors. metric defaults to cosine when omitted.

2. Store Vectors

Use upsert to add or replace vector records:

app.post("/api/vectors", async () => {
  const result = await docs.upsert({
    id: "guide_1#chunk_1",
    values: [0.01, 0.02, /* ... 768 values */],
    metadata: {
      title: "Getting Started Guide",
    },
  })

  return { count: result.count, ids: result.ids }
})

Each record needs an application-defined id, a values array that matches the index dimensions, and optional metadata.

3. Search by Similarity

Query the index with a vector to find the closest matches:

app.post("/api/search", async () => {
  const result = await docs.query({
    vector: [0.01, 0.02, /* ... 768 values */],
    topK: 10,
    returnMetadata: true,
  })

  return result.matches
})

Each match includes the vector id, a score, and metadata when requested.

4. Deploy

When you deploy with layeron deploy, Layeron creates a Cloudflare Vectorize index in your Cloudflare account and wires the Worker binding automatically.