From 1000003689868947cc2e0477819534e57151e7ed Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Mon, 24 Nov 2025 15:08:56 +0000 Subject: [PATCH 1/5] Added clause 7.4.2.5 Temporal pagination --- md/clause-7.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/md/clause-7.md b/md/clause-7.md index 901fa73..fd225bc 100644 --- a/md/clause-7.md +++ b/md/clause-7.md @@ -1729,6 +1729,21 @@ Entities no longer fulfilling the filter criteria of the query. As a result, the first page when going backward, and the last page, when going forward, may have less than the maximum number of Entities. +#### 7.4.2.5 Temporal pagination + +Temporal representation of resources adds an additional dimension to the pagination. +Depending on the requested time range, the response will contain multiple instances +of the requested Attribute, and therefore an additional pagination mechanism for +those temporal representations is required, in order to limit the time range of the +response. If no limits are specified, a default limit is enforced, depending on +implementation specific configurations. + +Temporal pagination can be done in ascending order using the _`firstN`_ parameter +and in descending order using the _`lastN`_ parameter, whose respective value (N) +indicates the **limit**, i.e. the maximum number of temporal instances of any +Attribute allowed on a page. _`offset`_ is used to select the respective page +in the chosen order. + ## 7.5 Counting results Given that NGSI-LD Query operations can potentially return a result set -- GitLab From cfffa4afd4b63934c148904b3397ac5abc8c2ab5 Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Mon, 24 Nov 2025 17:14:19 +0000 Subject: [PATCH 2/5] Added offsetN as separate parameter --- md/clause-7.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/md/clause-7.md b/md/clause-7.md index fd225bc..992021c 100644 --- a/md/clause-7.md +++ b/md/clause-7.md @@ -1741,8 +1741,9 @@ implementation specific configurations. Temporal pagination can be done in ascending order using the _`firstN`_ parameter and in descending order using the _`lastN`_ parameter, whose respective value (N) indicates the **limit**, i.e. the maximum number of temporal instances of any -Attribute allowed on a page. _`offset`_ is used to select the respective page -in the chosen order. +Attribute allowed on a page. If the transparent behaviour described in +Clause+++root.4.2.3 is applied to temporal pagination, _`offsetN`_ is used to select +the respective page in the chosen order. ## 7.5 Counting results -- GitLab From 0adecf8c2083b19e13f1d7c566d49bf1bbaa045d Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Tue, 25 Nov 2025 14:36:07 +0000 Subject: [PATCH 3/5] Added parameters to temporal query --- md/clause-11.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/md/clause-11.md b/md/clause-11.md index fd17915..ba294fa 100644 --- a/md/clause-11.md +++ b/md/clause-11.md @@ -553,9 +553,15 @@ Figure: Retrieve Temporal Evolution of an Entity use case (optional). - An NGSI-LD temporal query as mandated by Clause+++clause-7+++root.2.6 (optional). +- A parameter (_`firstN`_) conveying that only the first N instances (per + Attribute) within the concerned temporal interval shall be retrieved + (optional). - A parameter (_`lastN`_) conveying that only the last N instances (per Attribute) within the concerned temporal interval shall be retrieved (optional). +- A parameter (_`offsetN`_) conveying the offset when paginating temporal + Attribute instances (optional). To be used in combination with _`firstN`_ + (ascending order) or _`lastN`_ (descending order). - An optional JSON-LD context. - A flag indicating whether to return the location of the [Entity Map]{.HTML-Keyboard} used within the operation (optional). @@ -717,8 +723,15 @@ Figure: Query Temporal Evolution of Entities use case per Clause+++clause-7+++root.2.3 (optional). - A limit to the number of Entities to be retrieved. See Clause+++clause-7+++root.4.2. -- A parameter (lastN) conveying that only the last N instances (per Attribute) - within the concerned temporal interval shall be retrieved (optional). +- A parameter (_`firstN`_) conveying that only the first N instances (per + Attribute) within the concerned temporal interval shall be retrieved + (optional). +- A parameter (_`lastN`_) conveying that only the last N instances (per + Attribute) within the concerned temporal interval shall be retrieved + (optional). +- A parameter (_`offsetN`_) conveying the offset when paginating temporal + Attribute instances (optional). To be used in combination with _`firstN`_ + (ascending order) or _`lastN`_ (descending order). - A specified language filter as per Clause+++clause-7+++root.2.7 (optional). - A list (one or more) of Attribute names whose values shall be expanded to URIs prior to executing a query (optional). -- GitLab From 373a2d485b89cdb1cfe4ed08f5246feeb4e2b109 Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Tue, 25 Nov 2025 14:58:19 +0000 Subject: [PATCH 4/5] Added firstN and offsetN for temporal queries --- md/clause-5.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/md/clause-5.md b/md/clause-5.md index 49248b6..d111c05 100644 --- a/md/clause-5.md +++ b/md/clause-5.md @@ -409,6 +409,8 @@ Table: Matrix of all Attributes +--------------------------------+-----------------------------------------------------------------------+ | features | FeatureCollection | +--------------------------------+-----------------------------------------------------------------------+ +| firstN | TemporalParams | ++--------------------------------+-----------------------------------------------------------------------+ | format | NotificationParams | +--------------------------------+-----------------------------------------------------------------------+ | geoQ | Feature, Query, Subscription | @@ -507,6 +509,8 @@ Table: Matrix of all Attributes | | LanguageProperty, JsonProperty, VocabProperty | | | | +--------------------------------+-----------------------------------------------------------------------+ +| offsetN | TemporalParams | ++--------------------------------+-----------------------------------------------------------------------+ | omit | Query, NotificationParams | +--------------------------------+-----------------------------------------------------------------------+ | operations | CSourceRegistration | @@ -2070,7 +2074,7 @@ Table: Query data type definition +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | scopeQ | String | See Clause+++clause-7+++7.2.5 | 0..1 | Scope query. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ -| temporalQ | TemporalQuery | See data type definition in Clause+++root.2.6.7.4 | 0..1 | Temporal Query to be present only for "Query | +| temporalQ | TemporalParams | See data type definition in Clause+++root.2.6.7.4 | 0..1 | Temporal Query to be present only for "Query | | | | | | [Temporal Evolution of Entities]{.HTML-Keyboard}" operation (Clause+++clause-11+++11.3.3). | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | attrs | String[] | Attribute name as short hand strings or URIs. | 0..1 | A synonym for a combination of the *pick* and*q* members. **Deprecated** | @@ -2197,7 +2201,7 @@ Table: Subscription data type definition +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | scopeQ | String | See Clause+++clause-7+++7.2.5 | 0..1 | Scope query. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ -| temporalQ | TemporalQuery | See data type definition in Clause+++root.2.6.7.4 | 0..1 | Temporal Query to be used **only** in *Context Registration Subscriptions* | +| temporalQ | TemporalParams | See data type definition in Clause+++root.2.6.7.4 | 0..1 | Temporal Query to be used **only** in *Context Registration Subscriptions* | | | | | | for matching [Context Source Registrations]{.HTML-Keyboard} of | | | | | | [Context Sources]{.HTML-Keyboard} providing temporal information. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ @@ -3026,7 +3030,11 @@ Table: TemporalParams data type definition | endTimeAt | String representing the _`endTimeAt`_ parameter as defined by | It shall be a _DateTime_. Cardinality shall be 1 if _`timerel`_ is equal to ["between"]{.HTML-Code} | 0..1 | | | | Clause+++clause-7+++7.2.6 | | | | +--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| lastN | Positive integer | | 0..1 | Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. | +| firstN | Positive integer | Cannot be used in combination with _`lastN`_. | 0..1 | Only the first n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. This is relative to _`offsetN`_ parameter if specified. | ++--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lastN | Positive integer | Cannot be used in combination with _`firstN`_. | 0..1 | Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. This is relative to _`offsetN`_ parameter if specified. | ++--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| offsetN | Positive integer | Shall only be used in combination with either _`firstN`_ or _`lastN`_. | 0..1 | Provides the offset for temporal pagination (ascending in case of _`firstN`_ and descending in case of _`lastN`_) | +--------------------+-------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | timeproperty | String representing a Temporal Property name | Allowed values: ["observedAt"]{.HTML-Code}, ["createdAt"]{.HTML-Code}, ["modifiedAt"]{.HTML-Code} and ["deletedAt"]{.HTML-Code}. If not specified, the default is ["observedAt"]{.HTML-Code}. (See Clause+++root.2.4) | 0..1 | | | | | | | Only applicable if ["aggregatedValues"]{.HTML-Code} is present in the _`format`_ or _`options`_ parameter. | -- GitLab From 44eb54868e3918d901cd1f7bf6484c024b48766f Mon Sep 17 00:00:00 2001 From: Martin Bauer Date: Tue, 25 Nov 2025 16:23:54 +0000 Subject: [PATCH 5/5] Added temporal parameters --- md/annex-b.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/md/annex-b.md b/md/annex-b.md index bf85277..3f8b5bc 100644 --- a/md/annex-b.md +++ b/md/annex-b.md @@ -163,6 +163,7 @@ Such definition has been tested using [i.19]. "@container": "@set", "@id": "geojson:features" }, + "firstN": "ngsi-ld:firstN", "format": "ngsi-ld:format", "geoQ": "ngsi-ld:geoQ", "geometry": "geojson:geometry", @@ -281,6 +282,7 @@ Such definition has been tested using [i.19]. "@id": "ngsi-ld:observedAt", "@type": "DateTime" }, + "offsetN": "ngsi-ld:offsetN", "omit": "ngsi-ld:omit", "operations": "ngsi-ld:operations", "operationSpace": "ngsi-ld:operationSpace", -- GitLab