Create data models
LindormTSDB organizes data into databases and time series tables. This topic explains how to create both, and how to make the key decisions that affect query performance and storage costs.
Create a Lindorm time series database
Every Lindorm instance includes a database named default. Data written without specifying a database goes into default, which cannot be deleted.
Create additional databases to physically isolate datasets, or to apply different retention and storage settings per dataset. See CREATE DATABASE for the full syntax reference.
Each database supports three independent settings:
| Setting | Parameter | Description |
|---|---|---|
| Data TTL (time to live) | ttl | Number of days that data is retained. Omit to keep data indefinitely. |
| Partition interval | partition_interval | Time span covered by each partition. Default is 30 days. |
| Hot and cold data boundary | cold_boundary | Number of days after which data moves to cold storage. Must be less than ttl. |
Examples
Create a database with no expiry:
CREATE DATABASE DB1;Create a database with a 60-day TTL:
CREATE DATABASE DB2 WITH (ttl=60);Create a database with a 60-day TTL and a 30-day hot and cold data boundary:
CREATE DATABASE DB3 WITH (cold_boundary=30, ttl=60);Both ttl and cold_boundary are measured in days. cold_boundary must be smaller than ttl.
Partition a database by time
Time partitioning stores data in segments by time. Each partition contains the time-series index and data. A query's time range determines which partitions are accessed.
When creating periodic time series causes the number of time series to grow rapidly, enable time partitioning to prevent index bloat from large numbers of inactive, expired time series in the same partition.
Avoid setting a partition interval that is too short. The default interval is 30 days; 7 or 30 days are recommended.
| Partition interval | Recommendation |
|---|---|
| 7 days | Recommended |
| 30 days | Default; recommended |
Create a database with a 30-day partition interval:
CREATE DATABASE DB4 WITH (partition_interval=30);Change the partition interval of an existing database:
ALTER DATABASE DB4 WITH (partition_interval=60);Changing the partition interval does not take effect immediately. The last day of the data currently in the database becomes the end of the current partition, and a new partition starts the following day. The new interval applies only to new partitions; existing partitions are unchanged. Example: DB4 uses a 30-day interval. If Partition 1 contains days 1–30 and Partition 2 contains days 31–50 when you change the interval to 60 days, data from day 51 onward is stored in a new partition that can hold 60 days. Existing partitions 1 and 2 are unaffected.
Configure hot and cold storage
LindormTSDB can automatically move data older than a threshold to cost-effective cold storage. Set the threshold with the cold_boundary parameter (in days).
Before configuring a boundary, enable cold storage for the database.
Create a database with a 30-day boundary:
CREATE DATABASE DB5 WITH (cold_boundary=30);Update the boundary on an existing database:
ALTER DATABASE DB5 WITH (cold_boundary=30);Data moved to cold storage cannot be moved back to hot storage.
Data transfer runs asynchronously in the background. After you set or change the hot and cold data boundary, wait for the cold storage capacity metrics to reflect the change.
Create a time series table
A time series table has three types of columns:
| Column type | Purpose | Indexing |
|---|---|---|
Tag (VARCHAR TAG) | Identifies a time series; used in WHERE filters | LindormTSDB creates an inverted index for each tag column |
Timestamp (TIMESTAMP) | Records when a data point was observed | Required; used for time-range queries and partition pruning |
Field (DOUBLE, etc.) | Stores the measured value | Not indexed |
Before creating a table, model your business scenario and decide which columns to use as tags, the timestamp, and fields.
Choose tags vs. fields
Use a tag when the value:
Identifies or groups a time series (device ID, region, sensor type)
Appears in filter conditions (
WHERE tag = 'value')Has a bounded, predictable set of distinct values
Use a field when the value:
Is a numeric measurement that changes continuously (temperature, CPU usage)
Is unique or highly variable per data point
Avoid putting high-cardinality data—unique IDs, random strings, hashes—into tag columns. LindormTSDB creates an inverted index for each tag column, so an unbounded number of distinct tag values leads to index bloat and increased memory usage. Recommended: Use a bounded identifier such as region or sensor_type as a tag. Not recommended: Use a UUID or random hash as a tag value.
Choose a primary key
Use the PRIMARY KEY clause to specify the shard key. LindormTSDB hashes data by this key and routes it to different backend nodes. If a query condition includes the shard key, the query can go directly to the target node instead of being broadcast to all nodes.
A unique ID is usually a good choice for the primary key—for example, a device ID in an IoT scenario.
Examples
Create a sensor table without a primary key:
CREATE TABLE sensor (
device_id VARCHAR TAG,
region VARCHAR TAG,
time TIMESTAMP,
temperature DOUBLE,
humidity DOUBLE);Create a sensor table with device_id as the primary key:
CREATE TABLE sensor (
device_id VARCHAR TAG,
region VARCHAR TAG,
time TIMESTAMP,
temperature DOUBLE,
humidity DOUBLE,
PRIMARY KEY(device_id));For more background on data modeling, see Data model and Design a time series table.
Automatic table creation
The Java Native SDK, line-protocol writes, and multi-value writes that use TSDB-compatible APIs let you specify one of three schema constraint policies:
| Policy | Behavior |
|---|---|
| Strong constraint | Rejects writes to tables or columns that do not exist |
| Weak constraint | Creates missing tables or columns automatically; validates column types when columns exist |
| No constraint | No schema enforcement |
With the weak constraint policy, LindormTSDB creates the table or column on the first write. See Constraint policies for schemas for details.
Single-value and multi-value data models
By default, data written via the OpenTSDB protocol or TSDB APIs uses the single-value model. LindormTSDB does not support automatic table creation for this model.
Use the multi-value model instead. LindormTSDB optimizes its underlying storage for multi-value data, which improves read performance. The weak schema constraint policy can also create tables automatically for this model.