Add document:upsert

doc/1/controllers/document/m-update/index.md

@@ -17,26 +17,23 @@ Updates multiple documents.
 ## Arguments
 
 ```java
-public CompletableFuture<Map<String, ArrayList<Object>>> mUpdate(
-      String index,
-      String collection,
-      ArrayList<Map<String, Object>> documents)
-throws NotConnectedException, InternalException
-
-public CompletableFuture<Map<String, ArrayList<Object>>> mUpdate(
-      String index,
-      String collection,
-      ArrayList<Map<String, Object>> documents,
-      Boolean waitForRefresh)
-throws NotConnectedException, InternalException
-
-public CompletableFuture<Map<String, ArrayList<Object>>> mUpdate(
-      String index,
-      String collection,
-      ArrayList<Map<String, Object>> documents,
-      Boolean waitForRefresh,
-      Integer retryOnConflict)
-throws NotConnectedException, InternalException
+public CompletableFuture<ConcurrentHashMap<String, ArrayList<Object>>> mUpdate(
+	String index,
+	String collection,
+	ArrayList<ConcurrentHashMap<String, Object>> documents) throws NotConnectedException, InternalException
+
+public CompletableFuture<ConcurrentHashMap<String, ArrayList<Object>>> mUpdate(
+	String index,
+	String collection,
+	ArrayList<ConcurrentHashMap<String, Object>> documents,
+	Boolean waitForRefresh)	throws NotConnectedException, InternalException
+
+public CompletableFuture<ConcurrentHashMap<String, ArrayList<Object>>> mUpdate(
+	String index,
+	String collection,
+	ArrayList<ConcurrentHashMap<String, Object>> documents,
+	Boolean waitForRefresh,
+	Integer retryOnConflict) throws NotConnectedException, InternalException
 ```
 
 | Arguments          | Type                                                    | Description                       |

doc/1/controllers/document/update-by-query/index.md

