org.tikv.raw

Class RawKVClient

java.lang.Object

org.tikv.raw.RawKVClient

All Implemented Interfaces:

AutoCloseable, RawKVClientBase

public class RawKVClient
extends Object
implements RawKVClientBase

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	RawKVClient.TikvIterator

Field Summary

Fields

Modifier and Type	Field and Description
static io.prometheus.client.Counter	RAW_REQUEST_FAILURE
static io.prometheus.client.Histogram	RAW_REQUEST_LATENCY
static io.prometheus.client.Counter	RAW_REQUEST_SUCCESS

Fields inherited from interface org.tikv.raw.RawKVClientBase

MAX_RAW_BATCH_LIMIT, MAX_RAW_SCAN_LIMIT, RAW_BATCH_DELETE_SIZE, RAW_BATCH_GET_SIZE, RAW_BATCH_PUT_SIZE

Constructor Summary

Constructors

Constructor and Description
RawKVClient(TiSession session, RegionStoreClient.RegionStoreClientBuilder clientBuilder)

Method Summary

Modifier and Type	Method and Description
void	batchDelete(List<com.google.protobuf.ByteString> keys) Delete a list of raw key-value pair from TiKV if key exists
List<Kvrpcpb.KvPair>	batchGet(List<com.google.protobuf.ByteString> keys) Get a list of raw key-value pair from TiKV if key exists
void	batchPut(Map<com.google.protobuf.ByteString,com.google.protobuf.ByteString> kvPairs) Put a set of raw key-value pair to TiKV.
void	batchPut(Map<com.google.protobuf.ByteString,com.google.protobuf.ByteString> kvPairs, long ttl) Put a set of raw key-value pair to TiKV.
List<List<Kvrpcpb.KvPair>>	batchScan(List<ScanOption> ranges) Create a new `batch scan` request.
List<List<com.google.protobuf.ByteString>>	batchScanKeys(List<Pair<com.google.protobuf.ByteString,com.google.protobuf.ByteString>> ranges, int eachLimit) Create a new `batch scan` request with `keyOnly` option Once resolved this request will result in a set of scanners over the given keys.
void	close()
void	compareAndSet(com.google.protobuf.ByteString key, Optional<com.google.protobuf.ByteString> prevValue, com.google.protobuf.ByteString value) Put a key-value pair if the prevValue matched the value in TiKV.
void	compareAndSet(com.google.protobuf.ByteString key, Optional<com.google.protobuf.ByteString> prevValue, com.google.protobuf.ByteString value, long ttl) pair if the prevValue matched the value in TiKV.
void	delete(com.google.protobuf.ByteString key) Delete a raw key-value pair from TiKV if key exists
void	deletePrefix(com.google.protobuf.ByteString key) Delete all raw key-value pairs with the prefix `key` from TiKV
void	deleteRange(com.google.protobuf.ByteString startKey, com.google.protobuf.ByteString endKey) Delete all raw key-value pairs in range [startKey, endKey) from TiKV
Optional<com.google.protobuf.ByteString>	get(com.google.protobuf.ByteString key) Get a raw key-value pair from TiKV if key exists
Optional<Long>	getKeyTTL(com.google.protobuf.ByteString key) Get the TTL of a raw key from TiKV if key exists
TiSession	getSession() Get the session of the current client
void	ingest(List<Pair<com.google.protobuf.ByteString,com.google.protobuf.ByteString>> list) Ingest KV pairs to RawKV using StreamKV API.
void	ingest(List<Pair<com.google.protobuf.ByteString,com.google.protobuf.ByteString>> list, Long ttl) Ingest KV pairs to RawKV using StreamKV API.
void	put(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value) Put a raw key-value pair to TiKV
void	put(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value, long ttl) Put a raw key-value pair to TiKV
Optional<com.google.protobuf.ByteString>	putIfAbsent(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value) Put a key-value pair if it does not exist.
Optional<com.google.protobuf.ByteString>	putIfAbsent(com.google.protobuf.ByteString key, com.google.protobuf.ByteString value, long ttl) Put a key-value pair with TTL if it does not exist.
List<Kvrpcpb.KvPair>	scan(com.google.protobuf.ByteString startKey, com.google.protobuf.ByteString endKey) Scan all raw key-value pairs from TiKV in range [startKey, endKey)
List<Kvrpcpb.KvPair>	scan(com.google.protobuf.ByteString startKey, com.google.protobuf.ByteString endKey, boolean keyOnly) Scan all raw key-value pairs from TiKV in range [startKey, endKey)
List<Kvrpcpb.KvPair>	scan(com.google.protobuf.ByteString startKey, com.google.protobuf.ByteString endKey, int limit) Scan raw key-value pairs from TiKV in range [startKey, endKey)
List<Kvrpcpb.KvPair>	scan(com.google.protobuf.ByteString startKey, com.google.protobuf.ByteString endKey, int limit, boolean keyOnly) Scan raw key-value pairs from TiKV in range [startKey, endKey)
List<Kvrpcpb.KvPair>	scan(com.google.protobuf.ByteString startKey, int limit) Scan raw key-value pairs from TiKV in range [startKey, ♾)
List<Kvrpcpb.KvPair>	scan(com.google.protobuf.ByteString startKey, int limit, boolean keyOnly) Scan raw key-value pairs from TiKV in range [startKey, ♾)
Iterator<Kvrpcpb.KvPair>	scan0(com.google.protobuf.ByteString startKey, com.google.protobuf.ByteString endKey) Scan all raw key-value pairs from TiKV in range [startKey, endKey)
Iterator<Kvrpcpb.KvPair>	scan0(com.google.protobuf.ByteString startKey, com.google.protobuf.ByteString endKey, boolean keyOnly) Scan all raw key-value pairs from TiKV in range [startKey, endKey)
Iterator<Kvrpcpb.KvPair>	scan0(com.google.protobuf.ByteString startKey, com.google.protobuf.ByteString endKey, int limit) Scan raw key-value pairs from TiKV in range [startKey, endKey)
Iterator<Kvrpcpb.KvPair>	scan0(com.google.protobuf.ByteString startKey, com.google.protobuf.ByteString endKey, int limit, boolean keyOnly) Scan raw key-value pairs from TiKV in range [startKey, endKey)
Iterator<Kvrpcpb.KvPair>	scan0(com.google.protobuf.ByteString startKey, int limit) Scan raw key-value pairs from TiKV in range [startKey, ♾)
Iterator<Kvrpcpb.KvPair>	scan0(com.google.protobuf.ByteString startKey, int limit, boolean keyOnly) Scan raw key-value pairs from TiKV in range [startKey, ♾)
List<Kvrpcpb.KvPair>	scanPrefix(com.google.protobuf.ByteString prefixKey)
List<Kvrpcpb.KvPair>	scanPrefix(com.google.protobuf.ByteString prefixKey, boolean keyOnly)
List<Kvrpcpb.KvPair>	scanPrefix(com.google.protobuf.ByteString prefixKey, int limit, boolean keyOnly) Scan keys with prefix
Iterator<Kvrpcpb.KvPair>	scanPrefix0(com.google.protobuf.ByteString prefixKey)
Iterator<Kvrpcpb.KvPair>	scanPrefix0(com.google.protobuf.ByteString prefixKey, boolean keyOnly)
Iterator<Kvrpcpb.KvPair>	scanPrefix0(com.google.protobuf.ByteString prefixKey, int limit, boolean keyOnly) Scan keys with prefix

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RAW_REQUEST_LATENCY

