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 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:

number
string
boolean
datetime
array (elements: number, string, boolean, datetime, or null)
blob (using the {"_blob": "<Base64-encoded data>"} wrapper)
JSON (using the {"_json": <JSON value>} wrapper)

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:

[{
    "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:

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": "<date string>"} 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.

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": <JSON value>} 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.

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

[{
    "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": {
        "_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"
            }
        }
    }
}]

Example​

Example