Struct Client

pub struct Client { /* private fields */ }

Sonnerie Client API

Implementations

impl Client

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.

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

Use a specific TCP connection to make a connection.

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

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

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.

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.

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

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)

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.

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

Discard and end the current transaction.

Same as drop, except you can see errors

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.

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

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.

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.

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.

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.

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.

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

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

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.

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.

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

impl Drop for Client

fn drop(&mut self)

Executes the destructor for this type.