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