meta-flow: Correctly set destination MAC in mf_set_flow_value().

[sliver-openvswitch.git] / ovsdb / SPECS

         ===================================================
          Open vSwitch Configuration Database Specification
         ===================================================

Basic Notation
--------------

OVSDB uses JSON, as defined by RFC 4627, for its schema format and its
wire protocol format.  The JSON implementation in Open vSwitch has the
following limitations:

     - Null bytes (\u0000) are not allowed in strings.

     - Only UTF-8 encoding is supported.  (RFC 4627 also mentions
       UTF-16BE, UTF-16LE, and UTF-32.)

     - RFC 4627 says that names within a JSON object should be unique.
       The Open vSwitch JSON parser discards all but the last value
       for a name that is specified more than once.

The descriptions below use the following shorthand notations for JSON
values.  Additional notation is presented later.

<string>

    A JSON string.  Any Unicode string is allowed, as specified by RFC
    4627.  Implementations may disallow null bytes.

<id>

    A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*.

    <id>s that begin with _ are reserved to the implementation and may
    not be used by the user.

<version>

    A JSON string that contains a version number that matches
    [0-9]+\.[0-9]+\.[0-9]+

<boolean>

    A JSON true or false value.

<number>

    A JSON number.

<integer>

    A JSON number with an integer value, within a certain range
    (currently -2**63...+2**63-1).

<json-value>

    Any JSON value.

<nonnull-json-value>

    Any JSON value except null.

<error>

    A JSON object with the following members:

        "error": <string>                       required
        "details": <string>                     optional

    The value of the "error" member is a short string, specified in
    this document, that broadly indicates the class of the error.
    Most "error" strings are specific to contexts described elsewhere
    in this document, but the following "error" strings may appear in
    any context where an <error> is permitted:

    "error": "resources exhausted"

        The operation requires more resources (memory, disk, CPU,
        etc.) than are currently available to the database server.

    "error": "I/O error"

        Problems accessing the disk, network, or other required
        resources prevented the operation from completing.

    Database implementations may use "error" strings not specified
    in this document to indicate errors that do not fit into any of
    the specified categories.

    Optionally, an <error> may include a "details" member, whose value
    is a string that describes the error in more detail for the
    benefit of a human user or administrator.  This document does not
    specify the format or content of the "details" string.

    An <error> may also have other members that describe the error in
    more detail.  This document does not specify the names or values
    of these members.

Schema Format
-------------

An Open vSwitch configuration database consists of a set of tables,
each of which has a number of columns and zero or more rows.  A schema
is represented by <database-schema>, as described below.

<database-schema>

    A JSON object with the following members:

        "name": <id>                            required
        "version": <version>                    required
        "cksum": <string>                       optional
        "tables": {<id>: <table-schema>, ...}   required

    The "name" identifies the database as a whole.  It must be
    provided to most JSON-RPC requests to identify the database being
    operated on.  The value of "tables" is a JSON object whose names
    are table names and whose values are <table-schema>s.

    The "version" reports the version of the database schema.  Because
    this is a recent addition to the schema format, OVSDB permits it
    to be omitted, but future versions of OVSDB will require it to be
    present.  Open vSwitch semantics for "version" are described in
    ovs-vswitchd.conf.db(5).

    The "cksum" optionally reports an implementation-defined checksum
    for the database schema.