public static final io.prometheus.client.Histogram RAW_REQUEST_LATENCY

RAW_REQUEST_SUCCESS

public static final io.prometheus.client.Counter RAW_REQUEST_SUCCESS

RAW_REQUEST_FAILURE

public static final io.prometheus.client.Counter RAW_REQUEST_FAILURE

Constructor Detail

RawKVClient

public RawKVClient(TiSession session,
                   RegionStoreClient.RegionStoreClientBuilder clientBuilder)

Method Detail

close

public void close()

Specified by:

close in interface AutoCloseable

put

public void put(com.google.protobuf.ByteString key,
                com.google.protobuf.ByteString value)

Description copied from interface: RawKVClientBase

Put a raw key-value pair to TiKV

Specified by:

put in interface RawKVClientBase

Parameters:

key - raw key

value - raw value

put

public void put(com.google.protobuf.ByteString key,
                com.google.protobuf.ByteString value,
                long ttl)

Description copied from interface: RawKVClientBase

Put a raw key-value pair to TiKV

Specified by:

put in interface RawKVClientBase

Parameters:

key - raw key

value - raw value

ttl - the ttl of the key (in seconds), 0 means the key will never be outdated

putIfAbsent

public Optional<com.google.protobuf.ByteString> putIfAbsent(com.google.protobuf.ByteString key,
                                                            com.google.protobuf.ByteString value)

