tikv
/
client-rust
mirror of https://github.com/tikv/client-rust.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: raw client 

Signed-off-by: ekexium <ekexium@gmail.com>
This commit is contained in:
ekexium 2020-11-06 15:24:12 +08:00
parent c7eeff9e4a
commit 8fec6fbf26
4 changed files with 47 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
mock-tikv/Cargo.toml
View File

@ -5,7 +5,7 @@ edition = "2018"
[dependencies]
derive-new = "0.5.8"
futures = "0.3"
futures = "0.3.5"
grpcio = { version = "0.6", features = [ "secure", "prost-codec" ], default-features = false }
log = "0.4"
tikv-client-proto = { path = "../tikv-client-proto"}

12
src/kv/bound_range.rs
View File

@ -19,10 +19,16 @@ use tikv_client_proto::kvrpcpb;
/// In TiKV, keys are an ordered sequence of bytes. This means we can have ranges over those
/// bytes. Eg `001` is before `010`.
///
/// **Minimum key**: there is the minimum key: empty key. So a range may not be unbounded below.
/// The unbounded lower bound in a [`Range`](Range) will be converted to an empty key.
///
/// **Maximum key**: There is no limit of the maximum key. When an empty key is used as the upper bound, it means upper unbounded.
/// The unbounded upper_bound in a [`Range`](Range). The range covering all keys is just `vec![]..`.
///
/// You don't have to know the real representation keys. The conversion from range types to `BoundRange` is intuitive.
/// `Into<BoundRange>` has implementations for common range types like `a..b`, `a..=b` where `a` and `b`
/// `impl Into<Key>`. You can implement `Into<BoundRange>` for your own types by using `try_from`.
///
/// Invariant: a range may not be unbounded below.
///
/// ```rust
/// # use std::ops::{Range, RangeInclusive, RangeTo, RangeToInclusive, RangeFrom, RangeFull, Bound};
@ -52,8 +58,8 @@ use tikv_client_proto::kvrpcpb;
/// ```
///
/// **But, you should not need to worry about all this:** Most functions which operate
/// on ranges will accept any types which implement `Into<BoundRange>`.
/// which means all of the above types can be passed directly to those functions.
/// on ranges will accept any types which implement `Into<BoundRange>`.
/// It means all of the above types can be passed directly to those functions.
#[derive(Clone, Debug, Eq, PartialEq)]
#[cfg_attr(test, derive(Arbitrary))]
pub struct BoundRange {

44
src/raw/client.rs
View File

@ -11,7 +11,13 @@ use std::{sync::Arc, u32};
const MAX_RAW_KV_SCAN_LIMIT: u32 = 10240;
/// The TiKV raw [`Client`](Client) is used to issue requests to the TiKV server and PD cluster.
/// 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 requests are [`Future`](std::future::Future)s that must be awaited to execute.
///
#[derive(Clone)]
pub struct Client {
rpc: Arc<PdRpcClient>,
@ -43,6 +49,10 @@ impl Client {
/// This function returns a new `Client`, requests created with it will have the
/// supplied column family constraint. The original `Client` can still be used.
///
/// By default, raw client uses the `Default` column family.
///
/// For normal users of the raw API, you don't need to use other column families.
///
/// ```rust,no_run
/// # use tikv_client::{Config, RawClient, ColumnFamily};
/// # use futures::prelude::*;
@ -65,7 +75,10 @@ impl Client {
/// This function returns a new `Client`, requests created with it will have the
/// supplied `key_only` option. The original `Client` can still be used. `key_only`
/// is only relevant for `scan`-like requests, for other kinds of request, it
/// will be ignored.
/// will be ignored.
/// With `key_only` being true, `scan`-like requests will ignore values.
///
/// By default, `key_only` is set to false.
///
/// ```rust,no_run
/// # use tikv_client::{Config, RawClient, ToOwnedRange};
@ -88,6 +101,8 @@ impl Client {
/// 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.
///
/// ```rust,no_run
/// # use tikv_client::{Value, Config, RawClient};
/// # use futures::prelude::*;
@ -107,8 +122,9 @@ impl Client {
/// 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 be skipped. The order of the keys is not retained.
/// given keys.
///
/// Non-existent entries will not appear in the result. The order of the keys is not retained in the result.
///
/// ```rust,no_run
/// # use tikv_client::{KvPair, Config, RawClient};
@ -152,7 +168,7 @@ impl Client {
/// Create a new 'batch put' request.
///
/// Once resolved this request will result in the setting of the value associated with the given key.
/// Once resolved this request will result in the setting of the values associated with the given keys.
///
/// ```rust,no_run
/// # use tikv_client::{Error, Result, KvPair, Key, Value, Config, RawClient, ToOwnedRange};
@ -178,7 +194,8 @@ impl Client {
/// 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.
///
/// It does not return an error if the key does not exist in TiKV.
///
/// ```rust,no_run
/// # use tikv_client::{Key, Config, RawClient};
@ -199,6 +216,7 @@ impl Client {
/// 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.
///
/// ```rust,no_run
@ -219,7 +237,7 @@ impl Client {
/// Create a new 'delete range' request.
///
/// Once resolved this request will result in the deletion of all keys over the given range `[start_key, end_key)`.
/// Once resolved this request will result in the deletion of all keys lying in the given range.
///
/// ```rust,no_run
/// # use tikv_client::{Key, Config, RawClient, ToOwnedRange};
@ -239,7 +257,11 @@ impl Client {
/// Create a new 'scan' request.
///
/// Once resolved this request will result in a scanner over the given keys.
/// 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.
///
///
/// ```rust,no_run
/// # use tikv_client::{KvPair, Config, RawClient, ToOwnedRange};
@ -268,6 +290,12 @@ impl Client {
/// 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.
///
/// ```rust,no_run
/// # use tikv_client::{Key, Config, RawClient, ToOwnedRange};

2
src/raw/mod.rs
View File

@ -2,7 +2,7 @@
//! Raw related functionality.
//!
//! Using the [`raw::Client`](raw::Client) you can utilize TiKV's raw interface.
//! Using the [`raw::Client`](client::Client) you can utilize TiKV's raw interface.
//!
//! This interface offers optimal performance as it does not require coordination with a timestamp
//! oracle, while the transactional interface does.