<table-schema>

    A JSON object with the following members:

        "columns": {<id>: <column-schema>, ...}   required
        "maxRows": <integer>                      optional
        "isRoot": <boolean>                       optional
        "indexes": [<column-set>*]                optional

    The value of "columns" is a JSON object whose names are column
    names and whose values are <column-schema>s.

    Every table has the following columns whose definitions are not
    included in the schema:

        "_uuid": This column, which contains exactly one UUID value,
        is initialized to a random value by the database engine when
        it creates a row.  It is read-only, and its value never
        changes during the lifetime of a row.

        "_version": Like "_uuid", this column contains exactly one
        UUID value, initialized to a random value by the database
        engine when it creates a row, and it is read-only.  However,
        its value changes to a new random value whenever any other
        field in the row changes.  Furthermore, its value is
        ephemeral: when the database is closed and reopened, or when
        the database process is stopped and then started again, each
        "_version" also changes to a new random value.

    If "isRoot" is omitted or specified as false, then any given row
    in the table may exist only when there is at least one reference
    to it, with refType "strong", from a different row (in the same
    table or a different table).  This is a "deferred" action:
    unreferenced rows in the table are deleted just before transaction
    commit.  If "isRoot" is specified as true, then rows in the table
    exist independent of any references (they can be thought of as
    part of the "root set" in a garbage collector).

    For compatibility with schemas created before "isRoot" was
    introduced, if "isRoot" is omitted or false in every
    <table-schema> in a given <database-schema>, then every table is
    part of the root set.

    If "maxRows" is specified, as a positive integer, it limits the
    maximum number of rows that may be present in the table.  This is
    a "deferred" constraint, enforced only at transaction commit time
    (see the "transact" request below).  If "maxRows" is not
    specified, the size of the table is limited only by the resources
    available to the database server.  "maxRows" constraints are
    enforced after unreferenced rows are deleted from tables with a
    false "isRoot".

    If "indexes" is specified, it must be an array of zero or more
    <column-set>s.  A <column-set> is an array of one or more strings,
    each of which names a column.  Each <column-set> is a set of
    columns whose values, taken together within any given row, must be
    unique within the table.  This is a "deferred" constraint,
    enforced only at transaction commit time, after unreferenced rows
    are deleted and dangling weak references are removed.  Ephemeral
    columns may not be part of indexes.

<column-schema>

    A JSON object with the following members:

        "type": <type>                            required
        "ephemeral": <boolean>                    optional
        "mutable": <boolean>                      optional

    The "type" specifies the type of data stored in this column.

    If "ephemeral" is specified as true, then this column's values are
    not guaranteed to be durable; they may be lost when the database
    restarts.  A column whose type (either key or value) is a strong
    reference to a table that is not part of the root set is always
    durable, regardless of this value.  (Otherwise, restarting the
    database could lose entire rows.)

    If "mutable" is specified as false, then this column's values may
    not be modified after they are initially set with the "insert"
    operation.

<type>

    The type of a database column.  Either an <atomic-type> or a JSON
    object that describes the type of a database column, with the
    following members:

        "key": <base-type>                 required
        "value": <base-type>               optional
        "min": <integer>                   optional
        "max": <integer> or "unlimited"    optional

    If "min" or "max" is not specified, each defaults to 1.  If "max"
    is specified as "unlimited", then there is no specified maximum
    number of elements, although the implementation will enforce some
    limit.  After considering defaults, "min" must be exactly 0 or
    exactly 1, "max" must be at least 1, and "max" must be greater
    than or equal to "min".

    If "min" and "max" are both 1 and "value" is not specified, the
    type is the scalar type specified by "key".

    If "min" is not 1 or "max" is not 1, or both, and "value" is not
    specified, the type is a set of scalar type "key".

    If "value" is specified, the type is a map from type "key" to type
    "value".

<base-type>

    The type of a key or value in a database column.  Either an
    <atomic-type> or a JSON object with the following members:

        "type": <atomic-type>              required
        "enum": <value>                    optional
        "minInteger": <integer>            optional, integers only
        "maxInteger": <integer>            optional, integers only
        "minReal": <real>                  optional, reals only
        "maxReal": <real>                  optional, reals only
        "minLength": <integer>             optional, strings only
        "maxLength": <integer>             optional, strings only
        "refTable": <id>                   optional, uuids only
        "refType": "strong" or "weak"      optional, only with "refTable"

    An <atomic-type> by itself is equivalent to a JSON object with a
    single member "type" whose value is the <atomic-type>.

    "enum" may be specified as a <value> whose type is a set of one
    or more values specified for the member "type".  If "enum" is
    specified, then the valid values of the <base-type> are limited to
    those in the <value>.

    "enum" is mutually exclusive with the following constraints.

    If "type" is "integer", then "minInteger" or "maxInteger" or both
    may also be specified, restricting the valid integer range.  If
    both are specified, then the maxInteger must be greater than or
    equal to minInteger.

    If "type" is "real", then "minReal" or "maxReal" or both may also
    be specified, restricting the valid real range.  If both are
    specified, then the maxReal must be greater than or equal to
    minReal.

    If "type" is "string", then "minLength" and "maxLength" or both
    may be specified, restricting the valid length of value strings.
    If both are specified, then maxLength must be greater than or
    equal to minLength.  String length is measured in characters (not
    bytes or UTF-16 code units).

    If "type" is "uuid", then "refTable", if present, must be the name
    of a table within this database.  If "refTable" is specified, then
    "refType" may also be specified.  If "refTable" is set, the effect
    depends on "refType":

        - If "refType" is "strong" or if "refType" is omitted, the
          allowed UUIDs are limited to UUIDs for rows in the named
          table.

        - If "refType" is "weak", then any UUIDs are allowed, but
          UUIDs that do not correspond to rows in the named table will
          be automatically deleted.

    "refTable" constraints are "deferred" constraints: they are
    enforced only at transaction commit time (see the "transact"
    request below).  The other contraints on <base-type> are
    "immediate", enforced immediately by each operation.

