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