statelydb 0.32.2 → 0.33.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/lib/api/db/list_pb.rb +1 -2
- data/lib/api/db/transaction_pb.rb +1 -2
- data/lib/key_path.rb +1 -1
- data/lib/statelydb.rb +154 -52
- data/lib/transaction/transaction.rb +77 -36
- data/lib/version.rb +1 -1
- data/rbi/db/list_pb.rbi +0 -20
- data/rbi/db/transaction_pb.rbi +0 -20
- data/rbi/statelydb.rbi +235 -76
- data/sig/statelydb.rbs +231 -73
- metadata +2 -3
- data/lib/api/db/item_property_pb.rb +0 -17
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 862a94ca6faeae1cb5f4f74db3e0afac562b1690247caeb3c0f944c29c24d7a9
|
|
4
|
+
data.tar.gz: e6f7930cc6e9ae285e3693b64da692188f810f0bb63e0a87244f6688ec39fa51
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: e99656d028daca7e3ecaccd2dc449d12ed2e0a5ece1c3d68b798c206e8c09b36a0402112059d200e574577bd1cbfa6624df2e4d9d8b8164ff0c1e594eb46d321
|
|
7
|
+
data.tar.gz: 7f494d4d912642810ae48757f7e6e82ef362d53fe13eb799b0d0e46b8899e35c3cd4edc002c7359b86adb8bb54a0e177cac3a263901b9204c2e92341e258f5b6
|
data/lib/api/db/list_pb.rb
CHANGED
|
@@ -5,12 +5,11 @@
|
|
|
5
5
|
require 'google/protobuf'
|
|
6
6
|
|
|
7
7
|
require 'api/db/item_pb'
|
|
8
|
-
require 'api/db/item_property_pb'
|
|
9
8
|
require 'api/db/list_filters_pb'
|
|
10
9
|
require 'api/db/list_token_pb'
|
|
11
10
|
|
|
12
11
|
|
|
13
|
-
descriptor_data = "\n\rdb/list.proto\x12\nstately.db\x1a\rdb/item.proto\x1a\
|
|
12
|
+
descriptor_data = "\n\rdb/list.proto\x12\nstately.db\x1a\rdb/item.proto\x1a\x15\x64\x62/list_filters.proto\x1a\x13\x64\x62/list_token.proto\"\xa8\x03\n\x10\x42\x65ginListRequest\x12\x19\n\x08store_id\x18\x01 \x01(\x04R\x07storeId\x12&\n\x0fkey_path_prefix\x18\x02 \x01(\tR\rkeyPathPrefix\x12\x14\n\x05limit\x18\x03 \x01(\rR\x05limit\x12\x1f\n\x0b\x61llow_stale\x18\x04 \x01(\x08R\nallowStale\x12@\n\x0esort_direction\x18\x06 \x01(\x0e\x32\x19.stately.db.SortDirectionR\rsortDirection\x12*\n\x11schema_version_id\x18\x07 \x01(\rR\x0fschemaVersionId\x12\x1b\n\tschema_id\x18\x08 \x01(\x04R\x08schemaId\x12H\n\x11\x66ilter_conditions\x18\t \x03(\x0b\x32\x1b.stately.db.FilterConditionR\x10\x66ilterConditions\x12?\n\x0ekey_conditions\x18\n \x03(\x0b\x32\x18.stately.db.KeyConditionR\rkeyConditionsJ\x04\x08\x05\x10\x06\"\x8b\x01\n\x0cListResponse\x12\x37\n\x06result\x18\x01 \x01(\x0b\x32\x1d.stately.db.ListPartialResultH\x00R\x06result\x12\x36\n\x08\x66inished\x18\x02 \x01(\x0b\x32\x18.stately.db.ListFinishedH\x00R\x08\x66inishedB\n\n\x08response\";\n\x11ListPartialResult\x12&\n\x05items\x18\x01 \x03(\x0b\x32\x10.stately.db.ItemR\x05items\";\n\x0cListFinished\x12+\n\x05token\x18\x01 \x01(\x0b\x32\x15.stately.db.ListTokenR\x05token\"[\n\x0cKeyCondition\x12\x19\n\x08key_path\x18\x01 \x01(\tR\x07keyPath\x12\x30\n\x08operator\x18\x02 \x01(\x0e\x32\x14.stately.db.OperatorR\x08operator*8\n\rSortDirection\x12\x12\n\x0eSORT_ASCENDING\x10\x00\x12\x13\n\x0fSORT_DESCENDING\x10\x01*\x9c\x01\n\x08Operator\x12\x18\n\x14OPERATOR_UNSPECIFIED\x10\x00\x12\x19\n\x15OPERATOR_GREATER_THAN\x10\x04\x12\"\n\x1eOPERATOR_GREATER_THAN_OR_EQUAL\x10\x05\x12\x16\n\x12OPERATOR_LESS_THAN\x10\x06\x12\x1f\n\x1bOPERATOR_LESS_THAN_OR_EQUAL\x10\x07\x42\x64\n\x0e\x63om.stately.dbB\tListProtoP\x01\xa2\x02\x03SDX\xaa\x02\nStately.Db\xca\x02\nStately\\Db\xe2\x02\x16Stately\\Db\\GPBMetadata\xea\x02\x0bStately::Dbb\x06proto3"
|
|
14
13
|
|
|
15
14
|
pool = ::Google::Protobuf::DescriptorPool.generated_pool
|
|
16
15
|
pool.add_serialized_file(descriptor_data)
|
|
@@ -8,14 +8,13 @@ require 'api/db/continue_list_pb'
|
|
|
8
8
|
require 'api/db/delete_pb'
|
|
9
9
|
require 'api/db/get_pb'
|
|
10
10
|
require 'api/db/item_pb'
|
|
11
|
-
require 'api/db/item_property_pb'
|
|
12
11
|
require 'api/db/list_pb'
|
|
13
12
|
require 'api/db/list_filters_pb'
|
|
14
13
|
require 'api/db/put_pb'
|
|
15
14
|
require 'google/protobuf/empty_pb'
|
|
16
15
|
|
|
17
16
|
|
|
18
|
-
descriptor_data = "\n\x14\x64\x62/transaction.proto\x12\nstately.db\x1a\x16\x64\x62/continue_list.proto\x1a\x0f\x64\x62/delete.proto\x1a\x0c\x64\x62/get.proto\x1a\rdb/item.proto\x1a\
|
|
17
|
+
descriptor_data = "\n\x14\x64\x62/transaction.proto\x12\nstately.db\x1a\x16\x64\x62/continue_list.proto\x1a\x0f\x64\x62/delete.proto\x1a\x0c\x64\x62/get.proto\x1a\rdb/item.proto\x1a\rdb/list.proto\x1a\x15\x64\x62/list_filters.proto\x1a\x0c\x64\x62/put.proto\x1a\x1bgoogle/protobuf/empty.proto\"\x9f\x04\n\x12TransactionRequest\x12\x1d\n\nmessage_id\x18\x01 \x01(\rR\tmessageId\x12\x34\n\x05\x62\x65gin\x18\x02 \x01(\x0b\x32\x1c.stately.db.TransactionBeginH\x00R\x05\x62\x65gin\x12\x39\n\tget_items\x18\x03 \x01(\x0b\x32\x1a.stately.db.TransactionGetH\x00R\x08getItems\x12\x41\n\nbegin_list\x18\x04 \x01(\x0b\x32 .stately.db.TransactionBeginListH\x00R\tbeginList\x12J\n\rcontinue_list\x18\x05 \x01(\x0b\x32#.stately.db.TransactionContinueListH\x00R\x0c\x63ontinueList\x12\x39\n\tput_items\x18\x06 \x01(\x0b\x32\x1a.stately.db.TransactionPutH\x00R\x08putItems\x12\x42\n\x0c\x64\x65lete_items\x18\x07 \x01(\x0b\x32\x1d.stately.db.TransactionDeleteH\x00R\x0b\x64\x65leteItems\x12\x30\n\x06\x63ommit\x18\x08 \x01(\x0b\x32\x16.google.protobuf.EmptyH\x00R\x06\x63ommit\x12.\n\x05\x61\x62ort\x18\t \x01(\x0b\x32\x16.google.protobuf.EmptyH\x00R\x05\x61\x62ortB\t\n\x07\x63ommand\"\xc8\x02\n\x13TransactionResponse\x12\x1d\n\nmessage_id\x18\x01 \x01(\rR\tmessageId\x12\x45\n\x0bget_results\x18\x02 \x01(\x0b\x32\".stately.db.TransactionGetResponseH\x00R\ngetResults\x12\x38\n\x07put_ack\x18\x03 \x01(\x0b\x32\x1d.stately.db.TransactionPutAckH\x00R\x06putAck\x12H\n\x0clist_results\x18\x04 \x01(\x0b\x32#.stately.db.TransactionListResponseH\x00R\x0blistResults\x12=\n\x08\x66inished\x18\x05 \x01(\x0b\x32\x1f.stately.db.TransactionFinishedH\x00R\x08\x66inishedB\x08\n\x06result\"v\n\x10TransactionBegin\x12\x19\n\x08store_id\x18\x01 \x01(\x04R\x07storeId\x12*\n\x11schema_version_id\x18\x02 \x01(\rR\x0fschemaVersionId\x12\x1b\n\tschema_id\x18\x03 \x01(\x04R\x08schemaId\"9\n\x0eTransactionGet\x12\'\n\x04gets\x18\x01 \x03(\x0b\x32\x13.stately.db.GetItemR\x04gets\"\xa7\x02\n\x14TransactionBeginList\x12&\n\x0fkey_path_prefix\x18\x01 \x01(\tR\rkeyPathPrefix\x12\x14\n\x05limit\x18\x02 \x01(\rR\x05limit\x12@\n\x0esort_direction\x18\x04 \x01(\x0e\x32\x19.stately.db.SortDirectionR\rsortDirection\x12H\n\x11\x66ilter_conditions\x18\t \x03(\x0b\x32\x1b.stately.db.FilterConditionR\x10\x66ilterConditions\x12?\n\x0ekey_conditions\x18\n \x03(\x0b\x32\x18.stately.db.KeyConditionR\rkeyConditionsJ\x04\x08\x03\x10\x04\"y\n\x17TransactionContinueList\x12\x1d\n\ntoken_data\x18\x01 \x01(\x0cR\ttokenData\x12?\n\tdirection\x18\x04 \x01(\x0e\x32!.stately.db.ContinueListDirectionR\tdirection\"9\n\x0eTransactionPut\x12\'\n\x04puts\x18\x01 \x03(\x0b\x32\x13.stately.db.PutItemR\x04puts\"E\n\x11TransactionDelete\x12\x30\n\x07\x64\x65letes\x18\x01 \x03(\x0b\x32\x16.stately.db.DeleteItemR\x07\x64\x65letes\"@\n\x16TransactionGetResponse\x12&\n\x05items\x18\x01 \x03(\x0b\x32\x10.stately.db.ItemR\x05items\"D\n\x0bGeneratedID\x12\x14\n\x04uint\x18\x01 \x01(\x04H\x00R\x04uint\x12\x16\n\x05\x62ytes\x18\x02 \x01(\x0cH\x00R\x05\x62ytesB\x07\n\x05value\"Q\n\x11TransactionPutAck\x12<\n\rgenerated_ids\x18\x01 \x03(\x0b\x32\x17.stately.db.GeneratedIDR\x0cgeneratedIds\"\x96\x01\n\x17TransactionListResponse\x12\x37\n\x06result\x18\x01 \x01(\x0b\x32\x1d.stately.db.ListPartialResultH\x00R\x06result\x12\x36\n\x08\x66inished\x18\x02 \x01(\x0b\x32\x18.stately.db.ListFinishedH\x00R\x08\x66inishedB\n\n\x08response\"\xa7\x01\n\x13TransactionFinished\x12\x1c\n\tcommitted\x18\x01 \x01(\x08R\tcommitted\x12\x31\n\x0bput_results\x18\x02 \x03(\x0b\x32\x10.stately.db.ItemR\nputResults\x12?\n\x0e\x64\x65lete_results\x18\x03 \x03(\x0b\x32\x18.stately.db.DeleteResultR\rdeleteResultsBk\n\x0e\x63om.stately.dbB\x10TransactionProtoP\x01\xa2\x02\x03SDX\xaa\x02\nStately.Db\xca\x02\nStately\\Db\xe2\x02\x16Stately\\Db\\GPBMetadata\xea\x02\x0bStately::Dbb\x06proto3"
|
|
19
18
|
|
|
20
19
|
pool = ::Google::Protobuf::DescriptorPool.generated_pool
|
|
21
20
|
pool.add_serialized_file(descriptor_data)
|
data/lib/key_path.rb
CHANGED
data/lib/statelydb.rb
CHANGED
|
@@ -72,10 +72,12 @@ module StatelyDB
|
|
|
72
72
|
@token_provider&.close
|
|
73
73
|
end
|
|
74
74
|
|
|
75
|
-
#
|
|
76
|
-
#
|
|
77
|
-
#
|
|
78
|
-
#
|
|
75
|
+
# Returns a new client that is either OK with or not OK with stale reads.
|
|
76
|
+
# This affects get and list operations from the returned client. Use this
|
|
77
|
+
# only if you know you can tolerate stale reads. This can result in improved
|
|
78
|
+
# performance, availability, and cost.
|
|
79
|
+
# @param allow_stale [Boolean] Whether staleness is allowed or not.
|
|
80
|
+
# @return [self] A clone of the existing client with allow_stale set to the new value.
|
|
79
81
|
# @example
|
|
80
82
|
# client.with_allow_stale(true).get("/ItemType-identifier")
|
|
81
83
|
def with_allow_stale(allow_stale)
|
|
@@ -84,11 +86,11 @@ module StatelyDB
|
|
|
84
86
|
new_client
|
|
85
87
|
end
|
|
86
88
|
|
|
87
|
-
#
|
|
89
|
+
# get retrieves an item by its full key path.
|
|
88
90
|
#
|
|
89
|
-
# @param key_path [StatelyDB::KeyPath, String]
|
|
91
|
+
# @param key_path [StatelyDB::KeyPath, String] The full key path of the item.
|
|
90
92
|
# @return [StatelyDB::Item, NilClass] the Item or nil if not found
|
|
91
|
-
# @raise [StatelyDB::Error] if the parameters are invalid or if the item is not found
|
|
93
|
+
# @raise [StatelyDB::Error] if the parameters are invalid or nil if the item is not found
|
|
92
94
|
#
|
|
93
95
|
# @example
|
|
94
96
|
# client.get("/ItemType-identifier")
|
|
@@ -99,11 +101,15 @@ module StatelyDB
|
|
|
99
101
|
resp.first
|
|
100
102
|
end
|
|
101
103
|
|
|
102
|
-
#
|
|
104
|
+
# get_batch retrieves multiple items by their full key paths. This will
|
|
105
|
+
# return the corresponding items that exist. Use begin_list instead if you
|
|
106
|
+
# want to retrieve multiple items but don't already know the full key paths
|
|
107
|
+
# of the items you want to get. You can get items of different types in a
|
|
108
|
+
# single get_batch - you will need to check the class of each result to
|
|
109
|
+
# determine what item type it is.
|
|
103
110
|
#
|
|
104
|
-
# @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>]
|
|
105
|
-
#
|
|
106
|
-
# @return [Array<StatelyDB::Item>, NilClass] the items or nil if not found
|
|
111
|
+
# @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>] The full key path of each item to load.
|
|
112
|
+
# @return [Array<StatelyDB::Item>] the list of items that were found.
|
|
107
113
|
# @raise [StatelyDB::Error] if the parameters are invalid or if the item is not found
|
|
108
114
|
#
|
|
109
115
|
# @example
|
|
@@ -125,12 +131,23 @@ module StatelyDB
|
|
|
125
131
|
end
|
|
126
132
|
end
|
|
127
133
|
|
|
128
|
-
#
|
|
134
|
+
# begin_list retrieves Items that start with a specified key_path_prefix
|
|
135
|
+
# from a single Group. Because it can only list items from a single Group,
|
|
136
|
+
# the key path prefix must at least start with a full Group Key (a single
|
|
137
|
+
# key segment with a namespace and an ID, e.g. `/user-1234`).
|
|
138
|
+
#
|
|
139
|
+
# begin_list will return an empty result set if there are no items matching
|
|
140
|
+
# that key prefix. This API returns a token that you can pass to
|
|
141
|
+
# continue_list to expand the result set, or to sync_list to get updates
|
|
142
|
+
# within the result set.
|
|
143
|
+
#
|
|
144
|
+
# You can list items of different types in a single begin_list, and you can
|
|
145
|
+
# use `isinstance` to handle different item types.
|
|
129
146
|
#
|
|
130
|
-
# @param prefix [StatelyDB::KeyPath, String]
|
|
131
|
-
#
|
|
132
|
-
# @param
|
|
133
|
-
# @param sort_direction [Symbol, String, Integer] the direction to sort by (:ascending or :descending)
|
|
147
|
+
# @param prefix [StatelyDB::KeyPath, String] The key path prefix to query for.
|
|
148
|
+
# It must be at least a full Group Key (e.g. `/user-1234`).
|
|
149
|
+
# @param limit [Integer] The max number of items to retrieve. If set to 0 then the full set will be returned. Defaults to 0.
|
|
150
|
+
# @param sort_direction [Symbol, String, Integer] the direction to sort by (:ascending or :descending, default is :ascending).
|
|
134
151
|
# @param item_types [Array<Class<StatelyDB::Item>, String>] the item types to filter by. The returned
|
|
135
152
|
# items will be instances of one of these types.
|
|
136
153
|
# @param cel_filters [Array<Array<Class, String>, String>>] An optional list of
|
|
@@ -148,13 +165,13 @@ module StatelyDB
|
|
|
148
165
|
# that are rated `R`.
|
|
149
166
|
# Find the full CEL language definition here:
|
|
150
167
|
# https://github.com/google/cel-spec/blob/master/doc/langdef.md
|
|
151
|
-
# @param gt [StatelyDB::KeyPath
|
|
168
|
+
# @param gt [StatelyDB::KeyPath, String] filters results to only include items with a key greater than the
|
|
152
169
|
# specified value based on lexicographic ordering.
|
|
153
|
-
# @param gte [StatelyDB::KeyPath
|
|
170
|
+
# @param gte [StatelyDB::KeyPath, String] filters results to only include items with a key greater than or equal to the
|
|
154
171
|
# specified value based on lexicographic ordering.
|
|
155
|
-
# @param lt [StatelyDB::KeyPath
|
|
172
|
+
# @param lt [StatelyDB::KeyPath, String] filters results to only include items with a key less than the
|
|
156
173
|
# specified value based on lexicographic ordering.
|
|
157
|
-
# @param lte [StatelyDB::KeyPath
|
|
174
|
+
# @param lte [StatelyDB::KeyPath, String] filters results to only include items with a key less than or equal to the
|
|
158
175
|
# specified value based on lexicographic ordering.
|
|
159
176
|
|
|
160
177
|
# @return [Array<StatelyDB::Item>, StatelyDB::Token] the list of Items and the token
|
|
@@ -163,7 +180,6 @@ module StatelyDB
|
|
|
163
180
|
# client.data.begin_list("/ItemType-identifier", limit: 10, sort_direction: :ascending)
|
|
164
181
|
def begin_list(prefix,
|
|
165
182
|
limit: 100,
|
|
166
|
-
sort_property: nil,
|
|
167
183
|
sort_direction: :ascending,
|
|
168
184
|
item_types: [],
|
|
169
185
|
cel_filters: [],
|
|
@@ -186,7 +202,6 @@ module StatelyDB
|
|
|
186
202
|
store_id: @store_id,
|
|
187
203
|
key_path_prefix: String(prefix),
|
|
188
204
|
limit:,
|
|
189
|
-
sort_property:,
|
|
190
205
|
sort_direction:,
|
|
191
206
|
filter_conditions: build_filters(item_types: item_types, cel_filters: cel_filters),
|
|
192
207
|
key_conditions: key_conditions,
|
|
@@ -198,9 +213,24 @@ module StatelyDB
|
|
|
198
213
|
process_list_response(resp)
|
|
199
214
|
end
|
|
200
215
|
|
|
201
|
-
#
|
|
216
|
+
# continue_list takes the token from a begin_list call and returns the next
|
|
217
|
+
# "page" of results based on the original query parameters and pagination
|
|
218
|
+
# options. It doesn't have options because it is a continuation of a
|
|
219
|
+
# previous list operation. It will return a new token which can be used for
|
|
220
|
+
# another continue_list call, and so on. The token is the same one used by
|
|
221
|
+
# sync_list - each time you call either continue_list or sync_list, you
|
|
222
|
+
# should pass the latest version of the token, and the result will include a
|
|
223
|
+
# new version of the token to use in subsequent calls. You may interleave
|
|
224
|
+
# continue_list and sync_list calls however you like, but it does not make
|
|
225
|
+
# sense to make both calls in parallel. Calls to continue_list are tied to
|
|
226
|
+
# the authorization of the original begin_list call, so if the original
|
|
227
|
+
# begin_list call was allowed, continue_list with its token should also be
|
|
228
|
+
# allowed.
|
|
202
229
|
#
|
|
203
|
-
#
|
|
230
|
+
# You can list items of different types in a single continue_list, and you
|
|
231
|
+
# can check the class of each result to handle different item types.
|
|
232
|
+
#
|
|
233
|
+
# @param token [StatelyDB::Token] The latest token from a previous list operation.
|
|
204
234
|
# @return [Array<StatelyDB::Item>, StatelyDB::Token] the list of Items and the token
|
|
205
235
|
#
|
|
206
236
|
# @example
|
|
@@ -216,13 +246,14 @@ module StatelyDB
|
|
|
216
246
|
process_list_response(resp)
|
|
217
247
|
end
|
|
218
248
|
|
|
219
|
-
#
|
|
220
|
-
# the provided filters. This API returns a token that you can pass
|
|
221
|
-
# continue_scan to paginate through the result set.
|
|
222
|
-
# caller does not have permission to read Items.
|
|
249
|
+
# begin_scan initiates a scan request which will scan over the entire store
|
|
250
|
+
# and apply the provided filters. This API returns a token that you can pass
|
|
251
|
+
# to continue_scan to paginate through the result set.
|
|
223
252
|
#
|
|
224
|
-
#
|
|
225
|
-
#
|
|
253
|
+
# begin_scan can return items of many types, and you can check the class of
|
|
254
|
+
# each result to handle different item types.
|
|
255
|
+
#
|
|
256
|
+
# WARNING: THIS API CAN BE EXPENSIVE FOR STORES WITH A LARGE NUMBER OF ITEMS.
|
|
226
257
|
#
|
|
227
258
|
# @param limit [Integer] the max number of items to retrieve. If set to 0
|
|
228
259
|
# then the first page of results will be returned which may empty because it
|
|
@@ -275,12 +306,14 @@ module StatelyDB
|
|
|
275
306
|
process_list_response(resp)
|
|
276
307
|
end
|
|
277
308
|
|
|
278
|
-
# continue_scan takes the token from a begin_scan call and returns
|
|
279
|
-
# based on the original
|
|
309
|
+
# continue_scan takes the token from a begin_scan call and returns the
|
|
310
|
+
# next "page" of results based on the original query parameters and
|
|
311
|
+
# pagination options.
|
|
280
312
|
#
|
|
281
|
-
#
|
|
313
|
+
# You can scan items of different types in a single continue_scan, and you
|
|
314
|
+
# can check the class of each result to handle different item types.
|
|
282
315
|
#
|
|
283
|
-
# @param token [StatelyDB::Token] the token
|
|
316
|
+
# @param token [StatelyDB::Token] the token from the previous scan operation.
|
|
284
317
|
# @return [Array<StatelyDB::Item>, StatelyDB::Token] the list of Items and the token
|
|
285
318
|
#
|
|
286
319
|
# @example
|
|
@@ -296,7 +329,39 @@ module StatelyDB
|
|
|
296
329
|
process_list_response(resp)
|
|
297
330
|
end
|
|
298
331
|
|
|
299
|
-
#
|
|
332
|
+
# sync_list returns all changes to Items within the result set of a previous
|
|
333
|
+
# List operation. For all Items within the result set that were modified, it
|
|
334
|
+
# returns the full Item at in its current state. If the result set has
|
|
335
|
+
# already been expanded to the end (in the direction of the original
|
|
336
|
+
# begin_list request), sync_list will return newly created Items as well. It
|
|
337
|
+
# also returns a list of Item key paths that were deleted since the last
|
|
338
|
+
# sync_list, which you should reconcile with your view of items returned
|
|
339
|
+
# from previous begin_list/continue_list calls. Using this API, you can
|
|
340
|
+
# start with an initial set of items from begin_list, and then stay up to
|
|
341
|
+
# date on any changes via repeated sync_list requests over time.
|
|
342
|
+
#
|
|
343
|
+
# The token is the same one used by continue_list - each time you call
|
|
344
|
+
# either continue_list or sync_list, you should pass the latest version of
|
|
345
|
+
# the token, and then use the new token from the result in subsequent calls.
|
|
346
|
+
# You may interleave continue_list and sync_list calls however you like, but
|
|
347
|
+
# it does not make sense to make both calls in parallel. Calls to sync_list
|
|
348
|
+
# are tied to the authorization of the original begin_list call, so if the
|
|
349
|
+
# original begin_list call was allowed, sync_list with its token should also
|
|
350
|
+
# be allowed.
|
|
351
|
+
#
|
|
352
|
+
# The result will contain:
|
|
353
|
+
# - changed_items: Items that were changed or added since the last
|
|
354
|
+
# sync_list call.
|
|
355
|
+
# - deleted_item_paths: The key paths of items that were deleted since
|
|
356
|
+
# the last sync_list call.
|
|
357
|
+
# - updated_outside_list_window_paths: Item that were updated but
|
|
358
|
+
# are not within the current result set. You can treat this like
|
|
359
|
+
# deleted_item_paths, but the item hasn't actually been deleted, it's
|
|
360
|
+
# just not part of your view of the list anymore.
|
|
361
|
+
# - is_reset: A reset signal that indicates any previously cached
|
|
362
|
+
# view of the result set is no longer valid. You should throw away
|
|
363
|
+
# any locally cached data. Use the changed_items list from this result
|
|
364
|
+
# as the new view of the result set.
|
|
300
365
|
#
|
|
301
366
|
# @param token [StatelyDB::Token] the token to sync from
|
|
302
367
|
# @return [StatelyDB::SyncResult] the result of the sync operation
|
|
@@ -314,9 +379,16 @@ module StatelyDB
|
|
|
314
379
|
process_sync_response(resp)
|
|
315
380
|
end
|
|
316
381
|
|
|
317
|
-
#
|
|
382
|
+
# put adds an Item to the Store, or replaces the Item if it already exists
|
|
383
|
+
# at that path.
|
|
318
384
|
#
|
|
319
|
-
#
|
|
385
|
+
# This call will fail if:
|
|
386
|
+
# - The Item conflicts with an existing Item at the same path and the
|
|
387
|
+
# must_not_exist option is set, or the item's ID will be chosen with
|
|
388
|
+
# an `initialValue` and one of its other key paths conflicts with an
|
|
389
|
+
# existing item.
|
|
390
|
+
#
|
|
391
|
+
# @param item [StatelyDB::Item] An Item from your generated schema.
|
|
320
392
|
# @param must_not_exist [Boolean] A condition that indicates this item must
|
|
321
393
|
# not already exist at any of its key paths. If there is already an item
|
|
322
394
|
# at one of those paths, the Put operation will fail with a
|
|
@@ -330,7 +402,7 @@ module StatelyDB
|
|
|
330
402
|
# `fromMetadata`). Without this, those fields are always ignored and the
|
|
331
403
|
# server sets them to the appropriate times. This option can be useful when
|
|
332
404
|
# migrating data from another system.
|
|
333
|
-
# @return [StatelyDB::Item]
|
|
405
|
+
# @return [StatelyDB::Item] The item that was put, with any server-generated fields filled in.
|
|
334
406
|
#
|
|
335
407
|
# @example client.data.put(my_item)
|
|
336
408
|
# @example client.data.put(my_item, must_not_exist: true)
|
|
@@ -343,11 +415,20 @@ module StatelyDB
|
|
|
343
415
|
resp.first
|
|
344
416
|
end
|
|
345
417
|
|
|
346
|
-
#
|
|
418
|
+
# put_batch adds multiple Items to the Store, or replaces Items if they
|
|
419
|
+
# already exist at that path. You can put items of different types in a
|
|
420
|
+
# single put_batch. All puts in the request are applied atomically - there
|
|
421
|
+
# are no partial successes.
|
|
422
|
+
#
|
|
423
|
+
# This will fail if:
|
|
424
|
+
# - Any Item conflicts with an existing Item at the same path and its
|
|
425
|
+
# must_not_exist option is set, or the item's ID will be chosen with an
|
|
426
|
+
# `initialValue` and one of its other key paths conflicts with an existing
|
|
427
|
+
# item.
|
|
347
428
|
#
|
|
348
|
-
# @param items [StatelyDB::Item, Array<StatelyDB::Item>]
|
|
349
|
-
#
|
|
350
|
-
#
|
|
429
|
+
# @param items [StatelyDB::Item, Array<StatelyDB::Item>] Items from your generated schema.
|
|
430
|
+
# @return [Array<StatelyDB::Item>] The items that were put, with any server-generated fields filled in.
|
|
431
|
+
# They are returned in the same order they were provided.
|
|
351
432
|
#
|
|
352
433
|
# @example
|
|
353
434
|
# client.data.put_batch(item1, item2)
|
|
@@ -381,16 +462,19 @@ module StatelyDB
|
|
|
381
462
|
end
|
|
382
463
|
end
|
|
383
464
|
|
|
384
|
-
#
|
|
465
|
+
# delete removes one or more items from the Store by their full key paths.
|
|
466
|
+
# delete succeeds even if there isn't an item at that key path. Tombstones
|
|
467
|
+
# will be saved for deleted items for some time, so that sync_list can
|
|
468
|
+
# return information about deleted items. Deletes are always applied
|
|
469
|
+
# atomically; all will fail or all will succeed.
|
|
385
470
|
#
|
|
386
|
-
# @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>]
|
|
387
|
-
#
|
|
388
|
-
# @raise [StatelyDB::Error] if the
|
|
389
|
-
# @raise [StatelyDB::Error] if the item is not found
|
|
471
|
+
# @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>]
|
|
472
|
+
# The full key paths of the items. @raise [StatelyDB::Error] if the
|
|
473
|
+
# parameters are invalid @raise [StatelyDB::Error] if the item is not found
|
|
390
474
|
# @return [void] nil
|
|
391
475
|
#
|
|
392
|
-
# @example
|
|
393
|
-
#
|
|
476
|
+
# @example client.data.delete("/ItemType-identifier",
|
|
477
|
+
# "/ItemType-identifier2")
|
|
394
478
|
def delete(*key_paths)
|
|
395
479
|
key_paths = Array(key_paths).flatten
|
|
396
480
|
req = Stately::Db::DeleteRequest.new(
|
|
@@ -403,9 +487,27 @@ module StatelyDB
|
|
|
403
487
|
nil
|
|
404
488
|
end
|
|
405
489
|
|
|
406
|
-
#
|
|
407
|
-
#
|
|
408
|
-
#
|
|
490
|
+
# transaction allows you to issue reads and writes in any order, and all
|
|
491
|
+
# writes will either succeed or all will fail when the transaction finishes.
|
|
492
|
+
# It takes a block with a single argument that can be used to run commands
|
|
493
|
+
# within the transaction.
|
|
494
|
+
#
|
|
495
|
+
# Reads are guaranteed to reflect the state as of when the transaction
|
|
496
|
+
# started. A transaction may fail if another transaction commits before this
|
|
497
|
+
# one finishes - in that case, you should retry your transaction.
|
|
498
|
+
#
|
|
499
|
+
# If any error is thrown from the block, the transaction is aborted and none
|
|
500
|
+
# of the changes made in it will be applied. If the handler returns without
|
|
501
|
+
# error, the transaction is automatically committed.
|
|
502
|
+
#
|
|
503
|
+
# If any of the operations in the block fails (e.g. a request is invalid)
|
|
504
|
+
# you may not find out until the *next* operation, or once the block
|
|
505
|
+
# finishes, due to some technicalities about how requests are handled.
|
|
506
|
+
#
|
|
507
|
+
# When the transaction is committed, the result property will contain the
|
|
508
|
+
# full version of any items that were put in the transaction, and the
|
|
509
|
+
# committed property will be True. If the transaction was aborted, the
|
|
510
|
+
# committed property will be False.
|
|
409
511
|
#
|
|
410
512
|
# @return [StatelyDB::Transaction::Transaction::Result] the result of the transaction
|
|
411
513
|
# @raise [StatelyDB::Error] if the parameters are invalid
|
|
@@ -177,10 +177,9 @@ module StatelyDB
|
|
|
177
177
|
@is_transaction_open
|
|
178
178
|
end
|
|
179
179
|
|
|
180
|
-
#
|
|
181
|
-
# transaction.
|
|
180
|
+
# get retrieves an item by its full key path.
|
|
182
181
|
#
|
|
183
|
-
# @param key_path [StatelyDB::KeyPath, String]
|
|
182
|
+
# @param key_path [StatelyDB::KeyPath, String] The full key path of the item.
|
|
184
183
|
# @return [StatelyDB::Item, NilClass] the item or nil if not found
|
|
185
184
|
# @raise [StatelyDB::Error::InvalidParameters] if the parameters are invalid
|
|
186
185
|
# @raise [StatelyDB::Error::NotFound] if the item is not found
|
|
@@ -196,11 +195,14 @@ module StatelyDB
|
|
|
196
195
|
resp.first
|
|
197
196
|
end
|
|
198
197
|
|
|
199
|
-
#
|
|
200
|
-
#
|
|
201
|
-
#
|
|
198
|
+
# get_batch retrieves multiple items by their full key paths. This will
|
|
199
|
+
# return the corresponding items that exist. Use begin_list instead if you
|
|
200
|
+
# want to retrieve multiple items but don't already know the full key
|
|
201
|
+
# paths of the items you want to get. You can get items of different types
|
|
202
|
+
# in a single get_batch - you will need to check the class of each result
|
|
203
|
+
# to determine what item type each item is.
|
|
202
204
|
#
|
|
203
|
-
# @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>] the paths to the items.
|
|
205
|
+
# @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>] the paths to the items.
|
|
204
206
|
# key paths.
|
|
205
207
|
# @return [Array<StatelyDB::Item>] the items
|
|
206
208
|
# @raise [StatelyDB::Error::InvalidParameters] if the parameters are invalid
|
|
@@ -224,11 +226,16 @@ module StatelyDB
|
|
|
224
226
|
end
|
|
225
227
|
end
|
|
226
228
|
|
|
227
|
-
#
|
|
228
|
-
#
|
|
229
|
-
# the item
|
|
229
|
+
# put adds an Item to the Store, or replaces the Item if it already exists
|
|
230
|
+
# at that path. Unlike the put method outside of a transaction, this only
|
|
231
|
+
# returns the generated ID of the item, and then only if the item was
|
|
232
|
+
# newly created and has an `initialValue` field in its key. This is so you
|
|
233
|
+
# can use that ID in subsequent puts to reference newly created items. The
|
|
234
|
+
# final put items will not be returned until the transaction is committed,
|
|
235
|
+
# in which case they will be included in the `StatelyDB::Transaction::Transaction::Result.puts`
|
|
236
|
+
# list.
|
|
230
237
|
#
|
|
231
|
-
# @param item [StatelyDB::Item] the item to
|
|
238
|
+
# @param item [StatelyDB::Item] the item to put
|
|
232
239
|
# @param must_not_exist [Boolean] A condition that indicates this item must
|
|
233
240
|
# not already exist at any of its key paths. If there is already an item
|
|
234
241
|
# at one of those paths, the Put operation will fail with a
|
|
@@ -242,7 +249,10 @@ module StatelyDB
|
|
|
242
249
|
# `fromMetadata`). Without this, those fields are always ignored and the
|
|
243
250
|
# server sets them to the appropriate times. This option can be useful when
|
|
244
251
|
# migrating data from another system.
|
|
245
|
-
# @return [String, Integer]
|
|
252
|
+
# @return [String, Integer] a generated IDs for the item, if that item had an ID generated
|
|
253
|
+
# for its "initialValue" field. Otherwise the value is None. This
|
|
254
|
+
# value can be used in subsequent puts to reference newly created
|
|
255
|
+
# items.
|
|
246
256
|
#
|
|
247
257
|
# @example
|
|
248
258
|
# results = client.data.transaction do |txn|
|
|
@@ -258,14 +268,22 @@ module StatelyDB
|
|
|
258
268
|
resp.first
|
|
259
269
|
end
|
|
260
270
|
|
|
261
|
-
#
|
|
262
|
-
#
|
|
263
|
-
#
|
|
264
|
-
#
|
|
271
|
+
# put_batch adds multiple Items to the Store, or replaces Items if they
|
|
272
|
+
# already exist at that path. You can put items of different types in a
|
|
273
|
+
# single put_batch. Unlike the put_batch method outside of a transaction,
|
|
274
|
+
# this only returns the generated IDs of the items, and then only if the
|
|
275
|
+
# item was newly created and has an `initialValue` field in its key. The
|
|
276
|
+
# IDs are returned in the same order as the inputs. This is so you can use
|
|
277
|
+
# that ID in subsequent puts to reference newly created items. The final
|
|
278
|
+
# put items will not be returned until the transaction is committed, in
|
|
279
|
+
# which case they will be included in the `StatelyDB::Transaction::Transaction::Result.puts` list.
|
|
265
280
|
#
|
|
266
|
-
# @param items [StatelyDB::Item, Array<StatelyDB::Item>] the items to
|
|
267
|
-
#
|
|
268
|
-
#
|
|
281
|
+
# @param items [StatelyDB::Item, Array<StatelyDB::Item>] the items to put
|
|
282
|
+
# @return [Array<StatelyDB::UUID, String, Integer, NilClass>] an array of
|
|
283
|
+
# generated IDs for each item, if that item had an ID generated for its
|
|
284
|
+
# "initialValue" field. Otherwise the value is None.
|
|
285
|
+
# These are returned in the same order as the input items. This value
|
|
286
|
+
# can be used in subsequent puts to reference newly created items.
|
|
269
287
|
#
|
|
270
288
|
# @example
|
|
271
289
|
# results = client.data.transaction do |txn|
|
|
@@ -309,11 +327,10 @@ module StatelyDB
|
|
|
309
327
|
end
|
|
310
328
|
end
|
|
311
329
|
|
|
312
|
-
#
|
|
313
|
-
#
|
|
330
|
+
# delete removes one or more items from the Store by their full key paths.
|
|
331
|
+
# delete succeeds even if there isn't an item at that key path.
|
|
314
332
|
#
|
|
315
|
-
# @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>] the
|
|
316
|
-
# to the items. Max 50 key paths.
|
|
333
|
+
# @param key_paths [StatelyDB::KeyPath, String, Array<StatelyDB::KeyPath, String>] The full key paths of the items
|
|
317
334
|
# @return [void] nil
|
|
318
335
|
#
|
|
319
336
|
# Example:
|
|
@@ -331,11 +348,22 @@ module StatelyDB
|
|
|
331
348
|
nil
|
|
332
349
|
end
|
|
333
350
|
|
|
334
|
-
#
|
|
351
|
+
# begin_list retrieves Items that start with a specified key_path_prefix
|
|
352
|
+
# from a single Group. Because it can only list items from a single Group,
|
|
353
|
+
# the key path prefix must at least start with a full Group Key (a single
|
|
354
|
+
# key segment with a namespace and an ID, e.g. `/user-1234`).
|
|
335
355
|
#
|
|
336
|
-
#
|
|
337
|
-
#
|
|
338
|
-
#
|
|
356
|
+
# begin_list will return an empty result set if there are no items
|
|
357
|
+
# matching that key prefix. This API returns a token that you can pass to
|
|
358
|
+
# continue_list to expand the result set.
|
|
359
|
+
#
|
|
360
|
+
# You can list items of different types in a single begin_list, and you
|
|
361
|
+
# can check the class of each result to handle different item types.
|
|
362
|
+
#
|
|
363
|
+
# @param prefix [StatelyDB::KeyPath, String] the key path prefix to query for. It must be at
|
|
364
|
+
# least a full Group Key (e.g. `/user-1234`).
|
|
365
|
+
# @param limit [Integer] the max number of Items to retrieve. Defaults to 0 which
|
|
366
|
+
# fetches all Items.
|
|
339
367
|
# @param sort_direction [Symbol] the direction to sort by (:ascending or :descending)
|
|
340
368
|
# @param item_types [Array<StatelyDB::Item, String>] the item types to filter by. The returned
|
|
341
369
|
# items will be instances of one of these types.
|
|
@@ -354,15 +382,15 @@ module StatelyDB
|
|
|
354
382
|
# that are rated `R`.
|
|
355
383
|
# Find the full CEL language definition here:
|
|
356
384
|
# https://github.com/google/cel-spec/blob/master/doc/langdef.md
|
|
357
|
-
# @param gt [StatelyDB::KeyPath
|
|
385
|
+
# @param gt [StatelyDB::KeyPath, String] filters results to only include items with a key greater than the
|
|
358
386
|
# specified value based on lexicographic ordering.
|
|
359
|
-
# @param gte [StatelyDB::KeyPath
|
|
387
|
+
# @param gte [StatelyDB::KeyPath, String] filters results to only include items with a key greater than or equal to the
|
|
360
388
|
# specified value based on lexicographic ordering.
|
|
361
|
-
# @param lt [StatelyDB::KeyPath
|
|
389
|
+
# @param lt [StatelyDB::KeyPath, String] filters results to only include items with a key less than the
|
|
362
390
|
# specified value based on lexicographic ordering.
|
|
363
|
-
# @param lte [StatelyDB::KeyPath
|
|
391
|
+
# @param lte [StatelyDB::KeyPath, String] filters results to only include items with a key less than or equal to the
|
|
364
392
|
# specified value based on lexicographic ordering.
|
|
365
|
-
|
|
393
|
+
#
|
|
366
394
|
# @return [Array(Array<StatelyDB::Item>, ::Stately::Db::ListToken)] the list of Items and the token
|
|
367
395
|
#
|
|
368
396
|
# Example:
|
|
@@ -372,7 +400,6 @@ module StatelyDB
|
|
|
372
400
|
# end
|
|
373
401
|
def begin_list(prefix,
|
|
374
402
|
limit: 100,
|
|
375
|
-
sort_property: nil,
|
|
376
403
|
sort_direction: :ascending,
|
|
377
404
|
item_types: [],
|
|
378
405
|
cel_filters: [],
|
|
@@ -402,7 +429,6 @@ module StatelyDB
|
|
|
402
429
|
begin_list: Stately::Db::TransactionBeginList.new(
|
|
403
430
|
key_path_prefix: String(prefix),
|
|
404
431
|
limit:,
|
|
405
|
-
sort_property:,
|
|
406
432
|
sort_direction:,
|
|
407
433
|
filter_conditions: build_filters(item_types: item_types, cel_filters: cel_filters),
|
|
408
434
|
key_conditions: key_conditions
|
|
@@ -411,9 +437,24 @@ module StatelyDB
|
|
|
411
437
|
do_list_request_response(req)
|
|
412
438
|
end
|
|
413
439
|
|
|
414
|
-
#
|
|
440
|
+
# continue_list takes the token from a begin_list call and returns the
|
|
441
|
+
# next "page" of results based on the original query parameters and
|
|
442
|
+
# pagination options. It doesn't have options because it is a continuation
|
|
443
|
+
# of a previous list operation. It will return a new token which can be
|
|
444
|
+
# used for another continue_list call, and so on. The token is the same
|
|
445
|
+
# one used by sync_list - each time you call either continue_list or
|
|
446
|
+
# sync_list, you should pass the latest version of the token, and the
|
|
447
|
+
# result will include a new version of the token to use in subsequent
|
|
448
|
+
# calls. You may interleave continue_list and sync_list calls however you
|
|
449
|
+
# like, but it does not make sense to make both calls in parallel. Calls
|
|
450
|
+
# to continue_list are tied to the authorization of the original
|
|
451
|
+
# begin_list call, so if the original begin_list call was allowed,
|
|
452
|
+
# continue_list with its token should also be allowed.
|
|
453
|
+
#
|
|
454
|
+
# You can list items of different types in a single continueList, and you can
|
|
455
|
+
# check the class of each result to handle different item types.
|
|
415
456
|
#
|
|
416
|
-
# @param token [::Stately::Db::ListToken] the token
|
|
457
|
+
# @param token [::Stately::Db::ListToken] the token from the previous list operation
|
|
417
458
|
# @param continue_direction [Symbol] the direction to continue by (:forward or :backward)
|
|
418
459
|
# @return [Array(Array<StatelyDB::Item>, ::Stately::Db::ListToken)] the list of Items and the token
|
|
419
460
|
#
|
data/lib/version.rb
CHANGED