From 8fec6fbf26ddf445bc75b19efd4de8fd8fb06765 Mon Sep 17 00:00:00 2001 From: ekexium Date: Fri, 6 Nov 2020 15:24:12 +0800 Subject: [PATCH] doc: raw client Signed-off-by: ekexium --- mock-tikv/Cargo.toml | 2 +- src/kv/bound_range.rs | 12 +++++++++--- src/raw/client.rs | 44 +++++++++++++++++++++++++++++++++++-------- src/raw/mod.rs | 2 +- 4 files changed, 47 insertions(+), 13 deletions(-) diff --git a/mock-tikv/Cargo.toml b/mock-tikv/Cargo.toml index d2c3ab3..6bc11dd 100644 --- a/mock-tikv/Cargo.toml +++ b/mock-tikv/Cargo.toml @@ -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"} diff --git a/src/kv/bound_range.rs b/src/kv/bound_range.rs index 514cbfd..4cd6501 100644 --- a/src/kv/bound_range.rs +++ b/src/kv/bound_range.rs @@ -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` has implementations for common range types like `a..b`, `a..=b` where `a` and `b` /// `impl Into`. You can implement `Into` 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`. -/// which means all of the above types can be passed directly to those functions. +/// on ranges will accept any types which implement `Into`. +/// 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 { diff --git a/src/raw/client.rs b/src/raw/client.rs index 2246c5f..0841984 100644 --- a/src/raw/client.rs +++ b/src/raw/client.rs @@ -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, @@ -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}; diff --git a/src/raw/mod.rs b/src/raw/mod.rs index 55e4e47..b27063d 100644 --- a/src/raw/mod.rs +++ b/src/raw/mod.rs @@ -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.