Add document:upsert

build.gradle.kts

@@ -156,4 +156,5 @@ tasks.withType<Jar> {
             )
         )
     }
+    from(configurations.compileClasspath.get().map { if (it.isDirectory()) it else zipTree(it) })
 }

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

@@ -27,7 +27,15 @@ public CompletableFuture<ConcurrentHashMap<String, ArrayList<Object>>> mUpdate(
       String index,
       String collection,
       ArrayList<ConcurrentHashMap<String, Object>> documents,
-      UpdateOptions options)
+      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
 ```
 

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

@@ -20,18 +20,35 @@ An empty or null query will match all documents in the collection.
 
 
 ```java
-  public CompletableFuture<ConcurrentHashMap<String, ArrayList<Object>>> updateByQuery(
+    public CompletableFuture<ConcurrentHashMap<String, ArrayList<Object>>> updateByQuery(
+        String index,
+        String collection,
+        ConcurrentHashMap<String, Object> searchQuery,
+        ConcurrentHashMap<String, Object> changes) throws NotConnectedException, InternalException
+
+    public CompletableFuture<ConcurrentHashMap<String, ArrayList<Object>>> updateByQuery(
+    String index,
+    String collection,
+    ConcurrentHashMap<String, Object> searchQuery,
+    ConcurrentHashMap<String, Object> changes,
+    Boolean waitForRefresh) throws NotConnectedException, InternalException
+
+    public CompletableFuture<ConcurrentHashMap<String, ArrayList<Object>>> updateByQuery(
       String index,
       String collection,
       ConcurrentHashMap<String, Object> searchQuery,
-      ConcurrentHashMap<String, Object> changes) throws NotConnectedException, InternalException
-
-  public CompletableFuture<ConcurrentHashMap<String, ArrayList<Object>>> updateByQuery(
+      ConcurrentHashMap<String, Object> changes,
+      Boolean waitForRefresh,
+      Integer retryOnConflict) throws NotConnectedException, InternalException
+
+    public CompletableFuture<ConcurrentHashMap<String, ArrayList<Object>>> updateByQuery(
       String index,
       String collection,
       ConcurrentHashMap<String, Object> searchQuery,
       ConcurrentHashMap<String, Object> changes,
-      UpdateOptions options) throws NotConnectedException, InternalException
+      Boolean waitForRefresh,
+      Integer retryOnConflict,
+      Boolean source) throws NotConnectedException, InternalException
 ```
 
 | Argument           | Type                                         | Description     |

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

@@ -0,0 +1,138 @@
+---
+code: true
+type: page
+title: upsert
+---
+
+# 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<ConcurrentHashMap<String, Object>> upsert(
+    String index,
+    String collection,
+    ConcurrentHashMap<String, Object> changes) throws NotConnectedException, InternalException
+
+  public CompletableFuture<ConcurrentHashMap<String, Object>> upsert(
+    String index,
+    String collection,
+    ConcurrentHashMap<String, Object> changes,
+    ConcurrentHashMap<String, Object> defaults) throws NotConnectedException, InternalException
+
+  public CompletableFuture<ConcurrentHashMap<String, Object>> upsert(
+    String index,
+    String collection,
+    ConcurrentHashMap<String, Object> changes,
+    ConcurrentHashMap<String, Object> defaults,
+    Boolean waitForRefresh) throws NotConnectedException, InternalException
+
+  public CompletableFuture<ConcurrentHashMap<String, Object>> upsert(
+    String index,
+    String collection,
+    ConcurrentHashMap<String, Object> changes,
+    ConcurrentHashMap<String, Object> defaults,
+    Boolean waitForRefresh,
+    Integer retryOnConflict) throws NotConnectedException, InternalException
+
+  public CompletableFuture<ConcurrentHashMap<String, Object>> upsert(
+    String index,
+    String collection,
+    ConcurrentHashMap<String, Object> changes,
+    ConcurrentHashMap<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>ConcurrentHashMap<String, Object></pre> | Partial content of the document to update |
+
+### Options
+
+Additional query options
+
+| Options           | Type<br/>(default)              | Description                                                                        |
+| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
+| `defaults` | <pre>ConcurrentHashMap<String, Object><br/>(`{}`)        | (optional) 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 `ConcurrentHashMap<String, Object>` with the following properties:
+
+| Property     | Type                                         | Description                      |
+|------------- |--------------------------------------------- |--------------------------------- |
+| `_source`    | <pre>ConcurrentHashMap<String, Object></pre> | Updated document (if `source` option set to true)  |
+| `_id`        | <pre>String</pre>                            | ID of the udated 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: ConcurrentHashMap<String, Any?>,
+      defaults: ConcurrentHashMap<String, Any?>,
+      waitForRefresh: Boolean? = null,
+      retryOnConflict: Int? = null,
+      source: Boolean? = null): CompletableFuture<ConcurrentHashMap<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>ConcurrentHashMap<String, Any?></pre> | Partial content of the document to update |
+
+### Options
+
+Additional query options
+
+| Options           | Type<br/>(default)              | Description                                                                        |
+| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
+| `defaults` | <pre>ConcurrentHashMap<String, Any?><br/>(`{}`)        | (optional) 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 `ConcurrentHashMap<String, Any?>` with the following properties:
+
+| Property     | Type                                         | Description                      |
+|------------- |--------------------------------------------- |--------------------------------- |
+| `_source`    | <pre>ConcurrentHashMap<String, Any?></pre> | Updated document (if `source` option set to true)  |
+| `_id`        | <pre>String</pre>                            | ID of the udated 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 @@
+ConcurrentHashMap<String, Object> category = new ConcurrentHashMap<>();
+ConcurrentHashMap<String, Object> changes = new ConcurrentHashMap<>();
+category.put("category", "suv");
+changes.put("changes", category);
+
+ConcurrentHashMap<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: ConcurrentHashMap<String, Any?> =
+  ConcurrentHashMap<String, Any?>().apply {
+    put("category", "suv")
+  }
+
+val changes: ConcurrentHashMap<String, Any?> =
+  ConcurrentHashMap<String, Any?>().apply {
+    put("changes", category)  
+  }
+
+val result: ConcurrentHashMap<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

@@ -340,6 +340,36 @@ class DocumentController(kuzzle: Kuzzle) : BaseController(kuzzle) {
         .thenApplyAsync { response -> response.result as ConcurrentHashMap<String, Any?> }
   }
 
+  @JvmOverloads
+  fun upsert(
+      index: String,
+      collection: String,
+      id: String,
+      changes: ConcurrentHashMap<String, Any?>,
+      defaults: ConcurrentHashMap<String, Any?>? = null,
+      waitForRefresh: Boolean? = null,
+      retryOnConflict: Int? = null,
+      source: Boolean? = null): CompletableFuture<ConcurrentHashMap<String, Any?>> {
+    val query = KuzzleMap().apply {
+      put("index", index)
+      put("collection", collection)
+      put("controller", "document")
+      put("action", "upsert")
+      put("body", KuzzleMap()
+        .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 ConcurrentHashMap<String, Any?> }
+  }
+
   @JvmOverloads
   fun updateByQuery(
       index: String,