<atomic-type>

    One of the strings "integer", "real", "boolean", "string", or
    "uuid", representing the specified scalar type.

Wire Protocol
-------------

The database wire protocol is implemented in JSON-RPC 1.0.  We
encourage use of JSON-RPC over stream connections instead of JSON-RPC
over HTTP, for these reasons:

    * JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server
      protocol, which is a poor match.  Thus, JSON-RPC over HTTP
      requires the client to periodically poll the server to receive
      server requests.

    * HTTP is more complicated than stream connections and doesn't
      provide any corresponding advantage.

    * The JSON-RPC specification for HTTP transport is incomplete.

We are using TCP port 6632 for the database JSON-RPC connection.

The database wire protocol consists of the following JSON-RPC methods:

list_dbs
........

Request object members:

    "method": "list_dbs"              required
    "params": []                      required
    "id": <nonnull-json-value>        required

Response object members:

    "result": [<db-name>, ...]
    "error": null
    "id": same "id" as request

This operation retrieves an array whose elements are <db-name>s
that name the databases that can be accessed over this JSON-RPC
connection.

get_schema
..........

Request object members:

    "method": "get_schema"            required
    "params": [<db-name>]             required
    "id": <nonnull-json-value>        required

Response object members:

    "result": <database-schema>
    "error": null
    "id": same "id" as request

This operation retrieves a <database-schema> that describes hosted
database <db-name>.

transact
........

Request object members:

    "method": "transact"                  required
    "params": [<db-name>, <operation>*]   required
    "id": <nonnull-json-value>            required

Response object members:

    "result": [<object>*]
    "error": null
    "id": same "id" as request

The "params" array for this method consists of a <db-name> that
identifies the database to which the transaction applies, followed by
zero or more JSON objects, each of which represents a single database
operation.  The "Operations" section below describes the valid
operations.

The value of "id" must be unique among all in-flight transactions
within the current JSON-RPC session.  Otherwise, the server may return
a JSON-RPC error.

The database server executes each of the specified operations in the
specified order, except that if an operation fails, then the remaining
operations are not executed.

The set of operations is executed as a single atomic, consistent,
isolated transaction.  The transaction is committed only if every
operation succeeds.  Durability of the commit is not guaranteed unless
the "commit" operation, with "durable" set to true, is included in the
operation set (see below).

Regardless of whether errors occur, the response is always a JSON-RPC
response with null "error" and a "result" member that is an array with
the same number of elements as "params".  Each element of the "result"
array corresponds to the same element of the "params" array.  The
"result" array elements may be interpreted as follows:

    - A JSON object that does not contain an "error" member indicates
      that the operation completed successfully.  The specific members
      of the object are specified below in the descriptions of
      individual operations.  Some operations do not produce any
      results, in which case the object will have no members.

    - An <error>, which indicates that the operation completed with an
      error.

    - A JSON null value indicates that the operation was not attempted
      because a prior operation failed.

In general, "result" contains some number of successful results,
possibly followed by an error, in turn followed by enough JSON null
values to match the number of elements in "params".  There is one
exception: if all of the operations succeed, but the results cannot be
committed, then "result" will have one more element than "params",
with the additional element an <error>.  The possible "error" strings
include at least the following:

    "error": "referential integrity violation"

        When the commit was attempted, a column's value referenced the
        UUID for a row that did not exist in the table named by the
        column's <base-type> key or value "refTable" that has a
        "refType" of "strong".  (This can be caused by inserting a row
        that references a nonexistent row, by deleting a row that is
        still referenced by another row, by specifying the UUID for a
        row in the wrong table, and other ways.)

    "error": "constraint violation"

        A column with a <base-type> key or value "refTable" whose
        "refType" is "weak" became empty due to deletion(s) caused
        because the rows that it referenced were deleted (or never
        existed, if the column's row was inserted within the
        transaction), and this column is not allowed to be empty
        because its <type> has a "min" of 1.

    "error": "constraint violation"

        The number of rows in a table exceeds the maximum number
        permitted by the table's "maxRows" value (see <table-schema>).

    "error": "constraint violation"

        Two or more rows in a table had the same values in the columns
        that comprise an index.

    "error": "resources exhausted"
    "error": "I/O error"

        As described in the definition of <error> above.

