HarperFast / HarperFast/harper

Search-side automatic embedding for vector search (@embed counterpart)

Open
#1,277 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
JavaScript
Stars
89
Forks
10
Avg merge
2d 6h
Merged PRs (30d)
200

Description

`@embed` computes vectors automatically on the write side, but there is no search-side counterpart: querying an HNSW index requires the caller to produce the vector themselves (`models.embed(text, { inputType: 'query' })`) before calling `search`. Raised by @dawsontoth while reviewing the 5.1 models docs: HarperFast/documentation#523 (comment: https://github.com/HarperFast/documentation/pull/523#discussion_r3397221057).

## Sketch

Accept query text directly on the vector search descriptor and embed it with the attribute's configured `@embed` model before the index search, e.g.:

```javascript
Document.search({
sort: { attribute: 'embedding', text: 'what is harper?' },
});
```

- The attribute's `@embed(model: …)` declaration already names the right model; the search side would use it with `inputType: 'query'` (the write-side hook uses `'document'`), which matters for models with asymmetric document/query prefixes (e.g. nomic-embed-text).
- Same shape would apply to threshold conditions (`{ attribute, comparator: 'le', value, text }`).
- For attributes indexed HNSW without `@embed`, there is no model to infer — either reject, or accept an explicit `model` key on the descriptor.
- Ships in core alongside the existing `@embed`/search machinery (resources/models, resources/search.ts), consistent with #510's packaging.

Open questions: REST/operations-API exposure (the QUERY body path carries the descriptor through; `search_by_conditions` mapping would need the `text` key preserved), and whether embedding latency belongs inside the search call or should stay an explicit caller step for hot paths.

Related: #510 (models API), #1235 (5.1 GA readiness — listed there as a post-GA follow-up), HarperFast/documentation#523 (docs that surfaced the gap).

---

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.