create Method
Description
Creates a new TSDB table.
Syntax
create(backend, table, if_exists=FAIL, **kw)
The following syntax statement replaces the
create(backend, table, if_exists=FAIL, rate[, aggregates, aggregation_granularity])
The method has additional parameters that aren't currently supported for the TSDB backend. Therefore, when calling the method, be sure to explicitly specify the names of all parameters after
Parameters
- backend
The backend type —
"tsdb"for the TSDB backend. See Backend Types.- Type:
str
- Requirement: Required
- Type:
- table
The relative path to the backend data — a directory in the target data container (as configured for the client object) that represents a TSDB table. For example,
"mytable"or"examples/tsdb/my_metrics".- Type:
str
- Requirement: Required
- Type:
- if_exists
Determines whether to raise an error when the specified TSDB table (
table ) already exists.Type:
pb.ErrorOptionsenumeration. To use the enumeration, import theframes_pb2module; for example:from v3io_frames import frames_pb2 as fpb
- Requirement: Optional
- Valid Values:
FAILto raise an error when the specified table already exists;IGNOREto ignore this
- Default Value:
FAIL
- kw
This parameter is used for passing a variable-length list of additional keyword (named) arguments. See the following kw Arguments section for a list of additional arguments that are supported for the TSDB backend via the
kw parameter.- Type:
**— variable-length keyword arguments list
- Requirement: Required
- Type:
kw Arguments
The TSDB backend supports the following
- rate
The ingestion rate of the TSDB metric samples. It's recommended that you set the rate to the average expected ingestion rate for a unique label set (for example, for a single server in a data center), and that the ingestion rates for a given TSDB table don't vary significantly; when there's a big difference in the ingestion rates (for example, x10), consider using separate TSDB tables.
- Type:
str
- Requirement: Required
- Valid Values: A string of the format
"[0-9]+/[smh]"— where 's' = seconds, 'm' = minutes, and 'h' = hours. For example,"1/s"(one sample per minute),"20/m"(20 samples per minute), or"50/h"(50 samples per hour).
- Type:
- aggregates
A list of aggregation functions ("aggregators") for performing over-time aggregation in real time during the metric-samples ingestion ("pre-aggregation"). Over-time aggregation returns an aggregation time series for each unique metric label set. The aggregations results are stored in the TSDB table as array attributes ("pre-aggregates") and used to handle relevant aggregation queries. Use the
aggregation_granularity argument to configure the table's pre-aggregation granularity — the time interval for applying these aggregations.NoteYou can also perform aggregation queries for TSDB tables without pre-aggregates, but when configured correctly, pre-aggregation queries are more efficient. To ensure that pre-aggregation is used to process aggregation queries and improve performance —
- When creating the TSDB table, set its aggregation granularity (
aggregation_granularity ) to an interval that's significantly larger than the table's metric-samples ingestion rate (rate ). - When querying the table using the
read method, set the aggregation window (which is currently the aggregation step — see thestep parameter) to a sufficient multiplier of the table's aggregation granularity.
For example, if the table's ingestion rate is 1 sample per second (
"1/s") and you want to use hourly queries (i.e., use a query aggregation window of"1h"), you might set the table's pre-aggregation granularity to 20 minutes ("20m").For more information about aggregation queries, see the
read method.- Type:
str
- Requirement: Optional
Valid Values: A string containing a comma-separated list of supported aggregation functions; for example,
"count,avg,min,max". The following aggregation functions are supported:avg — the average of the sample values.count — the number of ingested samples.last — the value of the last sample (i.e., the sample with the latest time).max — the maximal sample value.min — the minimal sample value.rate — the change rate of the sample values, which is calculated as<last sample value of the previous interval> - <last sample value of the current interval>) / <aggregation granularity>.stddev — the standard deviance of the sample values.stdvar — the standard variance of the sample values.sum — the sum of the sample values.
- When creating the TSDB table, set its aggregation granularity (
- aggregation_granularity
The TSDB table's pre-aggregation granularity — i.e., the time interval for executing the aggregation functions that are configured in the
aggregatesargument for real-time aggregation during metric-samples ingestion.NoteTo get the expected pre-aggregation performance impact, the size of the aggregation-granularity interval (as set in the
aggregation_granularity argument) should be significantly larger than the size of the table's metric-samples ingestion rate (as set in therate argument). See theaggregates argument notes.- Type:
str
- Requirement: Optional
- Valid Values: A string of the format
"[0-9]+[mhd]"— where 'm' = minutes, 'h' = hours, and 'd' = days. For example,"30m"(30 minutes),"2h"(2 hours), or"1d"(1 day).
- Default Value:
"1h"(1 hour)
- Type:
Errors
In case of an error, the method raises a
Examples
Following are some usage examples for the
-
Create a TSDB table named "mytsdb" in the root directory of the client's data container (
table ) with an ingestion rate of 1 sample per second (rate ):tsdb_table = "mytsdb" client.create(backend="tsdb", table=tsdb_table, rate="1/s") -
Create a TSDB table named "my_metrics" in a
tsdb directory in the client's data container (table ) with an ingestion rate of 12 samples per hour (rate ). The table is created with thecount,avg,min, andmaxaggregation functions (aggregates ) and an aggregation granularity of 1 hour (aggregation_granularity ):tsdb_table = "/tsdb/my_metrics" client.create("tsdb", table=tsdb_table, rate="12/h", aggregates="count,avg,min,max", aggregation_granularity= "1h")