If "params" contains one or more "wait" operations, then the
transaction may take an arbitrary amount of time to complete.  The
database implementation must be capable of accepting, executing, and
replying to other transactions and other JSON-RPC requests while a
transaction or transactions containing "wait" operations are
outstanding on the same or different JSON-RPC sessions.

The section "Notation for the Wire Protocol" below describes
additional notation for use with the wire protocol.  After that, the
"Operations" section describes each operation.

cancel
......

Request object members:

    "method": "cancel"                              required
    "params": [the "id" for an outstanding request] required
    "id": null                                      required

Response object members:

    <no response>

This JSON-RPC notification instructs the database server to
immediately complete or cancel the "transact" request whose "id" is
the same as the notification's "params" value.

If the "transact" request can be completed immediately, then the
server sends a response in the form described for "transact", above.
Otherwise, the server sends a JSON-RPC error response of the following
form:

    "result": null
    "error": "canceled"
    "id": the request "id" member

The "cancel" notification itself has no reply.

monitor
.......

Request object members:

    "method": "monitor"                                       required
    "params": [<db-name>, <json-value>, <monitor-requests>]   required
    "id": <nonnull-json-value>                                required

<monitor-requests> is an object that maps from a table name to an
array of <monitor-request> objects.  For backward compatibility, a
single <monitor-request> may be used instead of an array; it is
treated as a single-element array.

Each <monitor-request> is an object with the following members:

    "columns": [<column>*]            optional
    "select": <monitor-select>        optional

<monitor-select> is an object with the following members:

    "initial": <boolean>              optional
    "insert": <boolean>               optional
    "delete": <boolean>               optional
    "modify": <boolean>               optional

Response object members:

    "result": <table-updates>
    "error": null
    "id": same "id" as request

This JSON-RPC request enables a client to replicate tables or subsets
of tables within database <db-name>.  Each element of
<monitor-requests> specifies a table to be replicated.  The JSON-RPC
response to the "monitor" includes the initial contents of each table,
unless disabled (see below).  Afterward, when changes to those tables
are committed, the changes are automatically sent to the client using
the "update" monitor notification.  This monitoring persists until the
JSON-RPC session terminates or until the client sends a
"monitor_cancel" JSON-RPC request.

Each <monitor-request> describes how to monitor columns in a table:

    The circumstances in which an "update" notification is sent for a
    row within the table are determined by <monitor-select>:

        If "initial" is omitted or true, every row in the table is
        sent as part of the reply to the "monitor" request.

        If "insert" is omitted or true, "update" notifications are
        sent for rows newly inserted into the table.

        If "delete" is omitted or true, "update" notifications are
        sent for rows deleted from the table.

        If "modify" is omitted or true, "update" notifications are
        sent whenever when a row in the table is modified.

    The "columns" member specifies the columns whose values are
    monitored.  It must not contain duplicates.  If "columns" is
    omitted, all columns in the table, except for "_uuid", are
    monitored.

If there is more than one <monitor-request> in an array of them, then
each <monitor-request> in the array should specify both "columns" and
"select", and the "columns" must be non-overlapping sets.

The "result" in the JSON-RPC response to the "monitor" request is a
<table-updates> object (see below) that contains the contents of the
tables for which "initial" rows are selected.  If no tables' initial
contents are requested, then "result" is an empty object.

update
......

Notification object members:

    "method": "update"
    "params": [<json-value>, <table-updates>]
    "id": null

The <json-value> in "params" is the same as the value passed as the
<json-value> in "params" for the "monitor" request.

<table-updates> is an object that maps from a table name to a
<table-update>.

A <table-update> is an object that maps from the row's UUID (as a
36-byte string) to a <row-update> object.

A <row-update> is an object with the following members:

    "old": <row>         present for "delete" and "modify" updates
    "new": <row>         present for "initial", "insert", and "modify" updates

