BULK.md

   1 # Bulk Operations\r
   2 \r
   3 ## Overview\r
   4 \r
   5 Bulk operations allow the client to bundle a number of actions into a single REST request.\r
   6 \r
   7 It is important to note that the individual operations bundled into a bulk request are considered by the Search Service to be completely independent operations.  This has a few consequences:\r
   8 \r
   9 * No guarantees are made with respect to the order in which the individual operations will be processed by the document store.\r
  10 \r
  11 * There is no implied transactionality between the operations.  The operations may succeed or fail independently of one another, and it is entirely possible to get back a result set indicating a mix of success and failure results for the individual operations.\r
  12 \r
  13 ## Syntax\r
  14 \r
  15 The request payload of a bulk operation must be structured in the following manner (we will flesh out this pseudo-json with a concrete example further down):\r
  16 \r
  17     [\r
  18         { <operation> : { <meta-data>, <document>  } },\r
  19                             .\r
  20                             .\r
  21         { <operation> : { <meta-data>, <document>  } }\r
  22     ]\r
  23     \r
  24 **Operation**\r
  25 The following table describes the operations which are supported as part of a _Bulk_ request:\r
  26 \r
  27 | Operation | Behaviour                                      | Expected Meta Data     | Expected Payload  |\r
  28 | --------- | ---------------------------------------------- | ---------------------- | ----------------- |\r
  29 | create    | Insert a new document into the document store. | document url           | document contents |   \r
  30 | update    | Update an existing document.                   | document url, etag     | document contents |\r
  31 | delete    | Remove a document from the document store.     | document url, etag     | none              |  \r
  32            \r
  33 **Meta-Data**\r
  34 Depending on the operation being requested, certain additional meta-data is required for the _Search Date Service_ to be able to carry out the operation.  These are described in the _operations_ table above.\r
  35 \r
  36 **Document**\r
  37 For those operations which involve creating or updating a _Document_, the contents of the document must be provided.\r
  38 \r
  39 _Example - Simple Bulk Request including all supported operations:_\r
  40 \r
  41 Request Payload:\r
  42 \r
  43         [\r
  44           {\r
  45             "create": {\r
  46               "metaData": {\r
  47                 "url": "/indexes/my-index/documents/"\r
  48               },\r
  49               "document": {\r
  50                 "field1": "value1",\r
  51                 "field2": "value2"\r
  52               }\r
  53             }\r
  54           },\r
  55           {\r
  56             "update": {\r
  57               "metaData": {\r
  58                 "url": "/indexes/my-other-index/documents/3",\r
  59                 "etag": "5"\r
  60               },\r
  61               "document": {\r
  62                 "field1": "some-value"\r
  63               }\r
  64             }\r
  65           },\r
  66           {\r
  67             "delete": {\r
  68               "metaData": {\r
  69                 "url": "/indexes/my-index/documents/7"\r
  70               }\r
  71             }\r
  72           }\r
  73         ]\r
  74 \r
  75 Response Payload:\r
  76 \r
  77         { \r
  78             "total_operations": 3, \r
  79             "total_success": 2, \r
  80             "total_fails": 1, \r
  81             "results": [\r
  82                 {\r
  83                     "operation": "create", \r
  84                     "url": "/services/search-data-service/v1/indexes/my-index/documents/1", \r
  85                     "etag": "1", \r
  86                     "status-code": "409", \r
  87                     "status-message": "[default][1]: document already exists"\r
  88                 }, \r
  89                 {\r
  90                     "operation": "update", \r
  91                     "url": "/services/search-data-service/v1/indexes/my-other-index/documents/3", \r
  92                     "etag": 6, \r
  93                     "status-code": "200", "status-message": "OK"\r
  94                 }, \r
  95                 {\r
  96                     "operation": "delete", \r
  97                     "url": "/services/search-data-service/v1/indexes/my-index/documents/7", \r
  98                     "status-code": "200", "status-message": "OK"\r
  99                 }\r
 100             ]\r
 101         }\r
 102         \r
 103 ## API\r
 104 \r
 105 **Submit A Bulk Operation**\r
 106 ---\r
 107 **URL**\r
 108 \r
 109     https://{host}:9509/services/search-data-service/v1/search/bulk/\r
 110 \r
 111 **Method** \r
 112 \r
 113     POST\r
 114 \r
 115 **URL Params**\r
 116 \r
 117     None\r
 118 \r
 119 **Request Header**\r
 120 \r
 121     Accept          = application/json\r
 122     X-TransactionId = Unique id set by client (for logging purposes)\r
 123     X-FromAppId     = Application identifier (for logging purposes)\r
 124     Content-Type    = application/json\r
 125     \r
 126 **Request Payload**\r
 127 \r
 128     Set of bulk operations to be executed (see Syntax Section) \r
 129 \r
 130 **Success Response**\r
 131 \r
 132     Code:      207 (Multi-Staltus)\r
 133     Header(s): None\r
 134     Body:      JSON format result set which includes individual status codes for each requested operation.  \r
 135     \r
 136 **Error Response**\r
 137 \r
 138     400 - Bad Request\r
 139     403 - Unauthorized\r
 140     500 - Internal Error\r
 141 \r
 142 ---\r