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