forked from openvswitch/ovs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathSPECS
1320 lines (925 loc) · 44.2 KB
/
SPECS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
===================================================
Open vSwitch Configuration Database Specification
===================================================
Basic Notation
--------------
OVSDB uses JSON, as defined by RFC 4627, for its schema format and its
wire protocol format. The JSON implementation in Open vSwitch has the
following limitations:
- Null bytes (\u0000) are not allowed in strings.
- Only UTF-8 encoding is supported. (RFC 4627 also mentions
UTF-16BE, UTF-16LE, and UTF-32.)
- RFC 4627 says that names within a JSON object should be unique.
The Open vSwitch JSON parser discards all but the last value
for a name that is specified more than once.
The descriptions below use the following shorthand notations for JSON
values. Additional notation is presented later.
<string>
A JSON string. Any Unicode string is allowed, as specified by RFC
4627. Implementations may disallow null bytes.
<id>
A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*.
<id>s that begin with _ are reserved to the implementation and may
not be used by the user.
<version>
A JSON string that contains a version number that matches
[0-9]+\.[0-9]+\.[0-9]+
<boolean>
A JSON true or false value.
<number>
A JSON number.
<integer>
A JSON number with an integer value, within a certain range
(currently -2**63...+2**63-1).
<json-value>
Any JSON value.
<nonnull-json-value>
Any JSON value except null.
<error>
A JSON object with the following members:
"error": <string> required
"details": <string> optional
The value of the "error" member is a short string, specified in
this document, that broadly indicates the class of the error.
Most "error" strings are specific to contexts described elsewhere
in this document, but the following "error" strings may appear in
any context where an <error> is permitted:
"error": "resources exhausted"
The operation requires more resources (memory, disk, CPU,
etc.) than are currently available to the database server.
"error": "I/O error"
Problems accessing the disk, network, or other required
resources prevented the operation from completing.
Database implementations may use "error" strings not specified
in this document to indicate errors that do not fit into any of
the specified categories.
Optionally, an <error> may include a "details" member, whose value
is a string that describes the error in more detail for the
benefit of a human user or administrator. This document does not
specify the format or content of the "details" string.
An <error> may also have other members that describe the error in
more detail. This document does not specify the names or values
of these members.
Schema Format
-------------
An Open vSwitch configuration database consists of a set of tables,
each of which has a number of columns and zero or more rows. A schema
is represented by <database-schema>, as described below.
<database-schema>
A JSON object with the following members:
"name": <id> required
"version": <version> required
"cksum": <string> optional
"tables": {<id>: <table-schema>, ...} required
The "name" identifies the database as a whole. It must be
provided to most JSON-RPC requests to identify the database being
operated on. The value of "tables" is a JSON object whose names
are table names and whose values are <table-schema>s.
The "version" reports the version of the database schema. Because
this is a recent addition to the schema format, OVSDB permits it
to be omitted, but future versions of OVSDB will require it to be
present. Open vSwitch semantics for "version" are described in
ovs-vswitchd.conf.db(5).
The "cksum" optionally reports an implementation-defined checksum
for the database schema.
<table-schema>
A JSON object with the following members:
"columns": {<id>: <column-schema>, ...} required
"maxRows": <integer> optional
"isRoot": <boolean> optional
"indexes": [<column-set>*] optional
The value of "columns" is a JSON object whose names are column
names and whose values are <column-schema>s.
Every table has the following columns whose definitions are not
included in the schema:
"_uuid": This column, which contains exactly one UUID value,
is initialized to a random value by the database engine when
it creates a row. It is read-only, and its value never
changes during the lifetime of a row.
"_version": Like "_uuid", this column contains exactly one
UUID value, initialized to a random value by the database
engine when it creates a row, and it is read-only. However,
its value changes to a new random value whenever any other
field in the row changes. Furthermore, its value is
ephemeral: when the database is closed and reopened, or when
the database process is stopped and then started again, each
"_version" also changes to a new random value.
If "isRoot" is omitted or specified as false, then any given row
in the table may exist only when there is at least one reference
to it, with refType "strong", from a different row (in the same
table or a different table). This is a "deferred" action:
unreferenced rows in the table are deleted just before transaction
commit. If "isRoot" is specified as true, then rows in the table
exist independent of any references (they can be thought of as
part of the "root set" in a garbage collector).
For compatibility with schemas created before "isRoot" was
introduced, if "isRoot" is omitted or false in every
<table-schema> in a given <database-schema>, then every table is
part of the root set.
If "maxRows" is specified, as a positive integer, it limits the
maximum number of rows that may be present in the table. This is
a "deferred" constraint, enforced only at transaction commit time
(see the "transact" request below). If "maxRows" is not
specified, the size of the table is limited only by the resources
available to the database server. "maxRows" constraints are
enforced after unreferenced rows are deleted from tables with a
false "isRoot".
If "indexes" is specified, it must be an array of zero or more
<column-set>s. A <column-set> is an array of one or more strings,
each of which names a column. Each <column-set> is a set of
columns whose values, taken together within any given row, must be
unique within the table. This is a "deferred" constraint,
enforced only at transaction commit time, after unreferenced rows
are deleted and dangling weak references are removed. Ephemeral
columns may not be part of indexes.
<column-schema>
A JSON object with the following members:
"type": <type> required
"ephemeral": <boolean> optional
"mutable": <boolean> optional
The "type" specifies the type of data stored in this column.
If "ephemeral" is specified as true, then this column's values are
not guaranteed to be durable; they may be lost when the database
restarts. A column whose type (either key or value) is a strong
reference to a table that is not part of the root set is always
durable, regardless of this value. (Otherwise, restarting the
database could lose entire rows.)
If "mutable" is specified as false, then this column's values may
not be modified after they are initially set with the "insert"
operation.
<type>
The type of a database column. Either an <atomic-type> or a JSON
object that describes the type of a database column, with the
following members:
"key": <base-type> required
"value": <base-type> optional
"min": <integer> optional
"max": <integer> or "unlimited" optional
If "min" or "max" is not specified, each defaults to 1. If "max"
is specified as "unlimited", then there is no specified maximum
number of elements, although the implementation will enforce some
limit. After considering defaults, "min" must be exactly 0 or
exactly 1, "max" must be at least 1, and "max" must be greater
than or equal to "min".
If "min" and "max" are both 1 and "value" is not specified, the
type is the scalar type specified by "key".
If "min" is not 1 or "max" is not 1, or both, and "value" is not
specified, the type is a set of scalar type "key".
If "value" is specified, the type is a map from type "key" to type
"value".
<base-type>
The type of a key or value in a database column. Either an
<atomic-type> or a JSON object with the following members:
"type": <atomic-type> required
"enum": <value> optional
"minInteger": <integer> optional, integers only
"maxInteger": <integer> optional, integers only
"minReal": <real> optional, reals only
"maxReal": <real> optional, reals only
"minLength": <integer> optional, strings only
"maxLength": <integer> optional, strings only
"refTable": <id> optional, uuids only
"refType": "strong" or "weak" optional, only with "refTable"
An <atomic-type> by itself is equivalent to a JSON object with a
single member "type" whose value is the <atomic-type>.
"enum" may be specified as a <value> whose type is a set of one
or more values specified for the member "type". If "enum" is
specified, then the valid values of the <base-type> are limited to
those in the <value>.
"enum" is mutually exclusive with the following constraints.
If "type" is "integer", then "minInteger" or "maxInteger" or both
may also be specified, restricting the valid integer range. If
both are specified, then the maxInteger must be greater than or
equal to minInteger.
If "type" is "real", then "minReal" or "maxReal" or both may also
be specified, restricting the valid real range. If both are
specified, then the maxReal must be greater than or equal to
minReal.
If "type" is "string", then "minLength" and "maxLength" or both
may be specified, restricting the valid length of value strings.
If both are specified, then maxLength must be greater than or
equal to minLength. String length is measured in characters (not
bytes or UTF-16 code units).
If "type" is "uuid", then "refTable", if present, must be the name
of a table within this database. If "refTable" is specified, then
"refType" may also be specified. If "refTable" is set, the effect
depends on "refType":
- If "refType" is "strong" or if "refType" is omitted, the
allowed UUIDs are limited to UUIDs for rows in the named
table.
- If "refType" is "weak", then any UUIDs are allowed, but
UUIDs that do not correspond to rows in the named table will
be automatically deleted.
"refTable" constraints are "deferred" constraints: they are
enforced only at transaction commit time (see the "transact"
request below). The other contraints on <base-type> are
"immediate", enforced immediately by each operation.
<atomic-type>
One of the strings "integer", "real", "boolean", "string", or
"uuid", representing the specified scalar type.
Wire Protocol
-------------
The database wire protocol is implemented in JSON-RPC 1.0. We
encourage use of JSON-RPC over stream connections instead of JSON-RPC
over HTTP, for these reasons:
* JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server
protocol, which is a poor match. Thus, JSON-RPC over HTTP
requires the client to periodically poll the server to receive
server requests.
* HTTP is more complicated than stream connections and doesn't
provide any corresponding advantage.
* The JSON-RPC specification for HTTP transport is incomplete.
We are currently using TCP port 6632 for the database JSON-RPC
connection, but future versions will switch to using IANA-assigned TCP
port 6640.
The database wire protocol consists of the following JSON-RPC methods:
list_dbs
........
Request object members:
"method": "list_dbs" required
"params": [] required
"id": <nonnull-json-value> required
Response object members:
"result": [<db-name>, ...]
"error": null
"id": same "id" as request
This operation retrieves an array whose elements are <db-name>s
that name the databases that can be accessed over this JSON-RPC
connection.
get_schema
..........
Request object members:
"method": "get_schema" required
"params": [<db-name>] required
"id": <nonnull-json-value> required
Response object members:
"result": <database-schema>
"error": null
"id": same "id" as request
This operation retrieves a <database-schema> that describes hosted
database <db-name>.
transact
........
Request object members:
"method": "transact" required
"params": [<db-name>, <operation>*] required
"id": <nonnull-json-value> required
Response object members:
"result": [<object>*]
"error": null
"id": same "id" as request
The "params" array for this method consists of a <db-name> that
identifies the database to which the transaction applies, followed by
zero or more JSON objects, each of which represents a single database
operation. The "Operations" section below describes the valid
operations.
The value of "id" must be unique among all in-flight transactions
within the current JSON-RPC session. Otherwise, the server may return
a JSON-RPC error.
The database server executes each of the specified operations in the
specified order, except that if an operation fails, then the remaining
operations are not executed.
The set of operations is executed as a single atomic, consistent,
isolated transaction. The transaction is committed only if every
operation succeeds. Durability of the commit is not guaranteed unless
the "commit" operation, with "durable" set to true, is included in the
operation set (see below).
Regardless of whether errors occur, the response is always a JSON-RPC
response with null "error" and a "result" member that is an array with
the same number of elements as "params". Each element of the "result"
array corresponds to the same element of the "params" array. The
"result" array elements may be interpreted as follows:
- A JSON object that does not contain an "error" member indicates
that the operation completed successfully. The specific members
of the object are specified below in the descriptions of
individual operations. Some operations do not produce any
results, in which case the object will have no members.
- An <error>, which indicates that the operation completed with an
error.
- A JSON null value indicates that the operation was not attempted
because a prior operation failed.
In general, "result" contains some number of successful results,
possibly followed by an error, in turn followed by enough JSON null
values to match the number of elements in "params". There is one
exception: if all of the operations succeed, but the results cannot be
committed, then "result" will have one more element than "params",
with the additional element an <error>. The possible "error" strings
include at least the following:
"error": "referential integrity violation"
When the commit was attempted, a column's value referenced the
UUID for a row that did not exist in the table named by the
column's <base-type> key or value "refTable" that has a
"refType" of "strong". (This can be caused by inserting a row
that references a nonexistent row, by deleting a row that is
still referenced by another row, by specifying the UUID for a
row in the wrong table, and other ways.)
"error": "constraint violation"
A column with a <base-type> key or value "refTable" whose
"refType" is "weak" became empty due to deletion(s) caused
because the rows that it referenced were deleted (or never
existed, if the column's row was inserted within the
transaction), and this column is not allowed to be empty
because its <type> has a "min" of 1.
"error": "constraint violation"
The number of rows in a table exceeds the maximum number
permitted by the table's "maxRows" value (see <table-schema>).
"error": "constraint violation"
Two or more rows in a table had the same values in the columns
that comprise an index.
"error": "resources exhausted"
"error": "I/O error"
As described in the definition of <error> above.
If "params" contains one or more "wait" operations, then the
transaction may take an arbitrary amount of time to complete. The
database implementation must be capable of accepting, executing, and
replying to other transactions and other JSON-RPC requests while a
transaction or transactions containing "wait" operations are
outstanding on the same or different JSON-RPC sessions.
The section "Notation for the Wire Protocol" below describes
additional notation for use with the wire protocol. After that, the
"Operations" section describes each operation.
cancel
......
Request object members:
"method": "cancel" required
"params": [the "id" for an outstanding request] required
"id": null required
Response object members:
<no response>
This JSON-RPC notification instructs the database server to
immediately complete or cancel the "transact" request whose "id" is
the same as the notification's "params" value.
If the "transact" request can be completed immediately, then the
server sends a response in the form described for "transact", above.
Otherwise, the server sends a JSON-RPC error response of the following
form:
"result": null
"error": "canceled"
"id": the request "id" member
The "cancel" notification itself has no reply.
monitor
.......
Request object members:
"method": "monitor" required
"params": [<db-name>, <json-value>, <monitor-requests>] required
"id": <nonnull-json-value> required
<monitor-requests> is an object that maps from a table name to an
array of <monitor-request> objects. For backward compatibility, a
single <monitor-request> may be used instead of an array; it is
treated as a single-element array.
Each <monitor-request> is an object with the following members:
"columns": [<column>*] optional
"select": <monitor-select> optional
<monitor-select> is an object with the following members:
"initial": <boolean> optional
"insert": <boolean> optional
"delete": <boolean> optional
"modify": <boolean> optional
Response object members:
"result": <table-updates>
"error": null
"id": same "id" as request
This JSON-RPC request enables a client to replicate tables or subsets
of tables within database <db-name>. Each element of
<monitor-requests> specifies a table to be replicated. The JSON-RPC
response to the "monitor" includes the initial contents of each table,
unless disabled (see below). Afterward, when changes to those tables
are committed, the changes are automatically sent to the client using
the "update" monitor notification. This monitoring persists until the
JSON-RPC session terminates or until the client sends a
"monitor_cancel" JSON-RPC request.
Each <monitor-request> describes how to monitor columns in a table:
The circumstances in which an "update" notification is sent for a
row within the table are determined by <monitor-select>:
If "initial" is omitted or true, every row in the table is
sent as part of the reply to the "monitor" request.
If "insert" is omitted or true, "update" notifications are
sent for rows newly inserted into the table.
If "delete" is omitted or true, "update" notifications are
sent for rows deleted from the table.
If "modify" is omitted or true, "update" notifications are
sent whenever when a row in the table is modified.
The "columns" member specifies the columns whose values are
monitored. It must not contain duplicates. If "columns" is
omitted, all columns in the table, except for "_uuid", are
monitored.
If there is more than one <monitor-request> in an array of them, then
each <monitor-request> in the array should specify both "columns" and
"select", and the "columns" must be non-overlapping sets.
The "result" in the JSON-RPC response to the "monitor" request is a
<table-updates> object (see below) that contains the contents of the
tables for which "initial" rows are selected. If no tables' initial
contents are requested, then "result" is an empty object.
update
......
Notification object members:
"method": "update"
"params": [<json-value>, <table-updates>]
"id": null
The <json-value> in "params" is the same as the value passed as the
<json-value> in "params" for the "monitor" request.
<table-updates> is an object that maps from a table name to a
<table-update>.
A <table-update> is an object that maps from the row's UUID (as a
36-byte string) to a <row-update> object.
A <row-update> is an object with the following members:
"old": <row> present for "delete" and "modify" updates
"new": <row> present for "initial", "insert", and "modify" updates
This JSON-RPC notification is sent from the server to the client to
tell it about changes to a monitored table (or the initial state of a
modified table). Each table in which one or more rows has changed (or
whose initial view is being presented) is represented in "updates".
Each row that has changed (or whose initial view is being presented)
is represented in its <table-update> as a member with its name taken
from the row's _uuid member. The corresponding value is a
<row-update>:
The "old" member is present for "delete" and "modify" updates.
For "delete" updates, each monitored column is included. For
"modify" updates, the prior value of each monitored column whose
value has changed is included (monitored columns that have not
changed are represented in "new").
The "new" member is present for "initial", "insert", and "modify"
updates. For "initial" and "insert" updates, each monitored
column is included. For "modify" updates, the new value of each
monitored column is included.
monitor_cancel
..............
Request object members:
"method": "monitor_cancel" required
"params": [<json-value>] required
"id": <nonnull-json-value> required
Response object members:
"result": {}
"error": null
"id": the request "id" member
Cancels the ongoing table monitor request, identified by the
<json-value> in "params" matching the <json-value> in "params" for an
ongoing "monitor" request. No more "update" messages will be sent for
this table monitor.
lock operations
...............
Request object members:
"method": "lock", "steal", or "unlock" required
"params": [<id>] required
"id": <nonnull-json-value> required
Response object members:
"result": {"locked": <boolean>} for "lock"
"result": {"locked": true} for "steal"
"result": {} for "unlock"
"error": null
"id": same "id" as request
Performs an operation on a "lock" object. The database server
supports an arbitrary number of locks, each of which is identified by
a client-defined id (given in "params"). At any given time, each lock
may have at most one owner.
The locking operation depends on "method":
- "lock": The database will assign this client ownership of the
lock as soon as it becomes available. When multiple clients
request the same lock, they will receive it in first-come, first
served order.
- "steal": The database immediately assigns this client ownership
of the lock. If there is an existing owner, it loses ownership.
- "unlock": If the client owns the lock, releases it. If the
client is waiting to obtain the lock, cancels the request and
stops waiting.
(Closing or otherwise disconnecting a database client connection
unlocks all of its locks.)
For any given lock, the client must alternate "lock" or "steal"
operations with "unlock" operations. That is, if the previous
operation on a lock was "lock" or "steal", it must be followed by an
"unlock" operation, and vice versa.
For a "lock" operation, the "locked" member in the response object is
true if the lock has already been acquired, false if another client
holds the lock and the client's request for it was queued. In the
latter case, the client will be notified later with a "locked" message
when acquisition succeeds.
These requests complete and send a response quickly, without waiting.
The "locked" and "stolen" notifications (see below) report
asynchronous changes to ownership.
The scope of a lock is a database server, not a database hosted by
that server. A naming convention, such as "<db-name>__<lock-name>",
can effectively limit the scope of a lock to a particular database.
locked
......
Notification object members:
"method": "locked"
"params": [<id>]
"id": null
Notifies the client that a "lock" operation that it previously
requested has succeeded. The client now owns the lock named in
"params".
The database server sends this notification after the reply to the
corresponding "lock" request (but only if the "locked" member of the
response was false), and before the reply to the client's subsequent
"unlock" request.
stolen
......
Notification object members:
"method": "stolen"
"params": [<id>]
"id": null
Notifies the client that owns a lock that another database client has
stolen ownership of the lock. The client no longer owns the lock
named in "params". The client must still issue an "unlock" request
before performing any subsequent "lock" or "steal" operation on the
lock.
If the client originally obtained the lock through a "lock" request,
then it will automatically regain the lock later after the client that
stole it releases it. (The database server will send the client a
"locked" notification at that point to let it know.)
If the client originally obtained the lock through a "steal" request,
the database server won't automatically reassign it ownership of the
lock when it later becomes available. To regain ownership, the client
must "unlock" and then "lock" or "steal" the lock again.
echo
....
Request object members:
"method": "echo" required
"params": JSON array with any contents required
"id": <json-value> required
Response object members:
"result": same as "params"
"error": null
"id": the request "id" member
Both the JSON-RPC client and the server must implement this request.
This JSON-RPC request and response can be used to implement connection
keepalives, by allowing the server to check that the client is still
there or vice versa.
Notation for the Wire Protocol
------------------------------
<db-name>
An <id> that names a database. The valid <db-name>s can be
obtained using a "list-db" request. The <db-name> is taken from
the "name" member of <database-schema>.
<table>
An <id> that names a table.
<column>
An <id> that names a table column.
<row>
A JSON object that describes a table row or a subset of a table
row. Each member is the name of a table column paired with the
<value> of that column.
<value>
A JSON value that represents the value of a column in a table row,
one of <atom>, a <set>, or a <map>.
<atom>
A JSON value that represents a scalar value for a column, one of
<string>, <number>, <boolean>, <uuid>, <named-uuid>.
<set>
Either an <atom>, representing a set with exactly one element, or
a 2-element JSON array that represents a database set value. The
first element of the array must be the string "set" and the second
element must be an array of zero or more <atom>s giving the values
in the set. All of the <atom>s must have the same type.
<map>
A 2-element JSON array that represents a database map value. The
first element of the array must be the string "map" and the second
element must be an array of zero or more <pair>s giving the values
in the map. All of the <pair>s must have the same key and value
types.
(JSON objects are not used to represent <map> because JSON only
allows string names in an object.)
<pair>
A 2-element JSON array that represents a pair within a database
map. The first element is an <atom> that represents the key, the
second element is an <atom> that represents the value.
<uuid>
A 2-element JSON array that represents a UUID. The first element
of the array must be the string "uuid" and the second element must
be a 36-character string giving the UUID in the format described
by RFC 4122. For example, the following <uuid> represents the
UUID 550e8400-e29b-41d4-a716-446655440000:
["uuid", "550e8400-e29b-41d4-a716-446655440000"]
<named-uuid>
A 2-element JSON array that represents the UUID of a row inserted
in an "insert" operation within the same transaction. The first
element of the array must be the string "named-uuid" and the
second element should be the <id> specified as the "uuid-name"
for an "insert" operation within the same transaction. For
example, if an "insert" operation within this transaction
specifies a "uuid-name" of "myrow", the following <named-uuid>
represents the UUID created by that operation:
["named-uuid", "myrow"]
A <named-uuid> may be used anywhere a <uuid> is valid.
<condition>
A 3-element JSON array of the form [<column>, <function>,
<value>] that represents a test on a column value.
Except as otherwise specified below, <value> must have the same
type as <column>.
The meaning depends on the type of <column>:
integer
real
<function> must be "<", "<=", "==", "!=", ">=", ">",
"includes", or "excludes".
The test is true if the column's value satisfies the
relation <function> <value>, e.g. if the column has value
1 and <value> is 2, the test is true if <function> is "<",
"<=" or "!=", but not otherwise.
"includes" is equivalent to "=="; "excludes" is equivalent
to "!=".
boolean
string
uuid
<function> must be "!=", "==", "includes", or "excludes".
If <function> is "==" or "includes", the test is true if
the column's value equals <value>. If <function> is "!="
or "excludes", the test is inverted.
set
map
<function> must be "!=", "==", "includes", or "excludes".
If <function> is "==", the test is true if the column's
value contains exactly the same values (for sets) or pairs
(for maps). If <function> is "!=", the test is inverted.
If <function> is "includes", the test is true if the
column's value contains all of the values (for sets) or
pairs (for maps) in <value>. The column's value may also
contain other values or pairs.
If <function> is "excludes", the test is true if the
column's value does not contain any of the values (for
sets) or pairs (for maps) in <value>. The column's value
may contain other values or pairs not in <value>.
If <function> is "includes" or "excludes", then the
required type of <value> is slightly relaxed, in that it
may have fewer than the minimum number of elements
specified by the column's type. If <function> is
"excludes", then the required type is additionally relaxed
in that <value> may have more than the maximum number of
elements specified by the column's type.
<function>
One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
<mutation>
A 3-element JSON array of the form [<column>, <mutator>, <value>]
that represents a change to a column value.
Except as otherwise specified below, <value> must have the same
type as <column>.
The meaning depends on the type of <column>:
integer
real
<mutator> must be "+=", "-=", "*=", "/=" or (integer only)
"%=". The value of <column> is changed to the sum,
difference, product, quotient, or remainder, respectively,
of <column> and <value>.
Constraints on <column> are ignored when parsing <value>.
boolean
string
uuid
No valid <mutator>s are currently defined for these types.
set
Any <mutator> valid for the set's element type may be
applied to the set, in which case the mutation is applied
to each member of the set individually. <value> must be a
scalar value of the same type as the set's element type,
except that contraints are ignored.
If <mutator> is "insert", then each of the values in the
set in <value> is added to <column> if it is not already
present. The required type of <value> is slightly
relaxed, in that it may have fewer than the minimum number
of elements specified by the column's type.
If <mutator> is "delete", then each of the values in the
set in <value> is removed from <column> if it is present
there. The required type is slightly relaxed in that
<value> may have more or less than the maximum number of
elements specified by the column's type.
map
<mutator> must be "insert" or "delete".
If <mutator> is "insert", then each of the key-value pairs
in the map in <value> is added to <column> only if its key
is not already present. The required type of <value> is
slightly relaxed, in that it may have fewer than the
minimum number of elements specified by the column's type.
If <mutator> is "delete", then <value> may have the same
type as <column> (a map type) or it may be a set whose
element type is the same as <column>'s key type:
- If <value> is a map, the mutation deletes each
key-value pair in <column> whose key and value equal
one of the key-value pairs in <value>.
- If <value> is a set, the mutation deletes each
key-value pair in <column> whose key equals one of
the values in <value>.
For "delete", <value> may have any number of elements,
regardless of restrictions on the number of elements in
<column>.
<mutator>
One of "+=", "-=", "*=", "/=", "%=", "insert", "delete".
Operations
----------
Each of the available operations is described below.
insert
......
Request object members:
"op": "insert" required
"table": <table> required
"row": <row> required
"uuid-name": <id> optional
Result object members:
"uuid": <uuid>
Semantics:
Inserts "row" into "table".