AddDescriptorSet

Add a descriptor set and properties associated with it.

Parameters

Parameter	JSON type	Behavior
_ref	integer, 1 through 100000	Optional. Declares a unique reference for later commands in this transaction. When omitted, no reference is available to later commands. If conditional insertion finds existing objects, the reference names those matches.
connect	connection object or array of connection objects	Optional. When omitted, no additional user connections are created. Each object requires an earlier node ref. Optional class chooses a connection class; direction is in or out (default out); properties sets connection properties. Omitted class uses this command’s default connection class. Connections are created only for a newly inserted object.
dimensions	integer, 1 through 4294967295	Required. Fixed number of float32 elements expected in each descriptor blob. Available storage and index resources may impose lower limits.
engine	string or array of strings	Optional. Uses IVF; an empty array has the same effect. Case-sensitive values: Flat, IVF, HNSW. Nonempty arrays configure multiple engines. If a search omits engine, it selects the first configured engine in the fixed order Flat, IVF, HNSW, regardless of input-array order.
if_not_found	array expression	Optional. Checks existing objects of this type before insertion. When omitted, only the descriptor-set name uniqueness check applies. A match skips creation, properties, and new connections; status is 2 and _ref names all matches. An empty expression array is invalid.
metric	string or array of strings	Optional. Uses L2; an empty array has the same effect. Case-sensitive values: L2, IP, CS. Nonempty arrays configure multiple metrics. If a search omits metric, it selects the first configured metric in the fixed order L2, IP, CS, regardless of input-array order.
name	string	Required. Unique descriptor-set name. An existing name prevents creation and returns status 2.
properties	object mapping property names to values	Optional. When omitted, no user properties are added. Stores booleans, numbers, strings, supported arrays, or single-key _date, _blob, and _json wrappers. Bare null is rejected; property names and wrapped values are validated. See the properties reference for nested value rules.

Details

A DescriptorSet groups descriptors produced by the same feature-extraction algorithm, with a fixed number of dimensions. For example, a set of OpenFace descriptors has 128 dimensions and supports indexing and matching across those descriptors.

The properties object stores key-value pairs on the new object.

The if_not_found condition inserts the object only when no existing object matches the condition.

The connect parameter creates connections between the new object and objects referenced earlier in the transaction.

name specifies the set name that will be used for later access to the set, or for running knn within the set. A DescriptorSet is conditionally added if and only if a DescriptorSet with the same name does not exist.

dimensions specifies the number of dimensions of the descriptor. For instance, a DescriptorSet used to store descriptors of faces using OpenFace will have 128 dimensions.

The engine parameter specifies the method used to index descriptors, and consequently, the structure of the index. Engines differ in search accuracy and latency. Flat performs exhaustive search; approximate indexes trade some accuracy for lower search latency. One or multiple engine values can be specified, using a string or an array of strings respectively. When a search omits engine, it selects the first configured engine in the fixed order Flat, IVF, HNSW, regardless of the input array order.

The supported engines are:

• Flat (Exhaustive search)

• IVF (Inverted File Index) [Default]

• HNSW (Hierarchical Navigable Small World)

Engine names are case-sensitive. Unknown names are rejected. Omitting the engine when creating a set selects IVF.

The metric parameter specifies the metric used to compute distances between descriptors, when performing similarity search. One or multiple metric values can be specified, using a string or an array of strings respectively. When a search omits metric, it selects the first configured metric in the fixed order L2, IP, CS, regardless of the input array order.

The supported metrics are:

• L2 (euclidean distance) [Default]

• IP (inner product)

• CS (cosine similarity)

Response and errors

An authenticated session with the objects create permission is required.

The response is an object under AddDescriptorSet with integer status. Status 0 means creation succeeded; status 2 means conditional insertion found existing objects. No output blob or created-object count is returned. Duplicate set names also return status 2.

Invalid field types, missing required fields, malformed expressions, and invalid references fail validation. Execution failures include a nonzero status and an info message; inspect the transaction response before assuming a mutation succeeded.

Examples

Insert a DescriptorSet for face recognition, using 128-dimensional descriptors and engine for exact search (Flat).

[{
    "AddDescriptorSet": {
        "name": "pretty_faces",
        "dimensions": 128,
        "engine": "Flat",
        "metric": "L2",
        "properties": {
            "year_created": 2018,
            "description": "face recognition descriptors"
        }
    }
}]

Successful response:

[{
    "AddDescriptorSet": {
        "status": 0
    }
}]

Insert a DescriptorSet for face recognition, using 2048-dimensional descriptors and support for 2 engines (exact search “Flat”, and approximate search “HNSW”).

[{
    "AddDescriptorSet": {
        "name": "pretty_faces_multi_engine",
        "dimensions": 2048,
        "engine": ["Flat", "HNSW"],
        "metric": ["L2", "IP"],
        "properties": {
            "year_created": 2018,
            "description": "face recognition descriptors"
        }
    }
}]

Successful response:

[{
    "AddDescriptorSet": {
        "status": 0
    }
}]