This JSON-RPC notification is sent from the server to the client to
tell it about changes to a monitored table (or the initial state of a
modified table).  Each table in which one or more rows has changed (or
whose initial view is being presented) is represented in "updates".
Each row that has changed (or whose initial view is being presented)
is represented in its <table-update> as a member with its name taken
from the row's _uuid member.  The corresponding value is a
<row-update>:

    The "old" member is present for "delete" and "modify" updates.
    For "delete" updates, each monitored column is included.  For
    "modify" updates, the prior value of each monitored column whose
    value has changed is included (monitored columns that have not
    changed are represented in "new").

    The "new" member is present for "initial", "insert", and "modify"
    updates.  For "initial" and "insert" updates, each monitored
    column is included.  For "modify" updates, the new value of each
    monitored column is included.

monitor_cancel
..............

Request object members:

    "method": "monitor_cancel"                              required
    "params": [<json-value>]                                required
    "id": <nonnull-json-value>                              required

Response object members:

    "result": {}
    "error": null
    "id": the request "id" member

Cancels the ongoing table monitor request, identified by the
<json-value> in "params" matching the <json-value> in "params" for an
ongoing "monitor" request.  No more "update" messages will be sent for
this table monitor.

lock operations
...............

Request object members:

    "method": "lock", "steal", or "unlock"          required
    "params": [<id>]                                required
    "id": <nonnull-json-value>                      required

Response object members:

    "result": {"locked": <boolean>}     for "lock"
    "result": {"locked": true}          for "steal"
    "result": {}                        for "unlock"
    "error": null
    "id": same "id" as request

Performs an operation on a "lock" object.  The database server
supports an arbitrary number of locks, each of which is identified by
a client-defined id (given in "params").  At any given time, each lock
may have at most one owner.

The locking operation depends on "method":

    - "lock": The database will assign this client ownership of the
      lock as soon as it becomes available.  When multiple clients
      request the same lock, they will receive it in first-come, first
      served order.

    - "steal": The database immediately assigns this client ownership
      of the lock.  If there is an existing owner, it loses ownership.

    - "unlock": If the client owns the lock, releases it.  If the
      client is waiting to obtain the lock, cancels the request and
      stops waiting.

      (Closing or otherwise disconnecting a database client connection
      unlocks all of its locks.)

For any given lock, the client must alternate "lock" or "steal"
operations with "unlock" operations.  That is, if the previous
operation on a lock was "lock" or "steal", it must be followed by an
"unlock" operation, and vice versa.

For a "lock" operation, the "locked" member in the response object is
true if the lock has already been acquired, false if another client
holds the lock and the client's request for it was queued.  In the
latter case, the client will be notified later with a "locked" message
when acquisition succeeds.

These requests complete and send a response quickly, without waiting.
The "locked" and "stolen" notifications (see below) report
asynchronous changes to ownership.

The scope of a lock is a database server, not a database hosted by
that server.  A naming convention, such as "<db-name>__<lock-name>",
can effectively limit the scope of a lock to a particular database.

locked
......

Notification object members:

    "method": "locked"
    "params": [<id>]
    "id": null

Notifies the client that a "lock" operation that it previously
requested has succeeded.  The client now owns the lock named in
"params".

The database server sends this notification after the reply to the
corresponding "lock" request (but only if the "locked" member of the
response was false), and before the reply to the client's subsequent
"unlock" request.

stolen
......

Notification object members:

    "method": "stolen"
    "params": [<id>]
    "id": null

Notifies the client that owns a lock that another database client has
stolen ownership of the lock.  The client no longer owns the lock
named in "params".  The client must still issue an "unlock" request
before performing any subsequent "lock" or "steal" operation on the
lock.

If the client originally obtained the lock through a "lock" request,
then it will automatically regain the lock later after the client that
stole it releases it.  (The database server will send the client a
"locked" notification at that point to let it know.)

If the client originally obtained the lock through a "steal" request,
the database server won't automatically reassign it ownership of the
lock when it later becomes available.  To regain ownership, the client
must "unlock" and then "lock" or "steal" the lock again.

echo
....

Request object members:

    "method": "echo"                                required
    "params": JSON array with any contents          required
    "id": <json-value>                              required

Response object members:

    "result": same as "params"
    "error": null
    "id": the request "id" member

Both the JSON-RPC client and the server must implement this request.

This JSON-RPC request and response can be used to implement connection
keepalives, by allowing the server to check that the client is still
there or vice versa.


