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

  • [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] n_descriptors: the number of descriptors represented in the blob (Default: 1)

  • [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] ids: indicates whether the ids 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

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 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": 10,
        "blobs":       true,
        "labels":      true,
        "distances":   true,
        "results": {
            "list": ["year_created", "description"]
        }
    }
} ]

# A blob must be passed together with the JSON Query.
# The blobs is an array of 32bit floating point values.

Find the 10 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 “FaissIVFFlat”.

[ {
    "FindDescriptorBatch": {
        "set": "party_faces",
        "n_descriptors": 100,
        "k_neighbors":   10,
        "engine":        "FaissIVFFlat"
        "blobs":         true,
        "labels":        true,
        "distances":     true,
        "results": {
            "list": ["year_created", "description"]
        }
    }
} ]

# A blob must be passed together with the JSON Query.
# The blob is an array of 32bit floating point values.