Skip to main content

FindDescriptorBatch

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​

  • set: Name of the set.
  • n_descriptors: the number of descriptors represented in the blob.
  • [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 distances to the k-nn search will be returned as part of the response (Default: false).
  • [optional] blobs: indicates whether the blobs will be returned
  • [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.

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 10 nearest-neighbors of a given batch of 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 computation.


    [{
        "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 32bit floating point values represeting 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
        }
    }]