Handling of Missing Data ======================== .. _summary: .. _purpose: A requested property that an object does not have is returned as ``null`` in JSON (``None`` after decoding into Python). Reading or sorting by that property does not create it. For example, asking for ``origin`` returns ``"origin": null`` for an apple with no ``origin`` property. .. _specification: Comparisons and sorting ----------------------- .. list-table:: Behavior for an unset property :header-rows: 1 :widths: 50 50 * - Operation - Result * - ``["$origin", "==", null]`` - Matches an unset ``origin``. * - ``["$enabled", "==", false]`` - Does not match an unset ``enabled``. * - ``["$enabled", "!=", true]`` - Matches an unset ``enabled``. * - ``["$score", "<", 5]`` or ``["$score", ">", 5]`` - Does not match an unset ``score``. * - Ascending / descending sort - Unset values appear first / last, respectively. An absent property is treated as an unset value whether the property exists on other objects or has never been stored in the database. For constraint comparisons, unset values are neither less than nor greater than non-null values. Sorting uses a different ordering, placing unset values below non-null values. See :doc:`parameters/constraints`, :doc:`parameters/sort`, and :doc:`parameters/results` for the complete query options. .. _example-1: Returning a missing property ------------------------------- This request adds two apple entities. Both have ``color`` and ``type`` properties; only the green apple has an ``origin``: Query: .. TESTED_EXAMPLE: HandlingOfMissingData_3 .. code-block:: json [{ "AddEntity": { "class": "Apple_3", "properties": { "color": "green", "type": "granny_smith", "origin": "Allen, Neuquen, Argentina" } } }, { "AddEntity": { "class": "Apple_3", "properties": { "color": "red", "type": "granny_smith" } } }] Response: .. TESTED_EXAMPLE: HandlingOfMissingData_3_response .. code-block:: json [{ "AddEntity": { "status": 0 } }, { "AddEntity": { "status": 0 } }] The following query requests the same three properties from both entities: Query: .. TESTED_EXAMPLE: HandlingOfMissingData_4 .. code-block:: json [{ "FindEntity": { "with_class": "Apple_3", "results": { "list": ["color", "type", "origin"] } } }] Response: .. TESTED_EXAMPLE: HandlingOfMissingData_4_response .. code-block:: json [{ "FindEntity": { "entities": [{ "_class": "Apple_3", "color": "green", "origin": "Allen, Neuquen, Argentina", "type": "granny_smith" }, { "_class": "Apple_3", "color": "red", "origin": null, "type": "granny_smith" }], "returned": 2, "status": 0 } }] The red apple has no ``origin`` property, so its response contains ``"origin": null``. .. _example-2: Sorting by a missing property -------------------------------- The next two queries assume that ``Apple_1`` and ``Apple_2`` each contain two apple entities with ``color`` and ``type`` properties. The first query sorts by ``IQ``, a property absent from every matching entity. The query succeeds and returns ``null`` for the requested missing property. Equal sort values use ascending object IDs. Query: .. TESTED_EXAMPLE: HandlingOfMissingData_1 .. code-block:: json [{ "FindEntity": { "with_class": "Apple_1", "sort": "IQ", "results": { "list": ["color", "type", "IQ"] } } }] Response: .. TESTED_EXAMPLE: HandlingOfMissingData_1_response .. code-block:: json [{ "FindEntity": { "entities": [{ "_class": "Apple_1", "IQ": null, "color": "red", "type": "granny_smith" }, { "_class": "Apple_1", "IQ": null, "color": "green", "type": "granny_smith" }], "returned": 2, "status": 0 } }] If a property unexpectedly returns ``null``, check its spelling and whether it was added to those objects. Omitting ``IQ`` from the requested output leaves the sort behavior unchanged: Query: .. TESTED_EXAMPLE: HandlingOfMissingData_2 .. code-block:: json [{ "FindEntity": { "with_class": "Apple_2", "sort": "IQ", "results": { "list": ["color", "type"] } } }] Response: .. TESTED_EXAMPLE: HandlingOfMissingData_2_response .. code-block:: json [{ "FindEntity": { "entities": [{ "_class": "Apple_2", "color": "red", "type": "granny_smith" }, { "_class": "Apple_2", "color": "green", "type": "granny_smith" }], "returned": 2, "status": 0 } }] .. _example-3: Finding objects with a missing property ------------------------------------------ A comparison with ``null`` selects objects where a property is absent. In this example, the ``Apple_5`` class contains a red apple with no ``origin`` property: .. TESTED_EXAMPLE: HandlingOfMissingData_5 .. code-block:: json [{ "FindEntity": { "with_class": "Apple_5", "constraints": ["$origin", "==", null], "results": { "list": ["color", "type", "origin"] } } }] Response: .. TESTED_EXAMPLE: HandlingOfMissingData_5_response .. code-block:: json [{ "FindEntity": { "entities": [{ "_class": "Apple_5", "color": "red", "origin": null, "type": "granny_smith" }], "returned": 1, "status": 0 } }]