@@ -30,10 +30,10 @@ An empty or null query will match all documents in the collection.
 
 ```java
   public CompletableFuture<Map<String, ArrayList<Object>>> updateByQuery(
-      String index,
-      String collection,
-      Map<String, Object> searchQuery,
-      Map<String, Object> changes) throws NotConnectedException, InternalException
+    String index,
+    String collection,
+    Map<String, Object> searchQuery,
+    Map<String, Object> changes) throws NotConnectedException, InternalException
 
   public CompletableFuture<Map<String, ArrayList<Object>>> updateByQuery(
     String index,
@@ -125,14 +125,14 @@ With the [Koncorde Filters DSL](/core/2/api/koncorde-filters-syntax) syntax.
 
 ```kotlin
 fun updateByQuery(
-      index: String,
-      collection: String,
-      searchQuery: Map<String, Any?>,
-      changes: Map<String, Any?>,
-      waitForRefresh: Boolean? = null,
-      retryOnConflict: Int? = null,
-      source: Boolean? = null,
-      lang: Lang = Lang.ELASTICSEARCH): CompletableFuture<Map<String, ArrayList<Any?>>>
+  index: String,
+  collection: String,
+  searchQuery: Map<String, Any?>,
+  changes: Map<String, Any?>,
+  waitForRefresh: Boolean? = null,
+  retryOnConflict: Int? = null,
+  source: Boolean? = null,
+  lang: Lang = Lang.ELASTICSEARCH): CompletableFuture<Map<String, ArrayList<Any?>>>
 ```
 
 | Argument           | Type                                         | Description     |

doc/1/controllers/document/upsert/index.md

@@ -0,0 +1,139 @@
+---
+code: true
+type: page
+title: upsert
+description: Applies partial changes to a document. If the document doesn't already exist, a new document is created.
+---
+
+# upsert
+
+<SinceBadge version="Kuzzle 2.8.0"/>
+<SinceBadge version="auto-version" />
+
+Applies partial changes to a document. If the document doesn't already exist, a new document is created.
+
+:::: tabs
+::: tab Java
+
+```java
+  public CompletableFuture<Map<String, Object>> upsert(
+    String index,
+    String collection,
+    Map<String, Object> changes) throws NotConnectedException, InternalException
+
+  public CompletableFuture<Map<String, Object>> upsert(
+    String index,
+    String collection,
+    Map<String, Object> changes,
+    Map<String, Object> defaults) throws NotConnectedException, InternalException
+
+  public CompletableFuture<Map<String, Object>> upsert(
+    String index,
+    String collection,
+    Map<String, Object> changes,
+    Map<String, Object> defaults,
+    Boolean waitForRefresh) throws NotConnectedException, InternalException
+
+  public CompletableFuture<Map<String, Object>> upsert(
+    String index,
+    String collection,
+    Map<String, Object> changes,
+    Map<String, Object> defaults,
+    Boolean waitForRefresh,
+    Integer retryOnConflict) throws NotConnectedException, InternalException
+
+  public CompletableFuture<Map<String, Object>> upsert(
+    String index,
+    String collection,
+    Map<String, Object> changes,
+    Map<String, Object> defaults,
+    Boolean waitForRefresh,
+    Integer retryOnConflict,
+    Boolean source) throws NotConnectedException, InternalException
+```
+
+| Argument     | Type              | Description                               |
+| ------------ | ----------------- | ----------------------------------------- |
+| `index`      | <pre>String</pre> | Index name                                |
+| `collection` | <pre>String</pre> | Collection name                           |
+| `id`         | <pre>String</pre> | Document ID                               |
+| `changes`       | <pre>Map<String, Object></pre> | Partial content of the document to update |
+
+### Options
+
+Additional query options
+
+| Options           | Type<br/>(default)              | Description                                                                        |
+| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
+| `defaults` | <pre>Map<String, Object><br/>(`{}`)        | Fields to add to the document if it gets created    |
+| `waitForRefresh`         | <pre>Boolean</pre><br/>(`""`)    | If set to `true`, waits for the change to be reflected for `search` (up to 1s) |
+| `retryOnConflict` | <pre>Integer</pre><br/>(`10`)        | The number of times the database layer should retry in case of version conflict    |
+| `source`          | <pre>Boolean</pre><br/>(`false`)| If true, returns the updated document inside the response
+
+
+## Returns
+
+A `Map<String, Object>` with the following properties:
+
+| Property     | Type                                         | Description                      |
+|------------- |--------------------------------------------- |--------------------------------- |
+| `_source`    | <pre>Map<String, Object></pre> | Updated document (if `source` option set to true)  |
+| `_id`        | <pre>String</pre>                            | ID of the updated document                   |
+| `_version`   | <pre>Integer</pre>                           | Version of the document in the persistent data storage |
+| `created`     | <pre>Boolean</pre>    
+
+## Usage
+
+<<< ./snippets/upsert-java.java
+
+:::
+::: tab Kotlin
+
+```kotlin
+fun upsert(
+  index: String,
+  collection: String,
+  id: String,
+  changes: Map<String, Any?>,
+  defaults: Map<String, Any?>,
+  waitForRefresh: Boolean? = null,
+  retryOnConflict: Int? = null,
+  source: Boolean? = null): CompletableFuture<Map<String, Any?>>
+```
+
+| Argument     | Type              | Description                               |
+| ------------ | ----------------- | ----------------------------------------- |
+| `index`      | <pre>String</pre> | Index name                                |
+| `collection` | <pre>String</pre> | Collection name                           |
+| `id`         | <pre>String</pre> | Document ID                               |
+| `changes`       | <pre>Map<String, Any?></pre> | Partial content of the document to update |
+
+### Options
+
+Additional query options
+
+| Options           | Type<br/>(default)              | Description                                                                        |
+| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
+| `defaults` | <pre>Map<String, Any?><br/>(`{}`)        | Fields to add to the document if it gets created    |
+| `waitForRefresh`         | <pre>Boolean</pre><br/>(`""`)    | If set to `true`, waits for the change to be reflected for `search` (up to 1s) |
+| `retryOnConflict` | <pre>Integer</pre><br/>(`10`)        | The number of times the database layer should retry in case of version conflict    |
+| `source`          | <pre>Boolean</pre><br/>(`false`)| If true, returns the updated document inside the response
+
+
+## Returns
+
+A `Map<String, Any?>` object, with the following properties:
+
+| Property     | Type                                         | Description                      |
+|------------- |--------------------------------------------- |--------------------------------- |
+| `_source`    | <pre>Map<String, Any?></pre> | Updated document (if `source` option set to true)  |
+| `_id`        | <pre>String</pre>                            | ID of the updated document                   |
+| `_version`   | <pre>Integer</pre>                           | Version of the document in the persistent data storage |
+| `created`     | <pre>Boolean</pre>    
+
+## Usage
+
+<<< ./snippets/upsert-kotlin.kt
+
+:::
+::::

doc/1/controllers/document/upsert/snippets/upsert-java.java

@@ -0,0 +1,17 @@
+Map<String, Object> category = new HashMap<>();
+Map<String, Object> changes = new HashMap<>();
+category.put("category", "suv");
+changes.put("changes", category);
+
+Map<String, Object> result = kuzzle
+    .getDocumentController()
+    .upsert("nyc-open-data", "yellow-taxi", "some-id", changes)
+    .get();
+
+/*
+{
+  created=true
+  _id="some_id",
+  version=1
+}
+*/

doc/1/controllers/document/upsert/snippets/upsert-java.test.yml

@@ -0,0 +1,10 @@
+name: java-document#upsert
+description: Applies a partial update to an existing document.
+hooks:
+  before: |
+    curl -XDELETE kuzzle:7512/nyc-open-data
+    curl -XPOST kuzzle:7512/nyc-open-data/_create
+    curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi
+  after:
+template: print-result
+expected: "{created=true, _id=some-id, _version=1}"

doc/1/controllers/document/upsert/snippets/upsert-kotlin.kt

@@ -0,0 +1,15 @@
+val category: Map<String, Any?> =
+  HashMap<String, Any?>().apply {
+    put("category", "suv")
+  }
+
+val changes: Map<String, Any?> =
+  HashMap<String, Any?>().apply {
+    put("changes", category)  
+  }
+
+val result: Map<String, Any?> =
+  kuzzle
+    .documentController
+    .upsert("nyc-open-data", "yellow-taxi", "some-id", changes)
+    .get()

doc/1/controllers/document/upsert/snippets/upsert-kotlin.test.yml

@@ -0,0 +1,10 @@
+name: kotlin-document#upsert
+description: Applies a partial update to an existing document.
+hooks:
+  before: |
+    curl -XDELETE kuzzle:7512/nyc-open-data
+    curl -XPOST kuzzle:7512/nyc-open-data/_create
+    curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi
+  after:
+template: print-result
+expected: "{created=true, _id=some-id, _version=1}"

src/main/kotlin/io/kuzzle/sdk/controllers/DocumentController.kt

@@ -365,6 +365,40 @@ class DocumentController(kuzzle: Kuzzle) : BaseController(kuzzle) {
         return search(index, collection, searchQuery, null, size, from, Lang.ELASTICSEARCH)
     }
 
+    @JvmOverloads
+    fun upsert(
+        index: String,
+        collection: String,
+        id: String,
+        changes: Map<String, Any?>,
+        defaults: Map<String, Any?>? = null,
+        waitForRefresh: Boolean? = null,
+        retryOnConflict: Int? = null,
+        source: Boolean? = null
+    ): CompletableFuture<Map<String, Any?>> {
+        val query = KuzzleMap().apply {
+            put("index", index)
+            put("collection", collection)
+            put("controller", "document")
+            put("action", "upsert")
+            put(
+                "body",
+                KuzzleMap().apply {
+                    put("changes", changes)
+                    put("defaults", defaults)
+                }
+            )
+            put("_id", id)
+            put("source", source)
+            put("retryOnConflict", retryOnConflict)
+            put("waitForRefresh", waitForRefresh)
+        }
+
+        return kuzzle
+            .query(query)
+            .thenApplyAsync { response -> response.result as Map<String, Any?> }
+    }
+
     @JvmOverloads
     fun update(
         index: String,