1 ===================================================
2 Open vSwitch Configuration Database Specification
3 ===================================================
8 OVSDB uses JSON, as defined by RFC 4627, for its schema format and its
9 wire protocol format. The JSON implementation in Open vSwitch has the
10 following limitations:
12 - Null bytes (\u0000) are not allowed in strings.
14 - Only UTF-8 encoding is supported. (RFC 4627 also mentions
15 UTF-16BE, UTF-16LE, and UTF-32.)
17 - RFC 4627 says that names within a JSON object should be unique.
18 The Open vSwitch JSON parser discards all but the last value
19 for a name that is specified more than once.
21 The descriptions below use the following shorthand notations for JSON
22 values. Additional notation is presented later.
26 A JSON string. Any Unicode string is allowed, as specified by RFC
27 4627. Implementations may disallow null bytes.
31 A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*.
33 <id>s that begin with _ are reserved to the implementation and may
34 not be used by the user.
38 A JSON string that contains a version number that matches
39 [0-9]+\.[0-9]+\.[0-9]+
43 A JSON true or false value.
51 A JSON number with an integer value, within a certain range
52 (currently -2**63...+2**63-1).
60 Any JSON value except null.
64 A JSON object with the following members:
66 "error": <string> required
67 "details": <string> optional
69 The value of the "error" member is a short string, specified in
70 this document, that broadly indicates the class of the error.
71 Most "error" strings are specific to contexts described elsewhere
72 in this document, but the following "error" strings may appear in
73 any context where an <error> is permitted:
75 "error": "resources exhausted"
77 The operation requires more resources (memory, disk, CPU,
78 etc.) than are currently available to the database server.
82 Problems accessing the disk, network, or other required
83 resources prevented the operation from completing.
85 Database implementations may use "error" strings not specified
86 in this document to indicate errors that do not fit into any of
87 the specified categories.
89 Optionally, an <error> may include a "details" member, whose value
90 is a string that describes the error in more detail for the
91 benefit of a human user or administrator. This document does not
92 specify the format or content of the "details" string.
94 An <error> may also have other members that describe the error in
95 more detail. This document does not specify the names or values
101 An Open vSwitch configuration database consists of a set of tables,
102 each of which has a number of columns and zero or more rows. A schema
103 is represented by <database-schema>, as described below.
107 A JSON object with the following members:
109 "name": <id> required
110 "version": <version> required
111 "cksum": <string> optional
112 "tables": {<id>: <table-schema>, ...} required
114 The "name" identifies the database as a whole. It must be
115 provided to most JSON-RPC requests to identify the database being
116 operated on. The value of "tables" is a JSON object whose names
117 are table names and whose values are <table-schema>s.
119 The "version" reports the version of the database schema. Because
120 this is a recent addition to the schema format, OVSDB permits it
121 to be omitted, but future versions of OVSDB will require it to be
122 present. Open vSwitch semantics for "version" are described in
123 ovs-vswitchd.conf.db(5).
125 The "cksum" optionally reports an implementation-defined checksum
126 for the database schema.
130 A JSON object with the following members:
132 "columns": {<id>: <column-schema>, ...} required
133 "maxRows": <integer> optional
134 "isRoot": <boolean> optional
135 "indexes": [<column-set>*] optional
137 The value of "columns" is a JSON object whose names are column
138 names and whose values are <column-schema>s.
140 Every table has the following columns whose definitions are not
141 included in the schema:
143 "_uuid": This column, which contains exactly one UUID value,
144 is initialized to a random value by the database engine when
145 it creates a row. It is read-only, and its value never
146 changes during the lifetime of a row.
148 "_version": Like "_uuid", this column contains exactly one
149 UUID value, initialized to a random value by the database
150 engine when it creates a row, and it is read-only. However,
151 its value changes to a new random value whenever any other
152 field in the row changes. Furthermore, its value is
153 ephemeral: when the database is closed and reopened, or when
154 the database process is stopped and then started again, each
155 "_version" also changes to a new random value.
157 If "isRoot" is omitted or specified as false, then any given row
158 in the table may exist only when there is at least one reference
159 to it, with refType "strong", from a different row (in the same
160 table or a different table). This is a "deferred" action:
161 unreferenced rows in the table are deleted just before transaction
162 commit. If "isRoot" is specified as true, then rows in the table
163 exist independent of any references (they can be thought of as
164 part of the "root set" in a garbage collector).
166 For compatibility with schemas created before "isRoot" was
167 introduced, if "isRoot" is omitted or false in every
168 <table-schema> in a given <database-schema>, then every table is
169 part of the root set.
171 If "maxRows" is specified, as a positive integer, it limits the
172 maximum number of rows that may be present in the table. This is
173 a "deferred" constraint, enforced only at transaction commit time
174 (see the "transact" request below). If "maxRows" is not
175 specified, the size of the table is limited only by the resources
176 available to the database server. "maxRows" constraints are
177 enforced after unreferenced rows are deleted from tables with a
180 If "indexes" is specified, it must be an array of zero or more
181 <column-set>s. A <column-set> is an array of one or more strings,
182 each of which names a column. Each <column-set> is a set of
183 columns whose values, taken together within any given row, must be
184 unique within the table. This is a "deferred" constraint,
185 enforced only at transaction commit time, after unreferenced rows
186 are deleted and dangling weak references are removed. Ephemeral
187 columns may not be part of indexes.
191 A JSON object with the following members:
193 "type": <type> required
194 "ephemeral": <boolean> optional
195 "mutable": <boolean> optional
197 The "type" specifies the type of data stored in this column.
199 If "ephemeral" is specified as true, then this column's values are
200 not guaranteed to be durable; they may be lost when the database
201 restarts. A column whose type (either key or value) is a strong
202 reference to a table that is not part of the root set is always
203 durable, regardless of this value. (Otherwise, restarting the
204 database could lose entire rows.)
206 If "mutable" is specified as false, then this column's values may
207 not be modified after they are initially set with the "insert"
212 The type of a database column. Either an <atomic-type> or a JSON
213 object that describes the type of a database column, with the
216 "key": <base-type> required
217 "value": <base-type> optional
218 "min": <integer> optional
219 "max": <integer> or "unlimited" optional
221 If "min" or "max" is not specified, each defaults to 1. If "max"
222 is specified as "unlimited", then there is no specified maximum
223 number of elements, although the implementation will enforce some
224 limit. After considering defaults, "min" must be exactly 0 or
225 exactly 1, "max" must be at least 1, and "max" must be greater
226 than or equal to "min".
228 If "min" and "max" are both 1 and "value" is not specified, the
229 type is the scalar type specified by "key".
231 If "min" is not 1 or "max" is not 1, or both, and "value" is not
232 specified, the type is a set of scalar type "key".
234 If "value" is specified, the type is a map from type "key" to type
239 The type of a key or value in a database column. Either an
240 <atomic-type> or a JSON object with the following members:
242 "type": <atomic-type> required
243 "enum": <value> optional
244 "minInteger": <integer> optional, integers only
245 "maxInteger": <integer> optional, integers only
246 "minReal": <real> optional, reals only
247 "maxReal": <real> optional, reals only
248 "minLength": <integer> optional, strings only
249 "maxLength": <integer> optional, strings only
250 "refTable": <id> optional, uuids only
251 "refType": "strong" or "weak" optional, only with "refTable"
253 An <atomic-type> by itself is equivalent to a JSON object with a
254 single member "type" whose value is the <atomic-type>.
256 "enum" may be specified as a <value> whose type is a set of one
257 or more values specified for the member "type". If "enum" is
258 specified, then the valid values of the <base-type> are limited to
259 those in the <value>.
261 "enum" is mutually exclusive with the following constraints.
263 If "type" is "integer", then "minInteger" or "maxInteger" or both
264 may also be specified, restricting the valid integer range. If
265 both are specified, then the maxInteger must be greater than or
268 If "type" is "real", then "minReal" or "maxReal" or both may also
269 be specified, restricting the valid real range. If both are
270 specified, then the maxReal must be greater than or equal to
273 If "type" is "string", then "minLength" and "maxLength" or both
274 may be specified, restricting the valid length of value strings.
275 If both are specified, then maxLength must be greater than or
276 equal to minLength. String length is measured in characters (not
277 bytes or UTF-16 code units).
279 If "type" is "uuid", then "refTable", if present, must be the name
280 of a table within this database. If "refTable" is specified, then
281 "refType" may also be specified. If "refTable" is set, the effect
282 depends on "refType":
284 - If "refType" is "strong" or if "refType" is omitted, the
285 allowed UUIDs are limited to UUIDs for rows in the named
288 - If "refType" is "weak", then any UUIDs are allowed, but
289 UUIDs that do not correspond to rows in the named table will
290 be automatically deleted.
292 "refTable" constraints are "deferred" constraints: they are
293 enforced only at transaction commit time (see the "transact"
294 request below). The other contraints on <base-type> are
295 "immediate", enforced immediately by each operation.
299 One of the strings "integer", "real", "boolean", "string", or
300 "uuid", representing the specified scalar type.
305 The database wire protocol is implemented in JSON-RPC 1.0. We
306 encourage use of JSON-RPC over stream connections instead of JSON-RPC
307 over HTTP, for these reasons:
309 * JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server
310 protocol, which is a poor match. Thus, JSON-RPC over HTTP
311 requires the client to periodically poll the server to receive
314 * HTTP is more complicated than stream connections and doesn't
315 provide any corresponding advantage.
317 * The JSON-RPC specification for HTTP transport is incomplete.
319 We are currently using TCP port 6632 for the database JSON-RPC
320 connection, but future versions will switch to using IANA-assigned TCP
323 The database wire protocol consists of the following JSON-RPC methods:
328 Request object members:
330 "method": "list_dbs" required
331 "params": [] required
332 "id": <nonnull-json-value> required
334 Response object members:
336 "result": [<db-name>, ...]
338 "id": same "id" as request
340 This operation retrieves an array whose elements are <db-name>s
341 that name the databases that can be accessed over this JSON-RPC
347 Request object members:
349 "method": "get_schema" required
350 "params": [<db-name>] required
351 "id": <nonnull-json-value> required
353 Response object members:
355 "result": <database-schema>
357 "id": same "id" as request
359 This operation retrieves a <database-schema> that describes hosted
365 Request object members:
367 "method": "transact" required
368 "params": [<db-name>, <operation>*] required
369 "id": <nonnull-json-value> required
371 Response object members:
373 "result": [<object>*]
375 "id": same "id" as request
377 The "params" array for this method consists of a <db-name> that
378 identifies the database to which the transaction applies, followed by
379 zero or more JSON objects, each of which represents a single database
380 operation. The "Operations" section below describes the valid
383 The value of "id" must be unique among all in-flight transactions
384 within the current JSON-RPC session. Otherwise, the server may return
387 The database server executes each of the specified operations in the
388 specified order, except that if an operation fails, then the remaining
389 operations are not executed.
391 The set of operations is executed as a single atomic, consistent,
392 isolated transaction. The transaction is committed only if every
393 operation succeeds. Durability of the commit is not guaranteed unless
394 the "commit" operation, with "durable" set to true, is included in the
395 operation set (see below).
397 Regardless of whether errors occur, the response is always a JSON-RPC
398 response with null "error" and a "result" member that is an array with
399 the same number of elements as "params". Each element of the "result"
400 array corresponds to the same element of the "params" array. The
401 "result" array elements may be interpreted as follows:
403 - A JSON object that does not contain an "error" member indicates
404 that the operation completed successfully. The specific members
405 of the object are specified below in the descriptions of
406 individual operations. Some operations do not produce any
407 results, in which case the object will have no members.
409 - An <error>, which indicates that the operation completed with an
412 - A JSON null value indicates that the operation was not attempted
413 because a prior operation failed.
415 In general, "result" contains some number of successful results,
416 possibly followed by an error, in turn followed by enough JSON null
417 values to match the number of elements in "params". There is one
418 exception: if all of the operations succeed, but the results cannot be
419 committed, then "result" will have one more element than "params",
420 with the additional element an <error>. The possible "error" strings
421 include at least the following:
423 "error": "referential integrity violation"
425 When the commit was attempted, a column's value referenced the
426 UUID for a row that did not exist in the table named by the
427 column's <base-type> key or value "refTable" that has a
428 "refType" of "strong". (This can be caused by inserting a row
429 that references a nonexistent row, by deleting a row that is
430 still referenced by another row, by specifying the UUID for a
431 row in the wrong table, and other ways.)
433 "error": "constraint violation"
435 A column with a <base-type> key or value "refTable" whose
436 "refType" is "weak" became empty due to deletion(s) caused
437 because the rows that it referenced were deleted (or never
438 existed, if the column's row was inserted within the
439 transaction), and this column is not allowed to be empty
440 because its <type> has a "min" of 1.
442 "error": "constraint violation"
444 The number of rows in a table exceeds the maximum number
445 permitted by the table's "maxRows" value (see <table-schema>).
447 "error": "constraint violation"
449 Two or more rows in a table had the same values in the columns
450 that comprise an index.
452 "error": "resources exhausted"
455 As described in the definition of <error> above.
457 If "params" contains one or more "wait" operations, then the
458 transaction may take an arbitrary amount of time to complete. The
459 database implementation must be capable of accepting, executing, and
460 replying to other transactions and other JSON-RPC requests while a
461 transaction or transactions containing "wait" operations are
462 outstanding on the same or different JSON-RPC sessions.
464 The section "Notation for the Wire Protocol" below describes
465 additional notation for use with the wire protocol. After that, the
466 "Operations" section describes each operation.
471 Request object members:
473 "method": "cancel" required
474 "params": [the "id" for an outstanding request] required
477 Response object members:
481 This JSON-RPC notification instructs the database server to
482 immediately complete or cancel the "transact" request whose "id" is
483 the same as the notification's "params" value.
485 If the "transact" request can be completed immediately, then the
486 server sends a response in the form described for "transact", above.
487 Otherwise, the server sends a JSON-RPC error response of the following
492 "id": the request "id" member
494 The "cancel" notification itself has no reply.
499 Request object members:
501 "method": "monitor" required
502 "params": [<db-name>, <json-value>, <monitor-requests>] required
503 "id": <nonnull-json-value> required
505 <monitor-requests> is an object that maps from a table name to an
506 array of <monitor-request> objects. For backward compatibility, a
507 single <monitor-request> may be used instead of an array; it is
508 treated as a single-element array.
510 Each <monitor-request> is an object with the following members:
512 "columns": [<column>*] optional
513 "select": <monitor-select> optional
515 <monitor-select> is an object with the following members:
517 "initial": <boolean> optional
518 "insert": <boolean> optional
519 "delete": <boolean> optional
520 "modify": <boolean> optional
522 Response object members:
524 "result": <table-updates>
526 "id": same "id" as request
528 This JSON-RPC request enables a client to replicate tables or subsets
529 of tables within database <db-name>. Each element of
530 <monitor-requests> specifies a table to be replicated. The JSON-RPC
531 response to the "monitor" includes the initial contents of each table,
532 unless disabled (see below). Afterward, when changes to those tables
533 are committed, the changes are automatically sent to the client using
534 the "update" monitor notification. This monitoring persists until the
535 JSON-RPC session terminates or until the client sends a
536 "monitor_cancel" JSON-RPC request.
538 Each <monitor-request> describes how to monitor columns in a table:
540 The circumstances in which an "update" notification is sent for a
541 row within the table are determined by <monitor-select>:
543 If "initial" is omitted or true, every row in the table is
544 sent as part of the reply to the "monitor" request.
546 If "insert" is omitted or true, "update" notifications are
547 sent for rows newly inserted into the table.
549 If "delete" is omitted or true, "update" notifications are
550 sent for rows deleted from the table.
552 If "modify" is omitted or true, "update" notifications are
553 sent whenever when a row in the table is modified.
555 The "columns" member specifies the columns whose values are
556 monitored. It must not contain duplicates. If "columns" is
557 omitted, all columns in the table, except for "_uuid", are
560 If there is more than one <monitor-request> in an array of them, then
561 each <monitor-request> in the array should specify both "columns" and
562 "select", and the "columns" must be non-overlapping sets.
564 The "result" in the JSON-RPC response to the "monitor" request is a
565 <table-updates> object (see below) that contains the contents of the
566 tables for which "initial" rows are selected. If no tables' initial
567 contents are requested, then "result" is an empty object.
572 Notification object members:
575 "params": [<json-value>, <table-updates>]
578 The <json-value> in "params" is the same as the value passed as the
579 <json-value> in "params" for the "monitor" request.
581 <table-updates> is an object that maps from a table name to a
584 A <table-update> is an object that maps from the row's UUID (as a
585 36-byte string) to a <row-update> object.
587 A <row-update> is an object with the following members:
589 "old": <row> present for "delete" and "modify" updates
590 "new": <row> present for "initial", "insert", and "modify" updates
592 This JSON-RPC notification is sent from the server to the client to
593 tell it about changes to a monitored table (or the initial state of a
594 modified table). Each table in which one or more rows has changed (or
595 whose initial view is being presented) is represented in "updates".
596 Each row that has changed (or whose initial view is being presented)
597 is represented in its <table-update> as a member with its name taken
598 from the row's _uuid member. The corresponding value is a
601 The "old" member is present for "delete" and "modify" updates.
602 For "delete" updates, each monitored column is included. For
603 "modify" updates, the prior value of each monitored column whose
604 value has changed is included (monitored columns that have not
605 changed are represented in "new").
607 The "new" member is present for "initial", "insert", and "modify"
608 updates. For "initial" and "insert" updates, each monitored
609 column is included. For "modify" updates, the new value of each
610 monitored column is included.
615 Request object members:
617 "method": "monitor_cancel" required
618 "params": [<json-value>] required
619 "id": <nonnull-json-value> required
621 Response object members:
625 "id": the request "id" member
627 Cancels the ongoing table monitor request, identified by the
628 <json-value> in "params" matching the <json-value> in "params" for an
629 ongoing "monitor" request. No more "update" messages will be sent for
635 Request object members:
637 "method": "lock", "steal", or "unlock" required
638 "params": [<id>] required
639 "id": <nonnull-json-value> required
641 Response object members:
643 "result": {"locked": <boolean>} for "lock"
644 "result": {"locked": true} for "steal"
645 "result": {} for "unlock"
647 "id": same "id" as request
649 Performs an operation on a "lock" object. The database server
650 supports an arbitrary number of locks, each of which is identified by
651 a client-defined id (given in "params"). At any given time, each lock
652 may have at most one owner.
654 The locking operation depends on "method":
656 - "lock": The database will assign this client ownership of the
657 lock as soon as it becomes available. When multiple clients
658 request the same lock, they will receive it in first-come, first
661 - "steal": The database immediately assigns this client ownership
662 of the lock. If there is an existing owner, it loses ownership.
664 - "unlock": If the client owns the lock, releases it. If the
665 client is waiting to obtain the lock, cancels the request and
668 (Closing or otherwise disconnecting a database client connection
669 unlocks all of its locks.)
671 For any given lock, the client must alternate "lock" or "steal"
672 operations with "unlock" operations. That is, if the previous
673 operation on a lock was "lock" or "steal", it must be followed by an
674 "unlock" operation, and vice versa.
676 For a "lock" operation, the "locked" member in the response object is
677 true if the lock has already been acquired, false if another client
678 holds the lock and the client's request for it was queued. In the
679 latter case, the client will be notified later with a "locked" message
680 when acquisition succeeds.
682 These requests complete and send a response quickly, without waiting.
683 The "locked" and "stolen" notifications (see below) report
684 asynchronous changes to ownership.
686 The scope of a lock is a database server, not a database hosted by
687 that server. A naming convention, such as "<db-name>__<lock-name>",
688 can effectively limit the scope of a lock to a particular database.
693 Notification object members:
699 Notifies the client that a "lock" operation that it previously
700 requested has succeeded. The client now owns the lock named in
703 The database server sends this notification after the reply to the
704 corresponding "lock" request (but only if the "locked" member of the
705 response was false), and before the reply to the client's subsequent
711 Notification object members:
717 Notifies the client that owns a lock that another database client has
718 stolen ownership of the lock. The client no longer owns the lock
719 named in "params". The client must still issue an "unlock" request
720 before performing any subsequent "lock" or "steal" operation on the
723 If the client originally obtained the lock through a "lock" request,
724 then it will automatically regain the lock later after the client that
725 stole it releases it. (The database server will send the client a
726 "locked" notification at that point to let it know.)
728 If the client originally obtained the lock through a "steal" request,
729 the database server won't automatically reassign it ownership of the
730 lock when it later becomes available. To regain ownership, the client
731 must "unlock" and then "lock" or "steal" the lock again.
736 Request object members:
738 "method": "echo" required
739 "params": JSON array with any contents required
740 "id": <json-value> required
742 Response object members:
744 "result": same as "params"
746 "id": the request "id" member
748 Both the JSON-RPC client and the server must implement this request.
750 This JSON-RPC request and response can be used to implement connection
751 keepalives, by allowing the server to check that the client is still
755 Notation for the Wire Protocol
756 ------------------------------
760 An <id> that names a database. The valid <db-name>s can be
761 obtained using a "list-db" request. The <db-name> is taken from
762 the "name" member of <database-schema>.
766 An <id> that names a table.
770 An <id> that names a table column.
774 A JSON object that describes a table row or a subset of a table
775 row. Each member is the name of a table column paired with the
776 <value> of that column.
780 A JSON value that represents the value of a column in a table row,
781 one of <atom>, a <set>, or a <map>.
785 A JSON value that represents a scalar value for a column, one of
786 <string>, <number>, <boolean>, <uuid>, <named-uuid>.
790 Either an <atom>, representing a set with exactly one element, or
791 a 2-element JSON array that represents a database set value. The
792 first element of the array must be the string "set" and the second
793 element must be an array of zero or more <atom>s giving the values
794 in the set. All of the <atom>s must have the same type.
798 A 2-element JSON array that represents a database map value. The
799 first element of the array must be the string "map" and the second
800 element must be an array of zero or more <pair>s giving the values
801 in the map. All of the <pair>s must have the same key and value
804 (JSON objects are not used to represent <map> because JSON only
805 allows string names in an object.)
809 A 2-element JSON array that represents a pair within a database
810 map. The first element is an <atom> that represents the key, the
811 second element is an <atom> that represents the value.
815 A 2-element JSON array that represents a UUID. The first element
816 of the array must be the string "uuid" and the second element must
817 be a 36-character string giving the UUID in the format described
818 by RFC 4122. For example, the following <uuid> represents the
819 UUID 550e8400-e29b-41d4-a716-446655440000:
821 ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
825 A 2-element JSON array that represents the UUID of a row inserted
826 in an "insert" operation within the same transaction. The first
827 element of the array must be the string "named-uuid" and the
828 second element should be the <id> specified as the "uuid-name"
829 for an "insert" operation within the same transaction. For
830 example, if an "insert" operation within this transaction
831 specifies a "uuid-name" of "myrow", the following <named-uuid>
832 represents the UUID created by that operation:
834 ["named-uuid", "myrow"]
836 A <named-uuid> may be used anywhere a <uuid> is valid.
840 A 3-element JSON array of the form [<column>, <function>,
841 <value>] that represents a test on a column value.
843 Except as otherwise specified below, <value> must have the same
846 The meaning depends on the type of <column>:
851 <function> must be "<", "<=", "==", "!=", ">=", ">",
852 "includes", or "excludes".
854 The test is true if the column's value satisfies the
855 relation <function> <value>, e.g. if the column has value
856 1 and <value> is 2, the test is true if <function> is "<",
857 "<=" or "!=", but not otherwise.
859 "includes" is equivalent to "=="; "excludes" is equivalent
866 <function> must be "!=", "==", "includes", or "excludes".
868 If <function> is "==" or "includes", the test is true if
869 the column's value equals <value>. If <function> is "!="
870 or "excludes", the test is inverted.
875 <function> must be "!=", "==", "includes", or "excludes".
877 If <function> is "==", the test is true if the column's
878 value contains exactly the same values (for sets) or pairs
879 (for maps). If <function> is "!=", the test is inverted.
881 If <function> is "includes", the test is true if the
882 column's value contains all of the values (for sets) or
883 pairs (for maps) in <value>. The column's value may also
884 contain other values or pairs.
886 If <function> is "excludes", the test is true if the
887 column's value does not contain any of the values (for
888 sets) or pairs (for maps) in <value>. The column's value
889 may contain other values or pairs not in <value>.
891 If <function> is "includes" or "excludes", then the
892 required type of <value> is slightly relaxed, in that it
893 may have fewer than the minimum number of elements
894 specified by the column's type. If <function> is
895 "excludes", then the required type is additionally relaxed
896 in that <value> may have more than the maximum number of
897 elements specified by the column's type.
901 One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
905 A 3-element JSON array of the form [<column>, <mutator>, <value>]
906 that represents a change to a column value.
908 Except as otherwise specified below, <value> must have the same
911 The meaning depends on the type of <column>:
916 <mutator> must be "+=", "-=", "*=", "/=" or (integer only)
917 "%=". The value of <column> is changed to the sum,
918 difference, product, quotient, or remainder, respectively,
919 of <column> and <value>.
921 Constraints on <column> are ignored when parsing <value>.
927 No valid <mutator>s are currently defined for these types.
931 Any <mutator> valid for the set's element type may be
932 applied to the set, in which case the mutation is applied
933 to each member of the set individually. <value> must be a
934 scalar value of the same type as the set's element type,
935 except that contraints are ignored.
937 If <mutator> is "insert", then each of the values in the
938 set in <value> is added to <column> if it is not already
939 present. The required type of <value> is slightly
940 relaxed, in that it may have fewer than the minimum number
941 of elements specified by the column's type.
943 If <mutator> is "delete", then each of the values in the
944 set in <value> is removed from <column> if it is present
945 there. The required type is slightly relaxed in that
946 <value> may have more or less than the maximum number of
947 elements specified by the column's type.
951 <mutator> must be "insert" or "delete".
953 If <mutator> is "insert", then each of the key-value pairs
954 in the map in <value> is added to <column> only if its key
955 is not already present. The required type of <value> is
956 slightly relaxed, in that it may have fewer than the
957 minimum number of elements specified by the column's type.
959 If <mutator> is "delete", then <value> may have the same
960 type as <column> (a map type) or it may be a set whose
961 element type is the same as <column>'s key type:
963 - If <value> is a map, the mutation deletes each
964 key-value pair in <column> whose key and value equal
965 one of the key-value pairs in <value>.
967 - If <value> is a set, the mutation deletes each
968 key-value pair in <column> whose key equals one of
969 the values in <value>.
971 For "delete", <value> may have any number of elements,
972 regardless of restrictions on the number of elements in
977 One of "+=", "-=", "*=", "/=", "%=", "insert", "delete".
982 Each of the available operations is described below.
987 Request object members:
989 "op": "insert" required
990 "table": <table> required
991 "row": <row> required
992 "uuid-name": <id> optional
994 Result object members:
1000 Inserts "row" into "table".
1002 If "row" does not specify values for all the columns in "table",
1003 those columns receive default values. The default value for a
1004 column depends on its type. The default for a column whose <type>
1005 specifies a "min" of 0 is an empty set or empty map. Otherwise,
1006 the default is a single value or a single key-value pair, whose
1007 value(s) depend on its <atomic-type>:
1009 - "integer" or "real": 0
1013 - "string": "" (the empty string)
1015 - "uuid": 00000000-0000-0000-0000-000000000000
1017 The new row receives a new, randomly generated UUID.
1019 If "uuid-name" is supplied, then it is an error if <id> is not
1020 unique among the "uuid-name"s supplied on all the "insert"
1021 operations within this transaction.
1023 The UUID for the new row is returned as the "uuid" member of the
1028 "error": "duplicate uuid-name"
1030 The same "uuid-name" appears on another "insert" operation
1031 within this transaction.
1033 "error": "constraint violation"
1035 One of the values in "row" does not satisfy the immediate
1036 constraints for its column's <base-type>. This error will
1037 occur for columns that are not explicitly set by "row" if the
1038 default value does not satisfy the column's constraints.
1043 Request object members:
1045 "op": "select" required
1046 "table": <table> required
1047 "where": [<condition>*] required
1048 "columns": [<column>*] optional
1050 Result object members:
1056 Searches "table" for rows that match all the conditions specified
1057 in "where". If "where" is an empty array, every row in "table" is
1060 The "rows" member of the result is an array of objects. Each
1061 object corresponds to a matching row, with each column
1062 specified in "columns" as a member, the column's name as the
1063 member name and its value as the member value. If "columns"
1064 is not specified, all the table's columns are included. If
1065 two rows of the result have the same values for all included
1066 columns, only one copy of that row is included in "rows".
1067 Specifying "_uuid" within "columns" will avoid dropping
1068 duplicates, since every row has a unique UUID.
1070 The ordering of rows within "rows" is unspecified.
1075 Request object members:
1077 "op": "update" required
1078 "table": <table> required
1079 "where": [<condition>*] required
1080 "row": <row> required
1082 Result object members:
1088 Updates rows in a table.
1090 Searches "table" for rows that match all the conditions
1091 specified in "where". For each matching row, changes the
1092 value of each column specified in "row" to the value for that
1093 column specified in "row".
1095 The "_uuid" and "_version" columns of a table may not be directly
1096 updated with this operation. Columns designated read-only in the
1097 schema also may not be updated.
1099 The "count" member of the result specifies the number of rows
1104 "error": "constraint violation"
1106 One of the values in "row" does not satisfy the immediate
1107 constraints for its column's <base-type>.
1111 Request object members:
1113 "op": "mutate" required
1114 "table": <table> required
1115 "where": [<condition>*] required
1116 "mutations": [<mutation>*] required
1118 Result object members:
1124 Mutates rows in a table.
1126 Searches "table" for rows that match all the conditions specified
1127 in "where". For each matching row, mutates its columns as
1128 specified by each <mutation> in "mutations", in the order
1131 The "_uuid" and "_version" columns of a table may not be directly
1132 modified with this operation. Columns designated read-only in the
1133 schema also may not be updated.
1135 The "count" member of the result specifies the number of rows
1140 "error": "domain error"
1142 The result of the mutation is not mathematically defined,
1143 e.g. division by zero.
1145 "error": "range error"
1147 The result of the mutation is not representable within the
1148 database's format, e.g. an integer result outside the range
1149 INT64_MIN...INT64_MAX or a real result outside the range
1152 "error": "constraint violation"
1154 The mutation caused the column's value to violate a
1155 constraint, e.g. it caused a column to have more or fewer
1156 values than are allowed, an arithmetic operation caused a set
1157 or map to have duplicate elements, or it violated a constraint
1158 specified by a column's <base-type>.
1163 Request object members:
1165 "op": "delete" required
1166 "table": <table> required
1167 "where": [<condition>*] required
1169 Result object members:
1175 Deletes all the rows from "table" that match all the conditions
1176 specified in "where".
1178 The "count" member of the result specifies the number of deleted
1184 Request object members:
1186 "op": "wait" required
1187 "timeout": <integer> optional
1188 "table": <table> required
1189 "where": [<condition>*] required
1190 "columns": [<column>*] required
1191 "until": "==" or "!=" required
1192 "rows": [<row>*] required
1194 Result object members:
1200 Waits until a condition becomes true.
1202 If "until" is "==", checks whether the query on "table" specified
1203 by "where" and "columns", which is evaluated in the same way as
1204 specified for "select", returns the result set specified by
1205 "rows". If it does, then the operation completes successfully.
1206 Otherwise, the entire transaction rolls back. It is automatically
1207 restarted later, after a change in the database makes it possible
1208 for the operation to succeed. The client will not receive a
1209 response until the operation permanently succeeds or fails.
1211 If "until" is "!=", the sense of the test is negated. That is, as
1212 long as the query on "table" specified by "where" and "columns"
1213 returns "rows", the transaction will be rolled back and restarted
1216 If "timeout" is specified, then the transaction aborts after the
1217 specified number of milliseconds. The transaction is guaranteed
1218 to be attempted at least once before it aborts. A "timeout" of 0
1219 will abort the transaction on the first mismatch.
1223 "error": "not supported"
1225 One or more of the columns in this table do not support
1226 triggers. This error will not occur if "timeout" is 0.
1228 "error": "timed out"
1230 The "timeout" was reached before the transaction was able to
1236 Request object members:
1238 "op": "commit" required
1239 "durable": <boolean> required
1241 Result object members:
1247 If "durable" is specified as true, then the transaction, if it
1248 commits, will be stored durably (to disk) before the reply is sent
1253 "error": "not supported"
1255 When "durable" is true, this database implementation does not
1256 support durable commits.
1261 Request object members:
1263 "op": "abort" required
1265 Result object members:
1271 Aborts the transaction with an error. This may be useful for
1278 This operation always fails with this error.
1284 Request object members:
1286 "op": "comment" required
1287 "comment": <string> required
1289 Result object members:
1295 Provides information to a database administrator on the purpose of
1296 a transaction. The OVSDB server, for example, adds comments in
1297 transactions that modify the database to the database journal.
1302 Request object members:
1304 "op": "assert" required
1305 "lock": <id> required
1307 Result object members:
1313 If the client does not own the lock named <string>, aborts the
1318 "error": "not owner"
1320 The client does not own the named lock.