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