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 }