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