.. _FindBlob: FindBlob ========== Find all blobs that satisfy the specified constraints. Requires an authenticated user with ``objects.read`` permission. Parameters ---------- .. include:: find_parameters.rst .. list-table:: :header-rows: 1 :widths: 22 23 55 * - Parameter - Type / required - Default and behavior * - :ref:`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. .. include:: url_updates_retention.rst The properties that will be retrieved for the found objects can be specified using :ref:`results`. .. include:: group_by_source_details.rst 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 :doc:`../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 :doc:`../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: .. TESTED_EXAMPLE: FindBlob_1 .. code-block:: json [{ "FindBlob": { "constraints": ["$start_year", ">=", 1990], "results": { "list": ["start_year", "end_year", "billing_id"] }, "blobs": true } }] Successful response: .. TESTED_EXAMPLE: FindBlob_1_response .. code-block:: json [{ "FindBlob": { "blobs_start": 0, "entities": [{ "_blob_index": 0, "billing_id": 125376, "end_year": 2002, "start_year": 1998, "_class": "Blobs" }, { "_blob_index": 1, "billing_id": 9987342, "end_year": 2021, "start_year": 2018, "_class": "Blobs" }], "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. .. TESTED_EXAMPLE: FindBlob_2 .. code-block:: json [{ "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: .. TESTED_EXAMPLE: FindBlob_2_response .. code-block:: json [{ "FindEntity": { "returned": 0, "status": 0 } }, { "FindBlob": { "entities": [{ "_class": "Blobs", "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: .. code-block:: json [{"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.