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.
13 A JSON string. Any Unicode string is allowed, as specified by RFC
14 4627. Implementations may disallowed null bytes.
18 A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*.
20 <id>s that begin with _ are reserved to the implementation and may
21 not be used by the user.
25 A JSON true or false value.
33 A JSON number with an integer value, within a certain range
34 (currently -2**63...+2**63-1).
43 An Open vSwitch configuration database consists of a set of tables,
44 each of which has a number of columns and zero or more rows. A schema
45 is represented by <database-schema>, as described below.
49 A JSON object with the following members:
52 "comment": <string> optional
53 "tables": {<id>: <table-schema>, ...} required
55 The "name" identifies the database as a whole. The "comment"
56 optionally provides more information about the database. The
57 value of "tables" is a JSON object whose names are table names and
58 whose values are <table-schema>s.
62 A JSON object with the following members:
64 "comment": <string> optional
65 "columns": {<id>: <column-schema>, ...} required
67 The "comment" optionally provides information about this table for
68 a human reader. The value of "columns" is a JSON object whose
69 names are column names and whose values are <column-schema>s.
71 Every table has the following columns whose definitions are not
72 included in the schema:
74 "_uuid": This column, which contains exactly one UUID value,
75 is initialized to a random value by the database engine when
76 it creates a row. It is read-only, and its value never
77 changes during the lifetime of a row.
79 "_version": Like "_uuid", this column contains exactly one
80 UUID value, initialized to a random value by the database
81 engine when it creates a row, and it is read-only. However,
82 its value changes to a new random value whenever any other
83 field in the row changes. Furthermore, its value is
84 ephemeral: when the database is closed and reopened, or when
85 the database process is stopped and then started again, each
86 "_version" also changes to a new random value.
90 A JSON object with the following members:
92 "comment": <string> optional
93 "type": <type> required
94 "ephemeral": <boolean> optional
96 The "comment" optionally provides information about this column
97 for a human reader. The "type" specifies the type of data stored
98 in this column. If "ephemeral" is specified as true, then this
99 column's values are not guaranteed to be durable; they may be lost
100 when the database restarts.
104 The type of a database column. Either an <atomic-type> or a JSON
105 object that describes the type of a database column, with the
108 "key": <atomic-type> required
109 "value": <atomic-type> optional
110 "min": <integer> optional
111 "max": <integer> or "unlimited" optional
113 If "min" or "max" is not specified, each defaults to 1. If "max"
114 is specified as "unlimited", then there is no specified maximum
115 number of elements, although the implementation will enforce some
116 limit. After considering defaults, "min" must be at least 0,
117 "max" must be at least 1, and "max" must be greater than or equal
120 If "min" and "max" are both 1 and "value" is not specified, the
121 type is the scalar type specified by "key".
123 If "min" is not 1 or "max" is not 1, or both, and "value" is not
124 specified, the type is a set of scalar type "key".
126 If "value" is specified, the type is a map from type "key" to type
131 One of the strings "integer", "real", "boolean", "string", or
132 "uuid", representing the specified scalar type.
137 The database wire protocol is implemented in JSON-RPC 1.0. We
138 encourage use of JSON-RPC over stream connections instead of JSON-RPC
139 over HTTP, for these reasons:
141 * JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server
142 protocol, which is a poor match. Thus, JSON-RPC over HTTP
143 requires the client to periodically poll the server to receive
146 * HTTP is more complicated than stream connections and doesn't
147 provide any corresponding advantage.
149 * The JSON-RPC specification for HTTP transport is incomplete.
151 The database wire protocol consists of the following JSON-RPC methods:
156 Request object members:
158 "method": "get_schema" required
159 "params": [] required
160 "id": any JSON value except null required
162 Response object members:
164 "result": <database-schema>
166 "id": same "id" as request
168 This operation retrieves a <database-schema> that describes the
174 Request object members:
176 "method": "transact" required
177 "params": [<operation>*] required
178 "id": any JSON value except null required
180 Response object members:
182 "result": [<object>*]
184 "id": same "id" as request
186 The "params" array for this method consists of zero or more JSON
187 objects, each of which represents a single database operation. The
188 "Operations" section below describes the valid operations.
190 The value of "id" must be unique among all in-flight transactions
191 within the current JSON-RPC session. Otherwise, the server may return
194 The database server executes each of the specified operations in the
195 specified order, except that if an operation fails, then the remaining
196 operations are not executed.
198 The set of operations is executed as a single atomic, consistent,
199 isolated transaction. The transaction is committed only if every
200 operation succeeds. Durability of the commit is not guaranteed unless
201 the "commit" operation, with "durable" set to true, is included in the
202 operation set (see below).
204 Regardless of whether errors occur, the response is always a JSON-RPC
205 response with null "error" and a "result" member that is an array with
206 the same number of elements as "params". Each element of the "result"
207 array corresponds to the same element of the "params" array. The
208 "result" array elements may be interpreted as follows:
210 - A JSON object that does not contain an "error" member indicates
211 that the operation completed successfully. The specific members
212 of the object are specified below in the descriptions of
213 individual operations. Some operations do not produce any
214 results, in which case the object will have no members.
216 - A JSON object that contains an "error" member indicates that the
217 operation completed with an error. The value of the "error"
218 member is a short string, specified in this document, that
219 broadly indicates the class of the error. Besides the ones
220 listed for a specific operation, any operation may result in one
221 the following "error"s:
223 "error": "resources exhausted"
225 The operation or the transaction requires more resources
226 (memory, disk, CPU, etc.) than are currently available to
229 "error": "syntax error"
231 The operation is not specified correctly: a required request
232 object member is missing, an unknown or unsupported request
233 object member is present, the operation attempts to act on a
234 table that does not exist, the operation modifies a
235 read-only table column, etc.
237 Database implementations may use "error" strings not specified
238 in this document to indicate errors that do not fit into any of
239 the specified categories.
241 Optionally, the object may include a "details" member, whose
242 value is a string that describes the error in more detail for
243 the benefit of a human user or administrator. The object may
244 also have other members that describe the error in more detail.
245 This document does not specify the names or values of these
248 - A JSON null value indicates that the operation was not attempted
249 because a prior operation failed.
251 In general, "result" contains some number of successful results,
252 possibly followed by an error, in turn followed by enough JSON null
253 values to match the number of elements in "params". There is one
254 exception: if all of the operations succeed, but the results cannot be
255 committed (e.g. due to I/O errors), then "result" will have one more
256 element than "params", with the additional element describing the
259 If "params" contains one or more "wait" operations, then the
260 transaction may take an arbitrary amount of time to complete. The
261 database implementation must be capable of accepting, executing, and
262 replying to other transactions and other JSON-RPC requests while a
263 transaction or transactions containing "wait" operations are
264 outstanding on the same or different JSON-RPC sessions.
266 The section "Notation for the Wire Protocol" below describes
267 additional notation for use with the wire protocol. After that, the
268 "Operations" section describes each operation.
273 Request object members:
275 "method": "cancel" required
276 "params": [the "id" for an outstanding request] required
279 Response object members:
283 This JSON-RPC notification instructs the database server to
284 immediately complete or cancel the "transact" request whose "id" is
285 the same as the notification's "params" value.
287 If the "transact" request can be completed immediately, then the
288 server sends a response in the form described for "transact", above.
289 Otherwise, the server sends a JSON-RPC error response of the following
294 "id": the request "id" member
296 The "cancel" notification itself has no reply.
301 Request object members:
303 "method": "monitor" required
304 "params": [<value>, <monitor-requests>] required
305 "id": any JSON value except null required
307 <monitor-requests> is an object that maps from a table name to a
310 Each <monitor-request> is an object with the following members:
312 "columns": [<column>*] optional
313 "select": <monitor-select> optional
315 <monitor-select> is an object with the following members:
317 "initial": <boolean> optional
318 "insert": <boolean> optional
319 "delete": <boolean> optional
320 "modify": <boolean> optional
322 Response object members:
324 "result": <table-updates>
326 "id": same "id" as request
328 This JSON-RPC request enables a client to replicate tables or subsets
329 of tables. Each <monitor-request> specifies a table to be replicated.
330 The JSON-RPC response to the "monitor" includes the initial contents
331 of each table. Afterward, when changes to those tables are committed,
332 the changes are automatically sent to the client using the "update"
333 monitor notification. This monitoring persists until the JSON-RPC
334 session terminates or until the client sends a "monitor_cancel"
337 Each <monitor-request> describes how to monitor a table:
339 The circumstances in which an "update" notification is sent for a
340 row within the table are determined by <monitor-select>:
342 If "initial" is omitted or true, every row in the table is
343 sent as part of the reply to the "monitor" request.
345 If "insert" is omitted or true, "update" notifications are
346 sent for rows newly inserted into the table.
348 If "delete" is omitted or true, "update" notifications are
349 sent for rows deleted from the table.
351 If "modify" is omitted or true, "update" notifications are
352 sent whenever when a row in the table is modified.
354 The "columns" member specifies the columns whose values are
355 monitored. If "columns" is omitted, all columns in the table,
356 except for "_uuid", are monitored.
358 The "result" in the JSON-RPC response to the "monitor" request is a
359 <table-updates> object (see below) that contains the contents of the
360 tables for which "initial" rows are selected. If no tables' initial
361 contents are requested, then "result" is an empty object.
366 Notification object members:
369 "params": [<value>, <table-updates>]
372 The <value> in "params" is the same as the value passed as the <value>
373 in "params" for the "monitor" request.
375 <table-updates> is an object that maps from a table name to a
378 A <table-update> is an object that maps from the row's UUID (as a
379 36-byte string) to a <row-update> object.
381 A <row-update> is an object with the following members:
383 "old": <row> present for "delete" and "modify" updates
384 "new": <row> present for "initial", "insert", and "modify" updates
386 This JSON-RPC notification is sent from the server to the client to
387 tell it about changes to a monitored table (or the initial state of a
388 modified table). Each table in which one or more rows has changed (or
389 whose initial view is being presented) is represented in "updates".
390 Each row that has changed (or whose initial view is being presented)
391 is represented in its <table-update> as a member with its name taken
392 from the row's _uuid member. The corresponding value is a
395 The "old" member is present for "delete" and "modify" updates.
396 For "delete" updates, each monitored column is included. For
397 "modify" updates, the prior value of each monitored column whose
398 value has changed is included (monitored columns that have not
399 changed are represented in "new").
401 The "new" member is present for "initial", "insert", and "modify"
402 updates. For "initial" and "insert" updates, each monitored
403 column is included. For "modify" updates, the new value of each
404 monitored column is included.
409 Request object members:
411 "method": "monitor_cancel" required
412 "params": [<value>] required
413 "id": any JSON value except null required
415 Response object members:
419 "id": the request "id" member
421 Cancels the ongoing table monitor request, identified by the <value>
422 in "params" matching the <value> in "params" for an ongoing "monitor"
423 request. No more "update" messages will be sent for this table
429 Request object members:
431 "method": "echo" required
432 "params": JSON array with any contents required
433 "id": <value> required
435 Response object members:
437 "result": same as "params"
439 "id": the request "id" member
441 Both the JSON-RPC client and the server must implement this request.
443 This JSON-RPC request and response can be used to implement connection
444 keepalives, by allowing the server to check that the client is still
448 Notation for the Wire Protocol
449 ------------------------------
453 An <id> that names a table.
457 An <id> that names a table column.
461 A JSON object that describes a table row or a subset of a table
462 row. Each member is the name of a table column paired with the
463 <value> of that column.
467 A JSON value that represents the value of a column in a table row,
468 one of <atom>, a <set>, or a <map>.
472 A JSON value that represents a scalar value for a column, one of
473 <string>, <number>, <boolean>, <uuid>, <named-uuid>.
477 A 2-element JSON array that represents a database set value. The
478 first element of the array must be the string "set" and the second
479 element must be an array of zero or more <atom>s giving the values
480 in the set. All of the <atom>s must have the same type.
484 A 2-element JSON array that represents a database map value. The
485 first element of the array must be the string "map" and the second
486 element must be an array of zero or more <pair>s giving the values
487 in the map. All of the <pair>s must have the same key and value
490 (JSON objects are not used to represent <map> because JSON only
491 allows string names in an object.)
495 A 2-element JSON array that represents a pair within a database
496 map. The first element is an <atom> that represents the key, the
497 second element is an <atom> that represents the value.
501 A 2-element JSON array that represents a UUID. The first element
502 of the array must be the string "uuid" and the second element must
503 be a 36-character string giving the UUID in the format described
504 by RFC 4122. For example, the following <uuid> represents the
505 UUID 550e8400-e29b-41d4-a716-446655440000:
507 ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
511 A 2-element JSON array that represents the UUID of a row inserted
512 in a previous "insert" operation within the same transaction. The
513 first element of the array must be the string "named-uuid" and the
514 second element must be the string specified on this "insert"
515 operation's "uuid-name" or on a preceding "insert" within the same
516 transaction. For example, if this or a previous "insert"
517 operation specified a "uuid-name" of "myrow", the following
518 <named-uuid> represents the UUID created by that operation:
520 ["named-uuid", "myrow"]
522 A <named-uuid> may be used anywhere a <uuid> is valid.
526 A 3-element JSON array of the form [<column>, <function>,
527 <value>] that represents a test on a column value.
529 Except as otherwise specified below, <value> must have the same
532 The meaning depends on the type of <column>:
537 <function> must be "<", "<=", "==", "!=", ">=", ">",
538 "includes", or "excludes".
540 The test is true if the column's value satisfies the
541 relation <function> <value>, e.g. if the column has value
542 1 and <value> is 2, the test is true if <function> is "<",
543 "<=" or "!=", but not otherwise.
545 "includes" is equivalent to "=="; "excludes" is equivalent
552 <function> must be "!=", "==", "includes", or "excludes".
554 If <function> is "==" or "includes", the test is true if
555 the column's value equals <value>. If <function> is "!="
556 or "excludes", the test is inverted.
561 <function> must be "!=", "==", "includes", or "excludes".
563 If <function> is "==", the test is true if the column's
564 value contains exactly the same values (for sets) or pairs
565 (for maps). If <function> is "!=", the test is inverted.
567 If <function> is "includes", the test is true if the
568 column's value contains all of the values (for sets) or
569 pairs (for maps) in <value>. The column's value may also
570 contain other values or pairs.
572 If <function> is "excludes", the test is true if the
573 column's value does not contain any of the values (for
574 sets) or pairs (for maps) in <value>. The column's value
575 may contain other values or pairs not in <value>.
577 If <function> is "includes" or "excludes", then the
578 required type of <value> is slightly relaxed, in that it
579 may have fewer than the minimum number of elements
580 specified by the column's type. If <function> is
581 "excludes", then the required type is additionally relaxed
582 in that <value> may have more than the maximum number of
583 elements specified by the column's type.
587 One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
592 Each of the available operations is described below.
597 Request object members:
599 "op": "insert" required
600 "table": <table> required
601 "row": <row> required
602 "uuid-name": <string> optional
604 Result object members:
610 Inserts "row" into "table". If "row" does not specify values
611 for all the columns in "table", those columns receive default
614 The new row receives a new, randomly generated UUID, which is
615 returned as the "uuid" member of the result. If "uuid-name" is
616 supplied, then the UUID is made available under that name to this
617 operation and later operations within the same transaction.
622 Request object members:
624 "op": "select" required
625 "table": <table> required
626 "where": [<condition>*] required
627 "columns": [<column>*] optional
629 Result object members:
635 Searches "table" for rows that match all the conditions specified
636 in "where". If "where" is an empty array, every row in "table" is
639 The "rows" member of the result is an array of objects. Each
640 object corresponds to a matching row, with each column
641 specified in "columns" as a member, the column's name as the
642 member name and its value as the member value. If "columns"
643 is not specified, all the table's columns are included. If
644 two rows of the result have the same values for all included
645 columns, only one copy of that row is included in "rows".
646 Specifying "_uuid" within "columns" will avoid dropping
647 duplicates, since every row has a unique UUID.
649 The ordering of rows within "rows" is unspecified.
654 Request object members:
656 "op": "update" required
657 "table": <table> required
658 "where": [<condition>*] required
659 "row": <row> required
661 Result object members:
667 Updates rows in a table.
669 Searches "table" for rows that match all the conditions
670 specified in "where". For each matching row, changes the
671 value of each column specified in "row" to the value for that
672 column specified in "row".
674 The "_uuid" and "_version" columns of a table may not be directly
675 updated with this operation. Columns designated read-only in the
676 schema also may not be updated.
678 The "count" member of the result specifies the number of rows
684 Request object members:
686 "op": "delete" required
687 "table": <table> required
688 "where": [<condition>*] required
690 Result object members:
696 Deletes all the rows from "table" that match all the conditions
697 specified in "where".
699 The "count" member of the result specifies the number of deleted
705 Request object members:
707 "op": "wait" required
708 "timeout": <integer> optional
709 "table": <table> required
710 "where": [<condition>*] required
711 "columns": [<column>*] required
712 "until": "==" or "!=" required
713 "rows": [<row>*] required
715 Result object members:
721 Waits until a condition becomes true.
723 If "until" is "==", checks whether the query on "table" specified
724 by "where" and "columns", which is evaluated in the same way as
725 specified for "select", returns the result set specified by
726 "rows". If it does, then the operation completes successfully.
727 Otherwise, the entire transaction rolls back. It is automatically
728 restarted later, after a change in the database makes it possible
729 for the operation to succeed. The client will not receive a
730 response until the operation permanently succeeds or fails.
732 If "until" is "!=", the sense of the test is negated. That is, as
733 long as the query on "table" specified by "where" and "columns"
734 returns "rows", the transaction will be rolled back and restarted
737 If "timeout" is specified, then the transaction aborts after the
738 specified number of milliseconds. The transaction is guaranteed
739 to be attempted at least once before it aborts. A "timeout" of 0
740 will abort the transaction on the first mismatch.
744 "error": "not supported"
746 One or more of the columns in this table do not support
747 triggers. This error will not occur if "timeout" is 0.
751 The "timeout" was reached before the transaction was able to
757 Request object members:
759 "op": "commit" required
760 "durable": <boolean> required
762 Result object members:
768 If "durable" is specified as true, then the transaction, if it
769 commits, will be stored durably (to disk) before the reply is sent
774 "error": "not supported"
776 When "durable" is true, this database implementation does not
777 support durable commits.
782 Request object members:
784 "op": "abort" required
786 Result object members:
792 Aborts the transaction with an error. This may be useful for
799 This operation always fails with this error.