Skip to main content

Guides

The guides show the NGSI-LD API by example. Each one covers the common case with requests you can adapt, then points to the behaviour pages for the exact rules, so you can read them in any order. If you haven't run the broker yet, start with the quickstart.

Writing data​

Begin with the data model if NGSI-LD is new to you. It explains entities, the kinds of attribute, attributes on attributes, the @context and the shapes an answer can take, which every other guide assumes. JSON-LD explains where the short names in your JSON come from.

Entities covers writing, with a page for each of the seven operations, create, append, update, merge, replace, delete and batches. It shows what each write leaves behind and what it silently drops.

Concepts​

Datasets explains how one attribute can hold several values side by side, each with its own life. Timestamps separates the broker's clocks from your observedAt and expiresAt. Scopes stamps entities into hierarchies that you can filter with scopeQ.

Querying​

Filtering with q selects entities by what their attributes hold. Geoqueries select entities by place and return answers as GeoJSON. Temporal shows how to write and read history, with time windows, lastN, paging and aggregation. Multilingual queries choose which language a read returns and filter by language. Discovery lists which types and attributes exist and how widely they are used.

Notifications​

Subscriptions tell you when entities change. The guide creates one, watches a notification arrive, shapes what the notification holds, paces it, and pauses, changes and deletes the subscription.

Copies​

Snapshots freeze query results into a consistent copy that you can read, write and clone.

Distributed​

Distributed is for the day your data lives in more than one system. It explains how to register other systems as context sources, which requests reach them, and what happens when one fails. Federation covers sources that are whole brokers run by other teams. Entity maps remember which sources answered a query, and source subscriptions let you watch the registrations instead of the entities.

Running the examples​

Every request is shown as the raw HTTP request, with curl, with the Rust ngsi-ld crate, and with Python and requests. Pick one and every guide follows. The four versions send the same request, with the same path, query, headers and body, to a broker on localhost:1056, the default port. The http and curl examples are complete as they stand.

The Rust examples use the crate's typed values throughout. An entity identifier is an EntityId built from a checked IRI literal, an attribute name is an AttributeName that has been parsed, and attributes and queries are built with the crate's builders. A malformed identifier, name or filter is a compile error or a ? before any request leaves the machine. They run inside an async function that returns a Result, with a client built like this:

use iri_rs::iri;
use ngsi_ld::client::{Client, ReqwestTransport};
use url::Url;

let client = Client::builder()
    .base_url(Url::parse("http://localhost:1056/ngsi-ld/v1/")?)
    .transport(ReqwestTransport::try_default()?)
    .build()?;

The examples leave out their other use lines, and use values such as id for an entity identifier without building them each time. Build one the same way, with EntityId::from(iri!("urn:ngsi-ld:Vehicle:A4567")). The types are in the modules of the ngsi_ld crate, such as ngsi_ld::model and ngsi_ld::query.

The Python examples use requests, with the base URL of the API. Constants such as an entity's URL are built from it:

import requests

BASE = "http://localhost:1056/ngsi-ld/v1"
ENTITY = f"{BASE}/entities/urn:ngsi-ld:Vehicle:A4567"
Last updated on