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 If "params" contains one or more "wait" operations, then the
446 transaction may take an arbitrary amount of time to complete. The
447 database implementation must be capable of accepting, executing, and
448 replying to other transactions and other JSON-RPC requests while a
449 transaction or transactions containing "wait" operations are
450 outstanding on the same or different JSON-RPC sessions.
452 The section "Notation for the Wire Protocol" below describes
453 additional notation for use with the wire protocol. After that, the
454 "Operations" section describes each operation.
459 Request object members:
461 "method": "cancel" required
462 "params": [the "id" for an outstanding request] required
465 Response object members:
469 This JSON-RPC notification instructs the database server to
470 immediately complete or cancel the "transact" request whose "id" is
471 the same as the notification's "params" value.
473 If the "transact" request can be completed immediately, then the
474 server sends a response in the form described for "transact", above.
475 Otherwise, the server sends a JSON-RPC error response of the following
480 "id": the request "id" member
482 The "cancel" notification itself has no reply.
487 Request object members:
489 "method": "monitor" required
490 "params": [<db-name>, <json-value>, <monitor-requests>] required
491 "id": <nonnull-json-value> required
493 <monitor-requests> is an object that maps from a table name to an
494 array of <monitor-request> objects. For backward compatibility, a
495 single <monitor-request> may be used instead of an array; it is
496 treated as a single-element array.
498 Each <monitor-request> is an object with the following members:
500 "columns": [<column>*] optional
501 "select": <monitor-select> optional
503 <monitor-select> is an object with the following members:
505 "initial": <boolean> optional
506 "insert": <boolean> optional
507 "delete": <boolean> optional
508 "modify": <boolean> optional
510 Response object members:
512 "result": <table-updates>
514 "id": same "id" as request
516 This JSON-RPC request enables a client to replicate tables or subsets
517 of tables within database <db-name>. Each element of
518 <monitor-requests> specifies a table to be replicated. The JSON-RPC
519 response to the "monitor" includes the initial contents of each table,
520 unless disabled (see below). Afterward, when changes to those tables
521 are committed, the changes are automatically sent to the client using
522 the "update" monitor notification. This monitoring persists until the
523 JSON-RPC session terminates or until the client sends a
524 "monitor_cancel" JSON-RPC request.
526 Each <monitor-request> describes how to monitor columns in a table:
528 The circumstances in which an "update" notification is sent for a
529 row within the table are determined by <monitor-select>:
531 If "initial" is omitted or true, every row in the table is
532 sent as part of the reply to the "monitor" request.
534 If "insert" is omitted or true, "update" notifications are
535 sent for rows newly inserted into the table.
537 If "delete" is omitted or true, "update" notifications are
538 sent for rows deleted from the table.
540 If "modify" is omitted or true, "update" notifications are
541 sent whenever when a row in the table is modified.
543 The "columns" member specifies the columns whose values are
544 monitored. It must not contain duplicates. If "columns" is
545 omitted, all columns in the table, except for "_uuid", are
548 If there is more than one <monitor-request> in an array of them, then
549 each <monitor-request> in the array should specify both "columns" and
550 "select", and the "columns" must be non-overlapping sets.
552 The "result" in the JSON-RPC response to the "monitor" request is a
553 <table-updates> object (see below) that contains the contents of the
554 tables for which "initial" rows are selected. If no tables' initial
555 contents are requested, then "result" is an empty object.
560 Notification object members:
563 "params": [<json-value>, <table-updates>]
566 The <json-value> in "params" is the same as the value passed as the
567 <json-value> in "params" for the "monitor" request.
569 <table-updates> is an object that maps from a table name to a
572 A <table-update> is an object that maps from the row's UUID (as a
573 36-byte string) to a <row-update> object.
575 A <row-update> is an object with the following members:
577 "old": <row> present for "delete" and "modify" updates
578 "new": <row> present for "initial", "insert", and "modify" updates
580 This JSON-RPC notification is sent from the server to the client to
581 tell it about changes to a monitored table (or the initial state of a
582 modified table). Each table in which one or more rows has changed (or
583 whose initial view is being presented) is represented in "updates".
584 Each row that has changed (or whose initial view is being presented)
585 is represented in its <table-update> as a member with its name taken
586 from the row's _uuid member. The corresponding value is a
589 The "old" member is present for "delete" and "modify" updates.
590 For "delete" updates, each monitored column is included. For
591 "modify" updates, the prior value of each monitored column whose
592 value has changed is included (monitored columns that have not
593 changed are represented in "new").
595 The "new" member is present for "initial", "insert", and "modify"
596 updates. For "initial" and "insert" updates, each monitored
597 column is included. For "modify" updates, the new value of each
598 monitored column is included.
603 Request object members:
605 "method": "monitor_cancel" required
606 "params": [<json-value>] required
607 "id": <nonnull-json-value> required
609 Response object members:
613 "id": the request "id" member
615 Cancels the ongoing table monitor request, identified by the
616 <json-value> in "params" matching the <json-value> in "params" for an
617 ongoing "monitor" request. No more "update" messages will be sent for
623 Request object members:
625 "method": "echo" required
626 "params": JSON array with any contents required
627 "id": <json-value> required
629 Response object members:
631 "result": same as "params"
633 "id": the request "id" member
635 Both the JSON-RPC client and the server must implement this request.
637 This JSON-RPC request and response can be used to implement connection
638 keepalives, by allowing the server to check that the client is still
642 Notation for the Wire Protocol
643 ------------------------------
647 An <id> that names a database. The valid <db-name>s can be
648 obtained using a "list-db" request. The <db-name> is taken from
649 the "name" member of <database-schema>.
653 An <id> that names a table.
657 An <id> that names a table column.
661 A JSON object that describes a table row or a subset of a table
662 row. Each member is the name of a table column paired with the
663 <value> of that column.
667 A JSON value that represents the value of a column in a table row,
668 one of <atom>, a <set>, or a <map>.
672 A JSON value that represents a scalar value for a column, one of
673 <string>, <number>, <boolean>, <uuid>, <named-uuid>.
677 Either an <atom>, representing a set with exactly one element, or
678 a 2-element JSON array that represents a database set value. The
679 first element of the array must be the string "set" and the second
680 element must be an array of zero or more <atom>s giving the values
681 in the set. All of the <atom>s must have the same type.
685 A 2-element JSON array that represents a database map value. The
686 first element of the array must be the string "map" and the second
687 element must be an array of zero or more <pair>s giving the values
688 in the map. All of the <pair>s must have the same key and value
691 (JSON objects are not used to represent <map> because JSON only
692 allows string names in an object.)
696 A 2-element JSON array that represents a pair within a database
697 map. The first element is an <atom> that represents the key, the
698 second element is an <atom> that represents the value.
702 A 2-element JSON array that represents a UUID. The first element
703 of the array must be the string "uuid" and the second element must
704 be a 36-character string giving the UUID in the format described
705 by RFC 4122. For example, the following <uuid> represents the
706 UUID 550e8400-e29b-41d4-a716-446655440000:
708 ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
712 A 2-element JSON array that represents the UUID of a row inserted
713 in an "insert" operation within the same transaction. The first
714 element of the array must be the string "named-uuid" and the
715 second element should be the <id> specified as the "uuid-name"
716 for an "insert" operation within the same transaction. For
717 example, if an "insert" operation within this transaction
718 specifies a "uuid-name" of "myrow", the following <named-uuid>
719 represents the UUID created by that operation:
721 ["named-uuid", "myrow"]
723 A <named-uuid> may be used anywhere a <uuid> is valid.
727 A 3-element JSON array of the form [<column>, <function>,
728 <value>] that represents a test on a column value.
730 Except as otherwise specified below, <value> must have the same
733 The meaning depends on the type of <column>:
738 <function> must be "<", "<=", "==", "!=", ">=", ">",
739 "includes", or "excludes".
741 The test is true if the column's value satisfies the
742 relation <function> <value>, e.g. if the column has value
743 1 and <value> is 2, the test is true if <function> is "<",
744 "<=" or "!=", but not otherwise.
746 "includes" is equivalent to "=="; "excludes" is equivalent
753 <function> must be "!=", "==", "includes", or "excludes".
755 If <function> is "==" or "includes", the test is true if
756 the column's value equals <value>. If <function> is "!="
757 or "excludes", the test is inverted.
762 <function> must be "!=", "==", "includes", or "excludes".
764 If <function> is "==", the test is true if the column's
765 value contains exactly the same values (for sets) or pairs
766 (for maps). If <function> is "!=", the test is inverted.
768 If <function> is "includes", the test is true if the
769 column's value contains all of the values (for sets) or
770 pairs (for maps) in <value>. The column's value may also
771 contain other values or pairs.
773 If <function> is "excludes", the test is true if the
774 column's value does not contain any of the values (for
775 sets) or pairs (for maps) in <value>. The column's value
776 may contain other values or pairs not in <value>.
778 If <function> is "includes" or "excludes", then the
779 required type of <value> is slightly relaxed, in that it
780 may have fewer than the minimum number of elements
781 specified by the column's type. If <function> is
782 "excludes", then the required type is additionally relaxed
783 in that <value> may have more than the maximum number of
784 elements specified by the column's type.
788 One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
792 A 3-element JSON array of the form [<column>, <mutator>, <value>]
793 that represents a change to a column value.
795 Except as otherwise specified below, <value> must have the same
798 The meaning depends on the type of <column>:
803 <mutator> must be "+=", "-=", "*=", "/=" or (integer only)
804 "%=". The value of <column> is changed to the sum,
805 difference, product, quotient, or remainder, respectively,
806 of <column> and <value>.
808 Constraints on <column> are ignored when parsing <value>.
814 No valid <mutator>s are currently defined for these types.
818 Any <mutator> valid for the set's element type may be
819 applied to the set, in which case the mutation is applied
820 to each member of the set individually. <value> must be a
821 scalar value of the same type as the set's element type,
822 except that contraints are ignored.
824 If <mutator> is "insert", then each of the values in the
825 set in <value> is added to <column> if it is not already
826 present. The required type of <value> is slightly
827 relaxed, in that it may have fewer than the minimum number
828 of elements specified by the column's type.
830 If <mutator> is "delete", then each of the values in the
831 set in <value> is removed from <column> if it is present
832 there. The required type is slightly relaxed in that
833 <value> may have more or less than the maximum number of
834 elements specified by the column's type.
838 <mutator> must be "insert" or "delete".
840 If <mutator> is "insert", then each of the key-value pairs
841 in the map in <value> is added to <column> only if its key
842 is not already present. The required type of <value> is
843 slightly relaxed, in that it may have fewer than the
844 minimum number of elements specified by the column's type.
846 If <mutator> is "delete", then <value> may have the same
847 type as <column> (a map type) or it may be a set whose
848 element type is the same as <column>'s key type:
850 - If <value> is a map, the mutation deletes each
851 key-value pair in <column> whose key and value equal
852 one of the key-value pairs in <value>.
854 - If <value> is a set, the mutation deletes each
855 key-value pair in <column> whose key equals one of
856 the values in <value>.
858 For "delete", <value> may have any number of elements,
859 regardless of restrictions on the number of elements in
864 One of "+=", "-=", "*=", "/=", "%=", "insert", "delete".
869 Each of the available operations is described below.
874 Request object members:
876 "op": "insert" required
877 "table": <table> required
878 "row": <row> required
879 "uuid-name": <id> optional
881 Result object members:
887 Inserts "row" into "table".
889 If "row" does not specify values for all the columns in "table",
890 those columns receive default values. The default value for a
891 column depends on its type. The default for a column whose <type>
892 specifies a "min" of 0 is an empty set or empty map. Otherwise,
893 the default is a single value or a single key-value pair, whose
894 value(s) depend on its <atomic-type>:
896 - "integer" or "real": 0
900 - "string": "" (the empty string)
902 - "uuid": 00000000-0000-0000-0000-000000000000
904 The new row receives a new, randomly generated UUID.
906 If "uuid-name" is supplied, then it is an error if <id> is not
907 unique among the "uuid-name"s supplied on all the "insert"
908 operations within this transaction.
910 The UUID for the new row is returned as the "uuid" member of the
915 "error": "duplicate uuid-name"
917 The same "uuid-name" appears on another "insert" operation
918 within this transaction.
920 "error": "constraint violation"
922 One of the values in "row" does not satisfy the immediate
923 constraints for its column's <base-type>. This error will
924 occur for columns that are not explicitly set by "row" if the
925 default value does not satisfy the column's constraints.
930 Request object members:
932 "op": "select" required
933 "table": <table> required
934 "where": [<condition>*] required
935 "columns": [<column>*] optional
937 Result object members:
943 Searches "table" for rows that match all the conditions specified
944 in "where". If "where" is an empty array, every row in "table" is
947 The "rows" member of the result is an array of objects. Each
948 object corresponds to a matching row, with each column
949 specified in "columns" as a member, the column's name as the
950 member name and its value as the member value. If "columns"
951 is not specified, all the table's columns are included. If
952 two rows of the result have the same values for all included
953 columns, only one copy of that row is included in "rows".
954 Specifying "_uuid" within "columns" will avoid dropping
955 duplicates, since every row has a unique UUID.
957 The ordering of rows within "rows" is unspecified.
962 Request object members:
964 "op": "update" required
965 "table": <table> required
966 "where": [<condition>*] required
967 "row": <row> required
969 Result object members:
975 Updates rows in a table.
977 Searches "table" for rows that match all the conditions
978 specified in "where". For each matching row, changes the
979 value of each column specified in "row" to the value for that
980 column specified in "row".
982 The "_uuid" and "_version" columns of a table may not be directly
983 updated with this operation. Columns designated read-only in the
984 schema also may not be updated.
986 The "count" member of the result specifies the number of rows
991 "error": "constraint violation"
993 One of the values in "row" does not satisfy the immediate
994 constraints for its column's <base-type>.
998 Request object members:
1000 "op": "mutate" required
1001 "table": <table> required
1002 "where": [<condition>*] required
1003 "mutations": [<mutation>*] required
1005 Result object members:
1011 Mutates rows in a table.
1013 Searches "table" for rows that match all the conditions specified
1014 in "where". For each matching row, mutates its columns as
1015 specified by each <mutation> in "mutations", in the order
1018 The "_uuid" and "_version" columns of a table may not be directly
1019 modified with this operation. Columns designated read-only in the
1020 schema also may not be updated.
1022 The "count" member of the result specifies the number of rows
1027 "error": "domain error"
1029 The result of the mutation is not mathematically defined,
1030 e.g. division by zero.
1032 "error": "range error"
1034 The result of the mutation is not representable within the
1035 database's format, e.g. an integer result outside the range
1036 INT64_MIN...INT64_MAX or a real result outside the range
1039 "error": "constraint violation"
1041 The mutation caused the column's value to violate a
1042 constraint, e.g. it caused a column to have more or fewer
1043 values than are allowed, an arithmetic operation caused a set
1044 or map to have duplicate elements, or it violated a constraint
1045 specified by a column's <base-type>.
1050 Request object members:
1052 "op": "delete" required
1053 "table": <table> required
1054 "where": [<condition>*] required
1056 Result object members:
1062 Deletes all the rows from "table" that match all the conditions
1063 specified in "where".
1065 The "count" member of the result specifies the number of deleted
1071 Request object members:
1073 "op": "wait" required
1074 "timeout": <integer> optional
1075 "table": <table> required
1076 "where": [<condition>*] required
1077 "columns": [<column>*] required
1078 "until": "==" or "!=" required
1079 "rows": [<row>*] required
1081 Result object members:
1087 Waits until a condition becomes true.
1089 If "until" is "==", checks whether the query on "table" specified
1090 by "where" and "columns", which is evaluated in the same way as
1091 specified for "select", returns the result set specified by
1092 "rows". If it does, then the operation completes successfully.
1093 Otherwise, the entire transaction rolls back. It is automatically
1094 restarted later, after a change in the database makes it possible
1095 for the operation to succeed. The client will not receive a
1096 response until the operation permanently succeeds or fails.
1098 If "until" is "!=", the sense of the test is negated. That is, as
1099 long as the query on "table" specified by "where" and "columns"
1100 returns "rows", the transaction will be rolled back and restarted
1103 If "timeout" is specified, then the transaction aborts after the
1104 specified number of milliseconds. The transaction is guaranteed
1105 to be attempted at least once before it aborts. A "timeout" of 0
1106 will abort the transaction on the first mismatch.
1110 "error": "not supported"
1112 One or more of the columns in this table do not support
1113 triggers. This error will not occur if "timeout" is 0.
1115 "error": "timed out"
1117 The "timeout" was reached before the transaction was able to
1123 Request object members:
1125 "op": "commit" required
1126 "durable": <boolean> required
1128 Result object members:
1134 If "durable" is specified as true, then the transaction, if it
1135 commits, will be stored durably (to disk) before the reply is sent
1140 "error": "not supported"
1142 When "durable" is true, this database implementation does not
1143 support durable commits.
1148 Request object members:
1150 "op": "abort" required
1152 Result object members:
1158 Aborts the transaction with an error. This may be useful for
1165 This operation always fails with this error.
1171 Request object members:
1173 "op": "comment" required
1174 "comment": <string> required
1176 Result object members:
1182 Provides information to a database administrator on the purpose of
1183 a transaction. The OVSDB server, for example, adds comments in
1184 transactions that modify the database to the database journal.