1 /*
2 * Copyright 2021 TiKV Project Authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 *
16 */
17
18 package org.tikv.raw;
19
20 import com.google.protobuf.ByteString;
21 import java.util.List;
22 import java.util.Map;
23 import java.util.Optional;
24 import org.tikv.common.TiSession;
25 import org.tikv.common.util.Pair;
26 import org.tikv.common.util.ScanOption;
27 import org.tikv.kvproto.Kvrpcpb;
28
29 public interface RawKVClientBase extends AutoCloseable {
30 // https://www.github.com/pingcap/tidb/blob/master/store/tikv/rawkv.go
31 int MAX_RAW_SCAN_LIMIT = 10240;
32 int MAX_RAW_BATCH_LIMIT = 1024;
33 int RAW_BATCH_PUT_SIZE = 1024 * 1024;
34 int RAW_BATCH_GET_SIZE = 16 * 1024;
35 int RAW_BATCH_DELETE_SIZE = 16 * 1024;
36
37 /**
38 * Put a raw key-value pair to TiKV
39 *
40 * @param key raw key
41 * @param value raw value
42 */
43 void put(ByteString key, ByteString value);
44
45 /**
46 * Put a raw key-value pair to TiKV
47 *
48 * @param key raw key
49 * @param value raw value
50 * @param ttl the ttl of the key (in seconds), 0 means the key will never be outdated
51 */
52 void put(ByteString key, ByteString value, long ttl);
53
54 /**
55 * Put a key-value pair if it does not exist. This API is atomic.
56 *
57 * <p>To use this API, please enable `tikv.enable_atomic_for_cas`.
58 *
59 * @param key key
60 * @param value value
61 * @return a ByteString. returns Optional.EMPTY if the value is written successfully. returns the
62 * previous key if the value already exists, and does not write to TiKV.
63 */
64 Optional<ByteString> putIfAbsent(ByteString key, ByteString value);
65
66 /**
67 * Put a key-value pair with TTL if it does not exist. This API is atomic.
68 *
69 * <p>To use this API, please enable `tikv.enable_atomic_for_cas`.
70 *
71 * @param key key
72 * @param value value
73 * @param ttl TTL of key (in seconds), 0 means the key will never be outdated.
74 * @return a ByteString. returns Optional.EMPTY if the value is written successfully. returns the
75 * previous key if the value already exists, and does not write to TiKV.
76 */
77 Optional<ByteString> putIfAbsent(ByteString key, ByteString value, long ttl);
78
79 /**
80 * Put a key-value pair if the prevValue matched the value in TiKV. This API is atomic.
81 *
82 * <p>To use this API, please enable `tikv.enable_atomic_for_cas`.
83 *
84 * @param key key
85 * @param value value
86 */
87 void compareAndSet(ByteString key, Optional<ByteString> prevValue, ByteString value);
88
89 /**
90 * pair if the prevValue matched the value in TiKV. This API is atomic.
91 *
92 * <p>To use this API, please enable `tikv.enable_atomic_for_cas`.
93 *
94 * @param key key
95 * @param value value
96 * @param ttl TTL of key (in seconds), 0 means the key will never be outdated.
97 */
98 void compareAndSet(ByteString key, Optional<ByteString> prevValue, ByteString value, long ttl);
99
100 /**
101 * Put a set of raw key-value pair to TiKV.
102 *
103 * @param kvPairs kvPairs
104 */
105 void batchPut(Map<ByteString, ByteString> kvPairs);
106
107 /**
108 * Put a set of raw key-value pair to TiKV.
109 *
110 * @param kvPairs kvPairs
111 * @param ttl the TTL of keys to be put (in seconds), 0 means the keys will never be outdated
112 */
113 void batchPut(Map<ByteString, ByteString> kvPairs, long ttl);
114
115 /**
116 * Get a raw key-value pair from TiKV if key exists
117 *
118 * @param key raw key
119 * @return a ByteString value if key exists, ByteString.EMPTY if key does not exist
120 */
121 Optional<ByteString> get(ByteString key);
122
123 /**
124 * Get a list of raw key-value pair from TiKV if key exists
125 *
126 * @param keys list of raw key
127 * @return a ByteString value if key exists, ByteString.EMPTY if key does not exist
128 */
129 List<Kvrpcpb.KvPair> batchGet(List<ByteString> keys);
130
131 /**
132 * Delete a list of raw key-value pair from TiKV if key exists
133 *
134 * @param keys list of raw key
135 */
136 void batchDelete(List<ByteString> keys);
137
138 /**
139 * Get the TTL of a raw key from TiKV if key exists
140 *
141 * @param key raw key
142 * @return a Long indicating the TTL of key ttl is a non-null long value indicating TTL if key
143 * exists. - ttl=0 if the key will never be outdated. - ttl=null if the key does not exist
144 */
145 Optional<Long> getKeyTTL(ByteString key);
146
147 /**
148 * Create a new `batch scan` request with `keyOnly` option Once resolved this request will result
149 * in a set of scanners over the given keys.
150 *
151 * <p>WARNING: This method is experimental. The `each_limit` parameter does not work as expected.
152 * It does not limit the number of results returned of each range, instead it limits the number of
153 * results in each region of each range. As a result, you may get more than each_limit key-value
154 * pairs for each range. But you should not miss any entries.
155 *
156 * @param ranges a list of ranges
157 * @return a set of scanners for keys over the given keys.
158 */
159 List<List<ByteString>> batchScanKeys(List<Pair<ByteString, ByteString>> ranges, int eachLimit);
160
161 /**
162 * Create a new `batch scan` request. Once resolved this request will result in a set of scanners
163 * over the given keys.
164 *
165 * <p>WARNING: This method is experimental. The `each_limit` parameter does not work as expected.
166 * It does not limit the number of results returned of each range, instead it limits the number of
167 * results in each region of each range. As a result, you may get more than each_limit key-value
168 * pairs for each range. But you should not miss any entries.
169 *
170 * @param ranges a list of `ScanOption` for each range
171 * @return a set of scanners over the given keys.
172 */
173 List<List<Kvrpcpb.KvPair>> batchScan(List<ScanOption> ranges);
174
175 /**
176 * Scan raw key-value pairs from TiKV in range [startKey, endKey)
177 *
178 * @param startKey raw start key, inclusive
179 * @param endKey raw end key, exclusive
180 * @param limit limit of key-value pairs scanned, should be less than {@link #MAX_RAW_SCAN_LIMIT}
181 * @return list of key-value pairs in range
182 */
183 List<Kvrpcpb.KvPair> scan(ByteString startKey, ByteString endKey, int limit);
184
185 /**
186 * Scan raw key-value pairs from TiKV in range [startKey, endKey)
187 *
188 * @param startKey raw start key, inclusive
189 * @param endKey raw end key, exclusive
190 * @param limit limit of key-value pairs scanned, should be less than {@link #MAX_RAW_SCAN_LIMIT}
191 * @param keyOnly whether to scan in key-only mode
192 * @return list of key-value pairs in range
193 */
194 List<Kvrpcpb.KvPair> scan(ByteString startKey, ByteString endKey, int limit, boolean keyOnly);
195
196 /**
197 * Scan raw key-value pairs from TiKV in range [startKey, ♾)
198 *
199 * @param startKey raw start key, inclusive
200 * @param limit limit of key-value pairs scanned, should be less than {@link #MAX_RAW_SCAN_LIMIT}
201 * @return list of key-value pairs in range
202 */
203 List<Kvrpcpb.KvPair> scan(ByteString startKey, int limit);
204
205 /**
206 * Scan raw key-value pairs from TiKV in range [startKey, ♾)
207 *
208 * @param startKey raw start key, inclusive
209 * @param limit limit of key-value pairs scanned, should be less than {@link #MAX_RAW_SCAN_LIMIT}
210 * @param keyOnly whether to scan in key-only mode
211 * @return list of key-value pairs in range
212 */
213 List<Kvrpcpb.KvPair> scan(ByteString startKey, int limit, boolean keyOnly);
214
215 /**
216 * Scan all raw key-value pairs from TiKV in range [startKey, endKey)
217 *
218 * @param startKey raw start key, inclusive
219 * @param endKey raw end key, exclusive
220 * @return list of key-value pairs in range
221 */
222 List<Kvrpcpb.KvPair> scan(ByteString startKey, ByteString endKey);
223
224 /**
225 * Scan all raw key-value pairs from TiKV in range [startKey, endKey)
226 *
227 * @param startKey raw start key, inclusive
228 * @param endKey raw end key, exclusive
229 * @param keyOnly whether to scan in key-only mode
230 * @return list of key-value pairs in range
231 */
232 List<Kvrpcpb.KvPair> scan(ByteString startKey, ByteString endKey, boolean keyOnly);
233
234 /**
235 * Scan keys with prefix
236 *
237 * @param prefixKey prefix key
238 * @param limit limit of keys retrieved
239 * @param keyOnly whether to scan in keyOnly mode
240 * @return kvPairs with the specified prefix
241 */
242 List<Kvrpcpb.KvPair> scanPrefix(ByteString prefixKey, int limit, boolean keyOnly);
243
244 List<Kvrpcpb.KvPair> scanPrefix(ByteString prefixKey);
245
246 List<Kvrpcpb.KvPair> scanPrefix(ByteString prefixKey, boolean keyOnly);
247
248 /**
249 * Delete a raw key-value pair from TiKV if key exists
250 *
251 * @param key raw key to be deleted
252 */
253 void delete(ByteString key);
254
255 /**
256 * Delete all raw key-value pairs in range [startKey, endKey) from TiKV
257 *
258 * <p>Cautious, this API cannot be used concurrently, if multiple clients write keys into this
259 * range along with deleteRange API, the result will be undefined.
260 *
261 * @param startKey raw start key to be deleted
262 * @param endKey raw start key to be deleted
263 */
264 void deleteRange(ByteString startKey, ByteString endKey);
265
266 /**
267 * Delete all raw key-value pairs with the prefix `key` from TiKV
268 *
269 * <p>Cautious, this API cannot be used concurrently, if multiple clients write keys into this
270 * range along with deleteRange API, the result will be undefined.
271 *
272 * @param key prefix of keys to be deleted
273 */
274 void deletePrefix(ByteString key);
275
276 /** Get the session of the current client */
277 TiSession getSession();
278 }