Skip to main content

FindDescriptor

Find descriptor metadata, or nearest neighbors of one input vector. Requires objects.read permission.

Parameters​

Parameter

Type / required

Default and behavior

_ref

integer / optional

Omitted: do not retain a reference for later commands in this query.

with_class

string / optional

Omitted: all classes of this command’s object type. Otherwise restrict to that exact class before other filtering or top-k.

unique

Boolean / optional

false; require exactly one match when true.

constraints

expression / optional

Omitted: no property filter; other restrictions still apply.

is_connected_to

object / optional

Omitted: no graph-neighbor restriction.

is_endpoint_of

object / optional

Omitted: no connection-endpoint restriction.

group_by_source

Boolean / optional

false; group matches by the source of a relationship lookup.

per_group

Boolean / optional

false; true requires group_by_source: true and applies sort, offset and limit within each source group.

results

object / optional

Omitted: no requested property projection or aggregate. Select output or retain a reference as described below.

sort

string, object, or array / optional

Omitted: no explicit property ordering; nearest-neighbor commands have their own distance ordering.

limit

integer 0–2147483647 / optional

Omitted: no explicit result-count limit.

offset

integer 0–2147483647 / optional

0; skip this many matches after sorting.

uniqueids

Boolean / optional

false; include object identifiers when true.

Without k_neighbors, the command is a metadata lookup and consumes no input blob. With it, supply a positive k_neighbors (at most 2147483647), an explicit engine (Flat/IVF/HNSW/ACORN), and one finite float32 vector blob.

with_class optionally selects one descriptor class. Omitting it searches compatible class indexes. Its scope always applies before top-k, even with knn_first: true. See Descriptor classes and vector indexes for compatibility and global top-k behavior.

Additional options:

  • metric selects L2, IP or CS; omission selects the first common configured metric in that order.

  • knn_first defaults to false. True applies ordinary filters after the global top-k, potentially returning fewer matches.

  • filtered_knn defaults to false. True requires KNN and HNSW/ACORN and cannot combine with knn_first: true. ACORN uses its filtered search when applicable.

  • with_label restricts stored labels; labels: true projects them.

  • distances: true includes _distance with KNN.

  • blobs: true returns stored descriptor vectors as separate output blobs; it defaults to false.

The filtered_knn Boolean parameter enables filtered nearest-neighbor search for HNSW. It defaults to false. This traversal uses the HNSW graph to find neighbors that satisfy property, label, and relationship constraints. This can improve the performance of filtered searches. Neighbor selection is approximate, so the returned neighbors may differ from the default constrained search.

filtered_knn: true requires k_neighbors and an explicit engine: HNSW or engine: ACORN. It cannot be combined with knn_first: true. Descriptor and index changes share the graph transaction, including earlier writes in the same request. HNSW scans a small indexed matching subset exactly when its size is no greater than max(k_neighbors, effective efSearch). This fallback is automatic and uses the existing filtered_knn option. Larger subsets retain approximate graph traversal, which can return fewer than k_neighbors results despite enough matching descriptors.

For exact constrained search with HNSW, leave filtered_knn and knn_first false (their defaults). Without constraints, ordinary HNSW search is used.

The separate ACORN engine builds expanded, compressed graph links and automatically uses its filtered search. The filtered_knn flag is redundant for that engine; setting it to false does not disable filtered traversal. Its selective-subset fallback and settings are described in ACORN parameters.

For example, enable filtered HNSW search for up to four neighbors created since 2020:

[
{
"FindDescriptor": {
"engine": "HNSW",
"k_neighbors": 4,
"filtered_knn": true,
"constraints": [
"$year_created",
">=",
2020
],
"distances": true,
"results": {
"list": [
"year_created",
"description"
]
},
"with_class": "party_faces"
}
}
]

Pass the query descriptor in the array of blobs. FindDescriptorBatch accepts the same option and applies the constraints to each input descriptor’s neighbor search.

Results​

Single-vector KNN uses ascending L2 distance or descending IP/CS score, with a stable full-identity tie order. An explicit sort replaces presentation order. Offset and limit apply after the global neighbor selection. Index results merge the snapshot’s base and pending rows without returning superseded versions.

Projected rows include _class. Metadata lookup does not require a vector index. KNN over incompatible or populated unindexed classes fails. No matches is a successful empty result. See Responses for error envelopes.

[{
"FindDescriptor": {
"with_class": "party_faces",
"constraints": ["$year_created", ">=", 2020],
"blobs": true,
"results": {
"list": ["year_created", "description"]
}
}
}]

The metadata lookup above returns:

[{
"FindDescriptor": {
"blobs_start": 0,
"entities": [{
"_class": "party_faces",
"_blob_index": 0,
"description": "friends at a party",
"year_created": 2021
}],
"returned": 1,
"status": 0
}
}]

IVF nearest neighbors​

Supply one float32 vector blob with the following query.

[{
"FindDescriptor": {
"engine": "IVF",
"with_class": "party_faces",
"k_neighbors": 4,
"blobs": true,
"labels": true,
"distances": true,
"results": {
"list": ["year_created", "description"]
}
}
}]
[{
"FindDescriptor": {
"blobs_start": 0,
"entities": [{
"_class": "party_faces",
"_blob_index": 0,
"_distance": 1.0,
"_label": "Chaleb Zhen",
"description": "Picture of Chaleb Zhen",
"year_created": 2023
}, {
"_class": "party_faces",
"_blob_index": 1,
"_distance": 1.0,
"_label": "Emili Donna",
"description": "Picture of Emili Donna",
"year_created": 2023
}, {
"_class": "party_faces",
"_blob_index": 2,
"_distance": 2.0,
"_label": "Swarna Sonia",
"description": "Picture of Swarna Sonia",
"year_created": 2023
}, {
"_class": "party_faces",
"_blob_index": 3,
"_distance": 2.0,
"_label": "El Swarna",
"description": "Picture of El Swarna",
"year_created": 2023
}],
"returned": 4,
"status": 0
}
}]

HNSW nearest neighbors​

Supply one float32 vector blob with the following query.

[{
"FindDescriptor": {
"with_class": "party_faces",
"k_neighbors": 4,
"engine": "HNSW",
"blobs": true,
"labels": true,
"distances": true,
"results": {
"list": ["year_created", "description"]
}
}
}]
[{
"FindDescriptor": {
"blobs_start": 0,
"entities": [{
"_class": "party_faces",
"_blob_index": 0,
"_distance": 36.0,
"_label": "Harisha Balaram",
"description": "Picture of Harisha Balaram",
"year_created": 2023
}, {
"_class": "party_faces",
"_blob_index": 1,
"_distance": 49.0,
"_label": "Liidia Bertha",
"description": "Picture of Liidia Bertha",
"year_created": 2023
}, {
"_class": "party_faces",
"_blob_index": 2,
"_distance": 64.0,
"_label": "Emili Donna",
"description": "Picture of Emili Donna",
"year_created": 2023
}, {
"_class": "party_faces",
"_blob_index": 3,
"_distance": 81.0,
"_label": "Jockel Cecilie",
"description": "Picture of Jockel Cecilie",
"year_created": 2023
}],
"returned": 4,
"status": 0
}
}]