Description copied from interface: RawKVClientBase

Put a key-value pair if it does not exist. This API is atomic.

To use this API, please enable `tikv.enable_atomic_for_cas`.

Specified by:

putIfAbsent in interface RawKVClientBase

Parameters:

key - key

value - value

Returns:

a ByteString. returns Optional.EMPTY if the value is written successfully. returns the previous key if the value already exists, and does not write to TiKV.

putIfAbsent

public Optional<com.google.protobuf.ByteString> putIfAbsent(com.google.protobuf.ByteString key,
                                                            com.google.protobuf.ByteString value,
                                                            long ttl)

Description copied from interface: RawKVClientBase

Put a key-value pair with TTL if it does not exist. This API is atomic.

To use this API, please enable `tikv.enable_atomic_for_cas`.

Specified by:

putIfAbsent in interface RawKVClientBase

Parameters:

key - key

value - value

ttl - TTL of key (in seconds), 0 means the key will never be outdated.

Returns:

a ByteString. returns Optional.EMPTY if the value is written successfully. returns the previous key if the value already exists, and does not write to TiKV.

compareAndSet

public void compareAndSet(com.google.protobuf.ByteString key,
                          Optional<com.google.protobuf.ByteString> prevValue,
                          com.google.protobuf.ByteString value)
                   throws RawCASConflictException

Description copied from interface: RawKVClientBase

Put a key-value pair if the prevValue matched the value in TiKV. This API is atomic.

To use this API, please enable `tikv.enable_atomic_for_cas`.

Specified by:

compareAndSet in interface RawKVClientBase

Parameters:

key - key

value - value

Throws:

RawCASConflictException

compareAndSet

public void compareAndSet(com.google.protobuf.ByteString key,
                          Optional<com.google.protobuf.ByteString> prevValue,
                          com.google.protobuf.ByteString value,
                          long ttl)
                   throws RawCASConflictException

Description copied from interface: RawKVClientBase

pair if the prevValue matched the value in TiKV. This API is atomic.

To use this API, please enable `tikv.enable_atomic_for_cas`.

Specified by:

compareAndSet in interface RawKVClientBase

Parameters:

key - key

value - value

ttl - TTL of key (in seconds), 0 means the key will never be outdated.

Throws:

RawCASConflictException

batchPut

public void batchPut(Map<com.google.protobuf.ByteString,com.google.protobuf.ByteString> kvPairs)

Description copied from interface: RawKVClientBase

Put a set of raw key-value pair to TiKV.

Specified by:

batchPut in interface RawKVClientBase

Parameters:

kvPairs - kvPairs

batchPut

public void batchPut(Map<com.google.protobuf.ByteString,com.google.protobuf.ByteString> kvPairs,
                     long ttl)

Description copied from interface: RawKVClientBase

Put a set of raw key-value pair to TiKV.

Specified by:

batchPut in interface RawKVClientBase

Parameters:

kvPairs - kvPairs

ttl - the TTL of keys to be put (in seconds), 0 means the keys will never be outdated

get

public Optional<com.google.protobuf.ByteString> get(com.google.protobuf.ByteString key)

Description copied from interface: RawKVClientBase

Get a raw key-value pair from TiKV if key exists

Specified by:

get in interface RawKVClientBase

Parameters:

key - raw key

Returns:

