Filtered Search

A Predicate in the search config admits only the keys it approves, and non-matching entries still route the traversal, so recall does not collapse at low selectivity. Predicate.of takes a comptime function rather than a closure, so the trampoline that crosses the boundary is generated per call site and nothing is boxed. Its context travels as one pointer: pass {} for a predicate needing none, and a single-item pointer otherwise.

const admits = struct {
    fn call(_: void, key: usearch.Key) usearch.Admission {
        const value = key.asInteger() orelse return .reject;
        return if (value % 2 == 0) .admit else .reject;
}
}.call;

const even = try index.on(executor).search(try .of(f32, queries, 768), 10, &arena, .{
    .predicate = .of({}, admits),
});

It runs once per scored candidate, far more often than the “k” asked for, and concurrently from the executor’s threads, so it belongs on your fast path and must tolerate that. A VRAM index refuses a predicate with Error.Device, since a host callback cannot narrow a device walk.

Every long verb, namely insert, refine, search, absorb, multiply, attend, maxsim, save, saveBuffer and every load, takes a ProgressCallback in its config, called with the units finished so far and the units the call finishes if it runs to the end. Answering .cancel stops the call at the next increment boundary, except an insert, which ignores it.

const Deadline = struct {
    io: std.Io,
    stop_at: i64,
    fn reached(self: *const @This(), _: usize, _: usize) usearch.Continuation {
        const now = std.Io.Clock.awake.now(self.io).toMilliseconds();
        return if (now < self.stop_at) .@"continue" else .cancel;
}
};

const deadline: Deadline = .{ .io = io, .stop_at = std.Io.Clock.awake.now(io).toMilliseconds() + 30_000 };
_ = try index.on(executor).refine(.{
    .expansion_factor = 128,
    .progress = .of(&deadline, Deadline.reached),
});

Like a predicate, the handler is a comptime function whose trampoline is generated per call site, and its context travels as one pointer, {} where none is needed. It arrives on whichever thread advanced the work and never on two at once, so a counter or a deadline needs no synchronization of its own. Reports are denominated in whatever the verb consumes, such as entries for an insertion, queries for a search, donors for an absorb and shards for a checkpoint, and how often they arrive is the increment’s size rather than a guarantee, so read the counts and never the number of calls.

An insert cannot be stopped: it claims every entry before its first report and publishes the whole batch at once, so a batch is all-or-nothing with or without a handler. A stopped refine is not a failure but the time budget a whole-graph sweep is meant to run under: re-selection claims no identity, so the graph stays correct and merely less improved, and the next call sweeps again, so calling under a time budget still converges.