From 388a46046a6b9ff64189e92c2ebb81a044e5eb5b Mon Sep 17 00:00:00 2001 From: Yoann Abbes Date: Mon, 28 Dec 2020 14:24:30 +0100 Subject: [PATCH 1/6] Add document:upsert --- doc/2/controllers/document/upsert/index.md | 66 +++++++++++++++++++ .../document/upsert/snippets/upsert.dart | 6 ++ .../document/upsert/snippets/upsert.test.yml | 10 +++ lib/src/controllers/document.dart | 38 +++++++++++ 4 files changed, 120 insertions(+) create mode 100644 doc/2/controllers/document/upsert/index.md create mode 100644 doc/2/controllers/document/upsert/snippets/upsert.dart create mode 100644 doc/2/controllers/document/upsert/snippets/upsert.test.yml diff --git a/doc/2/controllers/document/upsert/index.md b/doc/2/controllers/document/upsert/index.md new file mode 100644 index 00000000..21cc27ca --- /dev/null +++ b/doc/2/controllers/document/upsert/index.md @@ -0,0 +1,66 @@ +--- +code: true +type: page +title: upsert +--- + +# upsert + + + + +Applies partial changes to a document. If the document doesn't already exist, a new document is created. + + +```dart + Future> upsert( + String index, + String collection, + String id, + Map body, { + bool waitForRefresh = false, + int retryOnConflict, + bool source, + }) +``` + +| Argument | Type | Description | +| ------------ | ----------------- | ----------------------------------------- | +| `index` | 
String
| Index name | +| `collection` | 
String
| Collection name | +| `id` | 
String
| Document ID | +| `body` | 
Map
| Partial content of the document to update and fields to add to the document if it gets created | + +### Body properties + + +| Argument | Type
(default) | Description | +| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- | +| `changes` | 
Map
| partial changes to apply to the document | +| `defaults` | 
Map

(`{}`) | (optional) fields to add to the document if it gets created | + +### Options + +Additional query options + +| Options | Type
(default) | Description | +| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- | +| `waitForRefresh` | 
bool

(`""`) | If set to `true`, waits for the change to be reflected for `search` (up to 1s) | +| `retryOnConflict` | 
int

(`10`) | The number of times the database layer should retry in case of version conflict | +| `source` | 
bool