Notation for the Wire Protocol
------------------------------

<db-name>

    An <id> that names a database.  The valid <db-name>s can be
    obtained using a "list-db" request.  The <db-name> is taken from
    the "name" member of <database-schema>.

<table>

    An <id> that names a table.

<column>

    An <id> that names a table column.

<row>

    A JSON object that describes a table row or a subset of a table
    row.  Each member is the name of a table column paired with the
    <value> of that column.

<value>

    A JSON value that represents the value of a column in a table row,
    one of <atom>, a <set>, or a <map>.

<atom>

    A JSON value that represents a scalar value for a column, one of
    <string>, <number>, <boolean>, <uuid>, <named-uuid>.

<set>

    Either an <atom>, representing a set with exactly one element, or
    a 2-element JSON array that represents a database set value.  The
    first element of the array must be the string "set" and the second
    element must be an array of zero or more <atom>s giving the values
    in the set.  All of the <atom>s must have the same type.

<map>

    A 2-element JSON array that represents a database map value.  The
    first element of the array must be the string "map" and the second
    element must be an array of zero or more <pair>s giving the values
    in the map.  All of the <pair>s must have the same key and value
    types.

    (JSON objects are not used to represent <map> because JSON only
    allows string names in an object.)

<pair>

    A 2-element JSON array that represents a pair within a database
    map.  The first element is an <atom> that represents the key, the
    second element is an <atom> that represents the value.

<uuid>

    A 2-element JSON array that represents a UUID.  The first element
    of the array must be the string "uuid" and the second element must
    be a 36-character string giving the UUID in the format described
    by RFC 4122.  For example, the following <uuid> represents the
    UUID 550e8400-e29b-41d4-a716-446655440000:

        ["uuid", "550e8400-e29b-41d4-a716-446655440000"]

<named-uuid>

    A 2-element JSON array that represents the UUID of a row inserted
    in an "insert" operation within the same transaction.  The first
    element of the array must be the string "named-uuid" and the
    second element should be the <id> specified as the "uuid-name"
    for an "insert" operation within the same transaction.  For
    example, if an "insert" operation within this transaction
    specifies a "uuid-name" of "myrow", the following <named-uuid>
    represents the UUID created by that operation:

        ["named-uuid", "myrow"]

    A <named-uuid> may be used anywhere a <uuid> is valid.

<condition>

    A 3-element JSON array of the form [<column>, <function>,
    <value>] that represents a test on a column value.

    Except as otherwise specified below, <value> must have the same
    type as <column>.

    The meaning depends on the type of <column>:

        integer
        real

            <function> must be "<", "<=", "==", "!=", ">=", ">",
            "includes", or "excludes".

            The test is true if the column's value satisfies the
            relation <function> <value>, e.g. if the column has value
            1 and <value> is 2, the test is true if <function> is "<",
            "<=" or "!=", but not otherwise.

            "includes" is equivalent to "=="; "excludes" is equivalent
            to "!=".

        boolean
        string
        uuid

            <function> must be "!=", "==", "includes", or "excludes".

            If <function> is "==" or "includes", the test is true if
            the column's value equals <value>.  If <function> is "!="
            or "excludes", the test is inverted.

        set
        map

            <function> must be "!=", "==", "includes", or "excludes".

            If <function> is "==", the test is true if the column's
            value contains exactly the same values (for sets) or pairs
            (for maps).  If <function> is "!=", the test is inverted.

            If <function> is "includes", the test is true if the
            column's value contains all of the values (for sets) or
            pairs (for maps) in <value>.  The column's value may also
            contain other values or pairs.

            If <function> is "excludes", the test is true if the
            column's value does not contain any of the values (for
            sets) or pairs (for maps) in <value>.  The column's value
            may contain other values or pairs not in <value>.

            If <function> is "includes" or "excludes", then the
            required type of <value> is slightly relaxed, in that it
            may have fewer than the minimum number of elements
            specified by the column's type.  If <function> is
            "excludes", then the required type is additionally relaxed
            in that <value> may have more than the maximum number of
            elements specified by the column's type.

<function>

    One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".

