FIX improve ordering results documetation in orion-api.md

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
 
+<a name="ties"></a>
+
+### 同値 (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
+```
+
 <a name="api-routes"></a>
 
 # API ルート (API Routes)

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 queries like this:
+
+```
+GET /v2/entities?orderBy=colour&limit=3&offset=0
+GET /v2/entities?orderBy=colour&limit=3&offset=3
+```
+
+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](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