Use Tablestore SDK for Go to create a time series table - Tablestore

You can call the CreateTimeseriesTable operation to create a time series table. When you create a time series table, you can specify the time to live (TTL) of data in the time series table, configuration information of time series metadata, custom time series identifiers, and custom data fields as the primary key columns of the time series table. You can also create a Lastpoint index and an analytical store. The analytical store can be used to quickly analyze time series data. The Lastpoint index can be used to quickly retrieve data of the latest point in time in time series in the time series table.

Prerequisites

An instance for the TimeSeries model is created. For more information, see Create an instance for the TimeSeries model.
Important
To use the analytical store or Lastpoint index feature, you must create an instance for the TimeSeries model in a region that supports the analytical store or Lastpoint index feature.
A client is initialized. For more information, see Initialize a Tablestore client.

Usage notes

The name of the time series table that you create cannot be the same as the name of an existing data table.
Note
You can call the ListTimeseriesTable operation to query the names of time series tables in an instance. For more information, see Query the names of time series tables.
You can create only one analytical store for a time series table.
The total number of Lastpoint indexes and analytical stores that you create for a time series table cannot exceed 10.
You can specify up to four data fields as the primary key columns of a time series table.
You can specify up to six fields as the fields of custom time series identifiers of a time series table.

Parameters

Parameter	Description
TimeseriesTableMeta	The configurations of the time series table. timeseriesTableName: the name of the time series table. timeseriesMetaOptions: the configurations of the time series metadata. The following parameters are included: metaTimeToLive: the TTL of the time series metadata. Unit: seconds. The value must be -1 or a value that is greater than or equal to 604800. A value of -1 specifies that the metadata never expires. A value of 604800 specifies 7 days. allowUpdateAttributes: specifies whether the property columns of the time series metadata can be modified. You can call the UpdateTimeseriesTable operation to modify the preceding parameters. timeseriesTableOptions: the configurations of the time series table. The following parameter is included: timeToLive: the TTL of the data in the time series table. Unit: seconds. If you do not want the data in the time series table to expire, set this parameter to -1. You can call the UpdateTimeseriesTable operation to modify this parameter. timeseriesKeys: the information of the custom time series identifiers. By default, the time series identifiers consist of the metric name, data source, and tags. For more information, see Specify custom time series identifiers and custom data fields as the primary key columns. This parameter is required when you specify custom time series identifiers. fieldPrimaryKeys: the data fields that are specified as the primary key columns. This parameter allows you to store multiple rows of time series data with the same time series identifiers and timestamp in a time series table. For more information, see Specify custom time series identifiers and custom data fields as the primary key columns. This parameter is required only when you want to store multiple rows of time series data with the same time series identifiers and timestamp in a time series table. lastpointIndexes: the name of the Lastpoint index. For more information, see Lastpoint index.
enableAnalyticalStore	Specifies whether to create the default analytical store. Default value: true, which specifies that the default analytical store is created. After you create an analytical store, you can use the analytical store to store time series data at low costs and query and analyze time series data. For more information, see Analytical store for time series. If you do not want to create an analytical store, set this parameter to false.
analyticalStores	The configurations of the analytical store, which consist of the following items: analyticalStoreName: the name of the analytical store. timeToLive: the TTL of the analytical store. Unit: seconds. You can set timeToLive to -1 or an int32 positive integer that is greater than or equal to 2592000. A value of -1 specifies that data in the analytical store never expires. A value of 2592000 specifies 30 days. syncOption: the data synchronization configuration. The value of this item is fixed to SYNC_TYPE_FULL.

Examples

Create a time series table without an analytical store

The following sample code provides an example on how to create a time series table:

/**
 * CreateTimeseriesTableSample is used to create a time series table. timeseriesTableName is used to specify the name of the time series table and timeTolive is used to specify the TTL of the time series table.
 */
