Batches

Batches use /ngsi-ld/v1/entityOperations.

A batch applies one operation to many entities in one request. The body is an array of entities, or of entity identifiers for a delete.

http
curl
rust
python

POST /ngsi-ld/v1/entityOperations/create
Content-Type: application/json

[
    {
        "id": "urn:ngsi-ld:Vehicle:A1",
        "type": "Vehicle"
    },
    {
        "id": "urn:ngsi-ld:Vehicle:A2",
        "type": "Vehicle"
    }
]

curl -i http://localhost:1056/ngsi-ld/v1/entityOperations/create \
  -H 'Content-Type: application/json' \
  -d '[
    {
        "id": "urn:ngsi-ld:Vehicle:A1",
        "type": "Vehicle"
    },
    {
        "id": "urn:ngsi-ld:Vehicle:A2",
        "type": "Vehicle"
    }
]'

let vehicles = [
    Entity::builder()
        .id(iri!("urn:ngsi-ld:Vehicle:A1"))
        .entity_type("Vehicle")
        .build()?,
    Entity::builder()
        .id(iri!("urn:ngsi-ld:Vehicle:A2"))
        .entity_type("Vehicle")
        .build()?,
];

if let BatchCreateOutcome::Partial(result) =
    client.entities().batch_create(&vehicles).send().await?
{
    for error in &result.errors {
        println!("{} failed: {:?}", error.entity_id, error.error.error_type);
    }
}

response = requests.post(
    f"{BASE}/entityOperations/create",
    json=[
        {
            "id": "urn:ngsi-ld:Vehicle:A1",
            "type": "Vehicle",
        },
        {
            "id": "urn:ngsi-ld:Vehicle:A2",
            "type": "Vehicle",
        },
    ],
)
assert response.status_code in (201, 207)

HTTP/1.1 201 Created
Content-Type: application/json

[
    "urn:ngsi-ld:Vehicle:A1",
    "urn:ngsi-ld:Vehicle:A2"
]

The five batch operations are as follows.

POST /entityOperations/create creates every entity and answers 201 with the identifiers.
POST /entityOperations/upsert creates the entities that don't exist and replaces the ones that do. It answers 201 with the identifiers it created, or 204 when it created none.
POST /entityOperations/update appends attributes to existing entities, overwriting by default, and answers 204.
POST /entityOperations/merge merges each entity, as a single merge does, and answers 204.
POST /entityOperations/delete deletes the entities whose identifiers the array lists, and answers 204.

upsert replaces the existing entities by default. With ?options=update, it appends to them instead, so an attribute you leave out of the body stays.

Partial failure

Each entity succeeds or fails on its own. When any fails, the answer is 207 with a success list and an errors list. Each error names its entity and carries a full problem document. Nothing is rolled back, so the successes stay written even though the request as a whole failed.

A fault in the batch as a whole refuses the request with 400 before any entity is written. A body that isn't an array is an example. Errors shows the 207 body.

Batches take only application/json and application/ld+json, never application/merge-patch+json.

Partial failure​

Partial failure