18. Follow Relationships in a Query

Follw Relationships in a Query is a feature that aims to allow us to retrieve entities with their linked sub-entities’ data using the join parameter. The join parameter has two supported values: inline and flat

  • If join=inline, the entity and sub-entities should be represented in a hierarchical structure.

  • If join=flat, the entity and sub-entities should be represented as they are currently, but target entities will be returned in the result list.

For example: a person holds several pieces of land type:AgriParcel. Each AgriParcel has some of its own attributes, e.g., soilType, cropType. Each AgriParcel also has its own related weather station (i.e., Relationship to an entity type:WeatherObserved) displaying values holding to current observed weather conditions. We also require a weather forecast (i.e. Relationship to an entity type:WeatherForecast) which covers a wider area encompassing multiple AgriParcels for a predicted weather conditions.

_images/followRelationshipDiagram.png

Note: The join parameter is compatible with the option parameter in all scenarios including - normalized and concise.

18.1. Example for Follow Relationship in a Query

18.1.1. 1. Create Operation

You can create entities by sending an HTTP POST request given below:

POST - http://localhost:9090/ngsi-ld/v1/entities/ with the given payloads.

Example of AgriParcel entity with objectType modifications:

{
    "id": "urn:ngsi-ld:AgriParcel:001",
    "type": "AgriParcel",
    "soilType": {
        "type": "Property",
        "value": "Loamy"
    },
    "cropType": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:AgriCrop:BuckWheat"
    },
    "location": {
        "type": "GeoProperty",
        "value": {
            "type": "Point",
            "coords": [
                13,
                58
            ]
        }
    },
    "prediction": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:WeatherForecast:XXX",
        "objectType": "WeatherForecast"
    },
    "observation": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:WeatherObserved:001",
        "providedBy": {
            "type": "Relationship",
            "object": "urn:ngsi-ld:Device:ABC"
        },
        "objectType": "WeatherObserved",
    }
}

Sub-entities for AgriParcel entity:

  • WeatherForecast

{
    "id": "urn:ngsi-ld:WeatherForecast:XXX",
    "type": "WeatherForecast",
    "humidity": {
        "type": "Property",
        "value": 98,
        "unitCode": "PCT"
    },
    "temperature": {
        "type": "Property",
        "value": 30,
        "unitCode": "CEL"
    },
    "windSpeed": {
        "type": "Property",
        "value": 3,
        "unitCode": "MPH"
    },
    "description": {
        "type": "Property",
        "value": "Rain"
    }
}

  • WeatherObserved

{
    "id": "urn:ngsi-ld:WeatherObserved:001",
    "type": "WeatherObserved",
    "humidity": {
        "type": "Property",
        "value": 80,
        "unitCode": "PCT"
    },
    "temperature": {
        "type": "Property",
        "value": 30,
        "unitCode": "CEL"
    },
    "windSpeed": {
        "type": "Property",
        "value": 3,
        "unitCode": "MPH"
    }
}

18.1.2. 2. Query Operation

  • Retrieve entity with concise and inline sub-entities

To retrieve AgriParcel entity in concise format and with inline sub-entities, you can send an HTTP GET to - http://<IP Address>:<port>/ngsi-ld/v1/entities/{entityId}?options=concise&join=inline and we will get data in hierarchical structure.

GET - http://localhost:9090/ngsi-ld/v1/entities/urn:ngsi-ld:AgriParcel:001?options=concise&join=inline&joinLevel=3

Response:

{
    "id": "urn:ngsi-ld:AgriParcel:001",
    "type": "AgriParcel",
    "cropType": {
        "object": "urn:ngsi-ld:AgriCrop:BuckWheat"
    },
    "observation": {
        "entity": {
            "id": "urn:ngsi-ld:WeatherObserved:001",
            "type": "WeatherObserved",
            "humidity": {
                "value": 80,
                "unitCode": "PCT"
            },
            "temperature": {
                "value": 30,
                "unitCode": "CEL"
            },
            "windSpeed": {
                "value": 3,
                "unitCode": "MPH"
            }
        },
        "objectType": "WeatherObserved",
        "providedBy": {
            "object": "urn:ngsi-ld:Device:ABC"
        },
        "object": "urn:ngsi-ld:WeatherObserved:001"
    },
    "prediction": {
        "entity": {
            "id": "urn:ngsi-ld:WeatherForecast:XXX",
            "type": "WeatherForecast",
            "description": "Rain",
            "humidity": {
                "value": 98,
                "unitCode": "PCT"
            },
            "temperature": {
                "value": 30,
                "unitCode": "CEL"
            },
            "windSpeed": {
                "value": 3,
                "unitCode": "MPH"
            }
        },
        "objectType": "WeatherForecast",
        "object": "urn:ngsi-ld:WeatherForecast:XXX"
    },
    "soilType": "Loamy",
    "location": {
        "type": "Point",
        "coords": [
            13,
            58
        ]
    }
}

  • Retrieve entity with concise and flat sub-entities

