]>
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 | ||
12996ef9 | 13 | A JSON string. Any Unicode string is allowed, as specified by RFC |
bd76d25d | 14 | 4627. Implementations may disallow null bytes. |
f85f8ebb BP |
15 | |
16 | <id> | |
17 | ||
18 | A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*. | |
19 | ||
20 | <id>s that begin with _ are reserved to the implementation and may | |
21 | not be used by the user. | |
22 | ||
23 | <boolean> | |
24 | ||
25 | A JSON true or false value. | |
26 | ||
27 | <number> | |
28 | ||
29 | A JSON number. | |
30 | ||
31 | <integer> | |
32 | ||
33 | A JSON number with an integer value, within a certain range | |
34 | (currently -2**63...+2**63-1). | |
35 | ||
a817e524 | 36 | <json-value> |
6e79e210 BP |
37 | |
38 | Any JSON value. | |
39 | ||
394ca249 BP |
40 | <nonnull-json-value> |
41 | ||
42 | Any JSON value except null. | |
43 | ||
bd76d25d BP |
44 | <error> |
45 | ||
46 | A JSON object with the following members: | |
47 | ||
48 | "error": <string> required | |
49 | "details": <string> optional | |
50 | ||
51 | The value of the "error" member is a short string, specified in | |
52 | this document, that broadly indicates the class of the error. | |
53 | Most "error" strings are specific to contexts described elsewhere | |
54 | in this document, but the following "error" strings may appear in | |
55 | any context where an <error> is permitted: | |
56 | ||
57 | "error": "resources exhausted" | |
58 | ||
59 | The operation requires more resources (memory, disk, CPU, | |
60 | etc.) than are currently available to the database server. | |
61 | ||
62 | "error": "I/O error" | |
63 | ||
64 | Problems accessing the disk, network, or other required | |
65 | resources prevented the operation from completing. | |
66 | ||
67 | Database implementations may use "error" strings not specified | |
68 | in this document to indicate errors that do not fit into any of | |
69 | the specified categories. | |
70 | ||
71 | Optionally, an <error> may include a "details" member, whose value | |
72 | is a string that describes the error in more detail for the | |
73 | benefit of a human user or administrator. This document does not | |
74 | specify the format or content of the "details" string. | |
75 | ||
76 | An <error> may also have other members that describe the error in | |
77 | more detail. This document does not specify the names or values | |
78 | of these members. | |
79 | ||
f85f8ebb BP |
80 | Schema Format |
81 | ------------- | |
82 | ||
83 | An Open vSwitch configuration database consists of a set of tables, | |
84 | each of which has a number of columns and zero or more rows. A schema | |
85 | is represented by <database-schema>, as described below. | |
86 | ||
87 | <database-schema> | |
88 | ||
89 | A JSON object with the following members: | |
90 | ||
91 | "name": <id> required | |
92 | "comment": <string> optional | |
93 | "tables": {<id>: <table-schema>, ...} required | |
94 | ||
9cb53f26 BP |
95 | The "name" identifies the database as a whole. It must be |
96 | provided to most JSON-RPC requests to identify the database being | |
97 | operated on. The "comment" optionally provides more information | |
98 | about the database. The value of "tables" is a JSON object whose | |
99 | names are table names and whose values are <table-schema>s. | |
f85f8ebb BP |
100 | |
101 | <table-schema> | |
102 | ||
103 | A JSON object with the following members: | |
104 | ||
105 | "comment": <string> optional | |
106 | "columns": {<id>: <column-schema>, ...} required | |
107 | ||
108 | The "comment" optionally provides information about this table for | |
e68c3e48 JP |
109 | a human reader. The value of "columns" is a JSON object whose |
110 | names are column names and whose values are <column-schema>s. | |
f85f8ebb BP |
111 | |
112 | Every table has the following columns whose definitions are not | |
113 | included in the schema: | |
114 | ||
115 | "_uuid": This column, which contains exactly one UUID value, | |
116 | is initialized to a random value by the database engine when | |
117 | it creates a row. It is read-only, and its value never | |
118 | changes during the lifetime of a row. | |
119 | ||
120 | "_version": Like "_uuid", this column contains exactly one | |
121 | UUID value, initialized to a random value by the database | |
122 | engine when it creates a row, and it is read-only. However, | |
123 | its value changes to a new random value whenever any other | |
124 | field in the row changes. Furthermore, its value is | |
125 | ephemeral: when the database is closed and reopened, or when | |
126 | the database process is stopped and then started again, each | |
127 | "_version" also changes to a new random value. | |
128 | ||
129 | <column-schema> | |
130 | ||
131 | A JSON object with the following members: | |
132 | ||
133 | "comment": <string> optional | |
134 | "type": <type> required | |
135 | "ephemeral": <boolean> optional | |
136 | ||
137 | The "comment" optionally provides information about this column | |
138 | for a human reader. The "type" specifies the type of data stored | |
139 | in this column. If "ephemeral" is specified as true, then this | |
140 | column's values are not guaranteed to be durable; they may be lost | |
141 | when the database restarts. | |
142 | ||
143 | <type> | |
144 | ||
145 | The type of a database column. Either an <atomic-type> or a JSON | |
146 | object that describes the type of a database column, with the | |
147 | following members: | |
148 | ||
bd76d25d BP |
149 | "key": <base-type> required |
150 | "value": <base-type> optional | |
f85f8ebb BP |
151 | "min": <integer> optional |
152 | "max": <integer> or "unlimited" optional | |
153 | ||
154 | If "min" or "max" is not specified, each defaults to 1. If "max" | |
155 | is specified as "unlimited", then there is no specified maximum | |
156 | number of elements, although the implementation will enforce some | |
31a763d7 BP |
157 | limit. After considering defaults, "min" must be exactly 0 or |
158 | exactly 1, "max" must be at least 1, and "max" must be greater | |
159 | than or equal to "min". | |
f85f8ebb BP |
160 | |
161 | If "min" and "max" are both 1 and "value" is not specified, the | |
162 | type is the scalar type specified by "key". | |
163 | ||
164 | If "min" is not 1 or "max" is not 1, or both, and "value" is not | |
165 | specified, the type is a set of scalar type "key". | |
166 | ||
167 | If "value" is specified, the type is a map from type "key" to type | |
168 | "value". | |
169 | ||
bd76d25d BP |
170 | <base-type> |
171 | ||
172 | The type of a key or value in a database column. Either an | |
173 | <atomic-type> or a JSON object with the following members: | |
174 | ||
175 | "type": <atomic-type> required | |
176 | "minInteger": <integer> optional, integers only | |
177 | "maxInteger": <integer> optional, integers only | |
178 | "minReal": <real> optional, reals only | |
179 | "maxReal": <real> optional, reals only | |
bd76d25d BP |
180 | "minLength": <integer> optional, strings only |
181 | "maxLength": <integer> optional, strings only | |
182 | "refTable": <id> optional, uuids only | |
183 | ||
184 | An <atomic-type> by itself is equivalent to a JSON object with a | |
185 | single member "type" whose value is the <atomic-type>. | |
186 | ||
187 | If "type" is "integer", then "minInteger" or "maxInteger" or both | |
188 | may also be specified, restricting the valid integer range. If | |
189 | both are specified, then the maxInteger must be greater than or | |
190 | equal to minInteger. | |
191 | ||
192 | If "type" is "real", then "minReal" or "maxReal" or both may also | |
193 | be specified, restricting the valid real range. If both are | |
194 | specified, then the maxReal must be greater than or equal to | |
195 | minReal. | |
196 | ||
89521e3f BP |
197 | If "type" is "string", then "minLength" and "maxLength" or both |
198 | may be specified, restricting the valid length of value strings. | |
199 | If both are specified, then maxLength must be greater than or | |
200 | equal to minLength. String length is measured in characters (not | |
201 | bytes or UTF-16 code units). | |
bd76d25d | 202 | |
0d0f05b9 BP |
203 | If "type" is "uuid", then "refTable", if present, must be the name |
204 | of a table within this database. If "refTable" is set, the | |
205 | allowed UUIDs are limited to UUIDs for rows in the named table. | |
206 | ||
207 | "refTable" constraints are "deferred" constraints: they are | |
208 | enforced only at transaction commit time (see the "transact" | |
209 | request below). The other contraints on <base-type> are | |
210 | "immediate", enforced immediately by each operation. | |
bd76d25d | 211 | |
f85f8ebb BP |
212 | <atomic-type> |
213 | ||
214 | One of the strings "integer", "real", "boolean", "string", or | |
215 | "uuid", representing the specified scalar type. | |
216 | ||
217 | Wire Protocol | |
218 | ------------- | |
219 | ||
12996ef9 BP |
220 | The database wire protocol is implemented in JSON-RPC 1.0. We |
221 | encourage use of JSON-RPC over stream connections instead of JSON-RPC | |
222 | over HTTP, for these reasons: | |
223 | ||
224 | * JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server | |
225 | protocol, which is a poor match. Thus, JSON-RPC over HTTP | |
226 | requires the client to periodically poll the server to receive | |
227 | server requests. | |
228 | ||
229 | * HTTP is more complicated than stream connections and doesn't | |
230 | provide any corresponding advantage. | |
231 | ||
232 | * The JSON-RPC specification for HTTP transport is incomplete. | |
233 | ||
234 | The database wire protocol consists of the following JSON-RPC methods: | |
f85f8ebb | 235 | |
9cb53f26 BP |
236 | list_dbs |
237 | ........ | |
238 | ||
239 | Request object members: | |
240 | ||
241 | "method": "list_dbs" required | |
242 | "params": [] required | |
394ca249 | 243 | "id": <nonnull-json-value> required |
9cb53f26 BP |
244 | |
245 | Response object members: | |
246 | ||
247 | "result": [<db-name>, ...] | |
248 | "error": null | |
249 | "id": same "id" as request | |
250 | ||
251 | This operation retrieves an array whose elements are <db-name>s | |
252 | that name the databases that can be accessed over this JSON-RPC | |
253 | connection. | |
254 | ||
f85f8ebb BP |
255 | get_schema |
256 | .......... | |
257 | ||
258 | Request object members: | |
259 | ||
260 | "method": "get_schema" required | |
9cb53f26 | 261 | "params": [<db-name>] required |
394ca249 | 262 | "id": <nonnull-json-value> required |
f85f8ebb BP |
263 | |
264 | Response object members: | |
265 | ||
266 | "result": <database-schema> | |
267 | "error": null | |
268 | "id": same "id" as request | |
269 | ||
9cb53f26 BP |
270 | This operation retrieves a <database-schema> that describes hosted |
271 | database <db-name>. | |
f85f8ebb BP |
272 | |
273 | transact | |
274 | ........ | |
275 | ||
276 | Request object members: | |
277 | ||
9cb53f26 BP |
278 | "method": "transact" required |
279 | "params": [<db-name>, <operation>*] required | |
394ca249 | 280 | "id": <nonnull-json-value> required |
f85f8ebb BP |
281 | |
282 | Response object members: | |
283 | ||
284 | "result": [<object>*] | |
285 | "error": null | |
286 | "id": same "id" as request | |
287 | ||
9cb53f26 BP |
288 | The "params" array for this method consists of a <db-name> that |
289 | identifies the database to which the transaction applies, followed by | |
290 | zero or more JSON objects, each of which represents a single database | |
291 | operation. The "Operations" section below describes the valid | |
292 | operations. | |
f85f8ebb BP |
293 | |
294 | The value of "id" must be unique among all in-flight transactions | |
295 | within the current JSON-RPC session. Otherwise, the server may return | |
296 | a JSON-RPC error. | |
297 | ||
298 | The database server executes each of the specified operations in the | |
299 | specified order, except that if an operation fails, then the remaining | |
300 | operations are not executed. | |
301 | ||
302 | The set of operations is executed as a single atomic, consistent, | |
303 | isolated transaction. The transaction is committed only if every | |
304 | operation succeeds. Durability of the commit is not guaranteed unless | |
305 | the "commit" operation, with "durable" set to true, is included in the | |
306 | operation set (see below). | |
307 | ||
308 | Regardless of whether errors occur, the response is always a JSON-RPC | |
309 | response with null "error" and a "result" member that is an array with | |
310 | the same number of elements as "params". Each element of the "result" | |
311 | array corresponds to the same element of the "params" array. The | |
312 | "result" array elements may be interpreted as follows: | |
313 | ||
314 | - A JSON object that does not contain an "error" member indicates | |
315 | that the operation completed successfully. The specific members | |
316 | of the object are specified below in the descriptions of | |
317 | individual operations. Some operations do not produce any | |
318 | results, in which case the object will have no members. | |
319 | ||
bd76d25d BP |
320 | - An <error>, which indicates that the operation completed with an |
321 | error. | |
f85f8ebb BP |
322 | |
323 | - A JSON null value indicates that the operation was not attempted | |
324 | because a prior operation failed. | |
325 | ||
326 | In general, "result" contains some number of successful results, | |
327 | possibly followed by an error, in turn followed by enough JSON null | |
328 | values to match the number of elements in "params". There is one | |
329 | exception: if all of the operations succeed, but the results cannot be | |
0d0f05b9 BP |
330 | committed, then "result" will have one more element than "params", |
331 | with the additional element an <error>. The possible "error" strings | |
332 | include at least the following: | |
333 | ||
334 | "error": "referential integrity violation" | |
335 | ||
336 | When the commit was attempted, a column's value referenced the | |
337 | UUID for a row that did not exist in the table named by the | |
338 | column's <base-type> key or value "refTable". (This can be | |
339 | caused by inserting a row that references a nonexistent row, | |
340 | by deleting a row that is still referenced by another row, by | |
341 | specifying the UUID for a row in the wrong table, and other | |
342 | ways.) | |
f85f8ebb BP |
343 | |
344 | If "params" contains one or more "wait" operations, then the | |
345 | transaction may take an arbitrary amount of time to complete. The | |
346 | database implementation must be capable of accepting, executing, and | |
347 | replying to other transactions and other JSON-RPC requests while a | |
348 | transaction or transactions containing "wait" operations are | |
349 | outstanding on the same or different JSON-RPC sessions. | |
350 | ||
351 | The section "Notation for the Wire Protocol" below describes | |
352 | additional notation for use with the wire protocol. After that, the | |
353 | "Operations" section describes each operation. | |
354 | ||
355 | cancel | |
356 | ...... | |
357 | ||
358 | Request object members: | |
359 | ||
360 | "method": "cancel" required | |
6e79e210 | 361 | "params": [the "id" for an outstanding request] required |
f85f8ebb BP |
362 | "id": null required |
363 | ||
364 | Response object members: | |
365 | ||
366 | <no response> | |
367 | ||
368 | This JSON-RPC notification instructs the database server to | |
369 | immediately complete or cancel the "transact" request whose "id" is | |
370 | the same as the notification's "params" value. | |
371 | ||
372 | If the "transact" request can be completed immediately, then the | |
373 | server sends a response in the form described for "transact", above. | |
374 | Otherwise, the server sends a JSON-RPC error response of the following | |
375 | form: | |
376 | ||
377 | "result": null | |
378 | "error": "canceled" | |
379 | "id": the request "id" member | |
380 | ||
381 | The "cancel" notification itself has no reply. | |
382 | ||
a8425c53 BP |
383 | monitor |
384 | ....... | |
385 | ||
386 | Request object members: | |
387 | ||
a817e524 BP |
388 | "method": "monitor" required |
389 | "params": [<db-name>, <json-value>, <monitor-requests>] required | |
394ca249 | 390 | "id": <nonnull-json-value> required |
a8425c53 BP |
391 | |
392 | <monitor-requests> is an object that maps from a table name to a | |
393 | <monitor-request>. | |
394 | ||
395 | Each <monitor-request> is an object with the following members: | |
396 | ||
397 | "columns": [<column>*] optional | |
398 | "select": <monitor-select> optional | |
399 | ||
400 | <monitor-select> is an object with the following members: | |
401 | ||
402 | "initial": <boolean> optional | |
403 | "insert": <boolean> optional | |
404 | "delete": <boolean> optional | |
405 | "modify": <boolean> optional | |
406 | ||
407 | Response object members: | |
408 | ||
409 | "result": <table-updates> | |
410 | "error": null | |
411 | "id": same "id" as request | |
412 | ||
413 | This JSON-RPC request enables a client to replicate tables or subsets | |
9cb53f26 BP |
414 | of tables within database <db-name>. Each <monitor-request> specifies |
415 | a table to be replicated. The JSON-RPC response to the "monitor" | |
416 | includes the initial contents of each table. Afterward, when changes | |
417 | to those tables are committed, the changes are automatically sent to | |
418 | the client using the "update" monitor notification. This monitoring | |
419 | persists until the JSON-RPC session terminates or until the client | |
420 | sends a "monitor_cancel" JSON-RPC request. | |
a8425c53 BP |
421 | |
422 | Each <monitor-request> describes how to monitor a table: | |
423 | ||
424 | The circumstances in which an "update" notification is sent for a | |
425 | row within the table are determined by <monitor-select>: | |
426 | ||
427 | If "initial" is omitted or true, every row in the table is | |
428 | sent as part of the reply to the "monitor" request. | |
429 | ||
430 | If "insert" is omitted or true, "update" notifications are | |
431 | sent for rows newly inserted into the table. | |
432 | ||
433 | If "delete" is omitted or true, "update" notifications are | |
434 | sent for rows deleted from the table. | |
435 | ||
436 | If "modify" is omitted or true, "update" notifications are | |
437 | sent whenever when a row in the table is modified. | |
438 | ||
439 | The "columns" member specifies the columns whose values are | |
440 | monitored. If "columns" is omitted, all columns in the table, | |
441 | except for "_uuid", are monitored. | |
442 | ||
443 | The "result" in the JSON-RPC response to the "monitor" request is a | |
444 | <table-updates> object (see below) that contains the contents of the | |
445 | tables for which "initial" rows are selected. If no tables' initial | |
446 | contents are requested, then "result" is an empty object. | |
447 | ||
448 | update | |
449 | ...... | |
450 | ||
451 | Notification object members: | |
452 | ||
453 | "method": "update" | |
a817e524 | 454 | "params": [<json-value>, <table-updates>] |
a8425c53 BP |
455 | "id": null |
456 | ||
a817e524 BP |
457 | The <json-value> in "params" is the same as the value passed as the |
458 | <json-value> in "params" for the "monitor" request. | |
a8425c53 BP |
459 | |
460 | <table-updates> is an object that maps from a table name to a | |
461 | <table-update>. | |
462 | ||
463 | A <table-update> is an object that maps from the row's UUID (as a | |
464 | 36-byte string) to a <row-update> object. | |
465 | ||
466 | A <row-update> is an object with the following members: | |
467 | ||
468 | "old": <row> present for "delete" and "modify" updates | |
469 | "new": <row> present for "initial", "insert", and "modify" updates | |
470 | ||
471 | This JSON-RPC notification is sent from the server to the client to | |
472 | tell it about changes to a monitored table (or the initial state of a | |
473 | modified table). Each table in which one or more rows has changed (or | |
474 | whose initial view is being presented) is represented in "updates". | |
475 | Each row that has changed (or whose initial view is being presented) | |
476 | is represented in its <table-update> as a member with its name taken | |
477 | from the row's _uuid member. The corresponding value is a | |
478 | <row-update>: | |
479 | ||
480 | The "old" member is present for "delete" and "modify" updates. | |
481 | For "delete" updates, each monitored column is included. For | |
482 | "modify" updates, the prior value of each monitored column whose | |
483 | value has changed is included (monitored columns that have not | |
484 | changed are represented in "new"). | |
485 | ||
486 | The "new" member is present for "initial", "insert", and "modify" | |
487 | updates. For "initial" and "insert" updates, each monitored | |
488 | column is included. For "modify" updates, the new value of each | |
489 | monitored column is included. | |
490 | ||
491 | monitor_cancel | |
492 | .............. | |
493 | ||
494 | Request object members: | |
495 | ||
496 | "method": "monitor_cancel" required | |
a817e524 | 497 | "params": [<json-value>] required |
394ca249 | 498 | "id": <nonnull-json-value> required |
a8425c53 BP |
499 | |
500 | Response object members: | |
501 | ||
502 | "result": {} | |
503 | "error": null | |
504 | "id": the request "id" member | |
505 | ||
a817e524 BP |
506 | Cancels the ongoing table monitor request, identified by the |
507 | <json-value> in "params" matching the <json-value> in "params" for an | |
508 | ongoing "monitor" request. No more "update" messages will be sent for | |
509 | this table monitor. | |
a8425c53 | 510 | |
6c2882f9 BP |
511 | echo |
512 | .... | |
513 | ||
514 | Request object members: | |
515 | ||
516 | "method": "echo" required | |
6e79e210 | 517 | "params": JSON array with any contents required |
a817e524 | 518 | "id": <json-value> required |
6c2882f9 BP |
519 | |
520 | Response object members: | |
521 | ||
522 | "result": same as "params" | |
523 | "error": null | |
524 | "id": the request "id" member | |
525 | ||
526 | Both the JSON-RPC client and the server must implement this request. | |
527 | ||
528 | This JSON-RPC request and response can be used to implement connection | |
529 | keepalives, by allowing the server to check that the client is still | |
530 | there or vice versa. | |
531 | ||
532 | ||
f85f8ebb BP |
533 | Notation for the Wire Protocol |
534 | ------------------------------ | |
535 | ||
9cb53f26 BP |
536 | <db-name> |
537 | ||
538 | An <id> that names a database. The valid <db-name>s can be | |
539 | obtained using a "list-db" request. The <db-name> is taken from | |
540 | the "name" member of <database-schema>. | |
541 | ||
f85f8ebb BP |
542 | <table> |
543 | ||
544 | An <id> that names a table. | |
545 | ||
546 | <column> | |
547 | ||
548 | An <id> that names a table column. | |
549 | ||
550 | <row> | |
551 | ||
552 | A JSON object that describes a table row or a subset of a table | |
553 | row. Each member is the name of a table column paired with the | |
554 | <value> of that column. | |
555 | ||
556 | <value> | |
557 | ||
558 | A JSON value that represents the value of a column in a table row, | |
559 | one of <atom>, a <set>, or a <map>. | |
560 | ||
561 | <atom> | |
562 | ||
563 | A JSON value that represents a scalar value for a column, one of | |
564 | <string>, <number>, <boolean>, <uuid>, <named-uuid>. | |
565 | ||
566 | <set> | |
567 | ||
ae8f13e2 BP |
568 | Either an <atom>, representing a set with exactly one element, or |
569 | a 2-element JSON array that represents a database set value. The | |
f85f8ebb BP |
570 | first element of the array must be the string "set" and the second |
571 | element must be an array of zero or more <atom>s giving the values | |
572 | in the set. All of the <atom>s must have the same type. | |
573 | ||
574 | <map> | |
575 | ||
576 | A 2-element JSON array that represents a database map value. The | |
577 | first element of the array must be the string "map" and the second | |
578 | element must be an array of zero or more <pair>s giving the values | |
579 | in the map. All of the <pair>s must have the same key and value | |
580 | types. | |
581 | ||
582 | (JSON objects are not used to represent <map> because JSON only | |
583 | allows string names in an object.) | |
584 | ||
585 | <pair> | |
586 | ||
587 | A 2-element JSON array that represents a pair within a database | |
588 | map. The first element is an <atom> that represents the key, the | |
589 | second element is an <atom> that represents the value. | |
590 | ||
591 | <uuid> | |
592 | ||
593 | A 2-element JSON array that represents a UUID. The first element | |
594 | of the array must be the string "uuid" and the second element must | |
595 | be a 36-character string giving the UUID in the format described | |
596 | by RFC 4122. For example, the following <uuid> represents the | |
597 | UUID 550e8400-e29b-41d4-a716-446655440000: | |
598 | ||
599 | ["uuid", "550e8400-e29b-41d4-a716-446655440000"] | |
600 | ||
601 | <named-uuid> | |
602 | ||
603 | A 2-element JSON array that represents the UUID of a row inserted | |
fbf925e4 BP |
604 | in an "insert" operation within the same transaction. The first |
605 | element of the array must be the string "named-uuid" and the | |
606 | second element should be the string specified as the "uuid-name" | |
607 | for an "insert" operation within the same transaction. For | |
608 | example, if an "insert" operation within this transaction | |
609 | specifies a "uuid-name" of "myrow", the following <named-uuid> | |
610 | represents the UUID created by that operation: | |
f85f8ebb BP |
611 | |
612 | ["named-uuid", "myrow"] | |
613 | ||
6e30ca63 BP |
614 | A <named-uuid> may be used anywhere a <uuid> is valid. |
615 | ||
f85f8ebb BP |
616 | <condition> |
617 | ||
618 | A 3-element JSON array of the form [<column>, <function>, | |
619 | <value>] that represents a test on a column value. | |
620 | ||
621 | Except as otherwise specified below, <value> must have the same | |
622 | type as <column>. | |
623 | ||
624 | The meaning depends on the type of <column>: | |
625 | ||
626 | integer | |
627 | real | |
628 | ||
629 | <function> must be "<", "<=", "==", "!=", ">=", ">", | |
630 | "includes", or "excludes". | |
631 | ||
632 | The test is true if the column's value satisfies the | |
633 | relation <function> <value>, e.g. if the column has value | |
634 | 1 and <value> is 2, the test is true if <function> is "<", | |
635 | "<=" or "!=", but not otherwise. | |
636 | ||
637 | "includes" is equivalent to "=="; "excludes" is equivalent | |
638 | to "!=". | |
639 | ||
640 | boolean | |
641 | string | |
642 | uuid | |
643 | ||
644 | <function> must be "!=", "==", "includes", or "excludes". | |
645 | ||
646 | If <function> is "==" or "includes", the test is true if | |
647 | the column's value equals <value>. If <function> is "!=" | |
648 | or "excludes", the test is inverted. | |
649 | ||
650 | set | |
651 | map | |
652 | ||
653 | <function> must be "!=", "==", "includes", or "excludes". | |
654 | ||
655 | If <function> is "==", the test is true if the column's | |
656 | value contains exactly the same values (for sets) or pairs | |
657 | (for maps). If <function> is "!=", the test is inverted. | |
658 | ||
659 | If <function> is "includes", the test is true if the | |
660 | column's value contains all of the values (for sets) or | |
661 | pairs (for maps) in <value>. The column's value may also | |
662 | contain other values or pairs. | |
663 | ||
664 | If <function> is "excludes", the test is true if the | |
665 | column's value does not contain any of the values (for | |
666 | sets) or pairs (for maps) in <value>. The column's value | |
667 | may contain other values or pairs not in <value>. | |
668 | ||
669 | If <function> is "includes" or "excludes", then the | |
670 | required type of <value> is slightly relaxed, in that it | |
671 | may have fewer than the minimum number of elements | |
672 | specified by the column's type. If <function> is | |
673 | "excludes", then the required type is additionally relaxed | |
674 | in that <value> may have more than the maximum number of | |
675 | elements specified by the column's type. | |
676 | ||
677 | <function> | |
678 | ||
679 | One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes". | |
680 | ||
e9f8f936 BP |
681 | <mutation> |
682 | ||
683 | A 3-element JSON array of the form [<column>, <mutator>, <value>] | |
684 | that represents a change to a column value. | |
685 | ||
686 | Except as otherwise specified below, <value> must have the same | |
687 | type as <column>. | |
688 | ||
689 | The meaning depends on the type of <column>: | |
690 | ||
691 | integer | |
692 | real | |
693 | ||
694 | <mutator> must be "+=", "-=", "*=", "/=" or (integer only) | |
695 | "%=". The value of <column> is changed to the sum, | |
696 | difference, product, quotient, or remainder, respectively, | |
697 | of <column> and <value>. | |
698 | ||
bd76d25d BP |
699 | Constraints on <column> are ignored when parsing <value>. |
700 | ||
e9f8f936 BP |
701 | boolean |
702 | string | |
703 | uuid | |
704 | ||
705 | No valid <mutator>s are currently defined for these types. | |
706 | ||
707 | set | |
708 | ||
709 | Any <mutator> valid for the set's element type may be | |
710 | applied to the set, in which case the mutation is applied | |
711 | to each member of the set individually. <value> must be a | |
bd76d25d BP |
712 | scalar value of the same type as the set's element type, |
713 | except that contraints are ignored. | |
e9f8f936 BP |
714 | |
715 | If <mutator> is "insert", then each of the values in the | |
716 | set in <value> is added to <column> if it is not already | |
717 | present. The required type of <value> is slightly | |
718 | relaxed, in that it may have fewer than the minimum number | |
719 | of elements specified by the column's type. | |
720 | ||
721 | If <mutator> is "delete", then each of the values in the | |
722 | set in <value> is removed from <column> if it is present | |
723 | there. The required type is slightly relaxed in that | |
724 | <value> may have more or less than the maximum number of | |
725 | elements specified by the column's type. | |
726 | ||
727 | map | |
728 | ||
729 | <mutator> must be "insert" or "delete". | |
730 | ||
731 | If <mutator> is "insert", then each of the key-value pairs | |
03b1f24e BP |
732 | in the map in <value> is added to <column> only if its key |
733 | is not already present. The required type of <value> is | |
e9f8f936 BP |
734 | slightly relaxed, in that it may have fewer than the |
735 | minimum number of elements specified by the column's type. | |
736 | ||
737 | If <mutator> is "delete", then <value> may have the same | |
738 | type as <column> (a map type) or it may be a set whose | |
739 | element type is the same as <column>'s key type: | |
740 | ||
741 | - If <value> is a map, the mutation deletes each | |
742 | key-value pair in <column> whose key and value equal | |
743 | one of the key-value pairs in <value>. | |
744 | ||
745 | - If <value> is a set, the mutation deletes each | |
746 | key-value pair in <column> whose key equals one of | |
747 | the values in <value>. | |
748 | ||
749 | For "delete", <value> may have any number of elements, | |
750 | regardless of restrictions on the number of elements in | |
751 | <column>. | |
752 | ||
753 | <mutator> | |
754 | ||
755 | One of "+=", "-=", "*=", "/=", "%=", "insert", "delete". | |
756 | ||
f85f8ebb BP |
757 | Operations |
758 | ---------- | |
759 | ||
760 | Each of the available operations is described below. | |
761 | ||
762 | insert | |
763 | ...... | |
764 | ||
765 | Request object members: | |
766 | ||
767 | "op": "insert" required | |
768 | "table": <table> required | |
769 | "row": <row> required | |
2d2d6d4a | 770 | "uuid-name": <id> optional |
f85f8ebb BP |
771 | |
772 | Result object members: | |
773 | ||
774 | "uuid": <uuid> | |
775 | ||
776 | Semantics: | |
777 | ||
bd76d25d BP |
778 | Inserts "row" into "table". |
779 | ||
780 | If "row" does not specify values for all the columns in "table", | |
781 | those columns receive default values. The default value for a | |
782 | column depends on its type. The default for a column whose <type> | |
783 | specifies a "min" of 0 is an empty set or empty map. Otherwise, | |
784 | the default is a single value or a single key-value pair, whose | |
785 | value(s) depend on its <atomic-type>: | |
786 | ||
787 | - "integer" or "real": 0 | |
788 | ||
789 | - "boolean": false | |
790 | ||
791 | - "string": "" (the empty string) | |
792 | ||
793 | - "uuid": 00000000-0000-0000-0000-000000000000 | |
f85f8ebb | 794 | |
fbf925e4 | 795 | The new row receives a new, randomly generated UUID. |
2d2d6d4a | 796 | |
fbf925e4 BP |
797 | If "uuid-name" is supplied, then it is an error if <id> is not |
798 | unique among the "uuid-name"s supplied on all the "insert" | |
799 | operations within this transaction. | |
2d2d6d4a BP |
800 | |
801 | The UUID for the new row is returned as the "uuid" member of the | |
802 | result. | |
803 | ||
804 | Errors: | |
805 | ||
806 | "error": "duplicate uuid-name" | |
807 | ||
fbf925e4 | 808 | The same "uuid-name" appears on another "insert" operation |
2d2d6d4a | 809 | within this transaction. |
f85f8ebb | 810 | |
bd76d25d BP |
811 | "error": "constraint violation" |
812 | ||
813 | One of the values in "row" does not satisfy the immediate | |
814 | constraints for its column's <base-type>. This error will | |
815 | occur for columns that are not explicitly set by "row" if the | |
816 | default value does not satisfy the column's constraints. | |
817 | ||
f85f8ebb BP |
818 | select |
819 | ...... | |
820 | ||
821 | Request object members: | |
822 | ||
823 | "op": "select" required | |
824 | "table": <table> required | |
825 | "where": [<condition>*] required | |
826 | "columns": [<column>*] optional | |
827 | ||
828 | Result object members: | |
829 | ||
830 | "rows": [<row>*] | |
831 | ||
832 | Semantics: | |
833 | ||
834 | Searches "table" for rows that match all the conditions specified | |
835 | in "where". If "where" is an empty array, every row in "table" is | |
836 | selected. | |
837 | ||
838 | The "rows" member of the result is an array of objects. Each | |
839 | object corresponds to a matching row, with each column | |
840 | specified in "columns" as a member, the column's name as the | |
841 | member name and its value as the member value. If "columns" | |
842 | is not specified, all the table's columns are included. If | |
843 | two rows of the result have the same values for all included | |
844 | columns, only one copy of that row is included in "rows". | |
845 | Specifying "_uuid" within "columns" will avoid dropping | |
846 | duplicates, since every row has a unique UUID. | |
847 | ||
848 | The ordering of rows within "rows" is unspecified. | |
849 | ||
850 | update | |
851 | ...... | |
852 | ||
853 | Request object members: | |
854 | ||
855 | "op": "update" required | |
856 | "table": <table> required | |
857 | "where": [<condition>*] required | |
858 | "row": <row> required | |
859 | ||
860 | Result object members: | |
861 | ||
862 | "count": <integer> | |
863 | ||
864 | Semantics: | |
865 | ||
866 | Updates rows in a table. | |
867 | ||
868 | Searches "table" for rows that match all the conditions | |
869 | specified in "where". For each matching row, changes the | |
870 | value of each column specified in "row" to the value for that | |
871 | column specified in "row". | |
872 | ||
e68c3e48 JP |
873 | The "_uuid" and "_version" columns of a table may not be directly |
874 | updated with this operation. Columns designated read-only in the | |
875 | schema also may not be updated. | |
f85f8ebb BP |
876 | |
877 | The "count" member of the result specifies the number of rows | |
878 | that matched. | |
879 | ||
bd76d25d BP |
880 | Errors: |
881 | ||
882 | "error": "constraint violation" | |
883 | ||
884 | One of the values in "row" does not satisfy the immediate | |
885 | constraints for its column's <base-type>. | |
e9f8f936 BP |
886 | mutate |
887 | ...... | |
888 | ||
889 | Request object members: | |
890 | ||
891 | "op": "mutate" required | |
892 | "table": <table> required | |
893 | "where": [<condition>*] required | |
894 | "mutations": [<mutation>*] required | |
895 | ||
896 | Result object members: | |
897 | ||
898 | "count": <integer> | |
899 | ||
900 | Semantics: | |
901 | ||
902 | Mutates rows in a table. | |
903 | ||
904 | Searches "table" for rows that match all the conditions specified | |
905 | in "where". For each matching row, mutates its columns as | |
906 | specified by each <mutation> in "mutations", in the order | |
907 | specified. | |
908 | ||
909 | The "_uuid" and "_version" columns of a table may not be directly | |
910 | modified with this operation. Columns designated read-only in the | |
911 | schema also may not be updated. | |
912 | ||
913 | The "count" member of the result specifies the number of rows | |
914 | that matched. | |
915 | ||
916 | Errors: | |
917 | ||
918 | "error": "domain error" | |
919 | ||
920 | The result of the mutation is not mathematically defined, | |
921 | e.g. division by zero. | |
922 | ||
923 | "error": "range error" | |
924 | ||
925 | The result of the mutation is not representable within the | |
926 | database's format, e.g. an integer result outside the range | |
927 | INT64_MIN...INT64_MAX or a real result outside the range | |
928 | -DBL_MAX...DBL_MAX. | |
929 | ||
930 | "error": "constraint violation" | |
931 | ||
932 | The mutation caused the column's value to violate a | |
933 | constraint, e.g. it caused a column to have more or fewer | |
bd76d25d BP |
934 | values than are allowed, an arithmetic operation caused a set |
935 | or map to have duplicate elements, or it violated a constraint | |
936 | specified by a column's <base-type>. | |
e9f8f936 | 937 | |
f85f8ebb BP |
938 | delete |
939 | ...... | |
940 | ||
941 | Request object members: | |
942 | ||
943 | "op": "delete" required | |
944 | "table": <table> required | |
945 | "where": [<condition>*] required | |
946 | ||
947 | Result object members: | |
948 | ||
949 | "count": <integer> | |
950 | ||
951 | Semantics: | |
952 | ||
953 | Deletes all the rows from "table" that match all the conditions | |
954 | specified in "where". | |
955 | ||
956 | The "count" member of the result specifies the number of deleted | |
957 | rows. | |
958 | ||
959 | wait | |
960 | .... | |
961 | ||
962 | Request object members: | |
963 | ||
964 | "op": "wait" required | |
965 | "timeout": <integer> optional | |
966 | "table": <table> required | |
967 | "where": [<condition>*] required | |
968 | "columns": [<column>*] required | |
969 | "until": "==" or "!=" required | |
970 | "rows": [<row>*] required | |
971 | ||
972 | Result object members: | |
973 | ||
974 | none | |
975 | ||
976 | Semantics: | |
977 | ||
978 | Waits until a condition becomes true. | |
979 | ||
980 | If "until" is "==", checks whether the query on "table" specified | |
981 | by "where" and "columns", which is evaluated in the same way as | |
982 | specified for "select", returns the result set specified by | |
983 | "rows". If it does, then the operation completes successfully. | |
984 | Otherwise, the entire transaction rolls back. It is automatically | |
985 | restarted later, after a change in the database makes it possible | |
986 | for the operation to succeed. The client will not receive a | |
987 | response until the operation permanently succeeds or fails. | |
988 | ||
989 | If "until" is "!=", the sense of the test is negated. That is, as | |
990 | long as the query on "table" specified by "where" and "columns" | |
991 | returns "rows", the transaction will be rolled back and restarted | |
992 | later. | |
993 | ||
994 | If "timeout" is specified, then the transaction aborts after the | |
995 | specified number of milliseconds. The transaction is guaranteed | |
996 | to be attempted at least once before it aborts. A "timeout" of 0 | |
997 | will abort the transaction on the first mismatch. | |
998 | ||
999 | Errors: | |
1000 | ||
1001 | "error": "not supported" | |
1002 | ||
1003 | One or more of the columns in this table do not support | |
1004 | triggers. This error will not occur if "timeout" is 0. | |
1005 | ||
1006 | "error": "timed out" | |
1007 | ||
1008 | The "timeout" was reached before the transaction was able to | |
1009 | complete. | |
1010 | ||
1011 | commit | |
1012 | ...... | |
1013 | ||
1014 | Request object members: | |
1015 | ||
1016 | "op": "commit" required | |
1017 | "durable": <boolean> required | |
1018 | ||
1019 | Result object members: | |
1020 | ||
1021 | none | |
1022 | ||
1023 | Semantics: | |
1024 | ||
1025 | If "durable" is specified as true, then the transaction, if it | |
1026 | commits, will be stored durably (to disk) before the reply is sent | |
1027 | to the client. | |
1028 | ||
1029 | Errors: | |
1030 | ||
1031 | "error": "not supported" | |
1032 | ||
1033 | When "durable" is true, this database implementation does not | |
1034 | support durable commits. | |
1035 | ||
1036 | abort | |
1037 | ..... | |
1038 | ||
1039 | Request object members: | |
1040 | ||
1041 | "op": "abort" required | |
1042 | ||
1043 | Result object members: | |
1044 | ||
1045 | (never succeeds) | |
1046 | ||
1047 | Semantics: | |
1048 | ||
1049 | Aborts the transaction with an error. This may be useful for | |
1050 | testing. | |
1051 | ||
1052 | Errors: | |
1053 | ||
1054 | "error": "aborted" | |
1055 | ||
1056 | This operation always fails with this error. | |
2d2d6d4a | 1057 | |
d171b584 BP |
1058 | comment |
1059 | ....... | |
1060 | ||
1061 | ||
1062 | Request object members: | |
1063 | ||
1064 | "op": "comment" required | |
1065 | "comment": <string> required | |
1066 | ||
1067 | Result object members: | |
1068 | ||
1069 | none | |
1070 | ||
1071 | Semantics: | |
1072 | ||
1073 | Provides information to a database administrator on the purpose of | |
1074 | a transaction. The OVSDB server, for example, adds comments in | |
1075 | transactions that modify the database to the database journal. |