<string>
- A JSON string.
+ A JSON string. Any Unicode string is allowed, as specified by RFC
+ 4627. Implementations may disallowed null bytes.
<id>
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 at least 0,
- "max" must be at least 1, and "max" must be greater than or equal
- to "min".
+ 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".
Wire Protocol
-------------
-The database wire protocol is implemented in JSON-RPC 1.0. It
-consists of the following JSON-RPC methods:
+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.
+
+The database wire protocol consists of the following JSON-RPC methods:
get_schema
..........
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>.
+
+ 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.
+
+ 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
----------
"op": "insert" required
"table": <table> required
"row": <row> required
- "uuid-name": <string> optional
+ "uuid-name": <id> optional
Result object members:
for all the columns in "table", those columns receive default
values.
- The new row receives a new, randomly generated UUID, which is
- returned as the "uuid" member of the result. If "uuid-name" is
- supplied, then the UUID is made available under that name to this
- operation and later operations within the same transaction.
+ If "uuid-name" is not supplied, the new row receives a new,
+ randomly generated UUID.
+
+ If "uuid-name" is supplied, then it is an error if <id> has
+ previously appeared as the "uuid-name" in an "insert" operation.
+
+ If "uuid-name" is supplied and its <id> previously appeared as the
+ "uuid-name" in a "declare" operation, then the new row receives
+ the UUID associated with that "uuid-name".
+
+ If "uuid-name" is supplied and its <id> has not previously
+ appeared as the "uuid-name" in a "declare" operation, then the new
+ row also receives a new, randomly generated UUID. This UUID is
+ also made available under that name to this operation and later
+ operations within the same 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" appeared on an earlier "insert" operation
+ within this transaction.
select
......
The "count" member of the result specifies the number of rows
that matched.
+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 or an arithmetic operation caused a
+ set or map to have duplicate elements.
+
delete
......
"error": "aborted"
This operation always fails with this error.
+
+declare
+.......
+
+Request object members:
+
+ "op": "declare" required
+ "uuid-name": <id> required
+
+Result object members:
+
+ "uuid": <uuid>
+
+Semantics:
+
+ Predeclares a UUID named <id> that may be referenced in later
+ operations as ["named-uuid", <id>] or (at most once) in an
+ "insert" operation as "uuid-name".
+
+ It is an error if <id> has appeared as the "uuid-name" in a prior
+ "insert" or "declare" operation within this transaction.
+
+ The generated UUID is returned as the "uuid" member of the result.
+
+Errors:
+
+ "error": "duplicate uuid-name"
+
+ The same "uuid-name" appeared on an earlier "insert" or
+ "declare" operation within this transaction.
+
+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.
projects / openvswitch / blobdiff