Transient Entities
A transient entity is a regular entity (i.e. it has id/type, a set of attributes, etc.) but with a expiration timestamp. When such point in time is reached the entity is automatically deleted from the context managed by Orion.
Thus, a first and very important piece of advice: be careful if you use transient entities as once the expiration time has come, the entity will be automatically deleted from database and there is no way of recovering it. Ensure the information you set in a transient entity is not relevant once the entity has expired (i.e. deleted).
In addition, have a look to the backward compatibility considerations section
in the case you are already using attributes with the exact name dateExpires
.
The dateExpires
attribute
The expiration timestamp of an entity is defined by means of the dateExpires
NGSIv2 builtin attribute. This is an
attribute of DateTime
type, according to the NGSIv2 specification.
Its value is the datetime when the entity will expire.
As any other NGSIv2 builtin attribute, dateExpires
is not shown by default, you need to use attrs
URI parameter (in GET
based queries) or "attrs"
field (in POST /v2/op/query
) in order to get it. Please have a look to sections "Builtin Attributes"
and "Filtering out attributes and metadata" in the NGSIv2 specification
for more details.
Valid transitions
Create entity with dateExpires
attribute
An entity is created with transient nature if it includes the dateExpires
attribute. For instance:
POST /v2/entities
{
"id": "t1",
"type": "Ticket",
...
"dateExpires": {
"value": "2028-07-07T21:35:00Z",
"type": "DateTime"
}
}
creates an entity that will expire at July 7th, 2028 at 21:35 UTC.
Additional considerations:
-
dateExpires
has to have a validDateTime
value (check NGSIv2 specification for details). Otherwise a 400 Bad Request would be returned. -
If
dateExpires
is set in the past, the entity is created expired (a bit weird, but functionally correct).
Add dateExpires
attribute to entity that previously doesn't have it
We can add the dateExpires
attribute to a regular entity (e.g. "t2"). For instance:
POST /v2/entities/t2/attrs
{
"dateExpires": {
"value": "2028-10-12T14:23:00Z",
"type": "DateTime"
}
}
will make that entity to expire on October 12th, 2028 at 14:23 UTC.
Additional considerations:
-
dateExpires
has to have a validDateTime
syntax (check NGSIv2 specification for details). Otherwise a 400 Bad Request would be returned. -
If
dateExpires
is set in the past, the entity gets automatically expired.
Update dateExpires
attribute in entity that previously has it
Context Broker allows several ways of updating an attribute value (check NGSIv2 specification for details). For instance using PUT on the attribute resource URL:
PUT /v2/entities/t2/attrs/dateExpires
{
"value": "2028-12-31T23:59:00Z",
"type": "DateTime"
}
will change expiration date to December 31th, 2028 at 23:59 UTC.
Additional considerations:
-
dateExpires
has to have a validDateTime
syntax (check NGSIv2 specification for details). Otherwise a 400 Bad Request would be returned. -
If
dateExpires
is set in the past, the entity gets automatically expired
Remove dateExpires
attribute from entity
Finally, you can remove dateExpires
attribute from a transient entity:
DELETE /v2/entities/t2/attrs/dateExpires
This become the entity into a regular (i.e. not transient) entity and will not be deleted due to expiration.
Deletion of expired entities
Expiration relies on the MongoDB feture to expire documents at a specific clock time. This is based in a background thread thats wakes up every 60 seconds, so your transient entities may remain in the database up to 60 seconds (or a bit more, if the MongoDB load is high) after expiration date (see MongoDB documentation for more details).
The default sleep interval for the TTL monitor thread can be changed in MongoDB, but that topic is out of the scope of this document. Have a look to this link for more detail.
Once a transient entity is removed, it cannot be recovered.
Backward compatibility considerations
Transient entity were introduced in Orion 1.15.0. Up to Orion 1.14.0 dateExpires
is interpreted as a regular
attribute without any special semantic. So, what would happen in the case you are already using an attribute
named dateExpires
in your application before upgrading to Orion 1.15.0?
Existing entities using dateExpires
will keep using it in the same way until the attribute gets updated.
That is, if dateExpires
is not a DateTime
(e.g. a number, a regular string, etc.) it will keep with
the same value (e.g. in GET operations, etc.). If dateExpires
is a DateTime
that datetime will not be
interpreted as an expiration date (i.e. the entity will not be deleted after the datetime passes).
However, even in the case the attribute would keep its previous value without any special semantic, note
that dataExpires
becomes a builtin attribute, so it is not shown except if explicetly requested with
attrs
URI parameter (in GET based queries) or "attrs"
field (in POST /v2/op/query
).
Once dateExpires
attribute get updated for first time, it will start to mean an expiration date on the given
entity, with the behaviour described in previous section. Please, take this into account in the case
you were implementing client-side expiration based on the value of that attribute, as your entities could
be automatically deleted in an unwanted way.