AddBlob

Adds a blob object and its properties. A blob is binary data that ApertureDB treats as a generic file.

The content comes from either the array of blobs or a remote url.

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.
if_not_found	array expression	Optional. Checks existing objects of this type before insertion. When omitted, no duplicate lookup is performed. A match skips creation, properties, and new connections; status is 2 and _ref names all matches. An empty expression array is invalid.
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.
url	string	Optional. Registers externally stored content at a supported, accessible URL without copying it into managed storage or consuming an input blob. When omitted, one input blob is required in the transaction blob array. URL validation, access, or size/media reads may fail.

Details

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.

A valid URL registers a remotely stored blob without copying its content into ApertureDB. The command consumes no input blob when url is supplied.

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.

Response and errors

An authenticated session with the objects create permission is required.

The response is an object under AddBlob 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.

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. Input-blob count/order must match the commands that consume blobs. Unreadable remote objects, invalid media, and storage/processing failures can also fail the command.

Examples

Add a “Blob” representing an audio file using AddBlob command:

[{
    "AddBlob": {
        "properties": {
            "type": "audio",
            "sample_f_Hz": 44000,
            "year": 2021
        }
    }
}]

A blob must be passed together with the JSON Query.

Successful response:

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

Conditionally add a “blob” if the id is not already registered:

[{
    "AddBlob": {
        "if_not_found": ["$id", "==", 44],
        "properties": {
            "type": "audio",
            "sample_f_Hz": 44000,
            "id": 44
        }
    }
}]

A blob must be passed together with the JSON Query.

Successful response:

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

Conditionally add a “blob” if the id is not already present, add a “Recording” event, and create a connection between the “Blob” and the “Recording”:

[{
    "AddEntity": {
        "_ref": 1,
        "class": "Recording",
        "properties": {
            "start": {
                "_date": "Mon Aug 7 10:59:24 PDT 2017"
            },
            "end": {
                "_date": "Mon Aug 7 12:59:24 PDT 2017"
            }
        }
    }
}, {
    "AddBlob": {
        "if_not_found": ["$id", "==", 4444],
        "properties": {
            "type": "audio",
            "sample_f_Hz": 44000,
            "id": 4444
        },
        "connect": {
            "ref": 1,
            "class": "taken_in_session"
        },
        "url": "s3://aperturedb-s3-api-testing-0/sample_config.log"
    }
}]

Successful response:

[{
    "AddEntity": {
        "status": 0
    }
}, {
    "AddBlob": {
        "status": 0
    }
}]