FindBlob

Find all blobs 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
blobs	boolean / optional	false; true retrieves each matched blob into the output blob array. No input blob is consumed.
urls	boolean / optional	false; true adds url to returned metadata. Objects stored without a remote URL return an empty string. This flag alone does not satisfy the required output selection.
with_url	string / optional	Omitted: no URL restriction. Compare the stored remote URL for exact equality.

Details

Specify results, _ref, uniqueids: true, or blobs: true. Without one of these output selections, validation fails; urls: true alone is insufficient. This command consumes no input blob.

Content referenced by url can change outside ApertureDB or expire under the remote storage service’s retention policy. A Find* command returns an error if the remote content is no longer accessible.

The properties that will be retrieved for the found objects can be specified using results.

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.

When blobs are returned, blobs_start identifies the first output blob. Where metadata accompanies blob data, _blob_index associates it with the query’s output blob array. See API Description for blob ordering.

Retrieval of local or remote blob data can fail after the graph lookup. Check the info message and remote credential/origin settings when applicable.

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 all blob objects where its “start_year” property is on or after 1990, and retrieve certain properties of the object:

[{
    "FindBlob": {
        "constraints": ["$start_year", ">=", 1990],
        "results": {
            "list": ["start_year", "end_year", "billing_id"]
        },
        "blobs": true
    }
}]

Successful response:

[{
    "FindBlob": {
        "blobs_start": 0,
        "entities": [{
            "_blob_index": 0,
            "billing_id": 125376,
            "end_year": 2002,
            "start_year": 1998
        }, {
            "_blob_index": 1,
            "billing_id": 9987342,
            "end_year": 2021,
            "start_year": 2018
        }],
        "returned": 2,
        "status": 0
    }
}]

The response also includes an array containing both entities’ binary data.

Find all blob objects where its “start_year” property is on or after 1990 that are associated with a “Patient” with a “unique_id” equal to 4325, and retrieve other properties of the visit. The first command uses unique to require exactly one match and _ref to reuse it without returning properties. The second command sets blobs to false to return metadata without binary data.

[{
    "FindEntity": {
        "with_class": "Patient",
        "_ref": 1,
        "unique": true,
        "constraints": ["$id", "==", 4325]
    }
}, {
    "FindBlob": {
        "constraints": ["$start_year", ">=", 1990],
        "is_connected_to": {
            "ref": 1,
            "direction": "in",
            "connection_class": "patient_has_study"
        },
        "blobs": false,
        "results": {
            "list": ["start_year", "end_year", "billing_id"]
        }
    }
}]

Successful response:

[{
    "FindEntity": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindBlob": {
        "entities": [{
            "billing_id": 756354,
            "end_year": 2012,
            "start_year": 2011
        }],
        "returned": 1,
        "status": 0
    }
}]

Filter by content type

_mime_type is a stored MIME string, supplied via AddBlob.mime_type or detected by the server. It can be returned, filtered, sorted, and indexed without fetching blob contents. No index is created by default; use CreateIndex on class _Blob and property _mime_type when needed. Filtering also works without an index:

[{"FindBlob": {
    "constraints": ["$_mime_type", "==", "application/pdf"],
    "results": {"list": ["_mime_type"]},
    "blobs": false
}}]

The same property can be used in AddBlob.if_not_found, UpdateBlob and DeleteBlob constraints. A user cannot overwrite or remove it.