a ByteString value if key exists, ByteString.EMPTY if key does not exist

batchGet

public List<Kvrpcpb.KvPair> batchGet(List<com.google.protobuf.ByteString> keys)

Description copied from interface: RawKVClientBase

Get a list of raw key-value pair from TiKV if key exists

Specified by:

batchGet in interface RawKVClientBase

Parameters:

keys - list of raw key

Returns:

a ByteString value if key exists, ByteString.EMPTY if key does not exist

batchDelete

public void batchDelete(List<com.google.protobuf.ByteString> keys)

Description copied from interface: RawKVClientBase

Delete a list of raw key-value pair from TiKV if key exists

Specified by:

batchDelete in interface RawKVClientBase

Parameters:

keys - list of raw key

getKeyTTL

public Optional<Long> getKeyTTL(com.google.protobuf.ByteString key)

Description copied from interface: RawKVClientBase

Get the TTL of a raw key from TiKV if key exists

Specified by:

getKeyTTL in interface RawKVClientBase

Parameters:

key - raw key

Returns:

a Long indicating the TTL of key ttl is a non-null long value indicating TTL if key exists. - ttl=0 if the key will never be outdated. - ttl=null if the key does not exist

batchScanKeys

public List<List<com.google.protobuf.ByteString>> batchScanKeys(List<Pair<com.google.protobuf.ByteString,com.google.protobuf.ByteString>> ranges,
                                                                int eachLimit)

Description copied from interface: RawKVClientBase

Create a new `batch scan` request with `keyOnly` option Once resolved this request will result in a set of scanners over the given keys.

WARNING: This method is experimental. The `each_limit` parameter does not work as expected. It does not limit the number of results returned of each range, instead it limits the number of results in each region of each range. As a result, you may get more than each_limit key-value pairs for each range. But you should not miss any entries.

Specified by:

batchScanKeys in interface RawKVClientBase

Parameters:

ranges - a list of ranges

Returns:

a set of scanners for keys over the given keys.

batchScan

public List<List<Kvrpcpb.KvPair>> batchScan(List<ScanOption> ranges)

Description copied from interface: RawKVClientBase

Create a new `batch scan` request. Once resolved this request will result in a set of scanners over the given keys.

WARNING: This method is experimental. The `each_limit` parameter does not work as expected. It does not limit the number of results returned of each range, instead it limits the number of results in each region of each range. As a result, you may get more than each_limit key-value pairs for each range. But you should not miss any entries.

Specified by:

batchScan in interface RawKVClientBase

Parameters:

ranges - a list of `ScanOption` for each range

Returns:

a set of scanners over the given keys.

scan

public List<Kvrpcpb.KvPair> scan(com.google.protobuf.ByteString startKey,
                                 com.google.protobuf.ByteString endKey,
                                 int limit)

Description copied from interface: RawKVClientBase

Scan raw key-value pairs from TiKV in range [startKey, endKey)

Specified by:

scan in interface RawKVClientBase

Parameters:

startKey - raw start key, inclusive

endKey - raw end key, exclusive

limit - limit of key-value pairs scanned, should be less than RawKVClientBase.MAX_RAW_SCAN_LIMIT

Returns:

list of key-value pairs in range

scan

public List<Kvrpcpb.KvPair> scan(com.google.protobuf.ByteString startKey,
                                 com.google.protobuf.ByteString endKey,
                                 int limit,
                                 boolean keyOnly)

Description copied from interface: RawKVClientBase

Scan raw key-value pairs from TiKV in range [startKey, endKey)

Specified by:

scan in interface RawKVClientBase

Parameters:

startKey - raw start key, inclusive

endKey - raw end key, exclusive

limit - limit of key-value pairs scanned, should be less than RawKVClientBase.MAX_RAW_SCAN_LIMIT

keyOnly - whether to scan in key-only mode

Returns:

list of key-value pairs in range

scan

public List<Kvrpcpb.KvPair> scan(com.google.protobuf.ByteString startKey,
                                 int limit)

Description copied from interface: RawKVClientBase

Scan raw key-value pairs from TiKV in range [startKey, ♾)

