Struct tikv_client::RawClient

pub struct RawClient<PdC: PdClient = PdRpcClient> { /* private fields */ }

The TiKV raw Client is used to interact with TiKV using raw requests.

Raw requests don’t need a wrapping transaction. Each request is immediately processed once executed.

The returned results of raw request methods are Futures that must be awaited to execute.

Implementations

impl Client<PdRpcClient>

pub async fn new<S: Into<String>>(pd_endpoints: Vec<S>) -> Result<Self>

Create a raw Client and connect to the TiKV cluster.

Because TiKV is managed by a PD cluster, the endpoints for PD must be provided, not the TiKV nodes. It’s important to include more than one PD endpoint (include all endpoints, if possible), this helps avoid having a single point of failure.

Examples

let client = RawClient::new(vec!["192.168.0.100"]).await.unwrap();

pub async fn new_with_config<S: Into<String>>( pd_endpoints: Vec<S>, config: Config, ) -> Result<Self>

Create a raw Client with a custom configuration, and connect to the TiKV cluster.

Because TiKV is managed by a PD cluster, the endpoints for PD must be provided, not the TiKV nodes. It’s important to include more than one PD endpoint (include all endpoints, if possible), this helps avoid having a single point of failure.

Examples

let client = RawClient::new_with_config(
    vec!["192.168.0.100"],
    Config::default().with_timeout(Duration::from_secs(60)),
)
.await
.unwrap();

pub fn with_cf(&self, cf: ColumnFamily) -> Self

Create a new client which is a clone of self, but which uses an explicit column family for all requests.

This function returns a new Client; requests created with the new client will use the supplied column family. The original Client can still be used (without the new column family).

By default, raw clients use the Default column family.

Examples

let client = RawClient::new(vec!["192.168.0.100"])
    .await
    .unwrap()
    .with_cf(ColumnFamily::Write);
// Fetch a value at "foo" from the Write CF.
let get_request = client.get("foo".to_owned());

pub fn with_backoff(&self, backoff: Backoff) -> Self

Set the Backoff strategy for retrying requests. The default strategy is DEFAULT_REGION_BACKOFF. See Backoff for more information.

Examples

let client = RawClient::new(vec!["192.168.0.100"])
    .await
    .unwrap()
    .with_backoff(DEFAULT_REGION_BACKOFF);
// Fetch a value at "foo" from the Write CF.
let get_request = client.get("foo".to_owned());

pub fn with_atomic_for_cas(&self) -> Self

Set to use the atomic mode.

The only reason of using atomic mode is the compare_and_swap operation. To guarantee the atomicity of CAS, write operations like put or delete in atomic mode are more expensive. Some operations are not supported in the mode.

impl<PdC: PdClient> Client<PdC>

pub async fn get(&self, key: impl Into<Key>) -> Result<Option<Value>>

Create a new ‘get’ request.

Once resolved this request will result in the fetching of the value associated with the given key.

Retuning Ok(None) indicates the key does not exist in TiKV.

Examples

let key = "TiKV".to_owned();
let req = client.get(key);
let result: Option<Value> = req.await.unwrap();

pub async fn batch_get( &self, keys: impl IntoIterator<Item = impl Into<Key>>, ) -> Result<Vec<KvPair>>

Create a new ‘batch get’ request.

Once resolved this request will result in the fetching of the values associated with the given keys.

Non-existent entries will not appear in the result. The order of the keys is not retained in the result.

Examples

let keys = vec!["TiKV".to_owned(), "TiDB".to_owned()];
let req = client.batch_get(keys);
let result: Vec<KvPair> = req.await.unwrap();

pub async fn get_key_ttl_secs(&self, key: impl Into<Key>) -> Result<Option<u64>>

Create a new ‘get key ttl’ request.

Once resolved this request will result in the fetching of the alive time left for the given key.

Retuning Ok(None) indicates the key does not exist in TiKV.

Examples

use tikv_client::{Value, Config, RawClient};

use futures::prelude::*;

futures::executor::block_on(async {

let client = RawClient::new(vec![“192.168.0.100”]).await.unwrap();

let key = “TiKV”.to_owned(); let req = client.get_key_ttl_secs(key); let result: Option = req.await.unwrap();

});

pub async fn put( &self, key: impl Into<Key>, value: impl Into<Value>, ) -> Result<()>

Create a new ‘put’ request.

Once resolved this request will result in the setting of the value associated with the given key.

Examples

let key = "TiKV".to_owned();
let val = "TiKV".to_owned();
let req = client.put(key, val);
let result: () = req.await.unwrap();

pub async fn put_with_ttl( &self, key: impl Into<Key>, value: impl Into<Value>, ttl_secs: u64, ) -> Result<()>

pub async fn batch_put( &self, pairs: impl IntoIterator<Item = impl Into<KvPair>>, ) -> Result<()>

Create a new ‘batch put’ request.

Once resolved this request will result in the setting of the values associated with the given keys.

Examples

let kvpair1 = ("PD".to_owned(), "Go".to_owned());
let kvpair2 = ("TiKV".to_owned(), "Rust".to_owned());
let iterable = vec![kvpair1, kvpair2];
let req = client.batch_put(iterable);
let result: () = req.await.unwrap();

pub async fn batch_put_with_ttl( &self, pairs: impl IntoIterator<Item = impl Into<KvPair>>, ttls: impl IntoIterator<Item = u64>, ) -> Result<()>

pub async fn delete(&self, key: impl Into<Key>) -> Result<()>

