Skip to main content

AddDescriptorSet

Add a descriptor set and properties associated with it.

Parameters​

  • name: Name of the DescriptorSet.
  • dimensions: Number of dimensions of the descriptor.
  • [optional] engine: Specifies the implementation for indexing and computing distances.
  • [optional] metric: Specifies the metric used to calculate distances.
  • [optional] _ref: reference to be used within the transaction.
  • [optional] properties
  • [optional] connect

Details​

A DescriptorSet is a group of descriptors with a fixed number of dimensions that are the result of the same algorithm for feature extraction. For instance, we can create a DescriptorSet and insert multiple descriptors obtained by using OpenFace (128 dimensions), and then index and perform matching operations over those descriptors.

properties are key-value pairs associated with the entity. Check properties for more details.

if_not_found can be used to turn this command into "conditional add". Check if_not_found for more details.

connect can be used to create a connection between the added object and other object(s). Check connect for more details.

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. The engine defines trade-offs of accuracy vs latency: some indexes will compute "exact" search, taking longer to compute, and some other indexes will compute an "approximate" search much faster. One or multiple engine values can be specified, using a string or an array of strings respectively. When specifying multiple engine values in an array, the first value will be used as the default engine.

The supported engines are:

  • Flat (Exhaustive search) [Default]
  • IVF (Inverted File Index)
  • HNSW (Hierarchical Navigable Small World)

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 specifying multiple metric values in an array, the first value will be used as the default metric.

The supported metrics are:

  • L2 (euclidean distance) [Default]
  • IP (inner product)
  • CS (cosine similarity)

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 approximated search "IVF").


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