]>
Commit | Line | Data |
---|---|---|
f85f8ebb BP |
1 | =================================================== |
2 | Open vSwitch Configuration Database Specification | |
3 | =================================================== | |
4 | ||
5 | Basic Notation | |
6 | -------------- | |
7 | ||
8 | The descriptions below use the following shorthand notations for JSON | |
9 | values. Additional notation is presented later. | |
10 | ||
11 | <string> | |
12 | ||
13 | A JSON string. | |
14 | ||
15 | <id> | |
16 | ||
17 | A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*. | |
18 | ||
19 | <id>s that begin with _ are reserved to the implementation and may | |
20 | not be used by the user. | |
21 | ||
22 | <boolean> | |
23 | ||
24 | A JSON true or false value. | |
25 | ||
26 | <number> | |
27 | ||
28 | A JSON number. | |
29 | ||
30 | <integer> | |
31 | ||
32 | A JSON number with an integer value, within a certain range | |
33 | (currently -2**63...+2**63-1). | |
34 | ||
6e79e210 BP |
35 | <value> |
36 | ||
37 | Any JSON value. | |
38 | ||
f85f8ebb BP |
39 | Schema Format |
40 | ------------- | |
41 | ||
42 | An Open vSwitch configuration database consists of a set of tables, | |
43 | each of which has a number of columns and zero or more rows. A schema | |
44 | is represented by <database-schema>, as described below. | |
45 | ||
46 | <database-schema> | |
47 | ||
48 | A JSON object with the following members: | |
49 | ||
50 | "name": <id> required | |
51 | "comment": <string> optional | |
52 | "tables": {<id>: <table-schema>, ...} required | |
53 | ||
54 | The "name" identifies the database as a whole. The "comment" | |
55 | optionally provides more information about the database. The | |
56 | value of "tables" is a JSON object whose names are table names and | |
57 | whose values are <table-schema>s. | |
58 | ||
59 | <table-schema> | |
60 | ||
61 | A JSON object with the following members: | |
62 | ||
63 | "comment": <string> optional | |
64 | "columns": {<id>: <column-schema>, ...} required | |
65 | ||
66 | The "comment" optionally provides information about this table for | |
e68c3e48 JP |
67 | a human reader. The value of "columns" is a JSON object whose |
68 | names are column names and whose values are <column-schema>s. | |
f85f8ebb BP |
69 | |
70 | Every table has the following columns whose definitions are not | |
71 | included in the schema: | |
72 | ||
73 | "_uuid": This column, which contains exactly one UUID value, | |
74 | is initialized to a random value by the database engine when | |
75 | it creates a row. It is read-only, and its value never | |
76 | changes during the lifetime of a row. | |
77 | ||
78 | "_version": Like "_uuid", this column contains exactly one | |
79 | UUID value, initialized to a random value by the database | |
80 | engine when it creates a row, and it is read-only. However, | |
81 | its value changes to a new random value whenever any other | |
82 | field in the row changes. Furthermore, its value is | |
83 | ephemeral: when the database is closed and reopened, or when | |
84 | the database process is stopped and then started again, each | |
85 | "_version" also changes to a new random value. | |
86 | ||
87 | <column-schema> | |
88 | ||
89 | A JSON object with the following members: | |
90 | ||
91 | "comment": <string> optional | |
92 | "type": <type> required | |
93 | "ephemeral": <boolean> optional | |
94 | ||
95 | The "comment" optionally provides information about this column | |
96 | for a human reader. The "type" specifies the type of data stored | |
97 | in this column. If "ephemeral" is specified as true, then this | |
98 | column's values are not guaranteed to be durable; they may be lost | |
99 | when the database restarts. | |
100 | ||
101 | <type> | |
102 | ||
103 | The type of a database column. Either an <atomic-type> or a JSON | |
104 | object that describes the type of a database column, with the | |
105 | following members: | |
106 | ||
107 | "key": <atomic-type> required | |
108 | "value": <atomic-type> optional | |
109 | "min": <integer> optional | |
110 | "max": <integer> or "unlimited" optional | |
111 | ||
112 | If "min" or "max" is not specified, each defaults to 1. If "max" | |
113 | is specified as "unlimited", then there is no specified maximum | |
114 | number of elements, although the implementation will enforce some | |
115 | limit. After considering defaults, "min" must be at least 0, | |
116 | "max" must be at least 1, and "max" must be greater than or equal | |
117 | to "min". | |
118 | ||
119 | If "min" and "max" are both 1 and "value" is not specified, the | |
120 | type is the scalar type specified by "key". | |
121 | ||
122 | If "min" is not 1 or "max" is not 1, or both, and "value" is not | |
123 | specified, the type is a set of scalar type "key". | |
124 | ||
125 | If "value" is specified, the type is a map from type "key" to type | |
126 | "value". | |
127 | ||
128 | <atomic-type> | |
129 | ||
130 | One of the strings "integer", "real", "boolean", "string", or | |
131 | "uuid", representing the specified scalar type. | |
132 | ||
133 | Wire Protocol | |
134 | ------------- | |
135 | ||
136 | The database wire protocol is implemented in JSON-RPC 1.0. It | |
137 | consists of the following JSON-RPC methods: | |
138 | ||
139 | get_schema | |
140 | .......... | |
141 | ||
142 | Request object members: | |
143 | ||
144 | "method": "get_schema" required | |
145 | "params": [] required | |
146 | "id": any JSON value except null required | |
147 | ||
148 | Response object members: | |
149 | ||
150 | "result": <database-schema> | |
151 | "error": null | |
152 | "id": same "id" as request | |
153 | ||
154 | This operation retrieves a <database-schema> that describes the | |
155 | hosted database. | |
156 | ||
157 | transact | |
158 | ........ | |
159 | ||
160 | Request object members: | |
161 | ||
162 | "method": "transact" required | |
163 | "params": [<operation>*] required | |
164 | "id": any JSON value except null required | |
165 | ||
166 | Response object members: | |
167 | ||
168 | "result": [<object>*] | |
169 | "error": null | |
170 | "id": same "id" as request | |
171 | ||
172 | The "params" array for this method consists of zero or more JSON | |
173 | objects, each of which represents a single database operation. The | |
174 | "Operations" section below describes the valid operations. | |
175 | ||
176 | The value of "id" must be unique among all in-flight transactions | |
177 | within the current JSON-RPC session. Otherwise, the server may return | |
178 | a JSON-RPC error. | |
179 | ||
180 | The database server executes each of the specified operations in the | |
181 | specified order, except that if an operation fails, then the remaining | |
182 | operations are not executed. | |
183 | ||
184 | The set of operations is executed as a single atomic, consistent, | |
185 | isolated transaction. The transaction is committed only if every | |
186 | operation succeeds. Durability of the commit is not guaranteed unless | |
187 | the "commit" operation, with "durable" set to true, is included in the | |
188 | operation set (see below). | |
189 | ||
190 | Regardless of whether errors occur, the response is always a JSON-RPC | |
191 | response with null "error" and a "result" member that is an array with | |
192 | the same number of elements as "params". Each element of the "result" | |
193 | array corresponds to the same element of the "params" array. The | |
194 | "result" array elements may be interpreted as follows: | |
195 | ||
196 | - A JSON object that does not contain an "error" member indicates | |
197 | that the operation completed successfully. The specific members | |
198 | of the object are specified below in the descriptions of | |
199 | individual operations. Some operations do not produce any | |
200 | results, in which case the object will have no members. | |
201 | ||
e68c3e48 | 202 | - A JSON object that contains an "error" member indicates that the |
f85f8ebb BP |
203 | operation completed with an error. The value of the "error" |
204 | member is a short string, specified in this document, that | |
205 | broadly indicates the class of the error. Besides the ones | |
206 | listed for a specific operation, any operation may result in one | |
207 | the following "error"s: | |
208 | ||
209 | "error": "resources exhausted" | |
210 | ||
211 | The operation or the transaction requires more resources | |
212 | (memory, disk, CPU, etc.) than are currently available to | |
213 | the database server. | |
214 | ||
215 | "error": "syntax error" | |
216 | ||
217 | The operation is not specified correctly: a required request | |
218 | object member is missing, an unknown or unsupported request | |
219 | object member is present, the operation attempts to act on a | |
220 | table that does not exist, the operation modifies a | |
221 | read-only table column, etc. | |
222 | ||
223 | Database implementations may use "error" strings not specified | |
224 | in this document to indicate errors that do not fit into any of | |
225 | the specified categories. | |
226 | ||
227 | Optionally, the object may include a "details" member, whose | |
228 | value is a string that describes the error in more detail for | |
229 | the benefit of a human user or administrator. The object may | |
230 | also have other members that describe the error in more detail. | |
231 | This document does not specify the names or values of these | |
232 | members. | |
233 | ||
234 | - A JSON null value indicates that the operation was not attempted | |
235 | because a prior operation failed. | |
236 | ||
237 | In general, "result" contains some number of successful results, | |
238 | possibly followed by an error, in turn followed by enough JSON null | |
239 | values to match the number of elements in "params". There is one | |
240 | exception: if all of the operations succeed, but the results cannot be | |
241 | committed (e.g. due to I/O errors), then "result" will have one more | |
242 | element than "params", with the additional element describing the | |
243 | error. | |
244 | ||
245 | If "params" contains one or more "wait" operations, then the | |
246 | transaction may take an arbitrary amount of time to complete. The | |
247 | database implementation must be capable of accepting, executing, and | |
248 | replying to other transactions and other JSON-RPC requests while a | |
249 | transaction or transactions containing "wait" operations are | |
250 | outstanding on the same or different JSON-RPC sessions. | |
251 | ||
252 | The section "Notation for the Wire Protocol" below describes | |
253 | additional notation for use with the wire protocol. After that, the | |
254 | "Operations" section describes each operation. | |
255 | ||
256 | cancel | |
257 | ...... | |
258 | ||
259 | Request object members: | |
260 | ||
261 | "method": "cancel" required | |
6e79e210 | 262 | "params": [the "id" for an outstanding request] required |
f85f8ebb BP |
263 | "id": null required |
264 | ||
265 | Response object members: | |
266 | ||
267 | <no response> | |
268 | ||
269 | This JSON-RPC notification instructs the database server to | |
270 | immediately complete or cancel the "transact" request whose "id" is | |
271 | the same as the notification's "params" value. | |
272 | ||
273 | If the "transact" request can be completed immediately, then the | |
274 | server sends a response in the form described for "transact", above. | |
275 | Otherwise, the server sends a JSON-RPC error response of the following | |
276 | form: | |
277 | ||
278 | "result": null | |
279 | "error": "canceled" | |
280 | "id": the request "id" member | |
281 | ||
282 | The "cancel" notification itself has no reply. | |
283 | ||
a8425c53 BP |
284 | monitor |
285 | ....... | |
286 | ||
287 | Request object members: | |
288 | ||
289 | "method": "monitor" required | |
290 | "params": [<value>, <monitor-requests>] required | |
291 | "id": any JSON value except null required | |
292 | ||
293 | <monitor-requests> is an object that maps from a table name to a | |
294 | <monitor-request>. | |
295 | ||
296 | Each <monitor-request> is an object with the following members: | |
297 | ||
298 | "columns": [<column>*] optional | |
299 | "select": <monitor-select> optional | |
300 | ||
301 | <monitor-select> is an object with the following members: | |
302 | ||
303 | "initial": <boolean> optional | |
304 | "insert": <boolean> optional | |
305 | "delete": <boolean> optional | |
306 | "modify": <boolean> optional | |
307 | ||
308 | Response object members: | |
309 | ||
310 | "result": <table-updates> | |
311 | "error": null | |
312 | "id": same "id" as request | |
313 | ||
314 | This JSON-RPC request enables a client to replicate tables or subsets | |
315 | of tables. Each <monitor-request> specifies a table to be replicated. | |
316 | The JSON-RPC response to the "monitor" includes the initial contents | |
317 | of each table. Afterward, when changes to those tables are committed, | |
318 | the changes are automatically sent to the client using the "update" | |
319 | monitor notification. This monitoring persists until the JSON-RPC | |
320 | session terminates or until the client sends a "monitor_cancel" | |
321 | JSON-RPC request. | |
322 | ||
323 | Each <monitor-request> describes how to monitor a table: | |
324 | ||
325 | The circumstances in which an "update" notification is sent for a | |
326 | row within the table are determined by <monitor-select>: | |
327 | ||
328 | If "initial" is omitted or true, every row in the table is | |
329 | sent as part of the reply to the "monitor" request. | |
330 | ||
331 | If "insert" is omitted or true, "update" notifications are | |
332 | sent for rows newly inserted into the table. | |
333 | ||
334 | If "delete" is omitted or true, "update" notifications are | |
335 | sent for rows deleted from the table. | |
336 | ||
337 | If "modify" is omitted or true, "update" notifications are | |
338 | sent whenever when a row in the table is modified. | |
339 | ||
340 | The "columns" member specifies the columns whose values are | |
341 | monitored. If "columns" is omitted, all columns in the table, | |
342 | except for "_uuid", are monitored. | |
343 | ||
344 | The "result" in the JSON-RPC response to the "monitor" request is a | |
345 | <table-updates> object (see below) that contains the contents of the | |
346 | tables for which "initial" rows are selected. If no tables' initial | |
347 | contents are requested, then "result" is an empty object. | |
348 | ||
349 | update | |
350 | ...... | |
351 | ||
352 | Notification object members: | |
353 | ||
354 | "method": "update" | |
355 | "params": [<value>, <table-updates>] | |
356 | "id": null | |
357 | ||
358 | The <value> in "params" is the same as the value passed as the <value> | |
359 | in "params" for the "monitor" request. | |
360 | ||
361 | <table-updates> is an object that maps from a table name to a | |
362 | <table-update>. | |
363 | ||
364 | A <table-update> is an object that maps from the row's UUID (as a | |
365 | 36-byte string) to a <row-update> object. | |
366 | ||
367 | A <row-update> is an object with the following members: | |
368 | ||
369 | "old": <row> present for "delete" and "modify" updates | |
370 | "new": <row> present for "initial", "insert", and "modify" updates | |
371 | ||
372 | This JSON-RPC notification is sent from the server to the client to | |
373 | tell it about changes to a monitored table (or the initial state of a | |
374 | modified table). Each table in which one or more rows has changed (or | |
375 | whose initial view is being presented) is represented in "updates". | |
376 | Each row that has changed (or whose initial view is being presented) | |
377 | is represented in its <table-update> as a member with its name taken | |
378 | from the row's _uuid member. The corresponding value is a | |
379 | <row-update>: | |
380 | ||
381 | The "old" member is present for "delete" and "modify" updates. | |
382 | For "delete" updates, each monitored column is included. For | |
383 | "modify" updates, the prior value of each monitored column whose | |
384 | value has changed is included (monitored columns that have not | |
385 | changed are represented in "new"). | |
386 | ||
387 | The "new" member is present for "initial", "insert", and "modify" | |
388 | updates. For "initial" and "insert" updates, each monitored | |
389 | column is included. For "modify" updates, the new value of each | |
390 | monitored column is included. | |
391 | ||
392 | monitor_cancel | |
393 | .............. | |
394 | ||
395 | Request object members: | |
396 | ||
397 | "method": "monitor_cancel" required | |
398 | "params": [<value>] required | |
399 | "id": any JSON value except null required | |
400 | ||
401 | Response object members: | |
402 | ||
403 | "result": {} | |
404 | "error": null | |
405 | "id": the request "id" member | |
406 | ||
407 | Cancels the ongoing table monitor request, identified by the <value> | |
408 | in "params" matching the <value> in "params" for an ongoing "monitor" | |
409 | request. No more "update" messages will be sent for this table | |
410 | monitor. | |
411 | ||
6c2882f9 BP |
412 | echo |
413 | .... | |
414 | ||
415 | Request object members: | |
416 | ||
417 | "method": "echo" required | |
6e79e210 BP |
418 | "params": JSON array with any contents required |
419 | "id": <value> required | |
6c2882f9 BP |
420 | |
421 | Response object members: | |
422 | ||
423 | "result": same as "params" | |
424 | "error": null | |
425 | "id": the request "id" member | |
426 | ||
427 | Both the JSON-RPC client and the server must implement this request. | |
428 | ||
429 | This JSON-RPC request and response can be used to implement connection | |
430 | keepalives, by allowing the server to check that the client is still | |
431 | there or vice versa. | |
432 | ||
433 | ||
f85f8ebb BP |
434 | Notation for the Wire Protocol |
435 | ------------------------------ | |
436 | ||
437 | <table> | |
438 | ||
439 | An <id> that names a table. | |
440 | ||
441 | <column> | |
442 | ||
443 | An <id> that names a table column. | |
444 | ||
445 | <row> | |
446 | ||
447 | A JSON object that describes a table row or a subset of a table | |
448 | row. Each member is the name of a table column paired with the | |
449 | <value> of that column. | |
450 | ||
451 | <value> | |
452 | ||
453 | A JSON value that represents the value of a column in a table row, | |
454 | one of <atom>, a <set>, or a <map>. | |
455 | ||
456 | <atom> | |
457 | ||
458 | A JSON value that represents a scalar value for a column, one of | |
459 | <string>, <number>, <boolean>, <uuid>, <named-uuid>. | |
460 | ||
461 | <set> | |
462 | ||
463 | A 2-element JSON array that represents a database set value. The | |
464 | first element of the array must be the string "set" and the second | |
465 | element must be an array of zero or more <atom>s giving the values | |
466 | in the set. All of the <atom>s must have the same type. | |
467 | ||
468 | <map> | |
469 | ||
470 | A 2-element JSON array that represents a database map value. The | |
471 | first element of the array must be the string "map" and the second | |
472 | element must be an array of zero or more <pair>s giving the values | |
473 | in the map. All of the <pair>s must have the same key and value | |
474 | types. | |
475 | ||
476 | (JSON objects are not used to represent <map> because JSON only | |
477 | allows string names in an object.) | |
478 | ||
479 | <pair> | |
480 | ||
481 | A 2-element JSON array that represents a pair within a database | |
482 | map. The first element is an <atom> that represents the key, the | |
483 | second element is an <atom> that represents the value. | |
484 | ||
485 | <uuid> | |
486 | ||
487 | A 2-element JSON array that represents a UUID. The first element | |
488 | of the array must be the string "uuid" and the second element must | |
489 | be a 36-character string giving the UUID in the format described | |
490 | by RFC 4122. For example, the following <uuid> represents the | |
491 | UUID 550e8400-e29b-41d4-a716-446655440000: | |
492 | ||
493 | ["uuid", "550e8400-e29b-41d4-a716-446655440000"] | |
494 | ||
495 | <named-uuid> | |
496 | ||
497 | A 2-element JSON array that represents the UUID of a row inserted | |
498 | in a previous "insert" operation within the same transaction. The | |
499 | first element of the array must be the string "named-uuid" and the | |
500 | second element must be the string specified on a previous "insert" | |
501 | operation's "uuid-name". For example, if a previous "insert" | |
502 | operation specified a "uuid-name" of "myrow", the following | |
503 | <named-uuid> represents the UUID created by that operation: | |
504 | ||
505 | ["named-uuid", "myrow"] | |
506 | ||
507 | <condition> | |
508 | ||
509 | A 3-element JSON array of the form [<column>, <function>, | |
510 | <value>] that represents a test on a column value. | |
511 | ||
512 | Except as otherwise specified below, <value> must have the same | |
513 | type as <column>. | |
514 | ||
515 | The meaning depends on the type of <column>: | |
516 | ||
517 | integer | |
518 | real | |
519 | ||
520 | <function> must be "<", "<=", "==", "!=", ">=", ">", | |
521 | "includes", or "excludes". | |
522 | ||
523 | The test is true if the column's value satisfies the | |
524 | relation <function> <value>, e.g. if the column has value | |
525 | 1 and <value> is 2, the test is true if <function> is "<", | |
526 | "<=" or "!=", but not otherwise. | |
527 | ||
528 | "includes" is equivalent to "=="; "excludes" is equivalent | |
529 | to "!=". | |
530 | ||
531 | boolean | |
532 | string | |
533 | uuid | |
534 | ||
535 | <function> must be "!=", "==", "includes", or "excludes". | |
536 | ||
537 | If <function> is "==" or "includes", the test is true if | |
538 | the column's value equals <value>. If <function> is "!=" | |
539 | or "excludes", the test is inverted. | |
540 | ||
541 | set | |
542 | map | |
543 | ||
544 | <function> must be "!=", "==", "includes", or "excludes". | |
545 | ||
546 | If <function> is "==", the test is true if the column's | |
547 | value contains exactly the same values (for sets) or pairs | |
548 | (for maps). If <function> is "!=", the test is inverted. | |
549 | ||
550 | If <function> is "includes", the test is true if the | |
551 | column's value contains all of the values (for sets) or | |
552 | pairs (for maps) in <value>. The column's value may also | |
553 | contain other values or pairs. | |
554 | ||
555 | If <function> is "excludes", the test is true if the | |
556 | column's value does not contain any of the values (for | |
557 | sets) or pairs (for maps) in <value>. The column's value | |
558 | may contain other values or pairs not in <value>. | |
559 | ||
560 | If <function> is "includes" or "excludes", then the | |
561 | required type of <value> is slightly relaxed, in that it | |
562 | may have fewer than the minimum number of elements | |
563 | specified by the column's type. If <function> is | |
564 | "excludes", then the required type is additionally relaxed | |
565 | in that <value> may have more than the maximum number of | |
566 | elements specified by the column's type. | |
567 | ||
568 | <function> | |
569 | ||
570 | One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes". | |
571 | ||
572 | Operations | |
573 | ---------- | |
574 | ||
575 | Each of the available operations is described below. | |
576 | ||
577 | insert | |
578 | ...... | |
579 | ||
580 | Request object members: | |
581 | ||
582 | "op": "insert" required | |
583 | "table": <table> required | |
584 | "row": <row> required | |
585 | "uuid-name": <string> optional | |
586 | ||
587 | Result object members: | |
588 | ||
589 | "uuid": <uuid> | |
590 | ||
591 | Semantics: | |
592 | ||
593 | Inserts "row" into "table". If "row" does not specify values | |
594 | for all the columns in "table", those columns receive default | |
595 | values. | |
596 | ||
597 | The new row receives a new, randomly generated UUID, which is | |
e68c3e48 | 598 | returned as the "uuid" member of the result. If "uuid-name" |
f85f8ebb BP |
599 | is supplied, then the UUID is made available under that name |
600 | to later operations within the same transaction. | |
601 | ||
602 | select | |
603 | ...... | |
604 | ||
605 | Request object members: | |
606 | ||
607 | "op": "select" required | |
608 | "table": <table> required | |
609 | "where": [<condition>*] required | |
610 | "columns": [<column>*] optional | |
611 | ||
612 | Result object members: | |
613 | ||
614 | "rows": [<row>*] | |
615 | ||
616 | Semantics: | |
617 | ||
618 | Searches "table" for rows that match all the conditions specified | |
619 | in "where". If "where" is an empty array, every row in "table" is | |
620 | selected. | |
621 | ||
622 | The "rows" member of the result is an array of objects. Each | |
623 | object corresponds to a matching row, with each column | |
624 | specified in "columns" as a member, the column's name as the | |
625 | member name and its value as the member value. If "columns" | |
626 | is not specified, all the table's columns are included. If | |
627 | two rows of the result have the same values for all included | |
628 | columns, only one copy of that row is included in "rows". | |
629 | Specifying "_uuid" within "columns" will avoid dropping | |
630 | duplicates, since every row has a unique UUID. | |
631 | ||
632 | The ordering of rows within "rows" is unspecified. | |
633 | ||
634 | update | |
635 | ...... | |
636 | ||
637 | Request object members: | |
638 | ||
639 | "op": "update" required | |
640 | "table": <table> required | |
641 | "where": [<condition>*] required | |
642 | "row": <row> required | |
643 | ||
644 | Result object members: | |
645 | ||
646 | "count": <integer> | |
647 | ||
648 | Semantics: | |
649 | ||
650 | Updates rows in a table. | |
651 | ||
652 | Searches "table" for rows that match all the conditions | |
653 | specified in "where". For each matching row, changes the | |
654 | value of each column specified in "row" to the value for that | |
655 | column specified in "row". | |
656 | ||
e68c3e48 JP |
657 | The "_uuid" and "_version" columns of a table may not be directly |
658 | updated with this operation. Columns designated read-only in the | |
659 | schema also may not be updated. | |
f85f8ebb BP |
660 | |
661 | The "count" member of the result specifies the number of rows | |
662 | that matched. | |
663 | ||
664 | delete | |
665 | ...... | |
666 | ||
667 | Request object members: | |
668 | ||
669 | "op": "delete" required | |
670 | "table": <table> required | |
671 | "where": [<condition>*] required | |
672 | ||
673 | Result object members: | |
674 | ||
675 | "count": <integer> | |
676 | ||
677 | Semantics: | |
678 | ||
679 | Deletes all the rows from "table" that match all the conditions | |
680 | specified in "where". | |
681 | ||
682 | The "count" member of the result specifies the number of deleted | |
683 | rows. | |
684 | ||
685 | wait | |
686 | .... | |
687 | ||
688 | Request object members: | |
689 | ||
690 | "op": "wait" required | |
691 | "timeout": <integer> optional | |
692 | "table": <table> required | |
693 | "where": [<condition>*] required | |
694 | "columns": [<column>*] required | |
695 | "until": "==" or "!=" required | |
696 | "rows": [<row>*] required | |
697 | ||
698 | Result object members: | |
699 | ||
700 | none | |
701 | ||
702 | Semantics: | |
703 | ||
704 | Waits until a condition becomes true. | |
705 | ||
706 | If "until" is "==", checks whether the query on "table" specified | |
707 | by "where" and "columns", which is evaluated in the same way as | |
708 | specified for "select", returns the result set specified by | |
709 | "rows". If it does, then the operation completes successfully. | |
710 | Otherwise, the entire transaction rolls back. It is automatically | |
711 | restarted later, after a change in the database makes it possible | |
712 | for the operation to succeed. The client will not receive a | |
713 | response until the operation permanently succeeds or fails. | |
714 | ||
715 | If "until" is "!=", the sense of the test is negated. That is, as | |
716 | long as the query on "table" specified by "where" and "columns" | |
717 | returns "rows", the transaction will be rolled back and restarted | |
718 | later. | |
719 | ||
720 | If "timeout" is specified, then the transaction aborts after the | |
721 | specified number of milliseconds. The transaction is guaranteed | |
722 | to be attempted at least once before it aborts. A "timeout" of 0 | |
723 | will abort the transaction on the first mismatch. | |
724 | ||
725 | Errors: | |
726 | ||
727 | "error": "not supported" | |
728 | ||
729 | One or more of the columns in this table do not support | |
730 | triggers. This error will not occur if "timeout" is 0. | |
731 | ||
732 | "error": "timed out" | |
733 | ||
734 | The "timeout" was reached before the transaction was able to | |
735 | complete. | |
736 | ||
737 | commit | |
738 | ...... | |
739 | ||
740 | Request object members: | |
741 | ||
742 | "op": "commit" required | |
743 | "durable": <boolean> required | |
744 | ||
745 | Result object members: | |
746 | ||
747 | none | |
748 | ||
749 | Semantics: | |
750 | ||
751 | If "durable" is specified as true, then the transaction, if it | |
752 | commits, will be stored durably (to disk) before the reply is sent | |
753 | to the client. | |
754 | ||
755 | Errors: | |
756 | ||
757 | "error": "not supported" | |
758 | ||
759 | When "durable" is true, this database implementation does not | |
760 | support durable commits. | |
761 | ||
762 | abort | |
763 | ..... | |
764 | ||
765 | Request object members: | |
766 | ||
767 | "op": "abort" required | |
768 | ||
769 | Result object members: | |
770 | ||
771 | (never succeeds) | |
772 | ||
773 | Semantics: | |
774 | ||
775 | Aborts the transaction with an error. This may be useful for | |
776 | testing. | |
777 | ||
778 | Errors: | |
779 | ||
780 | "error": "aborted" | |
781 | ||
782 | This operation always fails with this error. |