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] set: Name of the set.
  • [optional] _ref: Reference to be used within the transaction.
  • [optional] unique: Indicates whether a single object is expected to satisfy the constraints.
  • [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] 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
  • [optional] constraints
  • [optional] is_connected_to
  • [optional] group_by_source
  • [optional] results
  • [optional] batch

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

Find the 10 nearest-neighbors of a give 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": 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.