properties

The properties are key-value pairs associated with objects (Entity, Image, Video, Descriptor, etc) and connections.

Defining properties allow applications to later filter based on these properties.

There is no limit to the number of properties defined for an object. There is no restriction to add new, previously not present, properties to existing or new objects. Properties can be added, modified, or even deleted as needed.

NOTE: Property name starting with "_" are reserved for system-defined properties, thus, user-defined property names (keys) cannot start with "_".

The whole user-defined property name must match [A-Za-z][A-Za-z0-9_-]{0,63}: 1–64 ASCII characters, starting with a letter, followed by letters, digits, underscores, or hyphens. Dots, dollar signs, whitespace, and other punctuation are not allowed. Hyphens are literal name characters.

The supported types for property values are:

number
string
boolean
datetime * array (elements: number, string, boolean, or datetime) * 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 in the following way:

[{
    "AddEntity": {
        "class": "Person",
        "properties": {
            "key1": 2,             // Number value
            "key2": 3.4,           // Number value
            "key3": "some_string", // String value
            "key4": false,         // Boolean value

            // Time is a special case, defined as follows:
            "key6": {
                "_date": "2019-06-04T18:59:32+00:00"
            },
            "key5": {
                "_date": "Sat Jun 04 18:59:32 UTC 2019"
            }
        }
    }
}]

Note: Property types are enforced. Once a property is set for an Object, the type of the property will be enforced.

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. Ordinary expression and property-keyed numeric literals 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, and datetimes. 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 stored as packed native values in the Array partition and 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 cannot be null, 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.

Use ../commands/CreateIndex with kind: "array" to index array membership. Optional params: {"positions": [0, 2]} also records entries for the first and third positions. The expression planner currently evaluates at comparisons on candidates to preserve type errors. Without positions, the index covers membership only. GetIndexes reports the normalized positions for each definition. JSON properties and computed arrays are not indexed by this kind.

Use {"_json": <JSON value>} to store a JSON property. The 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. The _object spelling is no longer accepted.

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