FindDescriptor

Find descriptors that satisfy the specified constraints.

Nearest-neighbor search requires k_neighbors, set, and one descriptor in the array of blobs. Without k_neighbors, this is a metadata lookup and takes no input blob.

Requires an authenticated user with objects.read permission. See API Description for query and blob ordering, and Responses for response fields and errors.

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 / conditional	Required for nearest-neighbor search; omitted for an unrestricted metadata lookup.
k_neighbors	positive integer / optional	Omitted: metadata lookup. Present: requires `set` and one input vector blob.
knn_first	Boolean / optional	`false`; filter before nearest-neighbor selection.
acorn	Boolean / optional	`false`; approximate filtered HNSW search, with restrictions below.
engine	string / optional	Descriptor set default when omitted; engine must be available for that set.
metric	string / optional	Descriptor set default when omitted; see supported distance metrics.
labels	Boolean / optional	`false`; include `_label` when true.
distances	Boolean / optional	`false`; include `_distance` for nearest-neighbor results.
blobs	Boolean / optional	`false`; include returned vectors in the separate blob list.
with_label	string / optional	Omitted: no label restriction.
indexed_results_only	Boolean / optional	`false`; true excludes descriptors not yet covered by an index.

Details

The set parameter specifies the “name” of the DescriptorSet in which the k-nearest neighbor computation will be performed. If DescriptorSet with that “name” does not exist, an error is returned.

labels: true adds _label to the returned descriptor metadata.

distances: true adds the nearest-neighbor score as _distance. L2 scores are squared Euclidean distances (smaller means closer). IP and CS scores increase with similarity.

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.

When several eligible descriptors have exactly the same distance at the k_neighbors boundary, exact search may select any of those tied descriptors. The selected IDs can change after deletion, reinsertion, or index rebuilding. This does not change the distances, the eligible result count, or inclusion of strictly closer descriptors.

Search results exclude deleted descriptors. Flat search remains exact; HNSW and IVF use their configured approximate search parameters and may return fewer than k_neighbors results. Newly added descriptors 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.

Input, response, and recovery

k_neighbors is a positive integer. When present it requires set and exactly one input blob containing the set’s number of 32-bit floating-point values; see AddDescriptor. Otherwise the command consumes no blob. labels, distances, blobs, knn_first, acorn, and indexed_results_only are optional Booleans, all defaulting to false. set, with_label, engine, and metric are strings; omitted engine and metric use the descriptor set’s defaults.

Successful responses contain status and returned. Requested metadata and labels appear in entities; distances: true adds _distance for nearest-neighbor search. Returned vectors are separate blobs, located using blobs_start and each entity’s _blob_index.

status: -1 with DescriptorSet '<name>' Not Found! means the set must be created or its name corrected. A blob with the wrong dimensions also fails.
status: -1 with acorn requires the HNSW engine requires selecting an HNSW engine configured for that set. acorn also rejects knn_first: true and indexed_results_only: true.
status: 4 means returned vectors exceed the response budget; reduce limit or k_neighbors, or omit returned vectors.

See AddDescriptorSet, AddDescriptor, and Responses.

Examples

Find the descriptors that belong to the DescriptorSet named “party_faces”, where “year_created” is 2020 or later, retrieve the “year_created” and “description” properties of those descriptors, and also retrieve the Descriptor values:

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

Successful response:

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

Find the 4 nearest-neighbors of a given descriptor, retrieve the “year_created” and “description” properties of those descriptors, and also retrieve the “label” associated with the descriptor and the “distances” of the k-nn computation.

A blob must be passed together with the JSON Query. The blob is an array of 32-bit floating point values representing the query descriptor. See the AddDescriptor command for more details on the blob format.

[{
    "FindDescriptor": {
        "set": "party_faces",
        "k_neighbors": 4,
        "blobs": true,
        "labels": true,
        "distances": true,
        "results": {
            "list": ["year_created", "description"]
        }
    }
}]

Example response:

[{
    "FindDescriptor": {
        "blobs_start": 0,
        "entities": [{
            "_blob_index": 0,
            "_distance": 1.0,
            "_label": "Chaleb Zhen",
            "description": "Picture of Chaleb Zhen",
            "year_created": 2023
        }, {
            "_blob_index": 1,
            "_distance": 1.0,
            "_label": "Emili Donna",
            "description": "Picture of Emili Donna",
            "year_created": 2023
        }, {
            "_blob_index": 2,
            "_distance": 2.0,
            "_label": "Swarna Sonia",
            "description": "Picture of Swarna Sonia",
            "year_created": 2023
        }, {
            "_blob_index": 3,
            "_distance": 2.0,
            "_label": "El Swarna",
            "description": "Picture of El Swarna",
            "year_created": 2023
        }],
        "returned": 4,
        "status": 0
    }
}]

Find the 4 nearest-neighbors of the given descriptors, retrieve the “year_created” and “description” properties of those descriptors, and also retrieve the “label” associated with the descriptor and the “distances” of the k-nn computations, using the approximate engine “HNSW”.

[{
    "FindDescriptor": {
        "set": "party_faces",
        "k_neighbors": 4,
        "engine": "HNSW",
        "blobs": true,
        "labels": true,
        "distances": true,
        "results": {
            "list": ["year_created", "description"]
        }
    }
}]

Example response:

[{
    "FindDescriptor": {
        "blobs_start": 0,
        "entities": [{
            "_blob_index": 0,
            "_distance": 1.0,
            "_label": "Chaleb Zhen",
            "description": "Picture of Chaleb Zhen",
            "year_created": 2023
        }, {
            "_blob_index": 1,
            "_distance": 1.0,
            "_label": "Emili Donna",
            "description": "Picture of Emili Donna",
            "year_created": 2023
        }, {
            "_blob_index": 2,
            "_distance": 2.0,
            "_label": "Swarna Sonia",
            "description": "Picture of Swarna Sonia",
            "year_created": 2023
        }, {
            "_blob_index": 3,
            "_distance": 2.0,
            "_label": "El Swarna",
            "description": "Picture of El Swarna",
            "year_created": 2023
        }],
        "returned": 4,
        "status": 0
    }
}]

Parameters​

Details​

Input, response, and recovery​

Examples​

Parameters

Details

Input, response, and recovery

Examples