Purge dataset scope

Purge single datasetId instances of an attribute across many entities, instead of the whole attribute. DELETE /entities?type=Vehicle&drop=speed&datasetId=urn:ngsi-ld:Dataset:1 removes only the Dataset:1 instance of speed. Off by default.

At a glance

• Setting: extensions.purge_dataset_scope.mode, "disabled" (default) or "enabled"
• Environment variable: ANDROMEDA__EXTENSIONS__PURGE_DATASET_SCOPE__MODE
• Advertised as: purgeDatasetScope in contextSourceExtras.extensions
• Context sources: datasetId and deleteAll are forwarded with the purge, whether the source advertises the extension or not
• When off: datasetId and deleteAll on Purge Entities get 400 InvalidRequest

Turning it on

[extensions.purge_dataset_scope]
mode = "enabled"

Purge Entities (DELETE /entities) is a standard operation and is always there. Only its datasetId and deleteAll parameters belong to the extension.

Using it

DELETE /ngsi-ld/v1/entities?type=Vehicle&drop=speed&datasetId=urn:ngsi-ld:Dataset:1

The extension adds precision to a drop or keep purge. It doesn't change what a plain purge does:

Request	Removes
drop=speed	all of speed, every instance
drop=speed&deleteAll=true	all of speed, said explicitly
drop=speed&datasetId=urn:ngsi-ld:Dataset:1	only the Dataset:1 instance of speed
drop=speed&datasetId=@none	only the default instance of speed
keep=speed&datasetId=urn:ngsi-ld:Dataset:1	the Dataset:1 instance of every attribute except speed

Watch out for one difference from Delete Attribute. There, a plain delete removes only the default instance. Here, a plain drop or keep still removes the whole attribute, as the specification defines for Purge Entities.

What gets refused

• 400 BadRequestData for datasetId together with deleteAll, whether the extension is on or not

  deleteAll already means every dataset. Send one or the other.

Context sources

Purge Entities is forwarded to the matching registrations, and datasetId and deleteAll go with it, whether or not the source advertises purgeDatasetScope. A source without the extension answers them as it answers any parameter it doesn't support.

Why it is an extension

In the specification, Purge Entities removes whole attributes with drop and keep. Deleting one datasetId instance, or the default one, exists only for Delete Attribute, and only on one entity. Purge Entities has no such parameter, and a parameter an operation doesn't define is refused.

A bare drop keeps its standard meaning on purpose: changing what a plain purge removes would break conformance.