FindDescriptorBatch

Find descriptors that satisfy the specified constraints.

With k_neighbors, the command searches for neighbors of one or more input descriptors. Without it, the command performs a metadata lookup.

Any authenticated user can run this command, including users without 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.
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.
batch	object / optional	Omitted: no distributed result batching.
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.

Parameter	Type / required	Default and behavior
set	string / optional	Omitted: no set restriction for metadata lookup. Required when k_neighbors is supplied; the named set must exist, including a set created earlier in the query.
n_descriptors	positive uint64 integer / optional	1; with k_neighbors, the single input blob contains this many consecutive descriptors. Validated as nonzero even without KNN; otherwise unused.
k_neighbors	positive uint64 integer / optional	Omitted: metadata-only lookup with no input blob. Supplied: request up to this many neighbors per input descriptor, requiring set and exactly one float32 input blob.
knn_first	boolean / optional	false; with KNN and filters, filter graph candidates before nearest-neighbor selection. True selects neighbors first and then filters them, potentially returning fewer matches. Unused without KNN.
acorn	boolean / optional	false; true requires k_neighbors and HNSW, and rejects knn_first:true or indexed_results_only:true. Uses approximate filtered search when filters exist; otherwise ordinary HNSW search.
engine	string: Flat, IVF, HNSW / optional	With KNN, omitted selects the first engine in the set definition; a supplied engine must be available in that set. Validated but unused for metadata-only queries.
metric	string: L2, IP, CS / optional	With KNN, omitted selects the first metric in the set definition; a supplied metric must be available in that set. Validated but unused for metadata-only queries.
labels	boolean / optional	false; true returns descriptor _label when present.
distances	boolean / optional	false; with KNN, true returns _distances pairs [input descriptor index, score] for each returned descriptor. Unused without KNN.
indexed_results_only	boolean / optional	false; with KNN, true restricts neighbors to indexed coverage and can exclude recently added descriptors. No usable index yields no neighbors. Unused without KNN; incompatible with acorn:true.
blobs	boolean / optional	false; true returns stored descriptor float32 vectors as separate output blobs. This is independent of the input blob required by k_neighbors.
with_label	string / optional	Omitted: no label restriction. Compare stored _label for equality in metadata and KNN searches.
sort	string, object, or array / optional	Omitted: for one input vector, KNN orders by score (L2 ascending, IP/CS descending); for multiple input vectors, no single score order is added. Explicit property/expression sorts use the shared sort grammar.

Details

For KNN, set names the DescriptorSet in which to search, and a missing set is an error. For metadata-only queries, set is an optional equality filter; a nonexistent name produces no matches.

The k_neighbors parameter specifies the number of nearest neighbors to find. It requires input descriptor data in the array of blobs and a set name that defines the search space.

The knn_first Boolean controls when constraints are applied. With the default false, constraints filter the descriptors before nearest-neighbor selection. With true, neighbor selection precedes filtering.

With constraints, the default search computes exact nearest neighbors among the matching descriptors. acorn: true enables approximate filtered search with HNSW.

Searches exclude descriptors deleted before the query began. Flat search is exact. HNSW and IVF searches are approximate and may return fewer than k_neighbors results. Descriptors added since the index was built are also considered unless indexed_results_only is true.

indexed_results_only restricts the search to descriptors already indexed and returns no descriptors when no index is available. It preserves the ordering selected by knn_first: with constraints and knn_first: false, exact search runs over matching indexed descriptors; with knn_first: true, constraints are applied after selecting indexed neighbors.

The acorn Boolean parameter enables ACORN filtered nearest-neighbor search when set to true. It defaults to false. ACORN 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.

acorn: true requires k_neighbors and the HNSW engine, selected either by engine or by the descriptor set’s default engine. It cannot be combined with knn_first: true or indexed_results_only: true. Matching descriptors that have not yet been indexed are still considered. Indexed search remains approximate even for small matching subsets. It can return fewer than k_neighbors results despite enough matching descriptors.

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

For example, enable ACORN when finding up to four neighbors created since 2020:

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

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.

If only one ref parameter is used in the is_connected_to array, the resulting objects obtained after traversing the given connection can be associated with their source objects by specifying the parameter group_by_source as true. The parameter is ignored if is_connected_to is absent. It is set to false by default.

Response and recovery

A successful command returns status: 0 and returned. Requested metadata appears in entities; a reference-only lookup can match objects without returning metadata. returned counts delivered objects or blobs, not every graph match. Use results.count to request a match count.

When blobs are returned, blobs_start identifies the first output blob. Where metadata accompanies blob data, _blob_index associates it with the query’s output blob array. See API Description for blob ordering.

With k_neighbors, supply exactly one input blob containing n_descriptors * dimensions finite float32 values, laid out as consecutive vectors. A size mismatch or NaN/infinite component fails with status: -1. No input blob is consumed without k_neighbors. Unlike most Find commands, this command permits a metadata lookup without an output selector.

The result combines the matching neighbors from all input vectors; one stored descriptor can serve several inputs. With distances: true, each entity’s _distances contains [input_index, score] pairs, using zero-based input indices. It is not a separate result array per input vector. For more than one input vector, use an explicit sort when a stable application-specific order is required.

A missing KNN set, unavailable engine/metric, or invalid ACORN combination returns status: -1. Approximate searches and post-filtering can return fewer than k_neighbors matches per input. KNN options such as engine, metric, knn_first, distances, and indexed_results_only have no search effect without k_neighbors; enum validation still applies.

Invalid parameters, undeclared or incorrectly typed references, and failed output validation return status: -1 with info. A violated unique: true expectation returns status: 3. A response that exceeds the configured message budget can return status: 4; reduce the result limit or requested data. See Responses for error envelopes and retry guidance.

Examples

Find up to four neighbors for each of two input descriptors and return their labels and distance scores.

[{
    "FindDescriptorBatch": {
        "set": "party_faces",
        "k_neighbors": 4,
        "n_descriptors": 2,
        "labels": true,
        "distances": true
    }
}]

Note: A blob must be passed together with the JSON Query. The blob is an array of 32-bit floating-point values representing the input query descriptors.

Example response:

[{
    "FindDescriptorBatch": {
        "entities": [{
            "_distances": [
                [0, 2.0],
                [1, 4.0]
            ],
            "_label": "Pilypas Bruno"
        }, {
            "_distances": [
                [0, 2.0],
                [1, 4.0]
            ],
            "_label": "Era Aivar"
        }, {
            "_distances": [
                [0, 2.0],
                [1, 2.0]
            ],
            "_label": "Radha Akash"
        }, {
            "_distances": [
                [0, 1.0],
                [1, 3.0]
            ],
            "_label": "Kwasi Publius"
        }, {
            "_distances": [
                [1, 2.0],
                [0, 4.0]
            ],
            "_label": "Broccomaglos Tyree"
        }, {
            "_distances": [
                [1, 2.0],
                [0, 4.0]
            ],
            "_label": "Gregoria Hine"
        }, {
            "_distances": [
                [1, 1.0],
                [0, 3.0]
            ],
            "_label": "Marjeta Pe\u0111a"
        }, {
            "_distances": [
                [0, 1.0],
                [1, 5.0]
            ],
            "_label": "Harisha Balaram"
        }],
        "returned": 8,
        "status": 0
    }
}]