Bulk controller

doc/2/controllers/bulk/import/index.md

@@ -0,0 +1,83 @@
+---
+code: true
+type: page
+title: import
+description: Creates, updates or deletes large amounts of documents as fast as possible.
+---
+
+# Impport
+
+Creates, updates or deletes large amounts of documents as fast as possible.
+
+This route is faster than the `document:m*` routes family (e.g. [document:mCreate](/sdk/dart/2/controllers/document/m-create)), but no real-time notifications will be generated, even if some of the documents in the import match subscription filters.
+
+## Arguments
+
+```dart
+Future<Map<String, dynamic>> import(
+      String index, String collection, List<Map<String, dynamic>> documents)
+```
+
+| Argument     | Type              | Description                                                  |
+|--------------|-------------------|--------------------------------------------------------------|
+| `index`      | <pre>String</pre> | Index name                                                   |
+| `collection` | <pre>String</pre> | Collection name                                              |
+| `documents`   | <pre>List<Map<String, dynamic>></pre> | List of documents to import |
+
+### documents
+
+This API takes a JSON array containing a list of objects working in pairs.
+In each pair, the first object specifies the action to perform (the most common is `create`) and the second specifies the document itself, like in the example below:
+
+```json
+[
+  // Action object
+  { "create": { "_id": "id" } },
+  // Document object
+  { "myField": "myValue", "myOtherField": "myOtherValue" },
+
+  // Another action object
+  { "create": { "_id": "another-id" } },
+  // Another document object
+  { "myField": "anotherValue", "myOtherField": "yetAnotherValue" }
+];
+```
+
+Possible actions are `create`, `index`, `update`, `delete`.
+
+Learn more at [Elasticsearch Bulk API](https://www.elastic.co/guide/en/elasticsearch/reference/7.4/docs-bulk.html)
+
+## Return
+
+A Map<String, dynamic> containing 2 arrays:
+
+| Property | Type                | Description                                         |
+| -------- | ------------------- | --------------------------------------------------- |
+| `successes`  | <pre>List<dynamic></pre> | Array of object containing successful document import |
+| `errors` | <pre>List<dynamic></pre>  | Array of object containing failed document import     |
+
+Each item of the `successes` array is an object containing the action name as key and the corresponding object contain the following properties:
+
+| Property | Type                | Description                                         |
+| -------- | ------------------- | --------------------------------------------------- |
+| `_id`   | <pre>String</pre>   | Document unique identifier      |
+| `status`   | <pre>int</pre>   | HTTP status code for that query      |
+
+Each item of the `errors` array is an object containing the action name as key and the corresponding object contain the following properties:
+
+| Property | Type                | Description                                         |
+| -------- | ------------------- | --------------------------------------------------- |
+| `_id`   | <pre>String</pre>   | Document unique identifier      |
+| `status`   | <pre>int</pre>   | HTTP status code for that query      |
+| `error`   | <pre>Map<String, dynamic></pre>   | Error object      |
+
+Each `error` object contain the following properties:
+
+| Property | Type                | Description                                         |
+| -------- | ------------------- | --------------------------------------------------- |
+| `type`  | <pre>String</pre> | Elasticsearch client error type |
+| `reason`  | <pre>String</pre> | human readable error message |
+
+## Usage
+
+<<< ./snippets/import.dart

doc/2/controllers/bulk/import/snippets/import.dart

@@ -0,0 +1,13 @@
+final result = await kuzzle
+  .bulk
+  .import(
+    'nyc-open-data',
+    'yellow-taxi',
+    [
+      { 'index': { } },
+      { 'a': 'document', 'with': 'any', 'number': 'of fields' },
+      { 'create': { '_id': 'uniq-id-1' } },
+      { 'another': 'document' },
+      { 'create': { '_id': 'uniq-id-2' } },
+      { 'and': { 'another': 'one' } },
+    ]);

doc/2/controllers/bulk/import/snippets/import.test.yml

@@ -0,0 +1,9 @@
+name: Bulk#ImportAsync
+description: Creates, updates or deletes large amounts of documents as fast as possible.
+hooks:
+  before: |
+    curl -X POST kuzzle:7512/nyc-open-data/_create
+    curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi
+  after: curl -X DELETE kuzzle:7512/nyc-open-data
+template: default
+expected: "Success"

doc/2/controllers/bulk/index.md

@@ -0,0 +1,8 @@
+---
+code: true
+type: branch
+title: bulk
+description: Bulk Controller
+---
+
+# Bulk Controller

doc/2/controllers/bulk/mwrite/index.md

@@ -0,0 +1,63 @@
+---
+code: true
+type: page
+title: MWriteAsync
+description: Creates or replaces multiple documents directly into the storage engine.
+---
+
+# mWrite
+
+This is a low level route intended to bypass Kuzzle actions on document creation, notably:
+  - check [document validity](/core/2/guides/essentials/data-validation),
+  - add [kuzzle metadata](/core/2/guides/essentials/document-metadata),
+  - trigger [realtime notifications](/core/2/guides/essentials/real-time) (unless asked otherwise)
+
+## Arguments
+
+```dart
+Future<Map<String, dynamic>> import(
+      String index, 
+      String collection, 
+      List<Map<String, dynamic>> documents,
+      {
+        bool waitForRefresh = false,
+      })
+```
+
+| Argument     | Type              | Description                                                                                                                      |
+|--------------|-------------------|----------------------------------------------------------------------------------------------------------------------------------|
+| `index`      | <pre>String</pre> | Index name                                                                                                                       |
+| `collection` | <pre>String</pre> | Collection name                                                                                                                  |
+| `documents`  | <pre>List<Map<String, dynamic>></pre> | An array of Map<String, dynamic> representing the documents|
+| `waitForRefresh` | <pre>bool</pre><br>(`false`) | If set to true, Kuzzle will not respond until the created/replaced documents are indexed |
+
+### documents
+
+An array of `Map<String, dynamic>`. Each object describes a document to create or replace, by exposing the following properties:
+  - `_id`: document unique identifier (optional)
+  - `body`: document content
+
+## Return
+
+Returns a `Map<String, dynamic>` containing 2 arrays: `successes` and `errors`
+
+Each created or replaced document is an object of the `successes` array with the following properties:
+
+| Name      | Type              | Description                                            |
+| --------- | ----------------- | ------------------------------------------------------ |
+| `_id`      | <pre>String</pre> | Document ID                     |
+| `_version` | <pre>int</pre> | Version of the document in the persistent data storage |
+| `_source`  | <pre>Map<String, dynamic></pre> | Document content                                       |
+| `created`  | <pre>bool</pre> | True if the document was created |
+
+Each errored document is an object of the `errors` array with the following properties:
+
+| Name      | Type              | Description                                            |
+| --------- | ----------------- | ------------------------------------------------------ |
+| `document`  | <pre>Map<String, dynamic></pre> | Document that cause the error                                       |
+| `status` | <pre>int</pre> | HTTP error status |
+| `reason`  | <pre>String</pre> | Human readable reason |
+
+## Usage
+
+<<< ./snippets/mwrite.dart

doc/2/controllers/bulk/mwrite/snippets/mwrite.dart

@@ -0,0 +1,8 @@
+final result = await kuzzle
+  .bulk
+  .mWrite(
+    'nyc-open-data',
+    'yellow-taxi',
+    [
+      {'_id': 'foo', 'body': {},},
+    ]);

doc/2/controllers/bulk/mwrite/snippets/mwrite.test.yml

@@ -0,0 +1,9 @@
+name: Bulk#MWriteAsync
+description: Creates or replaces multiple documents directly into the storage engine.
+hooks:
+  before: |
+    curl -X POST kuzzle:7512/nyc-open-data/_create
+    curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi
+  after: curl -X DELETE kuzzle:7512/nyc-open-data
+template: default
+expected: "Success"

doc/2/controllers/bulk/write/index.md

@@ -0,0 +1,44 @@
+---
+code: true
+type: page
+title: write
+description: Creates or replaces a document directly into the storage engine.
+---
+
+# write
+
+Create or replace a document directly into the storage engine.
+
+## Arguments
+
+```dart
+Future<Map<String, dynamic>> write(
+      String index, 
+      String collection, 
+      Map<String, dynamic> document, {
+        String id,
+        bool waitForRefresh = false,
+      })
+```
+
+| Argument     | Type               | Description                 |
+|--------------|--------------------|-----------------------------|
+| `index`      | <pre>String</pre>  | Index name                  |
+| `collection` | <pre>String</pre>  | Collection name             |
+| `content`    | <pre>Map<String, dynamic></pre> | Document content to create. |
+| `id`          | <pre>String</pre><br>(`null`)  | Document id          
+| `waitForRefresh`   | <pre>bool</pre><br>(`false`)  | If set to `true`, Kuzzle will wait for the persistence layer to finish indexing |
+
+## Return
+
+Returns a `Map<String, dynamic>` with the following properties:
+
+| Property   | Type               | Description                                     |
+|------------|--------------------|-------------------------------------------------|
+| `_id`      | <pre>String</pre>  | Created document unique identifier. |
+| `_source`  | <pre>Map<String, dynamic></pre> | Document content. |
+| `_version` | <pre>int</pre> | Version number of the document |
+
+## Usage
+
+<<< ./snippets/write.dart

doc/2/controllers/bulk/write/snippets/write.dart

@@ -0,0 +1,13 @@
+final result = await kuzzle
+  .bulk
+  .write(
+    'nyc-open-data',
+    'yellow-taxi',
+    {
+      '_kuzzle_info': {
+        'author': '<kuid>',
+        'createdAt': 1481816934209,
+        'updatedAt': null,
+        'updater': null,
+      }
+    });

doc/2/controllers/bulk/write/snippets/write.test.yml

@@ -0,0 +1,9 @@
+name: Bulk#WriteAsync
+description: Creates or replaces a document directly into the storage engine.
+hooks:
+  before: |
+    curl -X POST kuzzle:7512/nyc-open-data/_create
+    curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi
+  after: curl -X DELETE kuzzle:7512/nyc-open-data
+template: default
+expected: "Success"

doc/2/controllers/document/m-create-or-replace/index.md

@@ -26,7 +26,7 @@ Future<Map<String, dynamic>> mCreateOrReplace(
 | ------------------ | ------------------------------------------------------- | --------------------------------- |
 | `index`            | <pre>String</pre>                                       | Index                             |
 | `collection`       | <pre>String</pre>                                       | Collection                        |
-| `documents`        | <pre>List<Map<String, dynamic>></pre> | ArrayList containing the documents to create |
+| `documents`        | <pre>List<Map<String, dynamic>></pre> | List containing the documents to create |
 | `waitForRefresh`   | <pre>bool</pre>                                      | If set to `true`, Kuzzle will wait for the persistence layer to finish indexing |
 
 ---

doc/2/controllers/document/m-create/index.md

@@ -23,7 +23,7 @@ Future<c> mCreate(
 | ------------------ | ------------------------------------------------------- | --------------------------------- |
 | `index`            | <pre>String</pre>                                       | Index                             |
 | `collection`       | <pre>String</pre>                                       | Collection                        |
-| `documents`        | <pre>List<Map<String, dynamic>></pre> | ArrayList containing the documents to create |
+| `documents`        | <pre>List<Map<String, dynamic>></pre> | List containing the documents to create |
 | `waitForRefresh`   | <pre>bool</pre><br>(`false`)                                      | If set to `true`, Kuzzle will wait for the persistence layer to finish indexing |
 
 ---
@@ -35,24 +35,24 @@ Each document has the following properties:
 | Arguments          | Type                                         | Description                       |
 | ------------------ | -------------------------------------------- | --------------------------------- |
 | `_id`              | <pre>String</pre>                            | Optional document ID. Will be auto-generated if not defined.             |
-| `body`             | <pre>List<Map<String, dynamic>></pre> | Document body |
+| `body`             | <pre>Map<String, dynamic></pre> | Document body |
 
 ## Return
 
-A `List<Map<String, dynamic>>` which has a `successes` and `errors`:
+A `Map<String, dynamic>` which has a `successes` and `errors`:
 Each created document is an object of the `successes` array with the following properties:
 
 | Property     | Type                                         | Description                      |
 |------------- |--------------------------------------------- |--------------------------------- |
-| `_source`    | <pre>List<Map<String, dynamic>></pre> | Created document                 |
+| `_source`    | <pre>Map<String, dynamic></pre> | Created document                 |
 | `_id`        | <pre>String</pre>                            | ID of the newly created document                       |
 | `_version`   | <pre>int</pre>                           | Version of the document in the persistent data storage |
 
 Each errored document is an object of the `errors` array with the following properties:
 
 | Property     | Type                                         | Description                      |
 |------------- |--------------------------------------------- |--------------------------------- |
-| `document`   | <pre>List<Map<String, dynamic>></pre> | Document that causes the error   |
+| `document`   | <pre>Map<String, dynamic></pre> | Document that causes the error   |
 | `status`     | <pre>int</pre>                           | HTTP error status                |
 | `reason`     | <pre>String</pre>                            | Human readable reason |
 

doc/2/controllers/document/m-get/index.md

@@ -30,12 +30,12 @@ Future<Map<String, dynamic>> mGet(
 
 ## Return
 
-A `List<String>` which has a `successes` and `errors`:
+A `Map<String, dynamic>` which has a `successes` and `errors`:
 Each created document is an object of the `successes` array with the following properties:
 
 | Property     | Type                                         | Description                      |
 |------------- |--------------------------------------------- |--------------------------------- |
-| `_source`    | <pre>List<String></pre> | Document content                 |
+| `_source`    | <pre>Map<String, dynamic></pre> | Document content                 |
 | `_id`        | <pre>String</pre>                            | Document ID                      |
 | `_version`   | <pre>int</pre>                           | Version of the document in the persistent data storage |