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.
283 Request object members:
285 "method": "echo" required
286 "params": any JSON value required
287 "id": any JSON value required
289 Response object members:
291 "result": same as "params"
293 "id": the request "id" member
295 Both the JSON-RPC client and the server must implement this request.
297 This JSON-RPC request and response can be used to implement connection
298 keepalives, by allowing the server to check that the client is still
302 Notation for the Wire Protocol
303 ------------------------------
307 An <id> that names a table.
311 An <id> that names a table column.
315 A JSON object that describes a table row or a subset of a table
316 row. Each member is the name of a table column paired with the
317 <value> of that column.
321 A JSON value that represents the value of a column in a table row,
322 one of <atom>, a <set>, or a <map>.
326 A JSON value that represents a scalar value for a column, one of
327 <string>, <number>, <boolean>, <uuid>, <named-uuid>.
331 A 2-element JSON array that represents a database set value. The
332 first element of the array must be the string "set" and the second
333 element must be an array of zero or more <atom>s giving the values
334 in the set. All of the <atom>s must have the same type.
338 A 2-element JSON array that represents a database map value. The
339 first element of the array must be the string "map" and the second
340 element must be an array of zero or more <pair>s giving the values
341 in the map. All of the <pair>s must have the same key and value
344 (JSON objects are not used to represent <map> because JSON only
345 allows string names in an object.)
349 A 2-element JSON array that represents a pair within a database
350 map. The first element is an <atom> that represents the key, the
351 second element is an <atom> that represents the value.
355 A 2-element JSON array that represents a UUID. The first element
356 of the array must be the string "uuid" and the second element must
357 be a 36-character string giving the UUID in the format described
358 by RFC 4122. For example, the following <uuid> represents the
359 UUID 550e8400-e29b-41d4-a716-446655440000:
361 ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
365 A 2-element JSON array that represents the UUID of a row inserted
366 in a previous "insert" operation within the same transaction. The
367 first element of the array must be the string "named-uuid" and the
368 second element must be the string specified on a previous "insert"
369 operation's "uuid-name". For example, if a previous "insert"
370 operation specified a "uuid-name" of "myrow", the following
371 <named-uuid> represents the UUID created by that operation:
373 ["named-uuid", "myrow"]
377 A 3-element JSON array of the form [<column>, <function>,
378 <value>] that represents a test on a column value.
380 Except as otherwise specified below, <value> must have the same
383 The meaning depends on the type of <column>:
388 <function> must be "<", "<=", "==", "!=", ">=", ">",
389 "includes", or "excludes".
391 The test is true if the column's value satisfies the
392 relation <function> <value>, e.g. if the column has value
393 1 and <value> is 2, the test is true if <function> is "<",
394 "<=" or "!=", but not otherwise.
396 "includes" is equivalent to "=="; "excludes" is equivalent
403 <function> must be "!=", "==", "includes", or "excludes".
405 If <function> is "==" or "includes", the test is true if
406 the column's value equals <value>. If <function> is "!="
407 or "excludes", the test is inverted.
412 <function> must be "!=", "==", "includes", or "excludes".
414 If <function> is "==", the test is true if the column's
415 value contains exactly the same values (for sets) or pairs
416 (for maps). If <function> is "!=", the test is inverted.
418 If <function> is "includes", the test is true if the
419 column's value contains all of the values (for sets) or
420 pairs (for maps) in <value>. The column's value may also
421 contain other values or pairs.
423 If <function> is "excludes", the test is true if the
424 column's value does not contain any of the values (for
425 sets) or pairs (for maps) in <value>. The column's value
426 may contain other values or pairs not in <value>.
428 If <function> is "includes" or "excludes", then the
429 required type of <value> is slightly relaxed, in that it
430 may have fewer than the minimum number of elements
431 specified by the column's type. If <function> is
432 "excludes", then the required type is additionally relaxed
433 in that <value> may have more than the maximum number of
434 elements specified by the column's type.
438 One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
443 Each of the available operations is described below.
448 Request object members:
450 "op": "insert" required
451 "table": <table> required
452 "row": <row> required
453 "uuid-name": <string> optional
455 Result object members:
461 Inserts "row" into "table". If "row" does not specify values
462 for all the columns in "table", those columns receive default
465 The new row receives a new, randomly generated UUID, which is
466 returned as the "_uuid" member of the result. If "uuid-name"
467 is supplied, then the UUID is made available under that name
468 to later operations within the same transaction.
473 Request object members:
475 "op": "select" required
476 "table": <table> required
477 "where": [<condition>*] required
478 "columns": [<column>*] optional
480 Result object members:
486 Searches "table" for rows that match all the conditions specified
487 in "where". If "where" is an empty array, every row in "table" is
490 The "rows" member of the result is an array of objects. Each
491 object corresponds to a matching row, with each column
492 specified in "columns" as a member, the column's name as the
493 member name and its value as the member value. If "columns"
494 is not specified, all the table's columns are included. If
495 two rows of the result have the same values for all included
496 columns, only one copy of that row is included in "rows".
497 Specifying "_uuid" within "columns" will avoid dropping
498 duplicates, since every row has a unique UUID.
500 The ordering of rows within "rows" is unspecified.
505 Request object members:
507 "op": "update" required
508 "table": <table> required
509 "where": [<condition>*] required
510 "row": <row> required
512 Result object members:
518 Updates rows in a table.
520 Searches "table" for rows that match all the conditions
521 specified in "where". For each matching row, changes the
522 value of each column specified in "row" to the value for that
523 column specified in "row".
525 The "_uuid" and "_version" columns of a table may not be updated.
526 Columns designated read-only in the schema also may not be
529 The "count" member of the result specifies the number of rows
535 Request object members:
537 "op": "delete" required
538 "table": <table> required
539 "where": [<condition>*] required
541 Result object members:
547 Deletes all the rows from "table" that match all the conditions
548 specified in "where".
550 The "count" member of the result specifies the number of deleted
556 Request object members:
558 "op": "wait" required
559 "timeout": <integer> optional
560 "table": <table> required
561 "where": [<condition>*] required
562 "columns": [<column>*] required
563 "until": "==" or "!=" required
564 "rows": [<row>*] required
566 Result object members:
572 Waits until a condition becomes true.
574 If "until" is "==", checks whether the query on "table" specified
575 by "where" and "columns", which is evaluated in the same way as
576 specified for "select", returns the result set specified by
577 "rows". If it does, then the operation completes successfully.
578 Otherwise, the entire transaction rolls back. It is automatically
579 restarted later, after a change in the database makes it possible
580 for the operation to succeed. The client will not receive a
581 response until the operation permanently succeeds or fails.
583 If "until" is "!=", the sense of the test is negated. That is, as
584 long as the query on "table" specified by "where" and "columns"
585 returns "rows", the transaction will be rolled back and restarted
588 If "timeout" is specified, then the transaction aborts after the
589 specified number of milliseconds. The transaction is guaranteed
590 to be attempted at least once before it aborts. A "timeout" of 0
591 will abort the transaction on the first mismatch.
595 "error": "not supported"
597 One or more of the columns in this table do not support
598 triggers. This error will not occur if "timeout" is 0.
602 The "timeout" was reached before the transaction was able to
608 Request object members:
610 "op": "commit" required
611 "durable": <boolean> required
613 Result object members:
619 If "durable" is specified as true, then the transaction, if it
620 commits, will be stored durably (to disk) before the reply is sent
625 "error": "not supported"
627 When "durable" is true, this database implementation does not
628 support durable commits.
633 Request object members:
635 "op": "abort" required
637 Result object members:
643 Aborts the transaction with an error. This may be useful for
650 This operation always fails with this error.