View Javadoc
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 }