Add document:upsert (#576)

Author: Yoann-Abbes

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

@@ -0,0 +1,45 @@
+---
+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.
+
+
+```js
+upsert(index, collection, id, changes, [options]);
+```
+
+| Argument     | Type              | Description                               |
+| ------------ | ----------------- | ----------------------------------------- |
+| `index`      | <pre>string</pre> | Index name                                |
+| `collection` | <pre>string</pre> | Collection name                           |
+| `id`         | <pre>string</pre> | Document ID                               |
+| `changes`       | <pre>object</pre> | Partial content of the document to update |
+
+### Options
+
+Additional query options
+
+| Options           | Type<br/>(default)              | Description                                                                        |
+| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
+| `defaults` | <pre>object</pre><br/>(`{}`)        | Fields to add to the document if it gets created |
+| `refresh`         | <pre>string</pre><br/>(`""`)    | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) |
+| `retryOnConflict` | <pre>int</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
+
+
+## Resolves
+
+Resolves to an object containing the document update result.
+
+## Usage
+
+<<< ./snippets/upsert.js

doc/7/controllers/document/upsert/snippets/upsert.js

@@ -0,0 +1,25 @@
+try {
+  await kuzzle.document.create(
+    'nyc-open-data',
+    'yellow-taxi',
+    { capacity: 4 },
+    'some-id'
+  );
+
+  const response = await kuzzle.document.upsert(
+    'nyc-open-data',
+    'yellow-taxi',
+    'some-id',
+    { changes: { category: 'suv' } }
+  );
+
+  console.log(response);
+  /*
+  {
+    id: 'some-id',
+    _version: 2
+  }
+  */
+} catch (error) {
+  console.error(error.message);
+}

doc/7/controllers/document/upsert/snippets/upsert.test.yml

@@ -0,0 +1,10 @@
+name: 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: default
+expected: "_id: 'some-id'"

src/Kuzzle.ts

@@ -543,6 +543,10 @@ export class Kuzzle extends KuzzleEventEmitter {
       request.refresh = options.refresh;
     }
 
+    if (request.retryOnConflict === undefined && options.retryOnConflict !== undefined) {
+      request.retryOnConflict = options.retryOnConflict;
+    }
+
     if (! request.volatile) {
       request.volatile = this.volatile;
     }

src/controllers/Document.ts

@@ -778,6 +778,43 @@ export class DocumentController extends BaseController {
       .then(response => response.result);
   }
 
+  /**
+   * Applies a partial update to an existing document.
+   * If the document doesn't already exist, a new document is created.
+   * @see https://docs.kuzzle.io/sdk/js/7/controllers/document/upsert/
+   *
+   * @param index Index name
+   * @param collection Collection name
+   * @param _id Unique document identifier
+   * @param changes Partial content of the document to update
+   * @param [options]
+   *    - `defaults` Fields to add to the document if it gets created
+   *    - `refresh` If set to `wait_for`, Kuzzle will not respond until the API key is indexed
+   *    - `retryOnConflict` Number of times the database layer should retry in case of version conflict
+   *    - `source` If true, returns the updated document inside the response
+   *
+   * @returns Information about the updated document
+  */
+  upsert (
+    index: string,
+    collection: string,
+    _id: string,
+    changes: JSONObject,
+    options: {defaults?: JSONObject; refresh?: string, retryOnConflict?: boolean, source?: boolean} = {}
+  ): Promise<Document> {
+    const request = {
+      index,
+      collection,
+      _id,
+      body: { changes, defaults: options.defaults },
+      action: 'upsert',
+      source: options.source
+    };
+
+    return this.query(request, options)
+      .then(response => response.result);
+  }
+
   /**
    * Validates a document against existing validation rules.
    *

src/types/Document.ts

@@ -48,6 +48,12 @@ export class Document {
    * Document Version (generated by Elasticsearch)
    */
   _version?: number;
+  /**
+   * If true, a new document was created,
+   * otherwise the document existed and was updated
+   * @see https://docs.kuzzle.io/sdk/js/7/controllers/document/upsert/
+   */
+  created?: boolean;
   /**
    * Document Content
    */
@@ -69,4 +75,4 @@ export interface DocumentHit extends Document {
    * Relevance score
    */
   _score: number;
-}
+}