1 ===================================================
2 Open vSwitch Configuration Database Specification
3 ===================================================
8 The descriptions below use the following shorthand notations for JSON
9 values. Additional notation is presented later.
17 A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*.
19 <id>s that begin with _ are reserved to the implementation and may
20 not be used by the user.
24 A JSON true or false value.
32 A JSON number with an integer value, within a certain range
33 (currently -2**63...+2**63-1).
42 An Open vSwitch configuration database consists of a set of tables,
43 each of which has a number of columns and zero or more rows. A schema
44 is represented by <database-schema>, as described below.
48 A JSON object with the following members:
51 "comment": <string> optional
52 "tables": {<id>: <table-schema>, ...} required
54 The "name" identifies the database as a whole. The "comment"
55 optionally provides more information about the database. The
56 value of "tables" is a JSON object whose names are table names and
57 whose values are <table-schema>s.
61 A JSON object with the following members:
63 "comment": <string> optional
64 "columns": {<id>: <column-schema>, ...} required
66 The "comment" optionally provides information about this table for
67 a human reader. The value of "tables" is a JSON object whose
68 names are table names and whose values are <column-schema>s.
70 Every table has the following columns whose definitions are not
71 included in the schema:
73 "_uuid": This column, which contains exactly one UUID value,
74 is initialized to a random value by the database engine when
75 it creates a row. It is read-only, and its value never
76 changes during the lifetime of a row.
78 "_version": Like "_uuid", this column contains exactly one
79 UUID value, initialized to a random value by the database
80 engine when it creates a row, and it is read-only. However,
81 its value changes to a new random value whenever any other
82 field in the row changes. Furthermore, its value is
83 ephemeral: when the database is closed and reopened, or when
84 the database process is stopped and then started again, each
85 "_version" also changes to a new random value.
89 A JSON object with the following members:
91 "comment": <string> optional
92 "type": <type> required
93 "ephemeral": <boolean> optional
95 The "comment" optionally provides information about this column
96 for a human reader. The "type" specifies the type of data stored
97 in this column. If "ephemeral" is specified as true, then this
98 column's values are not guaranteed to be durable; they may be lost
99 when the database restarts.
103 The type of a database column. Either an <atomic-type> or a JSON
104 object that describes the type of a database column, with the
107 "key": <atomic-type> required
108 "value": <atomic-type> optional
109 "min": <integer> optional
110 "max": <integer> or "unlimited" optional
112 If "min" or "max" is not specified, each defaults to 1. If "max"
113 is specified as "unlimited", then there is no specified maximum
114 number of elements, although the implementation will enforce some
115 limit. After considering defaults, "min" must be at least 0,
116 "max" must be at least 1, and "max" must be greater than or equal
119 If "min" and "max" are both 1 and "value" is not specified, the
120 type is the scalar type specified by "key".
122 If "min" is not 1 or "max" is not 1, or both, and "value" is not
123 specified, the type is a set of scalar type "key".
125 If "value" is specified, the type is a map from type "key" to type
130 One of the strings "integer", "real", "boolean", "string", or
131 "uuid", representing the specified scalar type.
136 The database wire protocol is implemented in JSON-RPC 1.0. It
137 consists of the following JSON-RPC methods:
142 Request object members:
144 "method": "get_schema" required
145 "params": [] required
146 "id": any JSON value except null required
148 Response object members:
150 "result": <database-schema>
152 "id": same "id" as request
154 This operation retrieves a <database-schema> that describes the
160 Request object members:
162 "method": "transact" required
163 "params": [<operation>*] required
164 "id": any JSON value except null required
166 Response object members:
168 "result": [<object>*]
170 "id": same "id" as request
172 The "params" array for this method consists of zero or more JSON
173 objects, each of which represents a single database operation. The
174 "Operations" section below describes the valid operations.
176 The value of "id" must be unique among all in-flight transactions
177 within the current JSON-RPC session. Otherwise, the server may return
180 The database server executes each of the specified operations in the
181 specified order, except that if an operation fails, then the remaining
182 operations are not executed.
184 The set of operations is executed as a single atomic, consistent,
185 isolated transaction. The transaction is committed only if every
186 operation succeeds. Durability of the commit is not guaranteed unless
187 the "commit" operation, with "durable" set to true, is included in the
188 operation set (see below).
190 Regardless of whether errors occur, the response is always a JSON-RPC
191 response with null "error" and a "result" member that is an array with
192 the same number of elements as "params". Each element of the "result"
193 array corresponds to the same element of the "params" array. The
194 "result" array elements may be interpreted as follows:
196 - A JSON object that does not contain an "error" member indicates
197 that the operation completed successfully. The specific members
198 of the object are specified below in the descriptions of
199 individual operations. Some operations do not produce any
200 results, in which case the object will have no members.
202 - A JSON object that contains a "error" member indicates that the
203 operation completed with an error. The value of the "error"
204 member is a short string, specified in this document, that
205 broadly indicates the class of the error. Besides the ones
206 listed for a specific operation, any operation may result in one
207 the following "error"s:
209 "error": "resources exhausted"
211 The operation or the transaction requires more resources
212 (memory, disk, CPU, etc.) than are currently available to
215 "error": "syntax error"
217 The operation is not specified correctly: a required request
218 object member is missing, an unknown or unsupported request
219 object member is present, the operation attempts to act on a
220 table that does not exist, the operation modifies a
221 read-only table column, etc.
223 Database implementations may use "error" strings not specified
224 in this document to indicate errors that do not fit into any of
225 the specified categories.
227 Optionally, the object may include a "details" member, whose
228 value is a string that describes the error in more detail for
229 the benefit of a human user or administrator. The object may
230 also have other members that describe the error in more detail.
231 This document does not specify the names or values of these
234 - A JSON null value indicates that the operation was not attempted
235 because a prior operation failed.
237 In general, "result" contains some number of successful results,
238 possibly followed by an error, in turn followed by enough JSON null
239 values to match the number of elements in "params". There is one
240 exception: if all of the operations succeed, but the results cannot be
241 committed (e.g. due to I/O errors), then "result" will have one more
242 element than "params", with the additional element describing the
245 If "params" contains one or more "wait" operations, then the
246 transaction may take an arbitrary amount of time to complete. The
247 database implementation must be capable of accepting, executing, and
248 replying to other transactions and other JSON-RPC requests while a
249 transaction or transactions containing "wait" operations are
250 outstanding on the same or different JSON-RPC sessions.
252 The section "Notation for the Wire Protocol" below describes
253 additional notation for use with the wire protocol. After that, the
254 "Operations" section describes each operation.
259 Request object members:
261 "method": "cancel" required
262 "params": [the "id" for an outstanding request] required
265 Response object members:
269 This JSON-RPC notification instructs the database server to
270 immediately complete or cancel the "transact" request whose "id" is
271 the same as the notification's "params" value.
273 If the "transact" request can be completed immediately, then the
274 server sends a response in the form described for "transact", above.
275 Otherwise, the server sends a JSON-RPC error response of the following
280 "id": the request "id" member
282 The "cancel" notification itself has no reply.
287 Request object members:
289 "method": "echo" required
290 "params": JSON array with any contents required
291 "id": <value> required
293 Response object members:
295 "result": same as "params"
297 "id": the request "id" member
299 Both the JSON-RPC client and the server must implement this request.
301 This JSON-RPC request and response can be used to implement connection
302 keepalives, by allowing the server to check that the client is still
306 Notation for the Wire Protocol
307 ------------------------------
311 An <id> that names a table.
315 An <id> that names a table column.
319 A JSON object that describes a table row or a subset of a table
320 row. Each member is the name of a table column paired with the
321 <value> of that column.
325 A JSON value that represents the value of a column in a table row,
326 one of <atom>, a <set>, or a <map>.
330 A JSON value that represents a scalar value for a column, one of
331 <string>, <number>, <boolean>, <uuid>, <named-uuid>.
335 A 2-element JSON array that represents a database set value. The
336 first element of the array must be the string "set" and the second
337 element must be an array of zero or more <atom>s giving the values
338 in the set. All of the <atom>s must have the same type.
342 A 2-element JSON array that represents a database map value. The
343 first element of the array must be the string "map" and the second
344 element must be an array of zero or more <pair>s giving the values
345 in the map. All of the <pair>s must have the same key and value
348 (JSON objects are not used to represent <map> because JSON only
349 allows string names in an object.)
353 A 2-element JSON array that represents a pair within a database
354 map. The first element is an <atom> that represents the key, the
355 second element is an <atom> that represents the value.
359 A 2-element JSON array that represents a UUID. The first element
360 of the array must be the string "uuid" and the second element must
361 be a 36-character string giving the UUID in the format described
362 by RFC 4122. For example, the following <uuid> represents the
363 UUID 550e8400-e29b-41d4-a716-446655440000:
365 ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
369 A 2-element JSON array that represents the UUID of a row inserted
370 in a previous "insert" operation within the same transaction. The
371 first element of the array must be the string "named-uuid" and the
372 second element must be the string specified on a previous "insert"
373 operation's "uuid-name". For example, if a previous "insert"
374 operation specified a "uuid-name" of "myrow", the following
375 <named-uuid> represents the UUID created by that operation:
377 ["named-uuid", "myrow"]
381 A 3-element JSON array of the form [<column>, <function>,
382 <value>] that represents a test on a column value.
384 Except as otherwise specified below, <value> must have the same
387 The meaning depends on the type of <column>:
392 <function> must be "<", "<=", "==", "!=", ">=", ">",
393 "includes", or "excludes".
395 The test is true if the column's value satisfies the
396 relation <function> <value>, e.g. if the column has value
397 1 and <value> is 2, the test is true if <function> is "<",
398 "<=" or "!=", but not otherwise.
400 "includes" is equivalent to "=="; "excludes" is equivalent
407 <function> must be "!=", "==", "includes", or "excludes".
409 If <function> is "==" or "includes", the test is true if
410 the column's value equals <value>. If <function> is "!="
411 or "excludes", the test is inverted.
416 <function> must be "!=", "==", "includes", or "excludes".
418 If <function> is "==", the test is true if the column's
419 value contains exactly the same values (for sets) or pairs
420 (for maps). If <function> is "!=", the test is inverted.
422 If <function> is "includes", the test is true if the
423 column's value contains all of the values (for sets) or
424 pairs (for maps) in <value>. The column's value may also
425 contain other values or pairs.
427 If <function> is "excludes", the test is true if the
428 column's value does not contain any of the values (for
429 sets) or pairs (for maps) in <value>. The column's value
430 may contain other values or pairs not in <value>.
432 If <function> is "includes" or "excludes", then the
433 required type of <value> is slightly relaxed, in that it
434 may have fewer than the minimum number of elements
435 specified by the column's type. If <function> is
436 "excludes", then the required type is additionally relaxed
437 in that <value> may have more than the maximum number of
438 elements specified by the column's type.
442 One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
447 Each of the available operations is described below.
452 Request object members:
454 "op": "insert" required
455 "table": <table> required
456 "row": <row> required
457 "uuid-name": <string> optional
459 Result object members:
465 Inserts "row" into "table". If "row" does not specify values
466 for all the columns in "table", those columns receive default
469 The new row receives a new, randomly generated UUID, which is
470 returned as the "_uuid" member of the result. If "uuid-name"
471 is supplied, then the UUID is made available under that name
472 to later operations within the same transaction.
477 Request object members:
479 "op": "select" required
480 "table": <table> required
481 "where": [<condition>*] required
482 "columns": [<column>*] optional
484 Result object members:
490 Searches "table" for rows that match all the conditions specified
491 in "where". If "where" is an empty array, every row in "table" is
494 The "rows" member of the result is an array of objects. Each
495 object corresponds to a matching row, with each column
496 specified in "columns" as a member, the column's name as the
497 member name and its value as the member value. If "columns"
498 is not specified, all the table's columns are included. If
499 two rows of the result have the same values for all included
500 columns, only one copy of that row is included in "rows".
501 Specifying "_uuid" within "columns" will avoid dropping
502 duplicates, since every row has a unique UUID.
504 The ordering of rows within "rows" is unspecified.
509 Request object members:
511 "op": "update" required
512 "table": <table> required
513 "where": [<condition>*] required
514 "row": <row> required
516 Result object members:
522 Updates rows in a table.
524 Searches "table" for rows that match all the conditions
525 specified in "where". For each matching row, changes the
526 value of each column specified in "row" to the value for that
527 column specified in "row".
529 The "_uuid" and "_version" columns of a table may not be updated.
530 Columns designated read-only in the schema also may not be
533 The "count" member of the result specifies the number of rows
539 Request object members:
541 "op": "delete" required
542 "table": <table> required
543 "where": [<condition>*] required
545 Result object members:
551 Deletes all the rows from "table" that match all the conditions
552 specified in "where".
554 The "count" member of the result specifies the number of deleted
560 Request object members:
562 "op": "wait" required
563 "timeout": <integer> optional
564 "table": <table> required
565 "where": [<condition>*] required
566 "columns": [<column>*] required
567 "until": "==" or "!=" required
568 "rows": [<row>*] required
570 Result object members:
576 Waits until a condition becomes true.
578 If "until" is "==", checks whether the query on "table" specified
579 by "where" and "columns", which is evaluated in the same way as
580 specified for "select", returns the result set specified by
581 "rows". If it does, then the operation completes successfully.
582 Otherwise, the entire transaction rolls back. It is automatically
583 restarted later, after a change in the database makes it possible
584 for the operation to succeed. The client will not receive a
585 response until the operation permanently succeeds or fails.
587 If "until" is "!=", the sense of the test is negated. That is, as
588 long as the query on "table" specified by "where" and "columns"
589 returns "rows", the transaction will be rolled back and restarted
592 If "timeout" is specified, then the transaction aborts after the
593 specified number of milliseconds. The transaction is guaranteed
594 to be attempted at least once before it aborts. A "timeout" of 0
595 will abort the transaction on the first mismatch.
599 "error": "not supported"
601 One or more of the columns in this table do not support
602 triggers. This error will not occur if "timeout" is 0.
606 The "timeout" was reached before the transaction was able to
612 Request object members:
614 "op": "commit" required
615 "durable": <boolean> required
617 Result object members:
623 If "durable" is specified as true, then the transaction, if it
624 commits, will be stored durably (to disk) before the reply is sent
629 "error": "not supported"
631 When "durable" is true, this database implementation does not
632 support durable commits.
637 Request object members:
639 "op": "abort" required
641 Result object members:
647 Aborts the transaction with an error. This may be useful for
654 This operation always fails with this error.