FindDescriptorSet

Find descriptor sets that satisfy the specified constraints.

Requires an authenticated user with objects.read permission.

Parameters

Parameter	Type / required	Default and behavior
_ref	integer / optional	Omitted: do not retain a reference for later commands in this query.
unique	Boolean / optional	false; require exactly one match when true.
constraints	expression / optional	Omitted: no property filter; other restrictions still apply.
is_connected_to	object / optional	Omitted: no graph-neighbor restriction.
is_endpoint_of	object / optional	Omitted: no connection-endpoint restriction.
group_by_source	Boolean / optional	false; group matches by the source of a relationship lookup.
per_group	Boolean / optional	false; true requires group_by_source: true and applies sort, offset and limit within each source group.
results	object / optional	Omitted: no requested property projection or aggregate. Select output or retain a reference as described below.
batch	object / optional	Omitted: no distributed result batching.
sort	string, object, or array / optional	Omitted: no explicit property ordering; nearest-neighbor commands have their own distance ordering.
limit	integer 0–2147483647 / optional	Omitted: no explicit result-count limit.
offset	integer 0–2147483647 / optional	0; skip this many matches after sorting.
uniqueids	Boolean / optional	false; include object identifiers when true.

Parameter	Type / required	Default and behavior
with_name	string / optional	Omitted: no name restriction. Match a non-deleted descriptor set by its unique name; a missing name produces no matches.
engines	boolean / optional	false unless results.all_properties:true; true returns the available engines as _engines. results.all_properties:true also requests it when engines:false.
engines_format	string: array, object / optional	array. object returns _engines in the 1.0.0 form, an object of engine settings, and omits _engine_params.
metrics	boolean / optional	false unless results.all_properties:true; true returns the available metrics as _metrics. results.all_properties:true also requests it when metrics:false.
dimensions	boolean / optional	false unless results.all_properties:true; true returns dimensionality as _dimensions. results.all_properties:true also requests it when dimensions:false.
counts	boolean / optional	false unless results.all_properties:true; true returns the stored descriptor count as _count. results.all_properties:true also requests it when counts:false.

Details

The with_name parameter specifies the “name” of the DescriptorSet and is guaranteed to be unique.

engines_format selects how _engines is returned, whether requested with engines, results.all_properties, or results.list. The default, array, lists the configured engine names, such as ["Flat", "HNSW"], with their settings in _engine_params when requested. object returns the form 1.0.0 always uses: each configured engine’s lowercase name mapped to its settings, with lazy_indexing: false and zero for settings that use their defaults, and no _engine_params. For example:

{"flat": {"lazy_indexing": false},
 "hnsw": {"M": 16, "efConstruction": 0, "efSearch": 0,
          "lazy_indexing": false}}

1.0.0 accepts "engines_format": "object", so applications can read the 1.0.0 form before upgrading. Both forms read the same stored configuration.

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.

Response and recovery

A successful command returns status: 0 and returned. Requested metadata appears in entities; a reference-only lookup can match objects without returning metadata. returned counts delivered objects or blobs, not every graph match. Use results.count to request a match count.

Choose at least one of _ref, results, uniqueids: true, or a true engines, metrics, dimensions, or counts selector. These selectors return _engines, _metrics, _dimensions, and _count, respectively. Deleted sets are excluded. This command consumes and returns no blobs.

Invalid parameters, undeclared or incorrectly typed references, and failed output validation return status: -1 with info. A violated unique: true expectation returns status: 3. A response that exceeds the configured message budget can return status: 4; reduce the result limit or requested data. See Responses for error envelopes and retry guidance.

Examples

Find the descriptor set that is named “party_faces”:

[{
    "FindDescriptorSet": {
        "_ref": 1,
        "with_name": "party_faces",
        "metrics": true,
        "engines": true,
        "results": {
            "list": ["year_created", "description"]
        }
    }
}]

Successful response:

[{
    "FindDescriptorSet": {
        "entities": [{
            "_engines": ["Flat"],
            "_metrics": ["CS", "L2"],
            "description": "Faces at a party",
            "year_created": 2020
        }],
        "returned": 1,
        "status": 0
    }
}]

Find descriptor sets that have a property “year_created” equal to 2020, and retrieve the “year_created” and “description” properties:

[{
    "FindDescriptorSet": {
        "constraints": ["$year_created", "==", 2020],
        "results": {
            "list": ["year_created", "description"]
        }
    }
}]

Successful response:

[{
    "FindDescriptorSet": {
        "entities": [{
            "description": "Faces at a party",
            "year_created": 2020
        }],
        "returned": 1,
        "status": 0
    }
}]