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