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

  • 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 neighbors to be returned.
  • [optional] knnfirst: Specifies whether the k-nearest neighbor computation will be run before or after the constraints are applied.

Blocks

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 a descriptor will be provided in the array of blobs.

The knnfirst 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 the constraints block. 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”.

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

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.

[ {
    "FindDescriptor": {
        "set": "party_faces",
        "k_neighbors": 10,
        "results": {
            "list": ["year_created", "description", "_label"],
            "blob": true
        }
    }
} ]

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