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
- Declare a vector column with
Akter.Vectorand a search index withAkter.searchIndexinnotes.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 }),
}),
})- 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],
})- Insert rows with
Akter.db, and search them withAkter.searchinnotebook.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 })),
),
},
})- 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- 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 areadonly number[]as 32-bit floats.dimensionsis an integer literal from 1 to 4096, andquantizationis"int8"or"binary". OtherdimensionsthrowInvalidVectorError. - 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.
searchIndexesmaps each index name toAkter.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.
lexicallists one or more text columns.filterslists text, integer, or boolean columns.vectornames one vector column that is not nullable. A declaration that breaks a rule throwsInvalidSearchIndexError. - Search calls.
Akter.search(Table, index, { filters, limit, text, vector })takestextandvectorasOptionvalues, and at least one isSome.limitis 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
limithits, best first. ASearchHitholds the typedrow, the fusedscore, andlexicalRankandvectorRankasOptionvalues. - 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
SearchRefusedErrordefect 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.
InMemoryHostfrom@akterjs/effect/testingserves search.akterdanswers a search withunsupported, so the turn stops withSearchRefusedError.