<mutation>

    A 3-element JSON array of the form [<column>, <mutator>, <value>]
    that represents a change to a column value.

    Except as otherwise specified below, <value> must have the same
    type as <column>.

    The meaning depends on the type of <column>:

        integer
        real

            <mutator> must be "+=", "-=", "*=", "/=" or (integer only)
            "%=".  The value of <column> is changed to the sum,
            difference, product, quotient, or remainder, respectively,
            of <column> and <value>.

            Constraints on <column> are ignored when parsing <value>.

        boolean
        string
        uuid

            No valid <mutator>s are currently defined for these types.

        set

            Any <mutator> valid for the set's element type may be
            applied to the set, in which case the mutation is applied
            to each member of the set individually.  <value> must be a
            scalar value of the same type as the set's element type,
            except that contraints are ignored.

            If <mutator> is "insert", then each of the values in the
            set in <value> is added to <column> if it is not already
            present.  The required type of <value> is slightly
            relaxed, in that it may have fewer than the minimum number
            of elements specified by the column's type.

            If <mutator> is "delete", then each of the values in the
            set in <value> is removed from <column> if it is present
            there.  The required type is slightly relaxed in that
            <value> may have more or less than the maximum number of
            elements specified by the column's type.

        map

            <mutator> must be "insert" or "delete".

            If <mutator> is "insert", then each of the key-value pairs
            in the map in <value> is added to <column> only if its key
            is not already present.  The required type of <value> is
            slightly relaxed, in that it may have fewer than the
            minimum number of elements specified by the column's type.

            If <mutator> is "delete", then <value> may have the same
            type as <column> (a map type) or it may be a set whose
            element type is the same as <column>'s key type:

                - If <value> is a map, the mutation deletes each
                  key-value pair in <column> whose key and value equal
                  one of the key-value pairs in <value>.

                - If <value> is a set, the mutation deletes each
                  key-value pair in <column> whose key equals one of
                  the values in <value>.

            For "delete", <value> may have any number of elements,
            regardless of restrictions on the number of elements in
            <column>.

<mutator>

    One of "+=", "-=", "*=", "/=", "%=", "insert", "delete".

Operations
----------

Each of the available operations is described below.

insert
......

Request object members:

    "op": "insert"          required
    "table": <table>        required
    "row": <row>            required
    "uuid-name": <id>       optional

Result object members:

    "uuid": <uuid>

Semantics:

    Inserts "row" into "table".

    If "row" does not specify values for all the columns in "table",
    those columns receive default values.  The default value for a
    column depends on its type.  The default for a column whose <type>
    specifies a "min" of 0 is an empty set or empty map.  Otherwise,
    the default is a single value or a single key-value pair, whose
    value(s) depend on its <atomic-type>:

        - "integer" or "real": 0

        - "boolean": false

        - "string": "" (the empty string)

        - "uuid": 00000000-0000-0000-0000-000000000000

    The new row receives a new, randomly generated UUID.

    If "uuid-name" is supplied, then it is an error if <id> is not
    unique among the "uuid-name"s supplied on all the "insert"
    operations within this transaction.

    The UUID for the new row is returned as the "uuid" member of the
    result.

Errors:

    "error": "duplicate uuid-name"

        The same "uuid-name" appears on another "insert" operation
        within this transaction.

    "error": "constraint violation"

        One of the values in "row" does not satisfy the immediate
        constraints for its column's <base-type>.  This error will
        occur for columns that are not explicitly set by "row" if the
        default value does not satisfy the column's constraints.

select
......

Request object members:

    "op": "select"                required
    "table": <table>              required
    "where": [<condition>*]       required
    "columns": [<column>*]        optional

Result object members:

    "rows": [<row>*]

Semantics:

    Searches "table" for rows that match all the conditions specified
    in "where".  If "where" is an empty array, every row in "table" is
    selected.

    The "rows" member of the result is an array of objects.  Each
    object corresponds to a matching row, with each column
    specified in "columns" as a member, the column's name as the
    member name and its value as the member value.  If "columns"
    is not specified, all the table's columns are included.  If
    two rows of the result have the same values for all included
    columns, only one copy of that row is included in "rows".
    Specifying "_uuid" within "columns" will avoid dropping
    duplicates, since every row has a unique UUID.

    The ordering of rows within "rows" is unspecified.

update
......

Request object members:

    "op": "update"                required
    "table": <table>              required
    "where": [<condition>*]       required
    "row": <row>                  required

Result object members:

    "count": <integer>

