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).
38 An Open vSwitch configuration database consists of a set of tables,
39 each of which has a number of columns and zero or more rows. A schema
40 is represented by <database-schema>, as described below.
44 A JSON object with the following members:
47 "comment": <string> optional
48 "tables": {<id>: <table-schema>, ...} required
50 The "name" identifies the database as a whole. The "comment"
51 optionally provides more information about the database. The
52 value of "tables" is a JSON object whose names are table names and
53 whose values are <table-schema>s.
57 A JSON object with the following members:
59 "comment": <string> optional
60 "columns": {<id>: <column-schema>, ...} required
62 The "comment" optionally provides information about this table for
63 a human reader. The value of "tables" is a JSON object whose
64 names are table names and whose values are <column-schema>s.
66 Every table has the following columns whose definitions are not
67 included in the schema:
69 "_uuid": This column, which contains exactly one UUID value,
70 is initialized to a random value by the database engine when
71 it creates a row. It is read-only, and its value never
72 changes during the lifetime of a row.
74 "_version": Like "_uuid", this column contains exactly one
75 UUID value, initialized to a random value by the database
76 engine when it creates a row, and it is read-only. However,
77 its value changes to a new random value whenever any other
78 field in the row changes. Furthermore, its value is
79 ephemeral: when the database is closed and reopened, or when
80 the database process is stopped and then started again, each
81 "_version" also changes to a new random value.
85 A JSON object with the following members:
87 "comment": <string> optional
88 "type": <type> required
89 "ephemeral": <boolean> optional
91 The "comment" optionally provides information about this column
92 for a human reader. The "type" specifies the type of data stored
93 in this column. If "ephemeral" is specified as true, then this
94 column's values are not guaranteed to be durable; they may be lost
95 when the database restarts.
99 The type of a database column. Either an <atomic-type> or a JSON
100 object that describes the type of a database column, with the
103 "key": <atomic-type> required
104 "value": <atomic-type> optional
105 "min": <integer> optional
106 "max": <integer> or "unlimited" optional
108 If "min" or "max" is not specified, each defaults to 1. If "max"
109 is specified as "unlimited", then there is no specified maximum
110 number of elements, although the implementation will enforce some
111 limit. After considering defaults, "min" must be at least 0,
112 "max" must be at least 1, and "max" must be greater than or equal
115 If "min" and "max" are both 1 and "value" is not specified, the
116 type is the scalar type specified by "key".
118 If "min" is not 1 or "max" is not 1, or both, and "value" is not
119 specified, the type is a set of scalar type "key".
121 If "value" is specified, the type is a map from type "key" to type
126 One of the strings "integer", "real", "boolean", "string", or
127 "uuid", representing the specified scalar type.
132 The database wire protocol is implemented in JSON-RPC 1.0. It
133 consists of the following JSON-RPC methods:
138 Request object members:
140 "method": "get_schema" required
141 "params": [] required
142 "id": any JSON value except null required
144 Response object members:
146 "result": <database-schema>
148 "id": same "id" as request
150 This operation retrieves a <database-schema> that describes the
156 Request object members:
158 "method": "transact" required
159 "params": [<operation>*] required
160 "id": any JSON value except null required
162 Response object members:
164 "result": [<object>*]
166 "id": same "id" as request
168 The "params" array for this method consists of zero or more JSON
169 objects, each of which represents a single database operation. The
170 "Operations" section below describes the valid operations.
172 The value of "id" must be unique among all in-flight transactions
173 within the current JSON-RPC session. Otherwise, the server may return
176 The database server executes each of the specified operations in the
177 specified order, except that if an operation fails, then the remaining
178 operations are not executed.
180 The set of operations is executed as a single atomic, consistent,
181 isolated transaction. The transaction is committed only if every
182 operation succeeds. Durability of the commit is not guaranteed unless
183 the "commit" operation, with "durable" set to true, is included in the
184 operation set (see below).
186 Regardless of whether errors occur, the response is always a JSON-RPC
187 response with null "error" and a "result" member that is an array with
188 the same number of elements as "params". Each element of the "result"
189 array corresponds to the same element of the "params" array. The
190 "result" array elements may be interpreted as follows:
192 - A JSON object that does not contain an "error" member indicates
193 that the operation completed successfully. The specific members
194 of the object are specified below in the descriptions of
195 individual operations. Some operations do not produce any
196 results, in which case the object will have no members.
198 - A JSON object that contains a "error" member indicates that the
199 operation completed with an error. The value of the "error"
200 member is a short string, specified in this document, that
201 broadly indicates the class of the error. Besides the ones
202 listed for a specific operation, any operation may result in one
203 the following "error"s:
205 "error": "resources exhausted"
207 The operation or the transaction requires more resources
208 (memory, disk, CPU, etc.) than are currently available to
211 "error": "syntax error"
213 The operation is not specified correctly: a required request
214 object member is missing, an unknown or unsupported request
215 object member is present, the operation attempts to act on a
216 table that does not exist, the operation modifies a
217 read-only table column, etc.
219 Database implementations may use "error" strings not specified
220 in this document to indicate errors that do not fit into any of
221 the specified categories.
223 Optionally, the object may include a "details" member, whose
224 value is a string that describes the error in more detail for
225 the benefit of a human user or administrator. The object may
226 also have other members that describe the error in more detail.
227 This document does not specify the names or values of these
230 - A JSON null value indicates that the operation was not attempted
231 because a prior operation failed.
233 In general, "result" contains some number of successful results,
234 possibly followed by an error, in turn followed by enough JSON null
235 values to match the number of elements in "params". There is one
236 exception: if all of the operations succeed, but the results cannot be
237 committed (e.g. due to I/O errors), then "result" will have one more
238 element than "params", with the additional element describing the
241 If "params" contains one or more "wait" operations, then the
242 transaction may take an arbitrary amount of time to complete. The
243 database implementation must be capable of accepting, executing, and
244 replying to other transactions and other JSON-RPC requests while a
245 transaction or transactions containing "wait" operations are
246 outstanding on the same or different JSON-RPC sessions.
248 The section "Notation for the Wire Protocol" below describes
249 additional notation for use with the wire protocol. After that, the
250 "Operations" section describes each operation.
255 Request object members:
257 "method": "cancel" required
258 "params": the "id" for an outstanding request required
261 Response object members:
265 This JSON-RPC notification instructs the database server to
266 immediately complete or cancel the "transact" request whose "id" is
267 the same as the notification's "params" value.
269 If the "transact" request can be completed immediately, then the
270 server sends a response in the form described for "transact", above.
271 Otherwise, the server sends a JSON-RPC error response of the following
276 "id": the request "id" member
278 The "cancel" notification itself has no reply.
280 Notation for the Wire Protocol
281 ------------------------------
285 An <id> that names a table.
289 An <id> that names a table column.
293 A JSON object that describes a table row or a subset of a table
294 row. Each member is the name of a table column paired with the
295 <value> of that column.
299 A JSON value that represents the value of a column in a table row,
300 one of <atom>, a <set>, or a <map>.
304 A JSON value that represents a scalar value for a column, one of
305 <string>, <number>, <boolean>, <uuid>, <named-uuid>.
309 A 2-element JSON array that represents a database set value. The
310 first element of the array must be the string "set" and the second
311 element must be an array of zero or more <atom>s giving the values
312 in the set. All of the <atom>s must have the same type.
316 A 2-element JSON array that represents a database map value. The
317 first element of the array must be the string "map" and the second
318 element must be an array of zero or more <pair>s giving the values
319 in the map. All of the <pair>s must have the same key and value
322 (JSON objects are not used to represent <map> because JSON only
323 allows string names in an object.)
327 A 2-element JSON array that represents a pair within a database
328 map. The first element is an <atom> that represents the key, the
329 second element is an <atom> that represents the value.
333 A 2-element JSON array that represents a UUID. The first element
334 of the array must be the string "uuid" and the second element must
335 be a 36-character string giving the UUID in the format described
336 by RFC 4122. For example, the following <uuid> represents the
337 UUID 550e8400-e29b-41d4-a716-446655440000:
339 ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
343 A 2-element JSON array that represents the UUID of a row inserted
344 in a previous "insert" operation within the same transaction. The
345 first element of the array must be the string "named-uuid" and the
346 second element must be the string specified on a previous "insert"
347 operation's "uuid-name". For example, if a previous "insert"
348 operation specified a "uuid-name" of "myrow", the following
349 <named-uuid> represents the UUID created by that operation:
351 ["named-uuid", "myrow"]
355 A 3-element JSON array of the form [<column>, <function>,
356 <value>] that represents a test on a column value.
358 Except as otherwise specified below, <value> must have the same
361 The meaning depends on the type of <column>:
366 <function> must be "<", "<=", "==", "!=", ">=", ">",
367 "includes", or "excludes".
369 The test is true if the column's value satisfies the
370 relation <function> <value>, e.g. if the column has value
371 1 and <value> is 2, the test is true if <function> is "<",
372 "<=" or "!=", but not otherwise.
374 "includes" is equivalent to "=="; "excludes" is equivalent
381 <function> must be "!=", "==", "includes", or "excludes".
383 If <function> is "==" or "includes", the test is true if
384 the column's value equals <value>. If <function> is "!="
385 or "excludes", the test is inverted.
390 <function> must be "!=", "==", "includes", or "excludes".
392 If <function> is "==", the test is true if the column's
393 value contains exactly the same values (for sets) or pairs
394 (for maps). If <function> is "!=", the test is inverted.
396 If <function> is "includes", the test is true if the
397 column's value contains all of the values (for sets) or
398 pairs (for maps) in <value>. The column's value may also
399 contain other values or pairs.
401 If <function> is "excludes", the test is true if the
402 column's value does not contain any of the values (for
403 sets) or pairs (for maps) in <value>. The column's value
404 may contain other values or pairs not in <value>.
406 If <function> is "includes" or "excludes", then the
407 required type of <value> is slightly relaxed, in that it
408 may have fewer than the minimum number of elements
409 specified by the column's type. If <function> is
410 "excludes", then the required type is additionally relaxed
411 in that <value> may have more than the maximum number of
412 elements specified by the column's type.
416 One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
421 Each of the available operations is described below.
426 Request object members:
428 "op": "insert" required
429 "table": <table> required
430 "row": <row> required
431 "uuid-name": <string> optional
433 Result object members:
439 Inserts "row" into "table". If "row" does not specify values
440 for all the columns in "table", those columns receive default
443 The new row receives a new, randomly generated UUID, which is
444 returned as the "_uuid" member of the result. If "uuid-name"
445 is supplied, then the UUID is made available under that name
446 to later operations within the same transaction.
451 Request object members:
453 "op": "select" required
454 "table": <table> required
455 "where": [<condition>*] required
456 "columns": [<column>*] optional
458 Result object members:
464 Searches "table" for rows that match all the conditions specified
465 in "where". If "where" is an empty array, every row in "table" is
468 The "rows" member of the result is an array of objects. Each
469 object corresponds to a matching row, with each column
470 specified in "columns" as a member, the column's name as the
471 member name and its value as the member value. If "columns"
472 is not specified, all the table's columns are included. If
473 two rows of the result have the same values for all included
474 columns, only one copy of that row is included in "rows".
475 Specifying "_uuid" within "columns" will avoid dropping
476 duplicates, since every row has a unique UUID.
478 The ordering of rows within "rows" is unspecified.
483 Request object members:
485 "op": "update" required
486 "table": <table> required
487 "where": [<condition>*] required
488 "row": <row> required
490 Result object members:
496 Updates rows in a table.
498 Searches "table" for rows that match all the conditions
499 specified in "where". For each matching row, changes the
500 value of each column specified in "row" to the value for that
501 column specified in "row".
503 The "_uuid" and "_version" columns of a table may not be updated.
504 Columns designated read-only in the schema also may not be
507 The "count" member of the result specifies the number of rows
513 Request object members:
515 "op": "delete" required
516 "table": <table> required
517 "where": [<condition>*] required
519 Result object members:
525 Deletes all the rows from "table" that match all the conditions
526 specified in "where".
528 The "count" member of the result specifies the number of deleted
534 Request object members:
536 "op": "wait" required
537 "timeout": <integer> optional
538 "table": <table> required
539 "where": [<condition>*] required
540 "columns": [<column>*] required
541 "until": "==" or "!=" required
542 "rows": [<row>*] required
544 Result object members:
550 Waits until a condition becomes true.
552 If "until" is "==", checks whether the query on "table" specified
553 by "where" and "columns", which is evaluated in the same way as
554 specified for "select", returns the result set specified by
555 "rows". If it does, then the operation completes successfully.
556 Otherwise, the entire transaction rolls back. It is automatically
557 restarted later, after a change in the database makes it possible
558 for the operation to succeed. The client will not receive a
559 response until the operation permanently succeeds or fails.
561 If "until" is "!=", the sense of the test is negated. That is, as
562 long as the query on "table" specified by "where" and "columns"
563 returns "rows", the transaction will be rolled back and restarted
566 If "timeout" is specified, then the transaction aborts after the
567 specified number of milliseconds. The transaction is guaranteed
568 to be attempted at least once before it aborts. A "timeout" of 0
569 will abort the transaction on the first mismatch.
573 "error": "not supported"
575 One or more of the columns in this table do not support
576 triggers. This error will not occur if "timeout" is 0.
580 The "timeout" was reached before the transaction was able to
586 Request object members:
588 "op": "commit" required
589 "durable": <boolean> required
591 Result object members:
597 If "durable" is specified as true, then the transaction, if it
598 commits, will be stored durably (to disk) before the reply is sent
603 "error": "not supported"
605 When "durable" is true, this database implementation does not
606 support durable commits.
611 Request object members:
613 "op": "abort" required
615 Result object members:
621 Aborts the transaction with an error. This may be useful for
628 This operation always fails with this error.