(`false`)| If true, returns the updated document inside the response + + +## Returns + +A `Map` with the following properties: + +| Property | Type | Description | +|------------- |--------------------------------------------- |--------------------------------- | +| `_source` | 
Map
| Updated document (if `source` option set to true) | +| `_id` | 
String
| ID of the udated document | +| `_version` | 
int
| Version of the document in the persistent data storage | +| `created` | 
bool
+ +## Usage + +<<< ./snippets/upsert.dart diff --git a/doc/2/controllers/document/upsert/snippets/upsert.dart b/doc/2/controllers/document/upsert/snippets/upsert.dart new file mode 100644 index 00000000..8c05a532 --- /dev/null +++ b/doc/2/controllers/document/upsert/snippets/upsert.dart @@ -0,0 +1,6 @@ +final result = await kuzzle + .document + .upsert('nyc-open-data', 'yellow-taxi', 'some-id', { + 'changes': { 'category': 'suv' }, + }, + ); \ No newline at end of file diff --git a/doc/2/controllers/document/upsert/snippets/upsert.test.yml b/doc/2/controllers/document/upsert/snippets/upsert.test.yml new file mode 100644 index 00000000..dc8b71c2 --- /dev/null +++ b/doc/2/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: print-result +expected: "{_id: some-id, _version: 1, created: true}" \ No newline at end of file diff --git a/lib/src/controllers/document.dart b/lib/src/controllers/document.dart index 997c689f..ca2ab7fb 100644 --- a/lib/src/controllers/document.dart +++ b/lib/src/controllers/document.dart @@ -414,6 +414,44 @@ class DocumentController extends KuzzleController { return response.result as Map; } + /// ####Updates a document content. + /// + /// **[index]**: index name \\\ + /// **[collection]**: collection name \\\ + /// **[uid]**: unique identifier of the document to update \\\ + /// **[body]**: Partial changes to apply to the document and Fields to add to the document if it gets created (optional) + + /// + /// Optional + /// + /// **[refresh]**: if set to wait_for, Kuzzle will not respond + /// until the update is indexed \\\ + /// **[retryOnConflict]**: conflicts may occur if the same document gets updated multiple times within a short timespan, in a database cluster. You can set the retryOnConflict optional argument (with a retry count), to tell Kuzzle to retry the failing updates the specified amount of times before rejecting the request with an error. \\\ + /// **[source]**: if set to true Kuzzle will return the updated document body in the response \\\ + Future> upsert( + String index, + String collection, + String id, + Map body, { + bool waitForRefresh = false, + int retryOnConflict, + bool source, + }) async { + final response = await kuzzle.query(KuzzleRequest( + controller: name, + action: 'upsert', + index: index, + collection: collection, + uid: id, + body: body, + waitForRefresh: waitForRefresh, + source: source, + retryOnConflict: retryOnConflict, + )); + + return response.result as Map; + } + /// Validates data against existing validation rules. /// /// Documents are always valid if no validation rules are defined From 8f331e926639283d48848d030081c592ff4a0ded Mon Sep 17 00:00:00 2001 From: Yoann Abbes Date: Mon, 28 Dec 2020 14:27:58 +0100 Subject: [PATCH 2/6] update comment --- lib/src/controllers/document.dart | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lib/src/controllers/document.dart b/lib/src/controllers/document.dart index ca2ab7fb..13d53dca 100644 --- a/lib/src/controllers/document.dart +++ b/lib/src/controllers/document.dart @@ -414,12 +414,14 @@ class DocumentController extends KuzzleController { return response.result as Map; } - /// ####Updates a document content. + /// ####Applies a partial update to an existing document. + /// If the document doesn't already exist, a new document is created. /// /// **[index]**: index name \\\ /// **[collection]**: collection name \\\ /// **[uid]**: unique identifier of the document to update \\\ - /// **[body]**: Partial changes to apply to the document and Fields to add to the document if it gets created (optional) + /// **[body]**: Partial changes to apply to the document + /// and Fields to add to the document if it gets created (optional) /// /// Optional From 8f2a45378f13113894db17afe9051d37b8de97af Mon Sep 17 00:00:00 2001 From: Yoann Abbes Date: Tue, 29 Dec 2020 15:52:37 +0100 Subject: [PATCH 3/6] change signature --- doc/2/controllers/document/upsert/index.md | 13 +++---------- lib/src/controllers/document.dart | 15 +++++++++------ lib/src/kuzzle/request.dart | 8 +++++++- 3 files changed, 19 insertions(+), 17 deletions(-) diff --git a/doc/2/controllers/document/upsert/index.md b/doc/2/controllers/document/upsert/index.md index 21cc27ca..75cc20c2 100644 --- a/doc/2/controllers/document/upsert/index.md +++ b/doc/2/controllers/document/upsert/index.md @@ -17,7 +17,7 @@ Applies partial changes to a document. If the document doesn't already exist, a String index, String collection, String id, - Map body, { + Map changes, { bool waitForRefresh = false, int retryOnConflict, bool source, @@ -29,15 +29,7 @@ Applies partial changes to a document. If the document doesn't already exist, a | `index` | 
String
| Index name | | `collection` | 
String
| Collection name | | `id` | 
String
| Document ID | -| `body` | 
Map
| Partial content of the document to update and fields to add to the document if it gets created | - -### Body properties - - -| Argument | Type
(default) | Description | -| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- | -| `changes` | 
Map
| partial changes to apply to the document | -| `defaults` | 
Map

(`{}`) | (optional) fields to add to the document if it gets created | +| `changes` | 
Map
| Partial content of the document to update | ### Options @@ -45,6 +37,7 @@ Additional query options | Options | Type
(default) | Description | | ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- | +| `defaults` | 
Map

(`{}`) | (optional) fields to add to the document if it gets created | | `waitForRefresh` | 
bool