To retrieve AgriParcel entity in concise format and with flat sub-entities, you can send an HTTP GET to - http://<IP Address>:<port>/ngsi-ld/v1/entities/{entityId}?options=concise&join=flat and we will get target entities returned in list.

GET - http://localhost:9090/ngsi-ld/v1/entities/urn:ngsi-ld:AgriParcel:001?options=concise&join=flat&joinLevel=3

Response:

[
    {
        "id": "urn:ngsi-ld:AgriParcel:001",
        "type": "AgriParcel",
        "cropType": {
            "object": "urn:ngsi-ld:AgriCrop:BuckWheat"
        },
        "observation": {
            "objectType": "WeatherObserved",
            "providedBy": {
                "object": "urn:ngsi-ld:Device:ABC"
            },
            "object": "urn:ngsi-ld:WeatherObserved:001"
        },
        "prediction": {
            "objectType": "WeatherForecast",
            "object": "urn:ngsi-ld:WeatherForecast:XXX"
        },
        "soilType": "Loamy",
        "location": {
            "type": "Point",
            "coords": [
                13,
                58
            ]
        }
    },
    {
        "id": "urn:ngsi-ld:WeatherObserved:001",
        "type": "WeatherObserved",
        "humidity": {
            "value": 80,
            "unitCode": "PCT"
        },
        "temperature": {
            "value": 30,
            "unitCode": "CEL"
        },
        "windSpeed": {
            "value": 3,
            "unitCode": "MPH"
        }
    },
    {
        "id": "urn:ngsi-ld:WeatherForecast:XXX",
        "type": "WeatherForecast",
        "description": "Rain",
        "humidity": {
            "value": 98,
            "unitCode": "PCT"
        },
        "temperature": {
            "value": 30,
            "unitCode": "CEL"
        },
        "windSpeed": {
            "value": 3,
            "unitCode": "MPH"
        }
    }
]

  • Retrieve entities with idsOnly parameter

To retrieve entities with idsOnly parameter, you can send an HTTP GET to - http://<IP Address>:<port>/ngsi-ld/v1/entities/{entityId}?dsOnly=true&joinLevel=3 and we will get target entities ids.

GET - http://localhost:9090/ngsi-ld/v1/entities/urn:ngsi-ld:AgriParcel:001?idsOnly=true&joinLevel=3

Response:

[
    {
        "id": "urn:ngsi-ld:AgriParcel:001"
    },
    {
        "id": "urn:ngsi-ld:WeatherForecast:XXX"
    },
    {
        "id": "urn:ngsi-ld:WeatherObserved:001"
    }
]

  • Retrieve entity in concise format, with inline sub-entities and attribute filters

To retrieve entities with inline sub-entities and attribute filters, you can send an HTTP GET to - http://<IP Address>:<port>/ngsi-ld/v1/entities/{entityId}?options=concise&join=inline&attrs={}.

Example: Give me the data corresponding to soil type and the observed humidity and wind speed

GET - http://localhost:9090/ngsi-ld/v1/entities/urn:ngsi-ld:AgriParcel:001?options=concise&join=inline&attrs=soilType,observation{humidity,windSpeed}&joinLevel=3

Note: You should use URL encoder here for consistency.

Response:

{
    "id": "urn:ngsi-ld:AgriParcel:001",
    "type": "AgriParcel",
    "observation": {
        "entity": {
            "id": "urn:ngsi-ld:WeatherObserved:001",
            "type": "WeatherObserved",
            "humidity": {
                "value": 80,
                "unitCode": "PCT"
            },
            "windSpeed": {
                "value": 3,
                "unitCode": "MPH"
            }
        },
        "objectType": "WeatherObserved",
        "providedBy": {
            "object": "urn:ngsi-ld:Device:ABC"
        },
        "object": "urn:ngsi-ld:WeatherObserved:001"
    },
    "soilType": "Loamy"
}