.. _properties: properties ========== **properties** stores key-value pairs on objects, such as entities, images, videos, and descriptors, and on connections. Queries can filter these objects by their property values. An object has no fixed limit on the number of properties. New property names can be added to existing or new objects, and property values can be modified or deleted. Property names starting with ``_`` are reserved for :ref:`system-defined properties `. User-defined names **cannot start with "_"**. The whole user-defined property name must match ``[A-Za-z0-9/-][A-Za-z0-9_/-]{0,63}``: 1-64 ASCII characters, starting with a letter, digit, forward slash, or hyphen, followed by letters, digits, underscores, forward slashes, or hyphens. Dots, dollar signs, whitespace, and other punctuation are not allowed. Slashes and hyphens are literal name characters; for example, ``/metrics/score`` is one property name, not a nested path. The supported types for property values are: .. include:: ../supported_types.rst Datetime values accept date-only strings such as ``2019-06-04`` and timestamps such as ``2019-06-04T18:59:32Z`` or ``2019-06-04T18:59:32+00:00``. Calendar dates must be valid, including leap-year rules. Years above 8191 are rejected; the year must also fit the storage range after conversion to UTC. Properties are defined as a JSON object. Numbers, strings, and booleans use their ordinary JSON forms; datetime values use the ``_date`` wrapper: .. TESTED_EXAMPLE: properties_1 .. code-block:: json [{ "AddEntity": { "class": "Person", "properties": { "key1": 2, "key2": 3.4, "key3": "some_string", "key4": false, "key6": { "_date": "2019-06-04T18:59:32+00:00" }, "key5": { "_date": "Sat Jun 04 18:59:32 UTC 2019" } } } }] A property retains its type after it is first stored on an object. Native numbers use binary64. Signed and unsigned integer inputs for ordinary scalar properties must be within the inclusive range ``[-9007199254740992, 9007199254740992]`` (±2^53). For example, ``9007199254740994`` is rejected as an ordinary scalar integer even though it is representable in binary64. Numeric literals in expressions use this same range. Decimal or exponent numeric tokens and arithmetic use binary64 and may round. An integer token too large for the JSON parser's integer representation may also enter the floating-point path, so the scalar range check does not guarantee rejection of every oversized integer token. Array properties contain numbers, strings, booleans, datetimes, and nulls. These types may be mixed in one array; element order and duplicates are preserved. Empty arrays are supported. For example, a Python client can store a list directly: .. TESTED_EXAMPLE: properties_3 .. code-block:: python from aperturedb import Connector db = Connector.Connector("localhost", user="admin", password="your-password") colors = ["red", "blue"] response, blobs = db.query([{ "AddEntity": { "class": "Palette", "properties": { "colors": colors, "details": {"_json": {"source": "manual", "weights": [1, 2]}} } } }]) The connector serializes ``colors`` as the JSON array ``["red", "blue"]``; pass the list directly rather than calling ``json.dumps`` on it. ``colors`` is stored as ``Array`` and ``details`` as ``Json``. These are also the type names reported by ``GetSchema``. Array values are returned as JSON arrays. Datetime elements use the same ``{"_date": ""}`` wrapper as scalar datetime properties. For example, ``["red", 2, true, {"_date": "2026-01-01"}]`` is a valid mixed array. Array elements may be null; null occupies a position and counts toward the array length. ``[null]`` is distinct from an empty array or a missing property. Array elements cannot be blobs, objects, or nested arrays. Numbers must be finite, and integer-to-number conversion must be exact; values that would lose precision are rejected. Native Array elements can therefore accept larger exact integers, such as ``9007199254740994``, while rejecting ``9007199254740993``. JSON properties can preserve arbitrary nested arrays, objects, and nulls through the ``_json`` wrapper. Query expression lists can also be nested; the stored Array element restriction does not change their list-construction rules. :doc:`../commands/CreateIndex` with ``kind: "array"`` creates an index for array membership, length, and equality queries. ``params: {"positions": [0, 2]}`` adds indexing for the first and third elements; ``params: {"positions": "all"}`` indexes every position. Indexed positions can also help with sorting small result pages. The **type_postings** option is enabled by default. Disabling it reduces storage and write work but may slow type queries and positional sorting. Query results remain the same. ``GetIndexes`` reports the configured positions. JSON properties and computed arrays are not supported by array indexes. The ``{"_json": }`` wrapper stores a JSON property. Its payload may be an object, array, string, number, boolean, or null. The wrapper is removed, and the payload is stored as type ``Json`` and returned as its original JSON value. For example, ``{"_json": {"_date": "label", "_blob": "text"}}`` stores an object with those two literal fields; ``{"_json": [null, [1, 2], {"key": 3}]}`` stores a JSON array with nested data. The wrapper selects the storage type: ``{"_json": [1, 2]}`` is ``Json``, while a bare ``[1, 2]`` is native ``Array``. Likewise, ``{"_json": 1}`` stores JSON rather than a native number. ``{"_json": null}`` stores a present JSON null. JSON payloads allow values unsupported by native Array properties, and preserve signed 64-bit and unsigned 64-bit integers without conversion to native binary64 numbers. Larger numeric tokens can already have rounded in the JSON parser. Consuming a JSON integer as a scalar number in an expression requires exact binary64 conversion; an inexact conversion raises an error. .. _property-wrappers: When a property value uses ``_date``, ``_blob``, or ``_json``, that key must be the object's only top-level key. Combining wrappers or adding sibling keys is invalid. ``_date`` requires a date string and ``_blob`` requires a Base64 string. Bare JSON objects, including ``{}``, are rejected as property values. Lists are accepted directly with the native Array element types listed above. All values inside an ``_json`` payload remain literal JSON: reserved-looking keys are not interpreted as wrappers, and strings beginning with ``$`` stay literal. Example ------- .. TESTED_EXAMPLE: properties_2 .. code-block:: json [{ "AddEntity": { "_ref": 1, "class": "Person", "properties": { "name": "Jane Doe", "email": "jane.doe@xyz.com", "gender": "F", "age": 11, "height": 145.4, "active": false, "date_of_birth": { "_date": "Sat May 29 18:59:24 PDT 2011" } } } }, { "AddImage": { "class": "Images", "_ref": 2, "properties": { "date_captured": { "_date": "Sat Jun 04 18:59:24 PDT 2019" }, "type": "landscape", "aperture": 2.34, "flash_active": true } } }, { "AddConnection": { "class": "BestFriendsForever", "src": 1, "dst": 2, "properties": { "place_met": "Interstellar Park", "date": { "_date": "Mon Aug 7 10:59:24 PDT 2017" } } } }]