Federation

A federation is a distributed setup in which each context source is a whole domain, not a single database or gateway. Think of a city where the parks department, the transport company and the water utility each run their own NGSI-LD broker. An application shouldn't have to know all three. It asks one broker, the federation broker, and gets one answer.

Everything in Distributed applies unchanged. A domain is registered like any other context source, and Andromeda forwards, merges and warns the same way. This page covers what is different when the sources are whole brokers run by other teams.

Registering a domain

A domain holds many kinds of entity in a wide area, so you describe it coarsely. Instead of listing buildings one by one, you register that the domain has entities of some types, within some area or Scope.

POST /ngsi-ld/v1/csourceRegistrations
Content-Type: application/json

{
    "id": "urn:ngsi-ld:ContextSourceRegistration:parks-department",
    "type": "ContextSourceRegistration",
    "information": [
        {
            "entities": [
                {
                    "type": "Park"
                },
                {
                    "type": "Tree"
                }
            ]
        }
    ],
    "location": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    2.2,
                    48.8
                ],
                [
                    2.5,
                    48.8
                ],
                [
                    2.5,
                    48.95
                ],
                [
                    2.2,
                    48.95
                ],
                [
                    2.2,
                    48.8
                ]
            ]
        ]
    },
    "scope": "/city/parks",
    "endpoint": "https://parks.example.org/"
}

endpoint is the domain broker's API root. The domain needs nothing beyond the ordinary NGSI-LD API, and can run any broker that implements it, not only Andromeda.

The registration has no propertyNames, so the domain is asked about any attribute of a Park or a Tree. location and scope narrow the requests that reach it.

• A geoquery goes only to domains whose location it can touch. A domain registered without a location may hold entities anywhere, so it is always asked.
• A scopeQ goes only to domains whose scope it matches, and a domain with no scope is asked as well.

So a query for trees inside one neighbourhood reaches the parks department and leaves the water utility alone.

Choosing a mode for a domain

An inclusive registration, the default, fits a domain best. The domain adds to what you hold, and answers are merged. An exclusive registration needs entity ids and attributes, so it suits a single entity, not a domain. Use redirect when the domain owns everything the registration covers and you hold none of it yourself. Distributed describes all four modes.

Domains with their own sources

A domain broker can have context sources of its own, and can itself be a federation of sub-domains. A request then travels down the chain, from your broker to the domain, and from the domain to its sources. Each hop merges the answers it gets.

Two registrations that lead back to each other would send a request around in circles. Andromeda recognises a request that would loop back to where it has already been, doesn't send it, and adds a 199 warning to the answer.

What to expect

• A domain that is down or slow doesn't fail the answer. The rest of the domains answer, with a warning that names the one that failed. Distributed covers the cooldown that keeps a failing domain from slowing every request.
• A domain's answers are checked as if you had written them locally. An entity that a local write would refuse is left out, and the answer says so in a warning.
• A large answer is bounded. Andromeda reads every domain's answer before it cuts your page, and a query that gathers too many entities is refused. The federation.query.max_entities setting is the limit, and Distributed operations explains it.
• To remember which domain answered which entity, use an entity map. To hear when a domain registers, changes or leaves, use a source subscription.

Registering a domain makes the broker send requests to its address. Security explains what to restrict.