Struct sonnerie_api::Client
source · pub struct Client { /* private fields */ }
Expand description
Sonnerie Client API
Implementations
sourceimpl Client
impl Client
sourcepub fn from_streams<R: 'static + Read + NBSocket, W: 'static + Write + NBSocket>(
reader: R,
writer: W
) -> Result<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.
sourcepub fn new_tcp(connection: TcpStream) -> Result<Client>
pub fn new_tcp(connection: TcpStream) -> Result<Client>
Use a specific TCP connection to make a connection.
sourcepub fn new_unix(connection: UnixStream) -> Result<Client>
pub fn new_unix(connection: UnixStream) -> Result<Client>
Use a specific Unix Domain Socket connection to make a connection.
sourcepub fn begin_read(&self) -> Result<()>
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.
sourcepub fn begin_write(&self) -> Result<()>
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.
sourcepub fn read_series_range_to<F>(
&mut self,
name: &str,
first_time: &NaiveDateTime,
last_time: &NaiveDateTime,
to: F
) -> Result<()>where
F: FnMut(NaiveDateTime, &[Column<'_>]),
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 fromlast_time
is the last timestamp to read (inclusive)to
is a callback function which receives each row
sourcepub fn read_series_range(
&mut self,
name: &str,
first_time: &NaiveDateTime,
last_time: &NaiveDateTime
) -> Result<Vec<(NaiveDateTime, Vec<OwnedColumn>)>>
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 fromlast_time
is the last timestamp to read (inclusive)
sourcepub fn read_series(
&mut self,
name: &str
) -> Result<Vec<(NaiveDateTime, Vec<OwnedColumn>)>>
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.
sourcepub fn rollback(&self) -> Result<()>
pub fn rollback(&self) -> Result<()>
Discard and end the current transaction.
Same as drop
, except you can see errors
sourcepub fn format(&self, series: &str) -> Result<String>
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.
sourcepub fn commit(&self) -> Result<()>
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()
.
sourcepub fn create_series(&mut self, name: &str, format: &str) -> Result<()>
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.
sourcepub fn add_value<V: FromValue>(
&mut self,
series_name: &str,
time: &NaiveDateTime,
value: V
) -> Result<()>
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 bycreate_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.
sourcepub fn add_row_raw(
&mut self,
series_name: &str,
time: &NaiveDateTime,
row: &str
) -> Result<()>
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 bycreate_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.
sourcepub fn add_rows<'s>(&'s mut self, series_name: &str) -> Result<RowAdder<'s>>
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.
sourcepub fn create_and_add<'s>(&'s mut self) -> Result<CreateAdder<'s>>
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.
sourcepub fn dump<F>(&mut self, like: &str, results: F) -> Result<()>where
F: FnMut(&str, NaiveDateTime, &[Column<'_>]),
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 with192.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).
sourcepub fn read_direction_like<F>(
&mut self,
like: &str,
timestamp: &NaiveDateTime,
direction: Direction,
results: F
) -> Result<()>where
F: FnMut(&str, NaiveDateTime, &[Column<'_>]),
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 with192.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 oftimestamp
(Direction::Forward
) or to the past oftimestamp
(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).
sourcepub fn erase_range(
&mut self,
series_name: &str,
first_time: &NaiveDateTime,
last_time: &NaiveDateTime
) -> Result<()>
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 failsfirst_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.
sourcepub fn erase_range_like(
&mut self,
like: &str,
first_time: &NaiveDateTime,
last_time: &NaiveDateTime
) -> Result<()>
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 with192.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.
sourcepub fn dump_range<F>(
&mut self,
like: &str,
first_time: &NaiveDateTime,
last_time: &NaiveDateTime,
results: F
) -> Result<()>where
F: FnMut(&str, NaiveDateTime, &[Column<'_>]),
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 with192.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).