Create a new ‘delete’ request.

Once resolved this request will result in the deletion of the given key.

It does not return an error if the key does not exist in TiKV.

Examples

let key = "TiKV".to_owned();
let req = client.delete(key);
let result: () = req.await.unwrap();

pub async fn batch_delete( &self, keys: impl IntoIterator<Item = impl Into<Key>>, ) -> Result<()>

Create a new ‘batch delete’ request.

Once resolved this request will result in the deletion of the given keys.

It does not return an error if some of the keys do not exist and will delete the others.

Examples

let keys = vec!["TiKV".to_owned(), "TiDB".to_owned()];
let req = client.batch_delete(keys);
let result: () = req.await.unwrap();

pub async fn delete_range(&self, range: impl Into<BoundRange>) -> Result<()>

Create a new ‘delete range’ request.

Once resolved this request will result in the deletion of all keys lying in the given range.

Examples

let inclusive_range = "TiKV"..="TiDB";
let req = client.delete_range(inclusive_range.into_owned());
let result: () = req.await.unwrap();

pub async fn scan( &self, range: impl Into<BoundRange>, limit: u32, ) -> Result<Vec<KvPair>>

Create a new ‘scan’ request.

Once resolved this request will result in a Vec of key-value pairs that lies in the specified range.

If the number of eligible key-value pairs are greater than limit, only the first limit pairs are returned, ordered by the key.

Examples

let inclusive_range = "TiKV"..="TiDB";
let req = client.scan(inclusive_range.into_owned(), 2);
let result: Vec<KvPair> = req.await.unwrap();

pub async fn scan_reverse( &self, range: impl Into<BoundRange>, limit: u32, ) -> Result<Vec<KvPair>>

Create a new ‘scan’ request but scans in “reverse” direction.

Once resolved this request will result in a Vec of key-value pairs that lies in the specified range.

If the number of eligible key-value pairs are greater than limit, only the first limit pairs are returned, ordered by the key.

Reverse Scan queries continuous kv pairs in range [startKey, endKey), from startKey(lowerBound) to endKey(upperBound) in reverse order, up to limit pairs. The returned keys are in reversed lexicographical order. If you want to include the endKey or exclude the startKey, push a ‘\0’ to the key. It doesn’t support Scanning from “”, because locating the last Region is not yet implemented.

Examples

let inclusive_range = "TiKV"..="TiDB";
let req = client.scan_reverse(inclusive_range.into_owned(), 2);
let result: Vec<KvPair> = req.await.unwrap();

pub async fn scan_keys( &self, range: impl Into<BoundRange>, limit: u32, ) -> Result<Vec<Key>>

Create a new ‘scan’ request that only returns the keys.

Once resolved this request will result in a Vec of keys that lies in the specified range.

If the number of eligible keys are greater than limit, only the first limit pairs are returned, ordered by the key.

Examples

let inclusive_range = "TiKV"..="TiDB";
let req = client.scan_keys(inclusive_range.into_owned(), 2);
let result: Vec<Key> = req.await.unwrap();

pub async fn scan_keys_reverse( &self, range: impl Into<BoundRange>, limit: u32, ) -> Result<Vec<Key>>

Create a new ‘scan’ request that only returns the keys in reverse order.

Once resolved this request will result in a Vec of keys that lies in the specified range.

If the number of eligible keys are greater than limit, only the first limit pairs are returned, ordered by the key.

Examples

let inclusive_range = "TiKV"..="TiDB";
let req = client.scan_keys(inclusive_range.into_owned(), 2);
let result: Vec<Key> = req.await.unwrap();

pub async fn batch_scan( &self, ranges: impl IntoIterator<Item = impl Into<BoundRange>>, each_limit: u32, ) -> Result<Vec<KvPair>>

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.

Examples

let inclusive_range1 = "TiDB"..="TiKV";
let inclusive_range2 = "TiKV"..="TiSpark";
let iterable = vec![inclusive_range1.into_owned(), inclusive_range2.into_owned()];
let req = client.batch_scan(iterable, 2);
let result = req.await;

pub async fn batch_scan_keys( &self, ranges: impl IntoIterator<Item = impl Into<BoundRange>>, each_limit: u32, ) -> Result<Vec<Key>>

Create a new ‘batch scan’ request that only returns the keys.

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 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.

Examples

let inclusive_range1 = "TiDB"..="TiKV";
let inclusive_range2 = "TiKV"..="TiSpark";
let iterable = vec![inclusive_range1.into_owned(), inclusive_range2.into_owned()];
let req = client.batch_scan(iterable, 2);
let result = req.await;

pub async fn compare_and_swap( &self, key: impl Into<Key>, previous_value: impl Into<Option<Value>>, new_value: impl Into<Value>, ) -> Result<(Option<Value>, bool)>

Create a new atomic ‘compare and set’ request.

Once resolved this request will result in an atomic `compare and set’ operation for the given key.

If the value retrived is equal to current_value, new_value is written.

Return Value

A tuple is returned if successful: the previous value and whether the value is swapped

pub async fn coprocessor( &self, copr_name: impl Into<String>, copr_version_req: impl Into<String>, ranges: impl IntoIterator<Item = impl Into<BoundRange>>, request_builder: impl Fn(Region, Vec<Range<Key>>) -> Vec<u8> + Send + Sync + 'static, ) -> Result<Vec<(Vec<Range<Key>>, Vec<u8>)>>

Trait Implementations

impl Clone for Client

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.