ClassifyDescriptor

Classify a query descriptor using labels from its nearest neighbors.

Requires objects.read permission and exactly one input blob containing 32-bit floating-point values. Its byte length must equal the DescriptorSet dimensions multiplied by four. Values must be finite; NaN and infinity are rejected. No output blob is produced.

Parameters

Parameter	Type / required	Default and behavior
set	string / required	DescriptorSet name; no default. The set may exist already or have been added earlier in this query.
k_neighbors	unsigned integer / required	Positive number of nearest neighbors to consider; zero is rejected and there is no default.
engine	string: Flat, IVF, HNSW / optional	The set’s first configured engine when omitted. Must be configured for the set. Required in 1.0.0, so send it to prepare for that release.

Details

The most frequent string label among the retrieved neighbors wins. Ties are resolved by the best distance for each label, then by label name. Unlabeled neighbors do not vote. The command selects the first configured metric for the set, and the first configured engine unless engine names one; it does not accept a separate metric selector. Labels are assigned when descriptors are added; see AddDescriptor.

Response and recovery

Success returns status: 0, the neighbor-search result fields, and label. returned counts retrieved neighbors, which can be fewer than k_neighbors. If no retrieved neighbor supplies a string label, the classification is the literal string "None".

Failure or empty result	Cause and recovery
DescriptorSet not found	Use an existing set or add it earlier in the same query.
Invalid blob size or missing input blob	Send one float32 vector with the configured dimensions.
No usable labels	Inspect descriptor labels; the returned label is “None”, not JSON null.

See Responses for validation, authentication, and permission error envelopes. Command errors use a negative status and an info message.

Examples

Classify a given descriptor using the labels of its 10 nearest neighbors:

[{
    "ClassifyDescriptor": {
        "set": "party_faces",
        "k_neighbors": 10
    }
}]

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

Example response:

[{
    "ClassifyDescriptor": {
        "entities": [{
            "_uniqueid": "10.11.58280"
        }, {
            "_uniqueid": "10.3.58120"
        }, {
            "_uniqueid": "10.9.58240"
        }, {
            "_uniqueid": "10.12.58300"
        }, {
            "_uniqueid": "10.15.58360"
        }, {
            "_uniqueid": "10.1.58080"
        }, {
            "_uniqueid": "10.4.58140"
        }, {
            "_uniqueid": "10.7.58200"
        }, {
            "_uniqueid": "10.10.58260"
        }, {
            "_uniqueid": "10.13.58320"
        }],
        "label": "bar",
        "returned": 10,
        "status": 0
    }
}]