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