Simple Relationships

Relationships

HexaDb considers JSON as a linked-document between objects. Every individual object can be linked to another simply by being referred through the id or by being in the body.

To demonstrate this, let us consider the following scenario. A building has two rooms. Each room has two different types of sensors. This is represented by the following document. The scenario is intentionally kept small for simplicity.

Simple Building Topology

Call the POST method in your store with the above data. POST /api/store/<storeid>

Note that relationships are expressed with nested object. The whole object does not have to be inline, the id is necessary and sufficient to express a relationship. For example the below JSON object expresses relationship between an object with id eTJkox6k that has a sensors relationship with two entities with id's 83ilcH3W and zHZgELDp. Those two sensors can be expressed together or separately.

{
        "id": "eTJkox6k",
        "description": "r:building:0:room:1",
        "type": "room",
        "name": "Entity room 1",
        "tag": "serene_beaver",
        "sensors": [
            {
                "id": "83ilcH3W"
            },
            {
                "id": "zHZgELDp"
            }
        ]
    }

To get this entity with id use the following

GET /api/store/<storeid>/eTJkox6k

This only returns the details associated with the document with id eTJkox6k. Notice that the relationships are only pointed to by the id's of the items contained in it.

To get the entities that are related as well use the query parameter level that indicates a nesting level.

GET /api/store/<storeid>/eTJkox6k?level=3 This returns a single JSON document with the relationships inline

{
    "id": "eTJkox6k",
    "description": "r:building:0:room:1",
    "name": "Entity room 1",
    "sensors": [
        {
            "id": "83ilcH3W",
            "description": "r:building:0:room:1:sensor:0",
            "firmware": "0.8",
            "humidity": 73.76,
            "marker": {
                "id": "83ilcH3W#marker",
                "blue": 3.8,
                "green": 1.7,
                "location": {
                    "id": "83ilcH3W#marker#location"
                },
                "red": 6.02,
                "status": "running"
            },
            "name": "sensor 2",
            "pressure": 904.81,
            "tag": "cocky_johnson",
            "temperature": 69.41,
            "type": "sensor"
        },
        {
            "id": "zHZgELDp",
            "corner1": {
                "id": "zHZgELDp#corner1",
                "humidity": 81.6,
                "temperature": 74.7
            },
            "corner2": {
                "id": "zHZgELDp#corner2",
                "humidity": 85.79,
                "temperature": 73.4
            },
            "description": "r:building:0:room:1:sensor:0:occupancy",
            "firmware": "1.6",
            "lastMeeting": {
                "id": "zHZgELDp#lastMeeting",
                "forMinutes": 54,
                "number": 8
            },
            "name": "sensor 3",
            "occupancy": 3,
            "tag": "objective_blackburn",
            "type": "occupancy"
        }
    ],
    "tag": "serene_beaver",
    "type": "room"
}

Note that this expands all relationships to level 3. To selectively expand relationships try the following query

GET /api/store/<appid>/eTJkox6k?level=3&expand=sensors

This will only inline the entities that have a sensors relationship with the entity.

Expand can be comma separated. the expand query parameter supports multiple relationships separated by comma. For example the below query will return multiple relationships

GET /api/store/<appid>/eTJkox6k?level=3&expand=sensors,marker,location