HarperFast / HarperFast/harper

SQL: "Circular reference" when selecting $distance from a vector LIKE query

Open
#777 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
89
Forks
10
Avg merge
2d 6h
Merged PRs (30d)
200

Description

## Bug

The Operations API SQL endpoint can't serialize a row that includes `$distance` after an HNSW vector search:

```bash
$ curl --unix-socket /…/operations-server -X POST http://localhost/ \
-H 'Content-Type: application/json' \
-d '{
"operation": "sql",
"sql": "SELECT name, $distance FROM data.Celebrity WHERE embedding LIKE (SELECT embedding FROM data.Celebrity WHERE id = '\''Tom Hanks'\'') LIMIT 5"
}'

{"error":"Circular reference"}
```

The same query via the Resource API works perfectly:

```js
const iter = tables.Celebrity.search({
conditions: { attribute: 'embedding', comparator: 'lt', value: 2, target: queryVector },
limit: 5,
select: ['name', '$distance'],
});
for await (const r of iter) console.log(r);
// → { name: 'Jon Stewart', $distance: 0.3254708... }
```

So the search itself is fine; the issue is the SQL → JSON serializer running into a cycle when materializing the row that carries the `$distance` metadata.

## Expected

`SELECT name, $distance FROM table WHERE embedding LIKE (…) LIMIT N` should return rows with `name` and `$distance` populated, matching the resource-API output.

## Repro

Any table with an HNSW `embedding` column and a few rows. Mine is the harper-celebrity-match demo (193 rows of CLIP-vit-large-patch14 embeddings, dim 768).

Tested against harper-pro 5.1.0 on harper 5.x (whatever ships in `harperfast/harper-pro-gpu:5.1.100`).

## Severity

Low — the resource-API path works, so users with a custom resource component aren't blocked. But SQL is the discovery path for most "let me see what's in the table" debugging, and getting `"Circular reference"` instead of useful output is a bad first impression for users prototyping vector search.

## Related

- harper#775 (vector search ergonomics) — found this while updating that issue with the V2 benchmark.

## Found in

`harper-celebrity-match`, running on `ada-4000-medium.harper-gpu-testing.harperfabric.com`.

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.