FindDescriptor

Find descriptors that satisfy the specified constraints.

If a descriptor is provided in the array of blobs, a k-nearest neighbor search is computed.

Parameters

• [optional] _ref: Reference to be used within the transaction.
• [optional] unique: Indicates whether a single object is expected to satisfy the constraints.
• [optional] constraints
• [optional] is_connected_to
• [optional] is_endpoint_of
• [optional] group_by_source
• [optional] results
• [optional] batch
• [optional] sort
• [optional] limit
• [optional] offset
• [optional] uniqueids: indicates whether unique ids will be returned as part of the response (Default: false).

• [optional] set: Name of the set.
• [optional] k_neighbors: Specifies the number of nearest neighbors to be returned.
• [optional] knn_first: Specifies whether the k-nearest neighbor computation will be run before or after the constraints are applied.
• [optional] acorn: Enables ACORN filtered nearest-neighbor search with HNSW (Default: false).
• [optional] engine: Specifies the engine used for indexing and computing distances. If not specified, the default engine will be used.
• [optional] metric: Specifies the metric used to compute distances. If not specified, the default metric will be used.
• [optional] labels: indicates whether the labels of the descriptor will be returned as part of the response (Default: false).
• [optional] distances: indicates whether the metric values for the k-nn search will be returned as part of the response (Default: false). For L2, the value is the square of the Euclidean distance and will decrease with similarity. For IP and CS, the value is related to the angle between the vectors and will increase with similarity.
• [optional] blobs: indicates whether the vectors will be returned as part of the response (Default: false)
• [optional] with_label
• [optional] indexed_results_only: only consider for nearest neighbor descriptors that have been indexed for search (Default: false). This makes the query more efficient at the risk of missing descriptors that have been added recently (typically, within the last hour or so).

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.

The k_neighbors parameter specifies the number of k-nearest neighbors that will be computed. This parameter requires that BOTH a descriptor will be provided in the array of blobs AND a set name is provided, as the set defined the search space.

The knn_first is a Boolean parameter that specifies whether the k-nearest neighbors computation must be run before or after filtering descriptors with the constraints. specified in constraints. If set to "true", k-nearest neighbors are computed first and then constraints are applied. If it is set to false, it applies constraints first and then k-nearest neighbors are computed. By default, it is set to "false". With constraints, the default search computes exact nearest neighbors among the matching descriptors. Set acorn to true to opt into 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.

Indexed searches validate candidates against the query's graph snapshot and refill results affected by deleted descriptors. Flat search remains exact; HNSW and IVF repair use their configured approximate search parameters 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 the index's published coverage 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). Exact evaluation is still used when no usable index is available or its snapshot is newer than the query's snapshot, and when merging matching descriptors that have not yet been indexed. 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.

Examples

Find the descriptors that belong to the DescriptorSet named "party_faces", where the "year_created" was greater than 2020, 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.

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

Note: 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.

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"]
            }
        }
    }]

Note: 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.

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
        }
    }]