(`""`) | If set to `true`, waits for the change to be reflected for `search` (up to 1s) | | `retryOnConflict` | 
int

(`10`) | The number of times the database layer should retry in case of version conflict | | `source` | 
bool

(`false`)| If true, returns the updated document inside the response diff --git a/lib/src/controllers/document.dart b/lib/src/controllers/document.dart index 13d53dca..95db2b0c 100644 --- a/lib/src/controllers/document.dart +++ b/lib/src/controllers/document.dart @@ -347,7 +347,7 @@ class DocumentController extends KuzzleController { /// /// Optional /// - /// **[refresh]**: if set to wait_for, Kuzzle will not respond + /// **[waitForRefresh]**: if set to wait_for, Kuzzle will not respond /// until the update is indexed \\\ /// **[retryOnConflict]**: conflicts may occur if the same document gets updated multiple times within a short timespan, in a database cluster. You can set the retryOnConflict optional argument (with a retry count), to tell Kuzzle to retry the failing updates the specified amount of times before rejecting the request with an error. \\\ /// **[source]**: if set to true Kuzzle will return the updated document body in the response \\\ @@ -419,14 +419,15 @@ class DocumentController extends KuzzleController { /// /// **[index]**: index name \\\ /// **[collection]**: collection name \\\ - /// **[uid]**: unique identifier of the document to update \\\ - /// **[body]**: Partial changes to apply to the document + /// **[id]**: unique identifier of the document to update \\\ + /// **[changes]**: Partial changes to apply to the document /// and Fields to add to the document if it gets created (optional) /// /// Optional /// - /// **[refresh]**: if set to wait_for, Kuzzle will not respond + /// **[defaults]**: Fields to add to the document if it gets created + /// **[waitForRefresh]**: if set to wait_for, Kuzzle will not respond /// until the update is indexed \\\ /// **[retryOnConflict]**: conflicts may occur if the same document gets updated multiple times within a short timespan, in a database cluster. You can set the retryOnConflict optional argument (with a retry count), to tell Kuzzle to retry the failing updates the specified amount of times before rejecting the request with an error. \\\ /// **[source]**: if set to true Kuzzle will return the updated document body in the response \\\ @@ -434,7 +435,8 @@ class DocumentController extends KuzzleController { String index, String collection, String id, - Map body, { + Map changes, { + Map defaults, bool waitForRefresh = false, int retryOnConflict, bool source, @@ -445,7 +447,8 @@ class DocumentController extends KuzzleController { index: index, collection: collection, uid: id, - body: body, + body: changes, + defaults: defaults, waitForRefresh: waitForRefresh, source: source, retryOnConflict: retryOnConflict, diff --git a/lib/src/kuzzle/request.dart b/lib/src/kuzzle/request.dart index ccb7070c..f2c8049b 100644 --- a/lib/src/kuzzle/request.dart +++ b/lib/src/kuzzle/request.dart @@ -30,6 +30,7 @@ class KuzzleRequest { this.scope, this.state, this.source, + this.defaults, this.userId, this.users, this.verb, @@ -67,6 +68,7 @@ class KuzzleRequest { users = request.users; verb = request.verb; source = request.source; + defaults = request.defaults; includeKuzzleMeta = request.includeKuzzleMeta; } @@ -105,6 +107,7 @@ class KuzzleRequest { users = data['users'] as String; verb = data['verb'] as String; source = data['source'] as bool; + defaults = data['defaults'] as Map; includeKuzzleMeta = data['includeKuzzleMeta'] as bool; } @@ -200,7 +203,9 @@ class KuzzleRequest { if (source != null) { map['source'] = source; } - + if (defaults != null) { + map['defaults'] = defaults; + } if (includeKuzzleMeta != null) { map['includeKuzzleMeta'] = includeKuzzleMeta; } @@ -235,6 +240,7 @@ class KuzzleRequest { int retryOnConflict; bool reset; bool source; + Map defaults; String scope; String state; String userId; From e3eb8a92313f2a5b6751de04867118bb1f219d51 Mon Sep 17 00:00:00 2001 From: Yoann Abbes Date: Wed, 30 Dec 2020 11:56:31 +0100 Subject: [PATCH 4/6] fix --- lib/src/controllers/document.dart | 6 ++++-- lib/src/kuzzle/request.dart | 7 ------- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/lib/src/controllers/document.dart b/lib/src/controllers/document.dart index 95db2b0c..64177f16 100644 --- a/lib/src/controllers/document.dart +++ b/lib/src/controllers/document.dart @@ -447,8 +447,10 @@ class DocumentController extends KuzzleController { index: index, collection: collection, uid: id, - body: changes, - defaults: defaults, + body: { + 'changes': changes, + 'defaults': defaults + }, waitForRefresh: waitForRefresh, source: source, retryOnConflict: retryOnConflict, diff --git a/lib/src/kuzzle/request.dart b/lib/src/kuzzle/request.dart index f2c8049b..5c5cda75 100644 --- a/lib/src/kuzzle/request.dart +++ b/lib/src/kuzzle/request.dart @@ -30,7 +30,6 @@ class KuzzleRequest { this.scope, this.state, this.source, - this.defaults, this.userId, this.users, this.verb, @@ -68,7 +67,6 @@ class KuzzleRequest { users = request.users; verb = request.verb; source = request.source; - defaults = request.defaults; includeKuzzleMeta = request.includeKuzzleMeta; } @@ -107,7 +105,6 @@ class KuzzleRequest { users = data['users'] as String; verb = data['verb'] as String; source = data['source'] as bool; - defaults = data['defaults'] as Map; includeKuzzleMeta = data['includeKuzzleMeta'] as bool; } @@ -203,9 +200,6 @@ class KuzzleRequest { if (source != null) { map['source'] = source; } - if (defaults != null) { - map['defaults'] = defaults; - } if (includeKuzzleMeta != null) { map['includeKuzzleMeta'] = includeKuzzleMeta; } @@ -240,7 +234,6 @@ class KuzzleRequest { int retryOnConflict; bool reset; bool source; - Map defaults; String scope; String state; String userId; From fa068488208a41dd76864630c295e0f0c43cded7 Mon Sep 17 00:00:00 2001 From: Yoann-Abbes <44844010+Yoann-Abbes@users.noreply.github.com> Date: Wed, 30 Dec 2020 14:36:22 +0100 Subject: [PATCH 5/6] Update lib/src/controllers/document.dart Co-authored-by: Adrien Maret --- lib/src/controllers/document.dart | 1 - 1 file changed, 1 deletion(-) diff --git a/lib/src/controllers/document.dart b/lib/src/controllers/document.dart index 64177f16..4bcd776c 100644 --- a/lib/src/controllers/document.dart +++ b/lib/src/controllers/document.dart @@ -421,7 +421,6 @@ class DocumentController extends KuzzleController { /// **[collection]**: collection name \\\ /// **[id]**: unique identifier of the document to update \\\ /// **[changes]**: Partial changes to apply to the document - /// and Fields to add to the document if it gets created (optional) /// /// Optional From 54612a8ec4809bffda39003c99b244040e0c7175 Mon Sep 17 00:00:00 2001 From: Yoann Abbes Date: Wed, 30 Dec 2020 14:38:22 +0100 Subject: [PATCH 6/6] update doc --- doc/2/controllers/document/upsert/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/2/controllers/document/upsert/index.md b/doc/2/controllers/document/upsert/index.md index 75cc20c2..90ef5d6a 100644 --- a/doc/2/controllers/document/upsert/index.md +++ b/doc/2/controllers/document/upsert/index.md @@ -2,6 +2,7 @@ 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 @@ -52,7 +53,7 @@ A `Map` with the following properties: | `_source` | 
Map
| Updated document (if `source` option set to true) | | `_id` | 
String
| ID of the udated document | | `_version` | 
int
| Version of the document in the persistent data storage | -| `created` | 
bool
+| `created` | 
bool
| If `true`, a new document was created, otherwise the document existed and was updated | ## Usage