diff --git a/md/annex-b.md b/md/annex-b.md index bf85277b9693f17b2256a6d4cb60cff184e9b645..3f8b5bc0fe7a5dc39ba11543f6274d77dfb8f878 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", diff --git a/md/clause-11.md b/md/clause-11.md index fd179151a3bcfb3b0b967147a1e5e6e0915ecedd..ba294fa63323e61de27278b6c19d272c3a980880 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). diff --git a/md/clause-5.md b/md/clause-5.md index 49248b6de99749a7bb4e0171222650cae3634243..d111c0505c4c8d58b073c764c92dafc4cdfaf695 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. | diff --git a/md/clause-7.md b/md/clause-7.md index 901fa73fc014b672b9564e19fee70347474b59ee..992021c8bcfc3296974c52bbdffbd8e8ef6c7722 100644 --- a/md/clause-7.md +++ b/md/clause-7.md @@ -1729,6 +1729,22 @@ 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. 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 Given that NGSI-LD Query operations can potentially return a result set