Commit 68885631 authored by Giuseppe Tropea's avatar Giuseppe Tropea
Browse files

Merge branch 'fix/pagination_on_temporal_instances' into 'master' 

DATA(25)000177_NGSI-LD_Core_Temporal_Pagination

See merge request !18
parents cf3beac8 44eb5486

md/annex-b.md

+2 −0
Original line number Diff line number Diff line
@@ -155,6 +155,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",
@@ -305,6 +306,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",

md/clause-11.md

+15 −2
Original line number Diff line number Diff line
@@ -577,9 +577,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).
@@ -741,8 +747,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).

md/clause-5.md

+11 −3
Original line number Diff line number Diff line
@@ -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.                                                                                                                                               |

md/clause-7.md

+16 −0
Original line number Diff line number Diff line
@@ -1734,6 +1734,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