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 "columns" is a JSON object whose
68 names are column 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 an "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": "monitor" required
290 "params": [<value>, <monitor-requests>] required
291 "id": any JSON value except null required
293 <monitor-requests> is an object that maps from a table name to a
296 Each <monitor-request> is an object with the following members:
298 "columns": [<column>*] optional
299 "select": <monitor-select> optional
301 <monitor-select> is an object with the following members:
303 "initial": <boolean> optional
304 "insert": <boolean> optional
305 "delete": <boolean> optional
306 "modify": <boolean> optional
308 Response object members:
310 "result": <table-updates>
312 "id": same "id" as request
314 This JSON-RPC request enables a client to replicate tables or subsets
315 of tables. Each <monitor-request> specifies a table to be replicated.
316 The JSON-RPC response to the "monitor" includes the initial contents
317 of each table. Afterward, when changes to those tables are committed,
318 the changes are automatically sent to the client using the "update"
319 monitor notification. This monitoring persists until the JSON-RPC
320 session terminates or until the client sends a "monitor_cancel"
323 Each <monitor-request> describes how to monitor a table:
325 The circumstances in which an "update" notification is sent for a
326 row within the table are determined by <monitor-select>:
328 If "initial" is omitted or true, every row in the table is
329 sent as part of the reply to the "monitor" request.
331 If "insert" is omitted or true, "update" notifications are
332 sent for rows newly inserted into the table.
334 If "delete" is omitted or true, "update" notifications are
335 sent for rows deleted from the table.
337 If "modify" is omitted or true, "update" notifications are
338 sent whenever when a row in the table is modified.
340 The "columns" member specifies the columns whose values are
341 monitored. If "columns" is omitted, all columns in the table,
342 except for "_uuid", are monitored.
344 The "result" in the JSON-RPC response to the "monitor" request is a
345 <table-updates> object (see below) that contains the contents of the
346 tables for which "initial" rows are selected. If no tables' initial
347 contents are requested, then "result" is an empty object.
352 Notification object members:
355 "params": [<value>, <table-updates>]
358 The <value> in "params" is the same as the value passed as the <value>
359 in "params" for the "monitor" request.
361 <table-updates> is an object that maps from a table name to a
364 A <table-update> is an object that maps from the row's UUID (as a
365 36-byte string) to a <row-update> object.
367 A <row-update> is an object with the following members:
369 "old": <row> present for "delete" and "modify" updates
370 "new": <row> present for "initial", "insert", and "modify" updates
372 This JSON-RPC notification is sent from the server to the client to
373 tell it about changes to a monitored table (or the initial state of a
374 modified table). Each table in which one or more rows has changed (or
375 whose initial view is being presented) is represented in "updates".
376 Each row that has changed (or whose initial view is being presented)
377 is represented in its <table-update> as a member with its name taken
378 from the row's _uuid member. The corresponding value is a
381 The "old" member is present for "delete" and "modify" updates.
382 For "delete" updates, each monitored column is included. For
383 "modify" updates, the prior value of each monitored column whose
384 value has changed is included (monitored columns that have not
385 changed are represented in "new").
387 The "new" member is present for "initial", "insert", and "modify"
388 updates. For "initial" and "insert" updates, each monitored
389 column is included. For "modify" updates, the new value of each
390 monitored column is included.
395 Request object members:
397 "method": "monitor_cancel" required
398 "params": [<value>] required
399 "id": any JSON value except null required
401 Response object members:
405 "id": the request "id" member
407 Cancels the ongoing table monitor request, identified by the <value>
408 in "params" matching the <value> in "params" for an ongoing "monitor"
409 request. No more "update" messages will be sent for this table
415 Request object members:
417 "method": "echo" required
418 "params": JSON array with any contents required
419 "id": <value> required
421 Response object members:
423 "result": same as "params"
425 "id": the request "id" member
427 Both the JSON-RPC client and the server must implement this request.
429 This JSON-RPC request and response can be used to implement connection
430 keepalives, by allowing the server to check that the client is still
434 Notation for the Wire Protocol
435 ------------------------------
439 An <id> that names a table.
443 An <id> that names a table column.
447 A JSON object that describes a table row or a subset of a table
448 row. Each member is the name of a table column paired with the
449 <value> of that column.
453 A JSON value that represents the value of a column in a table row,
454 one of <atom>, a <set>, or a <map>.
458 A JSON value that represents a scalar value for a column, one of
459 <string>, <number>, <boolean>, <uuid>, <named-uuid>.
463 A 2-element JSON array that represents a database set value. The
464 first element of the array must be the string "set" and the second
465 element must be an array of zero or more <atom>s giving the values
466 in the set. All of the <atom>s must have the same type.
470 A 2-element JSON array that represents a database map value. The
471 first element of the array must be the string "map" and the second
472 element must be an array of zero or more <pair>s giving the values
473 in the map. All of the <pair>s must have the same key and value
476 (JSON objects are not used to represent <map> because JSON only
477 allows string names in an object.)
481 A 2-element JSON array that represents a pair within a database
482 map. The first element is an <atom> that represents the key, the
483 second element is an <atom> that represents the value.
487 A 2-element JSON array that represents a UUID. The first element
488 of the array must be the string "uuid" and the second element must
489 be a 36-character string giving the UUID in the format described
490 by RFC 4122. For example, the following <uuid> represents the
491 UUID 550e8400-e29b-41d4-a716-446655440000:
493 ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
497 A 2-element JSON array that represents the UUID of a row inserted
498 in a previous "insert" operation within the same transaction. The
499 first element of the array must be the string "named-uuid" and the
500 second element must be the string specified on this "insert"
501 operation's "uuid-name" or on a preceding "insert" within the same
502 transaction. For example, if this or a previous "insert"
503 operation specified a "uuid-name" of "myrow", the following
504 <named-uuid> represents the UUID created by that operation:
506 ["named-uuid", "myrow"]
508 A <named-uuid> may be used anywhere a <uuid> is valid.
512 A 3-element JSON array of the form [<column>, <function>,
513 <value>] that represents a test on a column value.
515 Except as otherwise specified below, <value> must have the same
518 The meaning depends on the type of <column>:
523 <function> must be "<", "<=", "==", "!=", ">=", ">",
524 "includes", or "excludes".
526 The test is true if the column's value satisfies the
527 relation <function> <value>, e.g. if the column has value
528 1 and <value> is 2, the test is true if <function> is "<",
529 "<=" or "!=", but not otherwise.
531 "includes" is equivalent to "=="; "excludes" is equivalent
538 <function> must be "!=", "==", "includes", or "excludes".
540 If <function> is "==" or "includes", the test is true if
541 the column's value equals <value>. If <function> is "!="
542 or "excludes", the test is inverted.
547 <function> must be "!=", "==", "includes", or "excludes".
549 If <function> is "==", the test is true if the column's
550 value contains exactly the same values (for sets) or pairs
551 (for maps). If <function> is "!=", the test is inverted.
553 If <function> is "includes", the test is true if the
554 column's value contains all of the values (for sets) or
555 pairs (for maps) in <value>. The column's value may also
556 contain other values or pairs.
558 If <function> is "excludes", the test is true if the
559 column's value does not contain any of the values (for
560 sets) or pairs (for maps) in <value>. The column's value
561 may contain other values or pairs not in <value>.
563 If <function> is "includes" or "excludes", then the
564 required type of <value> is slightly relaxed, in that it
565 may have fewer than the minimum number of elements
566 specified by the column's type. If <function> is
567 "excludes", then the required type is additionally relaxed
568 in that <value> may have more than the maximum number of
569 elements specified by the column's type.
573 One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
578 Each of the available operations is described below.
583 Request object members:
585 "op": "insert" required
586 "table": <table> required
587 "row": <row> required
588 "uuid-name": <string> optional
590 Result object members:
596 Inserts "row" into "table". If "row" does not specify values
597 for all the columns in "table", those columns receive default
600 The new row receives a new, randomly generated UUID, which is
601 returned as the "uuid" member of the result. If "uuid-name" is
602 supplied, then the UUID is made available under that name to this
603 operation and later operations within the same transaction.
608 Request object members:
610 "op": "select" required
611 "table": <table> required
612 "where": [<condition>*] required
613 "columns": [<column>*] optional
615 Result object members:
621 Searches "table" for rows that match all the conditions specified
622 in "where". If "where" is an empty array, every row in "table" is
625 The "rows" member of the result is an array of objects. Each
626 object corresponds to a matching row, with each column
627 specified in "columns" as a member, the column's name as the
628 member name and its value as the member value. If "columns"
629 is not specified, all the table's columns are included. If
630 two rows of the result have the same values for all included
631 columns, only one copy of that row is included in "rows".
632 Specifying "_uuid" within "columns" will avoid dropping
633 duplicates, since every row has a unique UUID.
635 The ordering of rows within "rows" is unspecified.
640 Request object members:
642 "op": "update" required
643 "table": <table> required
644 "where": [<condition>*] required
645 "row": <row> required
647 Result object members:
653 Updates rows in a table.
655 Searches "table" for rows that match all the conditions
656 specified in "where". For each matching row, changes the
657 value of each column specified in "row" to the value for that
658 column specified in "row".
660 The "_uuid" and "_version" columns of a table may not be directly
661 updated with this operation. Columns designated read-only in the
662 schema also may not be updated.
664 The "count" member of the result specifies the number of rows
670 Request object members:
672 "op": "delete" required
673 "table": <table> required
674 "where": [<condition>*] required
676 Result object members:
682 Deletes all the rows from "table" that match all the conditions
683 specified in "where".
685 The "count" member of the result specifies the number of deleted
691 Request object members:
693 "op": "wait" required
694 "timeout": <integer> optional
695 "table": <table> required
696 "where": [<condition>*] required
697 "columns": [<column>*] required
698 "until": "==" or "!=" required
699 "rows": [<row>*] required
701 Result object members:
707 Waits until a condition becomes true.
709 If "until" is "==", checks whether the query on "table" specified
710 by "where" and "columns", which is evaluated in the same way as
711 specified for "select", returns the result set specified by
712 "rows". If it does, then the operation completes successfully.
713 Otherwise, the entire transaction rolls back. It is automatically
714 restarted later, after a change in the database makes it possible
715 for the operation to succeed. The client will not receive a
716 response until the operation permanently succeeds or fails.
718 If "until" is "!=", the sense of the test is negated. That is, as
719 long as the query on "table" specified by "where" and "columns"
720 returns "rows", the transaction will be rolled back and restarted
723 If "timeout" is specified, then the transaction aborts after the
724 specified number of milliseconds. The transaction is guaranteed
725 to be attempted at least once before it aborts. A "timeout" of 0
726 will abort the transaction on the first mismatch.
730 "error": "not supported"
732 One or more of the columns in this table do not support
733 triggers. This error will not occur if "timeout" is 0.
737 The "timeout" was reached before the transaction was able to
743 Request object members:
745 "op": "commit" required
746 "durable": <boolean> required
748 Result object members:
754 If "durable" is specified as true, then the transaction, if it
755 commits, will be stored durably (to disk) before the reply is sent
760 "error": "not supported"
762 When "durable" is true, this database implementation does not
763 support durable commits.
768 Request object members:
770 "op": "abort" required
772 Result object members:
778 Aborts the transaction with an error. This may be useful for
785 This operation always fails with this error.