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.
  14
  15 <id>
  16
  17     A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*.
  18
  19     <id>s that begin with _ are reserved to the implementation and may
  20     not be used by the user.
  21
  22 <boolean>
  23
  24     A JSON true or false value.
  25
  26 <number>
  27
  28     A JSON number.
  29
  30 <integer>
  31
  32     A JSON number with an integer value, within a certain range
  33     (currently -2**63...+2**63-1).
  34
  35 Schema Format
  36 -------------
  37
  38 An Open vSwitch configuration database consists of a set of tables,
  39 each of which has a number of columns and zero or more rows.  A schema
  40 is represented by <database-schema>, as described below.
  41
  42 <database-schema>
  43
  44     A JSON object with the following members:
  45
  46         "name": <id>                            required
  47         "comment": <string>                     optional
  48         "tables": {<id>: <table-schema>, ...}   required
  49
  50     The "name" identifies the database as a whole.  The "comment"
  51     optionally provides more information about the database.  The
  52     value of "tables" is a JSON object whose names are table names and
  53     whose values are <table-schema>s.
  54
  55 <table-schema>
  56
  57     A JSON object with the following members:
  58
  59         "comment": <string>                       optional
  60         "columns": {<id>: <column-schema>, ...}   required
  61
  62     The "comment" optionally provides information about this table for
  63     a human reader.  The value of "tables" is a JSON object whose
  64     names are table names and whose values are <column-schema>s.
  65
  66     Every table has the following columns whose definitions are not
  67     included in the schema:
  68
  69         "_uuid": This column, which contains exactly one UUID value,
  70         is initialized to a random value by the database engine when
  71         it creates a row.  It is read-only, and its value never
  72         changes during the lifetime of a row.
  73
  74         "_version": Like "_uuid", this column contains exactly one
  75         UUID value, initialized to a random value by the database
  76         engine when it creates a row, and it is read-only.  However,
  77         its value changes to a new random value whenever any other
  78         field in the row changes.  Furthermore, its value is
  79         ephemeral: when the database is closed and reopened, or when
  80         the database process is stopped and then started again, each
  81         "_version" also changes to a new random value.
  82
  83 <column-schema>
  84
  85     A JSON object with the following members:
  86
  87         "comment": <string>                       optional
  88         "type": <type>                            required
  89         "ephemeral": <boolean>                    optional
  90
  91     The "comment" optionally provides information about this column
  92     for a human reader.  The "type" specifies the type of data stored
  93     in this column.  If "ephemeral" is specified as true, then this
  94     column's values are not guaranteed to be durable; they may be lost
  95     when the database restarts.
  96
  97 <type>
  98
  99     The type of a database column.  Either an <atomic-type> or a JSON
 100     object that describes the type of a database column, with the
 101     following members:
 102
 103         "key": <atomic-type>               required
 104         "value": <atomic-type>             optional
 105         "min": <integer>                   optional
 106         "max": <integer> or "unlimited"    optional
 107
 108     If "min" or "max" is not specified, each defaults to 1.  If "max"
 109     is specified as "unlimited", then there is no specified maximum
 110     number of elements, although the implementation will enforce some
 111     limit.  After considering defaults, "min" must be at least 0,
 112     "max" must be at least 1, and "max" must be greater than or equal
 113     to "min".
 114
 115     If "min" and "max" are both 1 and "value" is not specified, the
 116     type is the scalar type specified by "key".
 117
 118     If "min" is not 1 or "max" is not 1, or both, and "value" is not
 119     specified, the type is a set of scalar type "key".
 120
 121     If "value" is specified, the type is a map from type "key" to type
 122     "value".
 123
 124 <atomic-type>
 125
 126     One of the strings "integer", "real", "boolean", "string", or
 127     "uuid", representing the specified scalar type.
 128
 129 Wire Protocol
 130 -------------
 131
 132 The database wire protocol is implemented in JSON-RPC 1.0.  It
 133 consists of the following JSON-RPC methods:
 134
 135 get_schema
 136 ..........
 137
 138 Request object members:
 139
 140     "method": "get_schema"            required
 141     "params": []                      required
 142     "id": any JSON value except null  required
 143
 144 Response object members:
 145
 146     "result": <database-schema>
 147     "error": null
 148     "id": same "id" as request
 149
 150 This operation retrieves a <database-schema> that describes the
 151 hosted database.
 152
 153 transact
 154 ........
 155
 156 Request object members:
 157
 158     "method": "transact"              required
 159     "params": [<operation>*]          required
 160     "id": any JSON value except null  required
 161
 162 Response object members:
 163
 164     "result": [<object>*]
 165     "error": null
 166     "id": same "id" as request
 167
 168 The "params" array for this method consists of zero or more JSON
 169 objects, each of which represents a single database operation.  The
 170 "Operations" section below describes the valid operations.
 171
 172 The value of "id" must be unique among all in-flight transactions
 173 within the current JSON-RPC session.  Otherwise, the server may return
 174 a JSON-RPC error.
 175
 176 The database server executes each of the specified operations in the
 177 specified order, except that if an operation fails, then the remaining
 178 operations are not executed.
 179
 180 The set of operations is executed as a single atomic, consistent,
 181 isolated transaction.  The transaction is committed only if every
 182 operation succeeds.  Durability of the commit is not guaranteed unless
 183 the "commit" operation, with "durable" set to true, is included in the
 184 operation set (see below).
 185
 186 Regardless of whether errors occur, the response is always a JSON-RPC
 187 response with null "error" and a "result" member that is an array with
 188 the same number of elements as "params".  Each element of the "result"
 189 array corresponds to the same element of the "params" array.  The
 190 "result" array elements may be interpreted as follows:
 191
 192     - A JSON object that does not contain an "error" member indicates
 193       that the operation completed successfully.  The specific members
 194       of the object are specified below in the descriptions of
 195       individual operations.  Some operations do not produce any
 196       results, in which case the object will have no members.
 197
 198     - A JSON object that contains a "error" member indicates that the
 199       operation completed with an error.  The value of the "error"
 200       member is a short string, specified in this document, that
 201       broadly indicates the class of the error.  Besides the ones
 202       listed for a specific operation, any operation may result in one
 203       the following "error"s:
 204
 205       "error": "resources exhausted"
 206
 207           The operation or the transaction requires more resources
 208           (memory, disk, CPU, etc.) than are currently available to
 209           the database server.
 210
 211       "error": "syntax error"
 212
 213           The operation is not specified correctly: a required request
 214           object member is missing, an unknown or unsupported request
 215           object member is present, the operation attempts to act on a
 216           table that does not exist, the operation modifies a
 217           read-only table column, etc.
 218
 219       Database implementations may use "error" strings not specified
 220       in this document to indicate errors that do not fit into any of
 221       the specified categories.
 222
 223       Optionally, the object may include a "details" member, whose
 224       value is a string that describes the error in more detail for
 225       the benefit of a human user or administrator.  The object may
 226       also have other members that describe the error in more detail.
 227       This document does not specify the names or values of these
 228       members.
 229
 230     - A JSON null value indicates that the operation was not attempted
 231       because a prior operation failed.
 232
 233 In general, "result" contains some number of successful results,
 234 possibly followed by an error, in turn followed by enough JSON null
 235 values to match the number of elements in "params".  There is one
 236 exception: if all of the operations succeed, but the results cannot be
 237 committed (e.g. due to I/O errors), then "result" will have one more
 238 element than "params", with the additional element describing the
 239 error.
 240
 241 If "params" contains one or more "wait" operations, then the
 242 transaction may take an arbitrary amount of time to complete.  The
 243 database implementation must be capable of accepting, executing, and
 244 replying to other transactions and other JSON-RPC requests while a
 245 transaction or transactions containing "wait" operations are
 246 outstanding on the same or different JSON-RPC sessions.
 247
 248 The section "Notation for the Wire Protocol" below describes
 249 additional notation for use with the wire protocol.  After that, the
 250 "Operations" section describes each operation.
 251
 252 cancel
 253 ......
 254
 255 Request object members:
 256
 257     "method": "cancel"                              required
 258     "params": the "id" for an outstanding request   required
 259     "id": null                                      required
 260
 261 Response object members:
 262
 263     <no response>
 264
 265 This JSON-RPC notification instructs the database server to
 266 immediately complete or cancel the "transact" request whose "id" is
 267 the same as the notification's "params" value.
 268
 269 If the "transact" request can be completed immediately, then the
 270 server sends a response in the form described for "transact", above.
 271 Otherwise, the server sends a JSON-RPC error response of the following
 272 form:
 273
 274     "result": null
 275     "error": "canceled"
 276     "id": the request "id" member
 277
 278 The "cancel" notification itself has no reply.
 279
 280 Notation for the Wire Protocol
 281 ------------------------------
 282
 283 <table>
 284
 285     An <id> that names a table.
 286
 287 <column>
 288
 289     An <id> that names a table column.
 290
 291 <row>
 292
 293     A JSON object that describes a table row or a subset of a table
 294     row.  Each member is the name of a table column paired with the
 295     <value> of that column.
 296
 297 <value>
 298
 299     A JSON value that represents the value of a column in a table row,
 300     one of <atom>, a <set>, or a <map>.
 301
 302 <atom>
 303
 304     A JSON value that represents a scalar value for a column, one of
 305     <string>, <number>, <boolean>, <uuid>, <named-uuid>.
 306
 307 <set>
 308
 309     A 2-element JSON array that represents a database set value.  The
 310     first element of the array must be the string "set" and the second
 311     element must be an array of zero or more <atom>s giving the values
 312     in the set.  All of the <atom>s must have the same type.
 313
 314 <map>
 315
 316     A 2-element JSON array that represents a database map value.  The
 317     first element of the array must be the string "map" and the second
 318     element must be an array of zero or more <pair>s giving the values
 319     in the map.  All of the <pair>s must have the same key and value
 320     types.
 321
 322     (JSON objects are not used to represent <map> because JSON only
 323     allows string names in an object.)
 324
 325 <pair>
 326
 327     A 2-element JSON array that represents a pair within a database
 328     map.  The first element is an <atom> that represents the key, the
 329     second element is an <atom> that represents the value.
 330
 331 <uuid>
 332
 333     A 2-element JSON array that represents a UUID.  The first element
 334     of the array must be the string "uuid" and the second element must
 335     be a 36-character string giving the UUID in the format described
 336     by RFC 4122.  For example, the following <uuid> represents the
 337     UUID 550e8400-e29b-41d4-a716-446655440000:
 338
 339         ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
 340
 341 <named-uuid>
 342
 343     A 2-element JSON array that represents the UUID of a row inserted
 344     in a previous "insert" operation within the same transaction.  The
 345     first element of the array must be the string "named-uuid" and the
 346     second element must be the string specified on a previous "insert"
 347     operation's "uuid-name".  For example, if a previous "insert"
 348     operation specified a "uuid-name" of "myrow", the following
 349     <named-uuid> represents the UUID created by that operation:
 350
 351         ["named-uuid", "myrow"]
 352
 353 <condition>
 354
 355     A 3-element JSON array of the form [<column>, <function>,
 356     <value>] that represents a test on a column value.
 357
 358     Except as otherwise specified below, <value> must have the same
 359     type as <column>.
 360
 361     The meaning depends on the type of <column>:
 362
 363         integer
 364         real
 365
 366             <function> must be "<", "<=", "==", "!=", ">=", ">",
 367             "includes", or "excludes".
 368
 369             The test is true if the column's value satisfies the
 370             relation <function> <value>, e.g. if the column has value
 371             1 and <value> is 2, the test is true if <function> is "<",
 372             "<=" or "!=", but not otherwise.
 373
 374             "includes" is equivalent to "=="; "excludes" is equivalent
 375             to "!=".
 376
 377         boolean
 378         string
 379         uuid
 380
 381             <function> must be "!=", "==", "includes", or "excludes".
 382
 383             If <function> is "==" or "includes", the test is true if
 384             the column's value equals <value>.  If <function> is "!="
 385             or "excludes", the test is inverted.
 386
 387         set
 388         map
 389
 390             <function> must be "!=", "==", "includes", or "excludes".
 391
 392             If <function> is "==", the test is true if the column's
 393             value contains exactly the same values (for sets) or pairs
 394             (for maps).  If <function> is "!=", the test is inverted.
 395
 396             If <function> is "includes", the test is true if the
 397             column's value contains all of the values (for sets) or
 398             pairs (for maps) in <value>.  The column's value may also
 399             contain other values or pairs.
 400
 401             If <function> is "excludes", the test is true if the
 402             column's value does not contain any of the values (for
 403             sets) or pairs (for maps) in <value>.  The column's value
 404             may contain other values or pairs not in <value>.
 405
 406             If <function> is "includes" or "excludes", then the
 407             required type of <value> is slightly relaxed, in that it
 408             may have fewer than the minimum number of elements
 409             specified by the column's type.  If <function> is
 410             "excludes", then the required type is additionally relaxed
 411             in that <value> may have more than the maximum number of
 412             elements specified by the column's type.
 413
 414 <function>
 415
 416     One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
 417
 418 Operations
 419 ----------
 420
 421 Each of the available operations is described below.
 422
 423 insert
 424 ......
 425
 426 Request object members:
 427
 428     "op": "insert"          required
 429     "table": <table>        required
 430     "row": <row>            required
 431     "uuid-name": <string>   optional
 432
 433 Result object members:
 434
 435     "uuid": <uuid>
 436
 437 Semantics:
 438
 439     Inserts "row" into "table".  If "row" does not specify values
 440     for all the columns in "table", those columns receive default
 441     values.
 442
 443     The new row receives a new, randomly generated UUID, which is
 444     returned as the "_uuid" member of the result.  If "uuid-name"
 445     is supplied, then the UUID is made available under that name
 446     to later operations within the same transaction.
 447
 448 select
 449 ......
 450
 451 Request object members:
 452
 453     "op": "select"                required
 454     "table": <table>              required
 455     "where": [<condition>*]       required
 456     "columns": [<column>*]        optional
 457
 458 Result object members:
 459
 460     "rows": [<row>*]
 461
 462 Semantics:
 463
 464     Searches "table" for rows that match all the conditions specified
 465     in "where".  If "where" is an empty array, every row in "table" is
 466     selected.
 467
 468     The "rows" member of the result is an array of objects.  Each
 469     object corresponds to a matching row, with each column
 470     specified in "columns" as a member, the column's name as the
 471     member name and its value as the member value.  If "columns"
 472     is not specified, all the table's columns are included.  If
 473     two rows of the result have the same values for all included
 474     columns, only one copy of that row is included in "rows".
 475     Specifying "_uuid" within "columns" will avoid dropping
 476     duplicates, since every row has a unique UUID.
 477
 478     The ordering of rows within "rows" is unspecified.
 479
 480 update
 481 ......
 482
 483 Request object members:
 484
 485     "op": "update"                required
 486     "table": <table>              required
 487     "where": [<condition>*]       required
 488     "row": <row>                  required
 489
 490 Result object members:
 491
 492     "count": <integer>
 493
 494 Semantics:
 495
 496     Updates rows in a table.
 497
 498     Searches "table" for rows that match all the conditions
 499     specified in "where".  For each matching row, changes the
 500     value of each column specified in "row" to the value for that
 501     column specified in "row".
 502
 503     The "_uuid" and "_version" columns of a table may not be updated.
 504     Columns designated read-only in the schema also may not be
 505     updated.
 506
 507     The "count" member of the result specifies the number of rows
 508     that matched.
 509
 510 delete
 511 ......
 512
 513 Request object members:
 514
 515     "op": "delete"                required
 516     "table": <table>              required
 517     "where": [<condition>*]       required
 518
 519 Result object members:
 520
 521     "count": <integer>
 522
 523 Semantics:
 524
 525     Deletes all the rows from "table" that match all the conditions
 526     specified in "where".
 527
 528     The "count" member of the result specifies the number of deleted
 529     rows.
 530
 531 wait
 532 ....
 533
 534 Request object members:
 535
 536     "op": "wait"                        required
 537     "timeout": <integer>                optional
 538     "table": <table>                    required
 539     "where": [<condition>*]             required
 540     "columns": [<column>*]              required
 541     "until": "==" or "!="               required
 542     "rows": [<row>*]                    required
 543
 544 Result object members:
 545
 546     none
 547
 548 Semantics:
 549
 550     Waits until a condition becomes true.
 551
 552     If "until" is "==", checks whether the query on "table" specified
 553     by "where" and "columns", which is evaluated in the same way as
 554     specified for "select", returns the result set specified by
 555     "rows".  If it does, then the operation completes successfully.
 556     Otherwise, the entire transaction rolls back.  It is automatically
 557     restarted later, after a change in the database makes it possible
 558     for the operation to succeed.  The client will not receive a
 559     response until the operation permanently succeeds or fails.
 560
 561     If "until" is "!=", the sense of the test is negated.  That is, as
 562     long as the query on "table" specified by "where" and "columns"
 563     returns "rows", the transaction will be rolled back and restarted
 564     later.
 565
 566     If "timeout" is specified, then the transaction aborts after the
 567     specified number of milliseconds.  The transaction is guaranteed
 568     to be attempted at least once before it aborts.  A "timeout" of 0
 569     will abort the transaction on the first mismatch.
 570
 571 Errors:
 572
 573     "error": "not supported"
 574
 575         One or more of the columns in this table do not support
 576         triggers.  This error will not occur if "timeout" is 0.
 577
 578     "error": "timed out"
 579
 580         The "timeout" was reached before the transaction was able to
 581         complete.
 582
 583 commit
 584 ......
 585
 586 Request object members:
 587
 588     "op": "commit"                      required
 589     "durable": <boolean>                required
 590
 591 Result object members:
 592
 593     none
 594
 595 Semantics:
 596
 597     If "durable" is specified as true, then the transaction, if it
 598     commits, will be stored durably (to disk) before the reply is sent
 599     to the client.
 600
 601 Errors:
 602
 603     "error": "not supported"
 604
 605         When "durable" is true, this database implementation does not
 606         support durable commits.
 607
 608 abort
 609 .....
 610
 611 Request object members:
 612
 613     "op": "abort"                      required
 614
 615 Result object members:
 616
 617     (never succeeds)
 618
 619 Semantics:
 620
 621     Aborts the transaction with an error.  This may be useful for
 622     testing.
 623
 624 Errors:
 625
 626     "error": "aborted"
 627
 628         This operation always fails with this error.