.. _AddBlob: 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 :ref:`array of blobs ` or a remote **url**. Parameters ---------- ``class`` is required; it names this object's application class within its type. .. list-table:: :header-rows: 1 :widths: 15 25 60 * - Parameter - JSON type - Behavior * - :ref:`_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. * - :ref:`connect ` - connection object or array of connection objects - Optional. When omitted, no additional user connections are created. Each object requires an earlier node ref. A customer class is required; direction is in or out (default out); properties sets connection properties. Connections are created only for a newly inserted object. * - :ref:`if_not_found ` - array expression - Optional. Checks existing objects of this exact type/class 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. * - :ref:`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. * - mime_type - string - Optional. Stores the supplied value as _mime_type and skips automatic content detection. When omitted, the server detects the MIME type from the content prefix. * - :ref:`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 ------- .. include:: add_details.rst A :ref:`valid URL ` registers a remotely stored blob without copying its content into ApertureDB. The command consumes no input blob when **url** is supplied. .. include:: url_updates_retention.rst 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: .. TESTED_EXAMPLE: AddBlob_1 .. code-block:: json [{ "AddBlob": { "class": "Blobs", "properties": { "type": "audio", "sample_f_Hz": 44000, "year": 2021 } } }] A blob must be passed together with the JSON Query. Successful response: .. TESTED_EXAMPLE: AddBlob_1_response .. code-block:: json [{ "AddBlob": { "status": 0 } }] Conditionally add a "blob" if the id is not already registered: .. TESTED_EXAMPLE: AddBlob_2 .. code-block:: json [{ "AddBlob": { "class": "Blobs", "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: .. TESTED_EXAMPLE: AddBlob_2_response .. code-block:: json [{ "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": .. TESTED_EXAMPLE: AddBlob_3 .. code-block:: json [{ "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": { "class": "Blobs", "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: .. TESTED_EXAMPLE: AddBlob_3_response .. code-block:: json [{ "AddEntity": { "status": 0 } }, { "AddBlob": { "status": 0 } }] Content type ------------ The stored ``_mime_type`` property identifies the blob's MIME type, such as ``application/pdf``. To force a value at ingestion, pass ``mime_type`` directly in ``AddBlob`` (for example, ``{"AddBlob": {"mime_type": "text/csv"}}``). The supplied string is stored unchanged and automatic detection is skipped, including the prefix read for URL ingestion. URL access and size checks still apply. The property cannot be set through ``properties`` or changed or removed with ``UpdateBlob``. When ``mime_type`` is omitted, the server detects the type from up to the first 4096 bytes. Filenames are not used. URL ingestion reads the prefix using the registered credential; an unreadable object fails the command. The server recognizes the following signatures. * Binary formats include PDF, PNG, JPEG, GIF, TIFF/BigTIFF, BMP, WebP, AVIF, WAV, AVI, MP4/M4A/QuickTime, FLAC, Ogg, ID3-tagged MPEG audio, ZIP, and gzip. ZIP-based Office files have the ZIP signature and yield ``application/zip``. * HTML (``text/html``) begins with an HTML doctype or an opening ``html``, ``head``, or ``body`` tag. An XML declaration identifies ``application/xml``. An opening ``svg`` tag identifies ``image/svg+xml`` even after an XML declaration. * vCard (``text/vcard``), iCalendar (``text/calendar``), and WebVTT (``text/vtt``) each have a distinctive first line. Other printable ASCII text yields ``text/plain``. Empty or unrecognized data yields ``application/octet-stream``. For formats without a distinctive signature, such as CSV or JSON, supply ``mime_type`` when the precise type matters. Changing content at an external URL does not update its stored MIME type.