Specified by:

scan in interface RawKVClientBase

Parameters:

startKey - raw start key, inclusive

limit - limit of key-value pairs scanned, should be less than RawKVClientBase.MAX_RAW_SCAN_LIMIT

Returns:

list of key-value pairs in range

scan

public List<Kvrpcpb.KvPair> scan(com.google.protobuf.ByteString startKey,
                                 int limit,
                                 boolean keyOnly)

Description copied from interface: RawKVClientBase

Scan raw key-value pairs from TiKV in range [startKey, ♾)

Specified by:

scan in interface RawKVClientBase

Parameters:

startKey - raw start key, inclusive

limit - limit of key-value pairs scanned, should be less than RawKVClientBase.MAX_RAW_SCAN_LIMIT

keyOnly - whether to scan in key-only mode

Returns:

list of key-value pairs in range

scan

public List<Kvrpcpb.KvPair> scan(com.google.protobuf.ByteString startKey,
                                 com.google.protobuf.ByteString endKey)

Description copied from interface: RawKVClientBase

Scan all raw key-value pairs from TiKV in range [startKey, endKey)

Specified by:

scan in interface RawKVClientBase

Parameters:

startKey - raw start key, inclusive

endKey - raw end key, exclusive

Returns:

list of key-value pairs in range

scan

public List<Kvrpcpb.KvPair> scan(com.google.protobuf.ByteString startKey,
                                 com.google.protobuf.ByteString endKey,
                                 boolean keyOnly)

Description copied from interface: RawKVClientBase

Scan all raw key-value pairs from TiKV in range [startKey, endKey)

Specified by:

scan in interface RawKVClientBase

Parameters:

startKey - raw start key, inclusive

endKey - raw end key, exclusive

keyOnly - whether to scan in key-only mode

Returns:

list of key-value pairs in range

scanPrefix

public List<Kvrpcpb.KvPair> scanPrefix(com.google.protobuf.ByteString prefixKey,
                                       int limit,
                                       boolean keyOnly)

Description copied from interface: RawKVClientBase

Scan keys with prefix

Specified by:

scanPrefix in interface RawKVClientBase

Parameters:

prefixKey - prefix key

limit - limit of keys retrieved

keyOnly - whether to scan in keyOnly mode

Returns:

kvPairs with the specified prefix

scanPrefix

public List<Kvrpcpb.KvPair> scanPrefix(com.google.protobuf.ByteString prefixKey)

Specified by:

scanPrefix in interface RawKVClientBase

scanPrefix

public List<Kvrpcpb.KvPair> scanPrefix(com.google.protobuf.ByteString prefixKey,
                                       boolean keyOnly)

Specified by:

scanPrefix in interface RawKVClientBase

delete

public void delete(com.google.protobuf.ByteString key)

Description copied from interface: RawKVClientBase

Delete a raw key-value pair from TiKV if key exists

Specified by:

delete in interface RawKVClientBase

Parameters:

key - raw key to be deleted

deleteRange

public void deleteRange(com.google.protobuf.ByteString startKey,
                        com.google.protobuf.ByteString endKey)

Description copied from interface: RawKVClientBase

Delete all raw key-value pairs in range [startKey, endKey) from TiKV

Cautious, this API cannot be used concurrently, if multiple clients write keys into this range along with deleteRange API, the result will be undefined.

Specified by:

deleteRange in interface RawKVClientBase

Parameters:

startKey - raw start key to be deleted

endKey - raw start key to be deleted

deletePrefix

public void deletePrefix(com.google.protobuf.ByteString key)

Description copied from interface: RawKVClientBase

Delete all raw key-value pairs with the prefix `key` from TiKV

Cautious, this API cannot be used concurrently, if multiple clients write keys into this range along with deleteRange API, the result will be undefined.

Specified by:

deletePrefix in interface RawKVClientBase

Parameters:

key - prefix of keys to be deleted

getSession

public TiSession getSession()

Description copied from interface: RawKVClientBase

Get the session of the current client

Specified by:

getSession in interface RawKVClientBase

ingest

