From 3a20d15c8af02cfc0225f969453bb70a1228e0ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferm=C3=ADn=20Gal=C3=A1n=20M=C3=A1rquez?= Date: Mon, 28 Aug 2023 11:44:47 +0200 Subject: [PATCH 1/4] FIX improve ordering results documetation in orion-api.md --- doc/manuals/orion-api.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/doc/manuals/orion-api.md b/doc/manuals/orion-api.md index 5d42c96685..3c88d1a46c 100644 --- a/doc/manuals/orion-api.md +++ b/doc/manuals/orion-api.md @@ -78,6 +78,7 @@ - [Subscriptions based in alteration type](#subscriptions-based-in-alteration-type) - [Pagination](#pagination) - [Ordering Results](#ordering-results) + - [Ties](#ties) - [API Routes](#api-routes) - [Entities Operations](#entities-operations) - [Entities List](#entities-list) @@ -2552,6 +2553,42 @@ From lowest to highest: 5. Array 6. Boolean +### Ties + +Note that in the cases of ties, Orion doesn't guarantee that the same query using `orderBy` will result in the same +results sequence. In other words, the tied results could be returned in different relative order when the same query is +repeated. This is the same behaviour that MongoDB (the underlying DB used by Orion) implements (see [this MongoDB documentation](https://www.mongodb.com/docs/manual/reference/method/cursor.sort/). + +Note this may be problematic in the case of pagination. Let's illustrate with the following example. Consider we have four entities (E1 to E4) + +* E1, with attribute `colour` set to `blue` +* E2, with attribute `colour` set to `blue` +* E3, with attribute `colour` set to `red` +* E4, with attribute `colour` set to `red` + +A first execution of `GET /v2/entities?orderBy=colour` could return `E1, E2, E3, E4` but a second execution of the query +could `E2, E1, E4, E3`, a third execution could return `E1, E2, E4, E3`, etc. + +Let's consider a typical paginated sequence of querys like this: + +``` +GET /v2/entities?orderBy=colour&limit=3&offset=0 +GET /v2/entities?orderBy=colour&limit=3&offset=3 +``` + +The same sequence of result is not guaranteed among queries, so in the first query the sequence could be `E1, E2, E3, E4` (so +client would get `E1, E2, E3`) but in the second query it could be (`E1, E2, E4, E3`) so the client will get `E3` again +(instead of the expected `E4`). + +Another similar (more complex case) is described in [this issue illustrates](https://github.com/telefonicaid/fiware-orion/issues/4394)). + +The solution is to add an attribute to `orderBy` to guarantee that ties doesn't occur. In this sense, `dateCreated` [builtin attributes](#builtin-attributes) is a very good candidate, so the above queries could be adapted the following way: + +``` +GET /v2/entities?orderBy=colour,dateCreated&limit=3&offset=0 +GET /v2/entities?orderBy=colour,dateCreated&limit=3&offset=3 +``` + # API Routes ## Entities Operations From ac8f5e409f77e94009cf26da3681f4d177a2a88b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ferm=C3=ADn=20Gal=C3=A1n=20M=C3=A1rquez?= Date: Mon, 28 Aug 2023 11:53:08 +0200 Subject: [PATCH 2/4] FIX typos in orion-api.md --- doc/manuals/orion-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/manuals/orion-api.md b/doc/manuals/orion-api.md index 3c88d1a46c..c6fa30bacf 100644 --- a/doc/manuals/orion-api.md +++ b/doc/manuals/orion-api.md @@ -2576,11 +2576,11 @@ GET /v2/entities?orderBy=colour&limit=3&offset=0 GET /v2/entities?orderBy=colour&limit=3&offset=3 ``` -The same sequence of result is not guaranteed among queries, so in the first query the sequence could be `E1, E2, E3, E4` (so +The same sequence of results is not guaranteed among queries, so in the first query the sequence could be `E1, E2, E3, E4` (so client would get `E1, E2, E3`) but in the second query it could be (`E1, E2, E4, E3`) so the client will get `E3` again (instead of the expected `E4`). -Another similar (more complex case) is described in [this issue illustrates](https://github.com/telefonicaid/fiware-orion/issues/4394)). +Another similar (more complex case) is described in [this issue](https://github.com/telefonicaid/fiware-orion/issues/4394)). The solution is to add an attribute to `orderBy` to guarantee that ties doesn't occur. In this sense, `dateCreated` [builtin attributes](#builtin-attributes) is a very good candidate, so the above queries could be adapted the following way: From 9c925aeafa06d1155045b1a490ec36833ee34d2c Mon Sep 17 00:00:00 2001 From: Kazuhito Suda Date: Mon, 28 Aug 2023 20:10:06 +0900 Subject: [PATCH 3/4] Fix typo --- doc/manuals/orion-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manuals/orion-api.md b/doc/manuals/orion-api.md index c6fa30bacf..fd4d7ca7a5 100644 --- a/doc/manuals/orion-api.md +++ b/doc/manuals/orion-api.md @@ -2569,7 +2569,7 @@ Note this may be problematic in the case of pagination. Let's illustrate with th A first execution of `GET /v2/entities?orderBy=colour` could return `E1, E2, E3, E4` but a second execution of the query could `E2, E1, E4, E3`, a third execution could return `E1, E2, E4, E3`, etc. -Let's consider a typical paginated sequence of querys like this: +Let's consider a typical paginated sequence of queries like this: ``` GET /v2/entities?orderBy=colour&limit=3&offset=0 From 13fc2d9a09868086d8b04c1c82aa38c2af22be8c Mon Sep 17 00:00:00 2001 From: Kazuhito Suda Date: Mon, 28 Aug 2023 20:12:42 +0900 Subject: [PATCH 4/4] (JP) FIX improve ordering results documentation in orion-api.md (#4405) --- doc/manuals.jp/orion-api.md | 43 +++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/doc/manuals.jp/orion-api.md b/doc/manuals.jp/orion-api.md index 7ae7a3a8c0..a6ce23ffaa 100644 --- a/doc/manuals.jp/orion-api.md +++ b/doc/manuals.jp/orion-api.md @@ -78,6 +78,7 @@ - [変更タイプに基づくサブスクリプション (Subscriptions based in alteration type)](#subscriptions-based-in-alteration-type) - [ページネーション (Pagination)](#pagination) - [結果の順序付け (Ordering Results)](#ordering-results) + - [同値 (Ties)](#ties) - [API ルート (API Routes)](#api-routes) - [エンティティの操作 (Entities Operations)](#entities-operations) - [エンティティのリスト (Entities List)](#entities-list) @@ -2533,6 +2534,48 @@ GET /v2/entities?orderBy=temperature,!humidity 5. Array 6. Boolean + + +### 同値 (Ties) + +同値 (ties) の場合、Orion は `orderBy` を使用した同じクエリが同じ結果シーケンスをもたらすことを保証しないことに +注意してください。つまり、同じクエリが繰り返されると、関連付けられた結果が異なる相対順序で返される可能性があります。 +これは、MongoDB (Orion によって使用される基礎となる DB) が実装する動作と同じです +([この MongoDB ドキュメント](https://www.mongodb.com/docs/manual/reference/method/cursor.sort/) を参照) + +これはページネーションの場合に問題となる可能性があることに注意してください。次の例で説明してみましょう。 +4つのエンティティ (E1～E4) があるとします: + +* E1, 属性 `colour` を `blue` に設定 +* E2, 属性 `colour` を `blue` に設定 +* E3, 属性 `colour` を `red` に設定 +* E4, 属性 `colour` を `red` に設定 + +`GET /v2/entities?orderBy=colour` の最初の実行では `E1, E2, E3, E4` が返される可能性がありますが、クエリの2回目の実行では +`E2, E1, E4, E3` が返され、3回目の実行では `E1, E2, E4, E3` などが返される可能性があります。 + +次のような典型的なページ分割された一連のクエリを考えてみましょう: + +``` +GET /v2/entities?orderBy=colour&limit=3&offset=0 +GET /v2/entities?orderBy=colour&limit=3&offset=3 +``` + +クエリ間で同じ結果の順序が保証されていないため、最初のクエリでは順序が `E1, E2, E3, E4` になる可能性があります (したがって、 +クライアントは `E1, E2, E3` を取得します)。2回目のクエリでは、シーケンスが (`E1、E2、E4、E3`) のようになる可能性があります。 +したがって、クライアントは (予期された `E4` ではなく) 再び `E3` を取得します。 + +別の同様の (より複雑なケース) については、[この issue](https://github.com/telefonicaid/fiware-orion/issues/4394) +で説明しています。 + +解決策は、別の属性を `orderBy` に追加して、同値が発生しないことを保証することです。この意味で、`dateCreated` +[組み込み属性](#builtin-attributes) は非常に良い候補であるため、上記のクエリは次のように適応できます: + +``` +GET /v2/entities?orderBy=colour,dateCreated&limit=3&offset=0 +GET /v2/entities?orderBy=colour,dateCreated&limit=3&offset=3 +``` + # API ルート (API Routes)