Skip to content

Search

A search finds rows in one actor’s table by meaning, by words, or by both. Declare a search index on the table, then call Akter.search from a command, a query, or a job turn.

Declare a search index and search it⁠

  1. Declare a vector column with Akter.Vector and a search index with Akter.searchIndex in notes.table.ts.
notes.table.ts
import { Schema } from "effect"
import { Akter } from "@akterjs/effect/contract"

export const NotesTable = Akter.table("notes", {
  columns: {
    body: Schema.String,
    embedding: Akter.Vector({ dimensions: 2, quantization: "int8" }),
    id: Schema.String,
    shelf: Schema.String,
  },
  indexes: [],
  primaryKey: ["id"],
  searchIndexes: (columns) => ({
    notes_search: Akter.searchIndex({ filters: [columns.shelf], lexical: [columns.body], vector: columns.embedding }),
  }),
})
  1. Declare a command that stores a note and a query that searches the notes in notebook.contract.ts.
notebook.contract.ts
import { Schema } from "effect"
import { Akter } from "@akterjs/effect/contract"
import { NotesTable } from "./notes.table.ts"

export const Writer = Akter.caller("user", Schema.Struct({ id: Akter.PrincipalId }))

export const Open = Schema.TaggedStruct("Open", {})

export const Note = Schema.Struct({
  body: Schema.String,
  embedding: Schema.Array(Schema.Finite),
  id: Schema.String,
  shelf: Schema.String,
})

export const Find = Schema.Struct({
  shelves: Schema.Array(Schema.String),
  text: Schema.String,
  vector: Schema.Array(Schema.Finite),
})

export const Found = Schema.Struct({ id: Schema.String, lexicalRank: Schema.Option(Schema.Int), vectorRank: Schema.Option(Schema.Int) })

export const Notebook = Akter.make("Notebook", {
  callers: [Writer],
  commands: {
    jot: Akter.command({ callers: [Writer], errors: [], from: [Open], input: Note, output: Schema.Void, to: [Open] }),
  },
  initial: { input: Schema.Void, to: Open },
  key: Schema.String,
  parent: Akter.Root,
  queries: {
    find: Akter.query({ callers: [Writer], errors: [], input: Find, output: Schema.Array(Found), states: [Open] }),
  },
  states: [Open],
  tables: [NotesTable],
})
  1. Insert rows with Akter.db, and search them with Akter.search in notebook.actor.ts. The index ranks each inserted row, so no code maintains it.
notebook.actor.ts
import { Array, Effect, Option } from "effect"
import { Akter } from "@akterjs/effect/contract"
import { NotesTable } from "./notes.table.ts"
import { Notebook, Open } from "./notebook.contract.ts"

export const NotebookLive = Notebook.toLayer({
  commands: {
    jot: (notebook, note) =>
      Effect.as(
        Effect.flatMap(Akter.db, (db) => db.insert(NotesTable).values(note)),
        { next: notebook },
      ),
  },
  initial: () => ({ next: Open.make({}) }),
  queries: {
    find: (_notebook, { shelves, text, vector }) =>
      Effect.map(
        Akter.search(NotesTable, "notes_search", {
          filters: Array.isReadonlyArrayNonEmpty(shelves) ? [{ column: NotesTable.shelf, values: shelves }] : [],
          limit: 3,
          text: Option.some(text),
          vector: Option.some(vector),
        }),
        Array.map(({ lexicalRank, row, vectorRank }) => ({ id: row.id, lexicalRank, vectorRank })),
      ),
  },
})
  1. Run a search in notebook.story.ts. A filter narrows the rows before the ranking.
notebook.story.ts
import { Effect, Option } from "effect"
import { Akter } from "@akterjs/effect/contract"
import { Story } from "@akterjs/effect/testing"
import { Notebook, Writer } from "./notebook.contract.ts"
import { NotebookLive } from "./notebook.actor.ts"

const as = { caller: Writer, principal: { id: Akter.PrincipalId.make("ada") } }

const rank = (value: Option.Option<number>): string => Option.match(value, { onNone: () => "-", onSome: String })

const program = Story.run(NotebookLive, function* (story) {
  const notebook = yield* story.actor(Notebook, "kitchen", { as })
  yield* notebook.jot({ body: "aged goat cheese", embedding: [1, 0], id: "cheese", shelf: "dairy" })
  yield* notebook.jot({ body: "fresh goat milk", embedding: [0.6, 0.8], id: "milk", shelf: "dairy" })
  yield* notebook.jot({ body: "sourdough bread", embedding: [0.9, 0.1], id: "bread", shelf: "bakery" })

  const everywhere = yield* notebook.find({ shelves: [], text: "goat", vector: [1, 0] })
  const dairy = yield* notebook.find({ shelves: ["dairy"], text: "bread", vector: [1, 0] })

  for (const hit of [...everywhere, ...dairy]) {
    console.log(`${hit.id} text ${rank(hit.lexicalRank)} vector ${rank(hit.vectorRank)}`)
  }
})

Effect.runPromise(program)
Text
cheese text 1 vector 1
milk text 2 vector 3
bread text - vector 2
cheese text - vector 1
milk text - vector 2
  1. To compute embeddings, call your embedding model from a job, then store the vector through <Actor>.turn. Commands and queries make no network calls.

Search reference⁠

  • Vector columns. Akter.Vector({ dimensions, quantization }) stores a readonly number[] as 32-bit floats. dimensions is an integer literal from 1 to 4096, and quantization is "int8" or "binary". Other dimensions throw InvalidVectorError.
  • Vector values. A vector with another length, with all zeros, or with a value outside the 32-bit float range fails the column check.
  • Search indexes. searchIndexes maps each index name to Akter.searchIndex({ filters, lexical, vector }). A name matches ^[a-z][a-z0-9_]*$, has at most 32 bytes, and is unique within the actor.
  • Index columns. lexical lists one or more text columns. filters lists text, integer, or boolean columns. vector names one vector column that is not nullable. A declaration that breaks a rule throws InvalidSearchIndexError.
  • Search calls. Akter.search(Table, index, { filters, limit, text, vector }) takes text and vector as Option values, and at least one is Some. limit is a positive integer.
  • Filters. Each filter is { column, values } with a filter column of the index and one or more values. A row passes when its column equals one of the values, and it must pass every filter.
  • Hits. The search returns at most limit hits, best first. A SearchHit holds the typed row, the fused score, and lexicalRank and vectorRank as Option values.
  • Ranking. Text ranks by BM25, and vectors rank by similarity. Reciprocal rank fusion merges the two rankings, so a row that ranks high in both comes first. The ABI specification lists every rule.
  • Scope. A search reads only its own actor’s table, inside the turn. It sees the committed rows and the turn’s own writes, and never a rolled-back write.
  • Refusals. A search that the host refuses stops the turn with a SearchRefusedError defect that names the table, the index, and the reason.
  • Migrations. A new search index or a change of quantization rebuilds the index from the rows. The host refuses a change of a vector column’s dimensions. It also refuses a column that becomes a vector column or stops being one.
  • Hosts. InMemoryHost from @akterjs/effect/testing serves search. akterd answers a search with unsupported, so the turn stops with SearchRefusedError.