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 using TCP port 6632 for the database JSON-RPC connection.
321 The database wire protocol consists of the following JSON-RPC methods:
326 Request object members:
328 "method": "list_dbs" required
329 "params": [] required
330 "id": <nonnull-json-value> required
332 Response object members:
334 "result": [<db-name>, ...]
336 "id": same "id" as request
338 This operation retrieves an array whose elements are <db-name>s
339 that name the databases that can be accessed over this JSON-RPC
345 Request object members:
347 "method": "get_schema" required
348 "params": [<db-name>] required
349 "id": <nonnull-json-value> required
351 Response object members:
353 "result": <database-schema>
355 "id": same "id" as request
357 This operation retrieves a <database-schema> that describes hosted
363 Request object members:
365 "method": "transact" required
366 "params": [<db-name>, <operation>*] required
367 "id": <nonnull-json-value> required
369 Response object members:
371 "result": [<object>*]
373 "id": same "id" as request
375 The "params" array for this method consists of a <db-name> that
376 identifies the database to which the transaction applies, followed by
377 zero or more JSON objects, each of which represents a single database
378 operation. The "Operations" section below describes the valid
381 The value of "id" must be unique among all in-flight transactions
382 within the current JSON-RPC session. Otherwise, the server may return
385 The database server executes each of the specified operations in the
386 specified order, except that if an operation fails, then the remaining
387 operations are not executed.
389 The set of operations is executed as a single atomic, consistent,
390 isolated transaction. The transaction is committed only if every
391 operation succeeds. Durability of the commit is not guaranteed unless
392 the "commit" operation, with "durable" set to true, is included in the
393 operation set (see below).
395 Regardless of whether errors occur, the response is always a JSON-RPC
396 response with null "error" and a "result" member that is an array with
397 the same number of elements as "params". Each element of the "result"
398 array corresponds to the same element of the "params" array. The
399 "result" array elements may be interpreted as follows:
401 - A JSON object that does not contain an "error" member indicates
402 that the operation completed successfully. The specific members
403 of the object are specified below in the descriptions of
404 individual operations. Some operations do not produce any
405 results, in which case the object will have no members.
407 - An <error>, which indicates that the operation completed with an
410 - A JSON null value indicates that the operation was not attempted
411 because a prior operation failed.
413 In general, "result" contains some number of successful results,
414 possibly followed by an error, in turn followed by enough JSON null
415 values to match the number of elements in "params". There is one
416 exception: if all of the operations succeed, but the results cannot be
417 committed, then "result" will have one more element than "params",
418 with the additional element an <error>. The possible "error" strings
419 include at least the following:
421 "error": "referential integrity violation"
423 When the commit was attempted, a column's value referenced the
424 UUID for a row that did not exist in the table named by the
425 column's <base-type> key or value "refTable" that has a
426 "refType" of "strong". (This can be caused by inserting a row
427 that references a nonexistent row, by deleting a row that is
428 still referenced by another row, by specifying the UUID for a
429 row in the wrong table, and other ways.)
431 "error": "constraint violation"
433 A column with a <base-type> key or value "refTable" whose
434 "refType" is "weak" became empty due to deletion(s) caused
435 because the rows that it referenced were deleted (or never
436 existed, if the column's row was inserted within the
437 transaction), and this column is not allowed to be empty
438 because its <type> has a "min" of 1.
440 "error": "constraint violation"
442 The number of rows in a table exceeds the maximum number
443 permitted by the table's "maxRows" value (see <table-schema>).
445 "error": "constraint violation"
447 Two or more rows in a table had the same values in the columns
448 that comprise an index.
450 "error": "resources exhausted"
453 As described in the definition of <error> above.
455 If "params" contains one or more "wait" operations, then the
456 transaction may take an arbitrary amount of time to complete. The
457 database implementation must be capable of accepting, executing, and
458 replying to other transactions and other JSON-RPC requests while a
459 transaction or transactions containing "wait" operations are
460 outstanding on the same or different JSON-RPC sessions.
462 The section "Notation for the Wire Protocol" below describes
463 additional notation for use with the wire protocol. After that, the
464 "Operations" section describes each operation.
469 Request object members:
471 "method": "cancel" required
472 "params": [the "id" for an outstanding request] required
475 Response object members:
479 This JSON-RPC notification instructs the database server to
480 immediately complete or cancel the "transact" request whose "id" is
481 the same as the notification's "params" value.
483 If the "transact" request can be completed immediately, then the
484 server sends a response in the form described for "transact", above.
485 Otherwise, the server sends a JSON-RPC error response of the following
490 "id": the request "id" member
492 The "cancel" notification itself has no reply.
497 Request object members:
499 "method": "monitor" required
500 "params": [<db-name>, <json-value>, <monitor-requests>] required
501 "id": <nonnull-json-value> required
503 <monitor-requests> is an object that maps from a table name to an
504 array of <monitor-request> objects. For backward compatibility, a
505 single <monitor-request> may be used instead of an array; it is
506 treated as a single-element array.
508 Each <monitor-request> is an object with the following members:
510 "columns": [<column>*] optional
511 "select": <monitor-select> optional
513 <monitor-select> is an object with the following members:
515 "initial": <boolean> optional
516 "insert": <boolean> optional
517 "delete": <boolean> optional
518 "modify": <boolean> optional
520 Response object members:
522 "result": <table-updates>
524 "id": same "id" as request
526 This JSON-RPC request enables a client to replicate tables or subsets
527 of tables within database <db-name>. Each element of
528 <monitor-requests> specifies a table to be replicated. The JSON-RPC
529 response to the "monitor" includes the initial contents of each table,
530 unless disabled (see below). Afterward, when changes to those tables
531 are committed, the changes are automatically sent to the client using
532 the "update" monitor notification. This monitoring persists until the
533 JSON-RPC session terminates or until the client sends a
534 "monitor_cancel" JSON-RPC request.
536 Each <monitor-request> describes how to monitor columns in a table:
538 The circumstances in which an "update" notification is sent for a
539 row within the table are determined by <monitor-select>:
541 If "initial" is omitted or true, every row in the table is
542 sent as part of the reply to the "monitor" request.
544 If "insert" is omitted or true, "update" notifications are
545 sent for rows newly inserted into the table.
547 If "delete" is omitted or true, "update" notifications are
548 sent for rows deleted from the table.
550 If "modify" is omitted or true, "update" notifications are
551 sent whenever when a row in the table is modified.
553 The "columns" member specifies the columns whose values are
554 monitored. It must not contain duplicates. If "columns" is
555 omitted, all columns in the table, except for "_uuid", are
558 If there is more than one <monitor-request> in an array of them, then
559 each <monitor-request> in the array should specify both "columns" and
560 "select", and the "columns" must be non-overlapping sets.
562 The "result" in the JSON-RPC response to the "monitor" request is a
563 <table-updates> object (see below) that contains the contents of the
564 tables for which "initial" rows are selected. If no tables' initial
565 contents are requested, then "result" is an empty object.
570 Notification object members:
573 "params": [<json-value>, <table-updates>]
576 The <json-value> in "params" is the same as the value passed as the
577 <json-value> in "params" for the "monitor" request.
579 <table-updates> is an object that maps from a table name to a
582 A <table-update> is an object that maps from the row's UUID (as a
583 36-byte string) to a <row-update> object.
585 A <row-update> is an object with the following members:
587 "old": <row> present for "delete" and "modify" updates
588 "new": <row> present for "initial", "insert", and "modify" updates
590 This JSON-RPC notification is sent from the server to the client to
591 tell it about changes to a monitored table (or the initial state of a
592 modified table). Each table in which one or more rows has changed (or
593 whose initial view is being presented) is represented in "updates".
594 Each row that has changed (or whose initial view is being presented)
595 is represented in its <table-update> as a member with its name taken
596 from the row's _uuid member. The corresponding value is a
599 The "old" member is present for "delete" and "modify" updates.
600 For "delete" updates, each monitored column is included. For
601 "modify" updates, the prior value of each monitored column whose
602 value has changed is included (monitored columns that have not
603 changed are represented in "new").
605 The "new" member is present for "initial", "insert", and "modify"
606 updates. For "initial" and "insert" updates, each monitored
607 column is included. For "modify" updates, the new value of each
608 monitored column is included.
613 Request object members:
615 "method": "monitor_cancel" required
616 "params": [<json-value>] required
617 "id": <nonnull-json-value> required
619 Response object members:
623 "id": the request "id" member
625 Cancels the ongoing table monitor request, identified by the
626 <json-value> in "params" matching the <json-value> in "params" for an
627 ongoing "monitor" request. No more "update" messages will be sent for
633 Request object members:
635 "method": "lock", "steal", or "unlock" required
636 "params": [<id>] required
637 "id": <nonnull-json-value> required
639 Response object members:
641 "result": {"locked": <boolean>} for "lock"
642 "result": {"locked": true} for "steal"
643 "result": {} for "unlock"
645 "id": same "id" as request
647 Performs an operation on a "lock" object. The database server
648 supports an arbitrary number of locks, each of which is identified by
649 a client-defined id (given in "params"). At any given time, each lock
650 may have at most one owner.
652 The locking operation depends on "method":
654 - "lock": The database will assign this client ownership of the
655 lock as soon as it becomes available. When multiple clients
656 request the same lock, they will receive it in first-come, first
659 - "steal": The database immediately assigns this client ownership
660 of the lock. If there is an existing owner, it loses ownership.
662 - "unlock": If the client owns the lock, releases it. If the
663 client is waiting to obtain the lock, cancels the request and
666 (Closing or otherwise disconnecting a database client connection
667 unlocks all of its locks.)
669 For any given lock, the client must alternate "lock" or "steal"
670 operations with "unlock" operations. That is, if the previous
671 operation on a lock was "lock" or "steal", it must be followed by an
672 "unlock" operation, and vice versa.
674 For a "lock" operation, the "locked" member in the response object is
675 true if the lock has already been acquired, false if another client
676 holds the lock and the client's request for it was queued. In the
677 latter case, the client will be notified later with a "locked" message
678 when acquisition succeeds.
680 These requests complete and send a response quickly, without waiting.
681 The "locked" and "stolen" notifications (see below) report
682 asynchronous changes to ownership.
684 The scope of a lock is a database server, not a database hosted by
685 that server. A naming convention, such as "<db-name>__<lock-name>",
686 can effectively limit the scope of a lock to a particular database.
691 Notification object members:
697 Notifies the client that a "lock" operation that it previously
698 requested has succeeded. The client now owns the lock named in
701 The database server sends this notification after the reply to the
702 corresponding "lock" request (but only if the "locked" member of the
703 response was false), and before the reply to the client's subsequent
709 Notification object members:
715 Notifies the client that owns a lock that another database client has
716 stolen ownership of the lock. The client no longer owns the lock
717 named in "params". The client must still issue an "unlock" request
718 before performing any subsequent "lock" or "steal" operation on the
721 If the client originally obtained the lock through a "lock" request,
722 then it will automatically regain the lock later after the client that
723 stole it releases it. (The database server will send the client a
724 "locked" notification at that point to let it know.)
726 If the client originally obtained the lock through a "steal" request,
727 the database server won't automatically reassign it ownership of the
728 lock when it later becomes available. To regain ownership, the client
729 must "unlock" and then "lock" or "steal" the lock again.
734 Request object members:
736 "method": "echo" required
737 "params": JSON array with any contents required
738 "id": <json-value> required
740 Response object members:
742 "result": same as "params"
744 "id": the request "id" member
746 Both the JSON-RPC client and the server must implement this request.
748 This JSON-RPC request and response can be used to implement connection
749 keepalives, by allowing the server to check that the client is still
753 Notation for the Wire Protocol
754 ------------------------------
758 An <id> that names a database. The valid <db-name>s can be
759 obtained using a "list-db" request. The <db-name> is taken from
760 the "name" member of <database-schema>.
764 An <id> that names a table.
768 An <id> that names a table column.
772 A JSON object that describes a table row or a subset of a table
773 row. Each member is the name of a table column paired with the
774 <value> of that column.
778 A JSON value that represents the value of a column in a table row,
779 one of <atom>, a <set>, or a <map>.
783 A JSON value that represents a scalar value for a column, one of
784 <string>, <number>, <boolean>, <uuid>, <named-uuid>.
788 Either an <atom>, representing a set with exactly one element, or
789 a 2-element JSON array that represents a database set value. The
790 first element of the array must be the string "set" and the second
791 element must be an array of zero or more <atom>s giving the values
792 in the set. All of the <atom>s must have the same type.
796 A 2-element JSON array that represents a database map value. The
797 first element of the array must be the string "map" and the second
798 element must be an array of zero or more <pair>s giving the values
799 in the map. All of the <pair>s must have the same key and value
802 (JSON objects are not used to represent <map> because JSON only
803 allows string names in an object.)
807 A 2-element JSON array that represents a pair within a database
808 map. The first element is an <atom> that represents the key, the
809 second element is an <atom> that represents the value.
813 A 2-element JSON array that represents a UUID. The first element
814 of the array must be the string "uuid" and the second element must
815 be a 36-character string giving the UUID in the format described
816 by RFC 4122. For example, the following <uuid> represents the
817 UUID 550e8400-e29b-41d4-a716-446655440000:
819 ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
823 A 2-element JSON array that represents the UUID of a row inserted
824 in an "insert" operation within the same transaction. The first
825 element of the array must be the string "named-uuid" and the
826 second element should be the <id> specified as the "uuid-name"
827 for an "insert" operation within the same transaction. For
828 example, if an "insert" operation within this transaction
829 specifies a "uuid-name" of "myrow", the following <named-uuid>
830 represents the UUID created by that operation:
832 ["named-uuid", "myrow"]
834 A <named-uuid> may be used anywhere a <uuid> is valid.
838 A 3-element JSON array of the form [<column>, <function>,
839 <value>] that represents a test on a column value.
841 Except as otherwise specified below, <value> must have the same
844 The meaning depends on the type of <column>:
849 <function> must be "<", "<=", "==", "!=", ">=", ">",
850 "includes", or "excludes".
852 The test is true if the column's value satisfies the
853 relation <function> <value>, e.g. if the column has value
854 1 and <value> is 2, the test is true if <function> is "<",
855 "<=" or "!=", but not otherwise.
857 "includes" is equivalent to "=="; "excludes" is equivalent
864 <function> must be "!=", "==", "includes", or "excludes".
866 If <function> is "==" or "includes", the test is true if
867 the column's value equals <value>. If <function> is "!="
868 or "excludes", the test is inverted.
873 <function> must be "!=", "==", "includes", or "excludes".
875 If <function> is "==", the test is true if the column's
876 value contains exactly the same values (for sets) or pairs
877 (for maps). If <function> is "!=", the test is inverted.
879 If <function> is "includes", the test is true if the
880 column's value contains all of the values (for sets) or
881 pairs (for maps) in <value>. The column's value may also
882 contain other values or pairs.
884 If <function> is "excludes", the test is true if the
885 column's value does not contain any of the values (for
886 sets) or pairs (for maps) in <value>. The column's value
887 may contain other values or pairs not in <value>.
889 If <function> is "includes" or "excludes", then the
890 required type of <value> is slightly relaxed, in that it
891 may have fewer than the minimum number of elements
892 specified by the column's type. If <function> is
893 "excludes", then the required type is additionally relaxed
894 in that <value> may have more than the maximum number of
895 elements specified by the column's type.
899 One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
903 A 3-element JSON array of the form [<column>, <mutator>, <value>]
904 that represents a change to a column value.
906 Except as otherwise specified below, <value> must have the same
909 The meaning depends on the type of <column>:
914 <mutator> must be "+=", "-=", "*=", "/=" or (integer only)
915 "%=". The value of <column> is changed to the sum,
916 difference, product, quotient, or remainder, respectively,
917 of <column> and <value>.
919 Constraints on <column> are ignored when parsing <value>.
925 No valid <mutator>s are currently defined for these types.
929 Any <mutator> valid for the set's element type may be
930 applied to the set, in which case the mutation is applied
931 to each member of the set individually. <value> must be a
932 scalar value of the same type as the set's element type,
933 except that contraints are ignored.
935 If <mutator> is "insert", then each of the values in the
936 set in <value> is added to <column> if it is not already
937 present. The required type of <value> is slightly
938 relaxed, in that it may have fewer than the minimum number
939 of elements specified by the column's type.
941 If <mutator> is "delete", then each of the values in the
942 set in <value> is removed from <column> if it is present
943 there. The required type is slightly relaxed in that
944 <value> may have more or less than the maximum number of
945 elements specified by the column's type.
949 <mutator> must be "insert" or "delete".
951 If <mutator> is "insert", then each of the key-value pairs
952 in the map in <value> is added to <column> only if its key
953 is not already present. The required type of <value> is
954 slightly relaxed, in that it may have fewer than the
955 minimum number of elements specified by the column's type.
957 If <mutator> is "delete", then <value> may have the same
958 type as <column> (a map type) or it may be a set whose
959 element type is the same as <column>'s key type:
961 - If <value> is a map, the mutation deletes each
962 key-value pair in <column> whose key and value equal
963 one of the key-value pairs in <value>.
965 - If <value> is a set, the mutation deletes each
966 key-value pair in <column> whose key equals one of
967 the values in <value>.
969 For "delete", <value> may have any number of elements,
970 regardless of restrictions on the number of elements in
975 One of "+=", "-=", "*=", "/=", "%=", "insert", "delete".
980 Each of the available operations is described below.
985 Request object members:
987 "op": "insert" required
988 "table": <table> required
989 "row": <row> required
990 "uuid-name": <id> optional
992 Result object members:
998 Inserts "row" into "table".
1000 If "row" does not specify values for all the columns in "table",
1001 those columns receive default values. The default value for a
1002 column depends on its type. The default for a column whose <type>
1003 specifies a "min" of 0 is an empty set or empty map. Otherwise,
1004 the default is a single value or a single key-value pair, whose
1005 value(s) depend on its <atomic-type>:
1007 - "integer" or "real": 0
1011 - "string": "" (the empty string)
1013 - "uuid": 00000000-0000-0000-0000-000000000000
1015 The new row receives a new, randomly generated UUID.
1017 If "uuid-name" is supplied, then it is an error if <id> is not
1018 unique among the "uuid-name"s supplied on all the "insert"
1019 operations within this transaction.
1021 The UUID for the new row is returned as the "uuid" member of the
1026 "error": "duplicate uuid-name"
1028 The same "uuid-name" appears on another "insert" operation
1029 within this transaction.
1031 "error": "constraint violation"
1033 One of the values in "row" does not satisfy the immediate
1034 constraints for its column's <base-type>. This error will
1035 occur for columns that are not explicitly set by "row" if the
1036 default value does not satisfy the column's constraints.
1041 Request object members:
1043 "op": "select" required
1044 "table": <table> required
1045 "where": [<condition>*] required
1046 "columns": [<column>*] optional
1048 Result object members:
1054 Searches "table" for rows that match all the conditions specified
1055 in "where". If "where" is an empty array, every row in "table" is
1058 The "rows" member of the result is an array of objects. Each
1059 object corresponds to a matching row, with each column
1060 specified in "columns" as a member, the column's name as the
1061 member name and its value as the member value. If "columns"
1062 is not specified, all the table's columns are included. If
1063 two rows of the result have the same values for all included
1064 columns, only one copy of that row is included in "rows".
1065 Specifying "_uuid" within "columns" will avoid dropping
1066 duplicates, since every row has a unique UUID.
1068 The ordering of rows within "rows" is unspecified.
1073 Request object members:
1075 "op": "update" required
1076 "table": <table> required
1077 "where": [<condition>*] required
1078 "row": <row> required
1080 Result object members:
1086 Updates rows in a table.
1088 Searches "table" for rows that match all the conditions
1089 specified in "where". For each matching row, changes the
1090 value of each column specified in "row" to the value for that
1091 column specified in "row".
1093 The "_uuid" and "_version" columns of a table may not be directly
1094 updated with this operation. Columns designated read-only in the
1095 schema also may not be updated.
1097 The "count" member of the result specifies the number of rows
1102 "error": "constraint violation"
1104 One of the values in "row" does not satisfy the immediate
1105 constraints for its column's <base-type>.
1109 Request object members:
1111 "op": "mutate" required
1112 "table": <table> required
1113 "where": [<condition>*] required
1114 "mutations": [<mutation>*] required
1116 Result object members:
1122 Mutates rows in a table.
1124 Searches "table" for rows that match all the conditions specified
1125 in "where". For each matching row, mutates its columns as
1126 specified by each <mutation> in "mutations", in the order
1129 The "_uuid" and "_version" columns of a table may not be directly
1130 modified with this operation. Columns designated read-only in the
1131 schema also may not be updated.
1133 The "count" member of the result specifies the number of rows
1138 "error": "domain error"
1140 The result of the mutation is not mathematically defined,
1141 e.g. division by zero.
1143 "error": "range error"
1145 The result of the mutation is not representable within the
1146 database's format, e.g. an integer result outside the range
1147 INT64_MIN...INT64_MAX or a real result outside the range
1150 "error": "constraint violation"
1152 The mutation caused the column's value to violate a
1153 constraint, e.g. it caused a column to have more or fewer
1154 values than are allowed, an arithmetic operation caused a set
1155 or map to have duplicate elements, or it violated a constraint
1156 specified by a column's <base-type>.
1161 Request object members:
1163 "op": "delete" required
1164 "table": <table> required
1165 "where": [<condition>*] required
1167 Result object members:
1173 Deletes all the rows from "table" that match all the conditions
1174 specified in "where".
1176 The "count" member of the result specifies the number of deleted
1182 Request object members:
1184 "op": "wait" required
1185 "timeout": <integer> optional
1186 "table": <table> required
1187 "where": [<condition>*] required
1188 "columns": [<column>*] required
1189 "until": "==" or "!=" required
1190 "rows": [<row>*] required
1192 Result object members:
1198 Waits until a condition becomes true.
1200 If "until" is "==", checks whether the query on "table" specified
1201 by "where" and "columns", which is evaluated in the same way as
1202 specified for "select", returns the result set specified by
1203 "rows". If it does, then the operation completes successfully.
1204 Otherwise, the entire transaction rolls back. It is automatically
1205 restarted later, after a change in the database makes it possible
1206 for the operation to succeed. The client will not receive a
1207 response until the operation permanently succeeds or fails.
1209 If "until" is "!=", the sense of the test is negated. That is, as
1210 long as the query on "table" specified by "where" and "columns"
1211 returns "rows", the transaction will be rolled back and restarted
1214 If "timeout" is specified, then the transaction aborts after the
1215 specified number of milliseconds. The transaction is guaranteed
1216 to be attempted at least once before it aborts. A "timeout" of 0
1217 will abort the transaction on the first mismatch.
1221 "error": "not supported"
1223 One or more of the columns in this table do not support
1224 triggers. This error will not occur if "timeout" is 0.
1226 "error": "timed out"
1228 The "timeout" was reached before the transaction was able to
1234 Request object members:
1236 "op": "commit" required
1237 "durable": <boolean> required
1239 Result object members:
1245 If "durable" is specified as true, then the transaction, if it
1246 commits, will be stored durably (to disk) before the reply is sent
1251 "error": "not supported"
1253 When "durable" is true, this database implementation does not
1254 support durable commits.
1259 Request object members:
1261 "op": "abort" required
1263 Result object members:
1269 Aborts the transaction with an error. This may be useful for
1276 This operation always fails with this error.
1282 Request object members:
1284 "op": "comment" required
1285 "comment": <string> required
1287 Result object members:
1293 Provides information to a database administrator on the purpose of
1294 a transaction. The OVSDB server, for example, adds comments in
1295 transactions that modify the database to the database journal.
1300 Request object members:
1302 "op": "assert" required
1303 "lock": <id> required
1305 Result object members:
1311 If the client does not own the lock named <string>, aborts the
1316 "error": "not owner"
1318 The client does not own the named lock.