Struct Client

Source
pub struct Client { /* private fields */ }
Expand description

Sonnerie Client API

Implementations§

Source§

impl Client

Source

pub fn from_streams<R: 'static + Read + NBSocket, W: 'static + Write + NBSocket>( reader: R, writer: W, ) -> Result<Client>

Create a Sonnerie client from a reader/writer stream.

This is useful if you want to connect to Sonnerie via a Unix Domain Socket tunnelled through SSH.

Failure may be caused by Sonnerie not sending its protocol “Hello” on connection.

Source

pub fn new_tcp(connection: TcpStream) -> Result<Client>

Use a specific TCP connection to make a connection.

Source

pub fn new_unix(connection: UnixStream) -> Result<Client>

Use a specific Unix Domain Socket connection to make a connection.

Source

pub fn begin_read(&self) -> Result<()>

Start a read transaction.

End the transaction with commit() or rollback(), which are both the same for a read transaction.

Read-only functions will automatically close and open a transaction, but calling this function allows you to not see changes made over the life if your transaction.

Transactions may not be nested.

Source

pub fn begin_write(&self) -> Result<()>

Create a writing transaction.

You must call this function before any calling any write functions. Write transactions are not made automatiicaly, to prevent you from accidentally making many small transactions, which are relatively slow.

You must call commit() for the transactions to be saved. You may also explicitly call rollback() to discard your changes.

Transactions may not be nested.

Source

pub fn read_series_range_to<F>( &mut self, name: &str, first_time: &NaiveDateTime, last_time: &NaiveDateTime, to: F, ) -> Result<()>
where F: FnMut(NaiveDateTime, &[Column<'_>]),

Read values within a range of timestamps in a specific series.

Fails if the series does not exist, but returns an empty Vec if no samples were contained in that range.

  • first_time is the first timestamp to begin reading from
  • last_time is the last timestamp to read (inclusive)
  • to is a callback function which receives each row
Source

pub fn read_series_range( &mut self, name: &str, first_time: &NaiveDateTime, last_time: &NaiveDateTime, ) -> Result<Vec<(NaiveDateTime, Vec<OwnedColumn>)>>

Read all the values in a specific series.

Fails if the series does not exist, but returns an empty Vec if no samples were contained in that range.

  • first_time is the first timestamp to begin reading from
  • last_time is the last timestamp to read (inclusive)
Source

pub fn read_series( &mut self, name: &str, ) -> Result<Vec<(NaiveDateTime, Vec<OwnedColumn>)>>

Read all the values in a specific series.

Fails if the series does not exist, but returns an empty Vec if the series does exist and is simply empty.

Source

pub fn rollback(&self) -> Result<()>

Discard and end the current transaction.

Same as drop, except you can see errors

Source

pub fn format(&self, series: &str) -> Result<String>

Read the format for a series

The string returned is the same specified as format in create_series().

Fails if the series doesn’t exist.

Source

pub fn commit(&self) -> Result<()>

Save and end the current transaction.

This must be called for any changes by a write transaction (that started by begin_write()) to be recorded.

In a read-only transaction, this is the same as rollback().

Source

pub fn create_series(&mut self, name: &str, format: &str) -> Result<()>

Ensures a series by the given name already exists.

Fails if the preexisting series has a different format, but otherwise does not fail.

format is a string, one character per column that defines how each sample in your time series is stored.

The permitted characters are:

  • f - a 32 bit float (f32)
  • F - a 64 bit float (f64)
  • u - a 32 bit unsigned integer (u32)
  • U - a 64 bit unsigned integer (u64)
  • i - a 32 bit signed integer (i32)
  • I - a 64 bit signed integer (i64)

For example, “FFii” stores a 4 column record with two 64-bit floats and two 32-bit signed integers.

Reading and writing to this series requires you to provide types that are compatible with the format string.

You must call begin_write() prior to this function.

Source

pub fn add_value<V: FromValue>( &mut self, series_name: &str, time: &NaiveDateTime, value: V, ) -> Result<()>

Adds a single value to a series

Fails if a value at the given timestamp already exists.

Fails if this series’s format doesn’t have exactly one column, and its type cannot be interpreted as compatible.

  • series_name is the name of the series, as created by create_series.
  • time is the point in time to add the sample, which must be unique (and also must be after all other timestamps in this series, until this feature is added which should be soon).
  • value is the sample to insert at this timepoint, and is interpreted according to the format for the series’s format.

You must call begin_write() prior to this function.

Source

pub fn add_row_raw( &mut self, series_name: &str, time: &NaiveDateTime, row: &str, ) -> Result<()>

Insert data that is parsed from a string

  • series_name is the name of the series, as created by create_series.
  • time is the point in time to add the sample, which must be unique (and also must be after all other timestamps in this series, until this feature is added which should be soon).
  • row is a space-delimited string whose values are parsed by column according to the series’s format.

This function panics if it the row contains a newline character.

You must call begin_write() prior to this function.

Source

pub fn add_rows<'s>(&'s mut self, series_name: &str) -> Result<RowAdder<'s>>

Efficiently add many samples into a timeseries.

Returns an object that can accept each row. The timestamps must be sorted ascending.

{
    // add rows with one column
    let mut adder = client.add_rows("fibonacci").unwrap();
    adder.row(&ts1, &[&1.0]);
    adder.row(&ts2, &[&1.0]);
    adder.row(&ts3, &[&2.0]);
    adder.row(&ts3, &[&3.0]);
}

{
    // add rows with two columns (in this case, a float and an integer)
    let mut adder = client.add_rows("san-francisco:temp-and-humidity").unwrap();
    adder.row(&ts1, &[&25.0, &45]);
    adder.row(&ts2, &[&24.5, &48]);
    adder.row(&ts3, &[&24.2, &49]);
    adder.row(&ts3, &[&23.9, &49]);
}

You must call begin_write() prior to this function.

Source

pub fn create_and_add<'s>(&'s mut self) -> Result<CreateAdder<'s>>

