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] 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] 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. The latter is a more expensive operation since a descriptor index is constructed on-the-fly with descriptors that satisfy the specified constraints. By default, it is set to "true".

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 32bit floating point values represeting the query descriptor.

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 32bit floating point values represeting the query descriptor.

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

FindDescriptor

Parameters​

Details​

Examples​

Parameters

Details

Examples