func CreateTimeseriesTableSample(client *tablestore.TimeseriesClient, timeseriesTableName string , timeToLive int64) {
    fmt.Println("[Info]: Begin to create timeseries table: " , timeseriesTableName)

    // Construct the configuration information of the time series table.
    timeseriesTableOptions := tablestore.NewTimeseriesTableOptions(timeToLive) 

    // Construct the metadata information of the table.
    // Specify the name of the time series table.
    timeseriesTableMeta := tablestore.NewTimeseriesTableMeta(timeseriesTableName) 
    // Specify the configuration information of the time series table.
    timeseriesTableMeta.SetTimeseriesTableOptions(timeseriesTableOptions)    

    // Construct the request to create the time series table.
    createTimeseriesTableRequest := tablestore.NewCreateTimeseriesTableRequest()   
    createTimeseriesTableRequest.SetTimeseriesTableMeta(timeseriesTableMeta)
    // Specify that the default analytical store is not created.
    createTimeseriesTableRequest.SetEnableAnalyticalStore(false)  

    // Call the client to create the time series table.
    createTimeseriesTableResponse , err := client.CreateTimeseriesTable(createTimeseriesTableRequest) 
    if err != nil {
        fmt.Println("[Error]: Failed to create timeseries table with error: " , err)
        return
    }
    fmt.Println("[Info]: CreateTimeseriesTable finished! RequestId: " , createTimeseriesTableResponse.RequestId)
}

Create a time series table and an analytical store

When you create a time series table, you can create the default analytical store or a custom analytical store.

Create a time series table and the default analytical store

The following sample code provides an example on how to create a time series table and the default analytical store at the same time. In this example, the name of the default analytical store is fixed to default_analytical_store and data in the default analytical store never expires.

/**
 * CreateTimeseriesTableSample is used to create a time series table. timeseriesTableName is used to specify the name of the time series table and timeTolive is used to specify the TTL of the time series table.
 */
func CreateTimeseriesTableSample(client *tablestore.TimeseriesClient, timeseriesTableName string , timeToLive int64) {
    fmt.Println("[Info]: Begin to create timeseries table: " , timeseriesTableName)

    // Construct the configuration information of the time series table.
    timeseriesTableOptions := tablestore.NewTimeseriesTableOptions(timeToLive)        

    // Construct the metadata information of the table.
    // Specify the name of the time series table.
    timeseriesTableMeta := tablestore.NewTimeseriesTableMeta(timeseriesTableName)  
    // Specify the configuration information of the time series table.
    timeseriesTableMeta.SetTimeseriesTableOptions(timeseriesTableOptions)      

    // Construct the request to create the time series table.
    createTimeseriesTableRequest := tablestore.NewCreateTimeseriesTableRequest()    
    createTimeseriesTableRequest.SetTimeseriesTableMeta(timeseriesTableMeta)

    // Call the client to create the time series table.
    createTimeseriesTableResponse , err := client.CreateTimeseriesTable(createTimeseriesTableRequest)    
    if err != nil {
        fmt.Println("[Error]: Failed to create timeseries table with error: " , err)
        return
    }
    fmt.Println("[Info]: CreateTimeseriesTable finished! RequestId: " , createTimeseriesTableResponse.RequestId)
}

Create a time series table and a custom analytical store

The following sample code provides an example on how to create a time series table and a custom analytical store at the same time. In this example, the name of the custom analytical store is test_analytical_store and data in the custom analytical store never expires.

/**
 * CreateTimeseriesTableSample is used to create a time series table. timeseriesTableName is used to specify the name of the time series table and timeTolive is used to specify the TTL of the time series table. In this example, an analytical store named test_analytical_store is created.
 */
func CreateTimeseriesTableSample(client *tablestore.TimeseriesClient, timeseriesTableName string , timeToLive int64) {
    fmt.Println("[Info]: Begin to create timeseries table: " , timeseriesTableName)

    // Construct the configuration information of the time series table.
    timeseriesTableOptions := tablestore.NewTimeseriesTableOptions(timeToLive)    

    // Construct the metadata information of the table.
    // Specify the name of the time series table.
    timeseriesTableMeta := tablestore.NewTimeseriesTableMeta(timeseriesTableName)  
    // Specify the configuration information of the time series table.
    timeseriesTableMeta.SetTimeseriesTableOptions(timeseriesTableOptions)  

    // Construct the request to create the time series table.
    createTimeseriesTableRequest := tablestore.NewCreateTimeseriesTableRequest() 
    createTimeseriesTableRequest.SetTimeseriesTableMeta(timeseriesTableMeta)

    // Construct the configuration information of the analytical store.
    createTimeseriesTableRequest.SetAnalyticalStores([]*tablestore.TimeseriesAnalyticalStore{
        tablestore.NewTimeseriesAnalyticalStore("test_analytical_store"),
    })

    // Call the client to create the time series table.
    createTimeseriesTableResponse , err := client.CreateTimeseriesTable(createTimeseriesTableRequest) 
    if err != nil {
        fmt.Println("[Error]: Failed to create timeseries table with error: " , err)
        return
    }
    fmt.Println("[Info]: CreateTimeseriesTable finished! RequestId: " , createTimeseriesTableResponse.RequestId)
}

