The ts_create_with_metadata() function

The ts_create_with_metadata() function creates a time series with user-defined metadata attached.

Syntax

ts_timeseries *
ts_create_with_metadata(MI_CONNECTION  *conn,
                       mi_string       *calname,
                       mi_datetime     *origin, 
                       mi_integer      threshold, 
                       mi_integer      flags, 
                       MI_TYPEID       *typeid,
                       mi_integer      nelem,
                       mi_string       *container,
                       mi_lvarchar     *metadata,
                       MI_TYPEID        *metadata_typeid)

ts_timeseries *
ts_create_with_metadata(MI_CONNECTION  *conn,
                       mi_string       *calname,
                       mi_datetime     *origin, 
                       mi_integer      threshold, 
                       MI_TYPEID       *typeid,
                       mi_integer      nelem,
                       mi_string       *container,
                       mi_lvarchar     *metadata,
                       MI_TYPEID        *metadata_typeid,
                       mi_integer      hertz)

ts_timeseries *
ts_create_with_metadata(MI_CONNECTION  *conn,
                       mi_string       *calname,
                       mi_datetime     *origin, 
                       mi_integer      threshold, 
                       mi_integer      flags, 
                       MI_TYPEID       *typeid,
                       mi_integer      nelem,
                       mi_string       *container,
                       mi_lvarchar     *metadata,
                       MI_TYPEID        *metadata_typeid,
                       mi_string        compression)

conn: A valid DataBlade® API connection.
calname: The name of the calendar.
origin: The time series origin.
threshold: The time series threshold. If the time series stores this number or more elements, it is stored in a container. If the time series holds fewer than this number, it is stored directly in the row that contains it. threshold must be greater than or equal to 0 and less than 256.
flags: 0 = Regular time series; 1 = Irregular time series; 3 = Hertz time series; 5 = Compressed time series
typeid: The ID of the new type for the time series to be created.
nelems: The initial number of elements to create space for in the time series. This space is reclaimed if not used, after the time series is written into the database.
container: The container for holding the time series. This parameter can be NULL if the time series can fit in a row or is not going to be assigned to a table.
metadata: The metadata to be put into the time series. For more information about metadata, see Creating a time series with metadata. Can be NULL.
metadata_typeid: The type ID of the metadata. Can be NULL if the metadata argument is NULL.
hertz (Optional): An integer 1-2047 or 100000 that specifies the number of records per second. Implicitly creates an irregular time series.; The value of the threshold parameter must be 0. The value of the flags parameter must be 3.
compression (Optional): A string that includes a compression definition for each column in the TimeSeries subtype except the first column. For the syntax of the compression parameter and descriptions of the compression types and attributes, see TSCreateIrr function.; The value of the threshold parameter must be 0. The value of the flags parameter must be 5.

Description

This function behaves the same as ts_create(), plus it saves the supplied metadata in the time series. The metadata can be NULL or a zero-length LVARCHAR; if either, ts_create_with_metadata() acts exactly like ts_create(). If the metadata pointer points to valid data, the metadata_typeid parameter must be a valid pointer to a valid type ID for a user-defined type.

If you include the hertz or compression parameter, you must run the ts_create() function within an explicit transaction.

The equivalent SQL function is TSCreate or TSCreateIrr.

Returns

A pointer to a new time series. The user can free this value by calling ts_free().