Add missing INFO.yaml blocks
[aai/search-data-service.git] / 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