Semantics:

    Updates rows in a table.

    Searches "table" for rows that match all the conditions
    specified in "where".  For each matching row, changes the
    value of each column specified in "row" to the value for that
    column specified in "row".

    The "_uuid" and "_version" columns of a table may not be directly
    updated with this operation.  Columns designated read-only in the
    schema also may not be updated.

    The "count" member of the result specifies the number of rows
    that matched.

Errors:

    "error": "constraint violation"

        One of the values in "row" does not satisfy the immediate
        constraints for its column's <base-type>.
mutate
......

Request object members:

    "op": "mutate"                required
    "table": <table>              required
    "where": [<condition>*]       required
    "mutations": [<mutation>*]    required

Result object members:

    "count": <integer>

Semantics:

    Mutates rows in a table.

    Searches "table" for rows that match all the conditions specified
    in "where".  For each matching row, mutates its columns as
    specified by each <mutation> in "mutations", in the order
    specified.

    The "_uuid" and "_version" columns of a table may not be directly
    modified with this operation.  Columns designated read-only in the
    schema also may not be updated.

    The "count" member of the result specifies the number of rows
    that matched.

Errors:

    "error": "domain error"

        The result of the mutation is not mathematically defined,
        e.g. division by zero.

    "error": "range error"

        The result of the mutation is not representable within the
        database's format, e.g. an integer result outside the range
        INT64_MIN...INT64_MAX or a real result outside the range
        -DBL_MAX...DBL_MAX.

    "error": "constraint violation"

        The mutation caused the column's value to violate a
        constraint, e.g. it caused a column to have more or fewer
        values than are allowed, an arithmetic operation caused a set
        or map to have duplicate elements, or it violated a constraint
        specified by a column's <base-type>.

delete
......

Request object members:

    "op": "delete"                required
    "table": <table>              required
    "where": [<condition>*]       required

Result object members:

    "count": <integer>

Semantics:

    Deletes all the rows from "table" that match all the conditions
    specified in "where".

    The "count" member of the result specifies the number of deleted
    rows.

wait
....

Request object members:

    "op": "wait"                        required
    "timeout": <integer>                optional
    "table": <table>                    required
    "where": [<condition>*]             required
    "columns": [<column>*]              required
    "until": "==" or "!="               required
    "rows": [<row>*]                    required

Result object members:

    none

Semantics:

    Waits until a condition becomes true.

    If "until" is "==", checks whether the query on "table" specified
    by "where" and "columns", which is evaluated in the same way as
    specified for "select", returns the result set specified by
    "rows".  If it does, then the operation completes successfully.
    Otherwise, the entire transaction rolls back.  It is automatically
    restarted later, after a change in the database makes it possible
    for the operation to succeed.  The client will not receive a
    response until the operation permanently succeeds or fails.

    If "until" is "!=", the sense of the test is negated.  That is, as
    long as the query on "table" specified by "where" and "columns"
    returns "rows", the transaction will be rolled back and restarted
    later.

    If "timeout" is specified, then the transaction aborts after the
    specified number of milliseconds.  The transaction is guaranteed
    to be attempted at least once before it aborts.  A "timeout" of 0
    will abort the transaction on the first mismatch.

Errors:

    "error": "not supported"

        One or more of the columns in this table do not support
        triggers.  This error will not occur if "timeout" is 0.

    "error": "timed out"

        The "timeout" was reached before the transaction was able to
        complete.

commit
......

Request object members:

    "op": "commit"                      required
    "durable": <boolean>                required

Result object members:

    none

Semantics:

    If "durable" is specified as true, then the transaction, if it
    commits, will be stored durably (to disk) before the reply is sent
    to the client.

Errors:

    "error": "not supported"

        When "durable" is true, this database implementation does not
        support durable commits.

abort
.....

Request object members:

    "op": "abort"                      required

Result object members:

    (never succeeds)

Semantics:

    Aborts the transaction with an error.  This may be useful for
    testing.

Errors:

    "error": "aborted"

        This operation always fails with this error.

comment
.......


Request object members:

    "op": "comment"                    required
    "comment": <string>                required

Result object members:

    none

Semantics:

    Provides information to a database administrator on the purpose of
    a transaction.  The OVSDB server, for example, adds comments in
    transactions that modify the database to the database journal.

assert
......

Request object members:

    "op": "assert"                     required
    "lock": <id>                       required

Result object members:

    none

Semantics:

    If the client does not own the lock named <string>, aborts the
    transaction.

Errors:

    "error": "not owner"

        The client does not own the named lock.