Specify custom time series identifiers and custom data fields as the primary key columns of a time series table

Important

The latest version of Tablestore SDK for Go allows you to specify custom time series identifiers and custom data fields as the primary key columns of a time series table. When you specify custom time series identifiers and custom data fields as the primary key columns of a time series table, make sure that you use the correct version of Tablestore SDK for Go.

The following sample code provides an example on how to create a time series table in which the time series identifiers consist of pk1 and pk2 and the field1 (Integer), field2 (String), and field3 (Binary) data fields are specified as the primary key columns:

/**
 * CreateTimeseriesTableSample is used to create a time series table. timeseriesTableName is used to specify the name of the time series table and timeTolive is used to specify the TTL of the time series table.
 */
func CreateTimeseriesTableSample(client *tablestore.TimeseriesClient, timeseriesTableName string, timeToLive int64) {
	fmt.Println("[Info]: Begin to create timeseries table: ", timeseriesTableName)

	timeseriesTableOptions := tablestore.NewTimeseriesTableOptions(timeToLive)
	timeseriesTableMeta := tablestore.NewTimeseriesTableMeta(timeseriesTableName)
	timeseriesTableMeta.SetTimeseriesTableOptions(timeseriesTableOptions)
	// Add custom time series identifiers.
	timeseriesTableMeta.AddTimeseriesKey("pk1")
	timeseriesTableMeta.AddTimeseriesKey("pk2")
	// Add data fields that are specified as the primary key columns of the time series table.
	timeseriesTableMeta.AddFieldPrimaryKey("field1", tablestore.PrimaryKeyType_INTEGER)
	timeseriesTableMeta.AddFieldPrimaryKey("field1", tablestore.PrimaryKeyType_STRING)
	timeseriesTableMeta.AddFieldPrimaryKey("field3", tablestore.PrimaryKeyType_BINARY)
	// Construct the request to create the time series table.
	createTimeseriesTableRequest := tablestore.NewCreateTimeseriesTableRequest()
	createTimeseriesTableRequest.SetTimeseriesTableMeta(timeseriesTableMeta)

	createTimeseriesTableResponse, err := client.CreateTimeseriesTable(createTimeseriesTableRequest)
	if err != nil {
		fmt.Println("[Error]: Failed to create timeseries table with error: ", err)
		return
	}
	fmt.Println("[Info]: CreateTimeseriesTable finished! RequestId: ", createTimeseriesTableResponse.RequestId)
}

Create a time series table and a Lastpoint index

Important

The latest version of Tablestore SDK for Go supports the Lastpoint index feature. When you use the Lastpoint index feature, make sure that you use the correct version of Tablestore SDK for Go.

The following sample code provides an example on how to create a time series table and a Lastpoint index named index1 for the time series table at the same time:

func createTimeseriesTable(client *tablestore.TimeseriesClient) {
	timeseriesTableMeta := tablestore.NewTimeseriesTableMeta("test_timeseries_table")
	timeseriesTableMeta.SetTimeseriesTableOptions(tablestore.NewTimeseriesTableOptions(-1))
	request := tablestore.NewCreateTimeseriesTableRequest()
	request.SetTimeseriesTableMeta(timeseriesTableMeta)
	request.SetLastpointIndexNames([]string{"index1"})
	_, err := client.CreateTimeseriesTable(request)
	if err != nil {
		log.Fatal(err)
	}
}

References

After you create a time series table, you can write time series data to the table and read time series data from the table. For more information, see Write time series data and Query time series data.
If you want to store time series data at low costs and quickly query and analyze time series data, you can create an analytical store for a time series table. For more information, see Create an analytical store.
You can modify the TTL of data in a time series table. For more information, see Update a time series table.
You can query all time series tables on the current instance. For more information, see Query the names of time series tables.
You can query the information about a time series table. For more information, see Query information of a time series table.
You can delete a time series table that you no longer require. For more information, see Delete a time series table.
To back up time series data in Tablestore in a cost-effective manner or export time series data as files to local devices, you can use the Data Integration feature of DataWorks to synchronize time series data from Tablestore to Object Storage Service (OSS) for storage or download. For more information, see Synchronize data from Tablestore to OSS.
To visualize time series data, you can connect Tablestore to Grafana. For more information, see Connect Tablestore to Grafana.
If you use Realtime Compute for Apache Flink to compute and analyze data, you can use Tablestore time series tables to store the results. For more information, see Tutorial (TimeSeries model).