Filtered Search

Sometimes you may want to cross-reference search results against some external database or filter them by some criteria. In most engines, you’d have to manually perform paging requests, successively filtering the results. In USearch you can pass a predicate to the search, which is applied during graph traversal.

void admits_tenant(usearch_key_t const* keys, usearch_admission_t* admissions, size_t count, void* state) {
    for (size_t i = 0; i != count; ++i)
        admissions[i] = keys[i].bytes[0] == *(uint8_t const*)state ? usearch_admit_k : usearch_reject_k;
}

uint8_t tenant = 7;
usearch_dense_search(&(usearch_dense_search_t) {.index = index,
                                                .executor = executor,
                                                .outcome = &outcome,
                                                .count = 1,
                                                .queries = {query, 0, 128, usearch_scalar_f32_k},
                                                .matches = &matches,
                                                .arena = arena,
                                                .wanted = 10,
                                                .predicate = {admits_tenant, &tenant}});

The predicate judges a batch of candidates per call, a quad of them at a time during a walk, so a handler backed by an external store answers each batch in one round trip.

Rejected entries still route the walk, so recall holds at low selectivity, and the predicate judges every scored candidate, concurrently on the executor’s threads, so it must be fast and tolerate that. An exact scan asks it only about entries closer than the worst match a query already holds, which makes the scan the fallback for predicates too selective for a walk to cross. A host predicate cannot narrow a device walk, so a VRAM search with one reports usearch_status_unsupported_k.

Long calls take a usearch_progress_t: a handler, which is also the only way to stop one, its state, and how many reports it hears:

usearch_continuation_t stop_when_asked(size_t completed, size_t total, void* state) {
    return *(int const*)state ? usearch_cancel_k : usearch_continue_k;
}

int stop = 0;
usearch_dense_search(&(usearch_dense_search_t) {
    .index = index, .executor = executor, .outcome = &outcome, .count = 1000000, .queries = queries,
    .wanted = 10, .arena = arena, .matches = &matches, .progress = {stop_when_asked, &stop, 20}});

Counts are in whatever units the verb consumes, entries for an insertion, queries for a search, shards for a checkpoint, and the handler is never called concurrently or after the call is final. A call reports at most steps times, the last at completion, and zero steps derive to ten. A batch verb hands its engine one slice per step, and a call without a handler runs as one slice, since every engine bounds its own scratch. A stopped call reports usearch_status_cancelled_k and leaves its outputs NULL. An insertion claims every entry before its first report, so its handler only reports, and all its entries publish at once.