public void ingest(List<Pair<com.google.protobuf.ByteString,com.google.protobuf.ByteString>> list)

Ingest KV pairs to RawKV using StreamKV API.

Parameters:

list -

ingest

public void ingest(List<Pair<com.google.protobuf.ByteString,com.google.protobuf.ByteString>> list,
                   Long ttl)
            throws GrpcException

Ingest KV pairs to RawKV using StreamKV API.

Parameters:

list -

ttl - the ttl of the key (in seconds), 0 means the key will never be outdated

Throws:

GrpcException

scan0

public Iterator<Kvrpcpb.KvPair> scan0(com.google.protobuf.ByteString startKey,
                                      com.google.protobuf.ByteString endKey,
                                      int limit)

Scan raw key-value pairs from TiKV in range [startKey, endKey)

Parameters:

startKey - raw start key, inclusive

endKey - raw end key, exclusive

limit - limit of key-value pairs scanned, should be less than RawKVClientBase.MAX_RAW_SCAN_LIMIT

Returns:

iterator of key-value pairs in range

scan0

public Iterator<Kvrpcpb.KvPair> scan0(com.google.protobuf.ByteString startKey,
                                      int limit)

Scan raw key-value pairs from TiKV in range [startKey, ♾)

Parameters:

startKey - raw start key, inclusive

limit - limit of key-value pairs scanned, should be less than RawKVClientBase.MAX_RAW_SCAN_LIMIT

Returns:

iterator of key-value pairs in range

scan0

public Iterator<Kvrpcpb.KvPair> scan0(com.google.protobuf.ByteString startKey,
                                      int limit,
                                      boolean keyOnly)

Scan raw key-value pairs from TiKV in range [startKey, ♾)

Parameters:

startKey - raw start key, inclusive

limit - limit of key-value pairs scanned, should be less than RawKVClientBase.MAX_RAW_SCAN_LIMIT

keyOnly - whether to scan in key-only mode

Returns:

iterator of key-value pairs in range

scan0

public Iterator<Kvrpcpb.KvPair> scan0(com.google.protobuf.ByteString startKey,
                                      com.google.protobuf.ByteString endKey,
                                      int limit,
                                      boolean keyOnly)

Scan raw key-value pairs from TiKV in range [startKey, endKey)

Parameters:

startKey - raw start key, inclusive

endKey - raw end key, exclusive

limit - limit of key-value pairs scanned, should be less than RawKVClientBase.MAX_RAW_SCAN_LIMIT

keyOnly - whether to scan in key-only mode

Returns:

iterator of key-value pairs in range

scan0

public Iterator<Kvrpcpb.KvPair> scan0(com.google.protobuf.ByteString startKey,
                                      com.google.protobuf.ByteString endKey)

Scan all raw key-value pairs from TiKV in range [startKey, endKey)

Parameters:

startKey - raw start key, inclusive

endKey - raw end key, exclusive

Returns:

iterator of key-value pairs in range

scanPrefix0

public Iterator<Kvrpcpb.KvPair> scanPrefix0(com.google.protobuf.ByteString prefixKey,
                                            int limit,
                                            boolean keyOnly)

Scan keys with prefix

Parameters:

prefixKey - prefix key

limit - limit of keys retrieved

keyOnly - whether to scan in keyOnly mode

Returns:

kvPairs iterator with the specified prefix

scanPrefix0

public Iterator<Kvrpcpb.KvPair> scanPrefix0(com.google.protobuf.ByteString prefixKey)

scanPrefix0

public Iterator<Kvrpcpb.KvPair> scanPrefix0(com.google.protobuf.ByteString prefixKey,
                                            boolean keyOnly)

scan0

public Iterator<Kvrpcpb.KvPair> scan0(com.google.protobuf.ByteString startKey,
                                      com.google.protobuf.ByteString endKey,
                                      boolean keyOnly)

Scan all raw key-value pairs from TiKV in range [startKey, endKey)

Parameters:

startKey - raw start key, inclusive

endKey - raw end key, exclusive

keyOnly - whether to scan in key-only mode

Returns:

iterator of key-value pairs in range