Add many rows, automatically creating the series if necessary.

Returns an object that can accept each row. The timestamps must be sorted ascending.

You must call begin_write() prior to this function.

Source

pub fn dump<F>(&mut self, like: &str, results: F) -> Result<()>
where F: FnMut(&str, NaiveDateTime, &[Column<'_>]),

Read all values from many series

Selects many series with an SQL-like “LIKE” operator and dumps values from those series.

  • like is a string with % as a wildcard. For example, "192.168.%" selects all series whose names start with 192.168.. If the % appears near the end, then the query is very efficient.
  • results is a function which receives each value.

Specify the types of the parameters to results, due to a Rust compiler bug.

The values are always generated first for each series in ascending order and then each timestamp in ascending order. (In other words, each series gets its own group of samples before moving to the following series).

Source

pub fn read_direction_like<F>( &mut self, like: &str, timestamp: &NaiveDateTime, direction: Direction, results: F, ) -> Result<()>
where F: FnMut(&str, NaiveDateTime, &[Column<'_>]),

Read the first value when searching from a specific timestamp

Selects many series with an SQL-like “LIKE” operator and outputs the dumps the value with a timestamp that is either less than or equal to, or greater than or equal to the given timestamp.

Returns at most one value per series.

  • like is a string with % as a wildcard. For example, "192.168.%" selects all series whose names start with 192.168.. If the % appears near the end, then the query is very efficient.
  • timestamp is the lower or upper bound of timestamps to consider.
  • direction indicates whether to search to the future of timestamp (Direction::Forward) or to the past of timestamp (Direction::Backward).
  • results is a function which receives each value.

by specifying max_time() for timestamp and a direction of Direction::Backward, you can get the most recent value for each series.

Specify the types of the parameters to results, due to a Rust compiler bug.

The values are always generated first for each series in ascending order and then each timestamp in ascending order. (In other words, each series gets its own group of samples before moving to the following series).

Source

pub fn erase_range( &mut self, series_name: &str, first_time: &NaiveDateTime, last_time: &NaiveDateTime, ) -> Result<()>

Erase a range of values from a series

  • series_name is the name of the series. If no such series exists, this function fails
  • first_time is the lower bound of timestamps to delete from.
  • last_time is the upper bound of timestamps (inclusive) to delete from.

Succeeds if the series was found, but there were no samples in that range.

Source

pub fn erase_range_like( &mut self, like: &str, first_time: &NaiveDateTime, last_time: &NaiveDateTime, ) -> Result<()>

Erase a range of values from each series whose matches a pattern.

  • like is a string with % as a wildcard. For example, "192.168.%" selects all series whose names start with 192.168.. If the % appears near the end, then the operation is more efficient.
  • first_time is the lower bound of timestamps to delete from.
  • last_time is the upper bound of timestamps (inclusive) to delete from.

Succeeds even if no series or timestamps were found within the given constraints.

Source

pub fn dump_range<F>( &mut self, like: &str, first_time: &NaiveDateTime, last_time: &NaiveDateTime, results: F, ) -> Result<()>
where F: FnMut(&str, NaiveDateTime, &[Column<'_>]),

Read many values from many series

Selects many series with an SQL-like “LIKE” operator and dumps values from those series.

  • like is a string with % as a wildcard. For example, "192.168.%" selects all series whose names start with 192.168.. If the % appears in the end, then the query is very efficient.
  • first_time is the first timestamp for which to print all values per series.
  • last_time is the last timestamp (inclusive) to print all values per series.
  • results is a function which receives each value.

Specify the types of the parameters to results, due to a Rust compiler bug.

The values are always generated first for each series in ascending order and then each timestamp in ascending order. (In other words, each series gets its own group of samples before moving to the following series).

Trait Implementations§

Source§

impl Drop for Client

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

impl !Freeze for Client

§

impl !RefUnwindSafe for Client

§

impl !Send for Client

§

impl !Sync for Client

§

impl Unpin for Client

§

impl !UnwindSafe for Client

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.