Skip to content

data-types.md

Latest commit

History

History
258 lines (202 loc) · 8.02 KB

data-types.md

File metadata and controls

258 lines (202 loc) · 8.02 KB
Raw

IoTDB Data Types Support

This document describes the complete set of IoTDB data types supported by the Node.js client, based on the official Apache TSFile type definitions.

Supported Data Types

The IoTDB Node.js client supports all standard IoTDB data types as defined in Apache TSFile:

Type CodeType NameDescriptionJavaScript TypeStorage Size
0BOOLEANBoolean valueboolean1 byte
1INT3232-bit signed integernumber4 bytes
2INT6464-bit signed integerbigint8 bytes
3FLOAT32-bit floating pointnumber4 bytes
4DOUBLE64-bit floating pointnumber8 bytes
5TEXTUTF-8 encoded textstringVariable (4-byte length + content)
6VECTORVector data (not yet implemented)--
7UNKNOWNUnknown type (reserved)--
8TIMESTAMPTimestamp (milliseconds)Date8 bytes
9DATECalendar date (INT32 yyyyMMdd, e.g. 20240101 for 2024-01-01)Date4 bytes
10BLOBBinary dataBufferVariable (4-byte length + content)
11STRINGUTF-8 encoded stringstringVariable (4-byte length + content)
12OBJECTObject type (reserved)--

Note: Types 0-5, 8-11 are fully supported. Types 6, 7, and 12 are reserved for future use.

Reference

Type definitions are based on:

Usage Examples

Creating Timeseries

import{Session}from'@iotdb/client';constsession=newSession({host: 'localhost',port: 6667,username: 'root',password: 'root'});awaitsession.open();// Create databaseawaitsession.executeNonQueryStatement('CREATE DATABASE root.test');// Create timeseries with different data typesawaitsession.executeNonQueryStatement('CREATE TIMESERIES root.test.device1.boolean_sensor WITH DATATYPE=BOOLEAN, ENCODING=PLAIN');awaitsession.executeNonQueryStatement('CREATE TIMESERIES root.test.device1.int32_sensor WITH DATATYPE=INT32, ENCODING=RLE');awaitsession.executeNonQueryStatement('CREATE TIMESERIES root.test.device1.float_sensor WITH DATATYPE=FLOAT, ENCODING=RLE');awaitsession.executeNonQueryStatement('CREATE TIMESERIES root.test.device1.text_sensor WITH DATATYPE=TEXT, ENCODING=PLAIN');

Inserting Data with All Types

constnow=Date.now();consttablet={deviceId: 'root.test.device1',measurements: ['boolean_sensor','int32_sensor','int64_sensor','float_sensor','double_sensor','text_sensor'],dataTypes: [0,1,2,3,4,5],// BOOLEAN, INT32, INT64, FLOAT, DOUBLE, TEXTtimestamps: [now,now+1,now+2],values: [[true,100,1000n,1.23,4.56,'hello'],[false,200,2000n,2.34,5.67,'world'],[true,300,3000n,3.45,6.78,'test'],],};awaitsession.insertTablet(tablet);

Working with BLOB Data

// Insert BLOB dataconsttablet={deviceId: 'root.test.device1',measurements: ['blob_sensor'],dataTypes: [10],// BLOB (type code 10)timestamps: [Date.now()],values: [[Buffer.from([0x01,0x02,0x03,0x04])],],};awaitsession.insertTablet(tablet);// Query BLOB dataconstresult=awaitsession.executeQueryStatement('SELECT blob_sensor FROM root.test.device1');// Result will contain Buffer objectsconstblobData=result.rows[0][1];// Bufferconsole.log(blobData);// <Buffer 01 02 03 04>

Working with TIMESTAMP and DATE

// TIMESTAMP stores millisecond precision, DATE stores day precisionconsttablet={deviceId: 'root.test.device1',measurements: ['timestamp_sensor','date_sensor'],dataTypes: [8,9],// TIMESTAMP=8, DATE=9timestamps: [Date.now()],values: [[newDate('2024-01-15T10:30:00Z'),newDate('2024-01-15')],],};awaitsession.insertTablet(tablet);// Query returns Date objectsconstresult=awaitsession.executeQueryStatement('SELECT timestamp_sensor, date_sensor FROM root.test.device1');consttimestampValue=result.rows[0][1];// Date object with timeconstdateValue=result.rows[0][2];// Date object (day precision)

Query Results with All Types

constresult=awaitsession.executeQueryStatement('SELECT * FROM root.test.device1');for(constrowofresult.rows){console.log({timestamp: row[0],// bigintboolean: row[1],// booleanint32: row[2],// numberint64: row[3],// bigintfloat: row[4],// numberdouble: row[5],// numbertext: row[6],// string});}

Type Conversions

JavaScript to IoTDB

JavaScript TypeIoTDB TypeNotes
booleanBOOLEANDirect mapping
numberINT32, FLOAT, DOUBLEDepends on dataType specified
bigintINT64, TIMESTAMPDirect mapping
stringTEXT, STRINGUTF-8 encoded
BufferBLOBBinary data
DateDATE, TIMESTAMPDATE: encoded as yyyyMMdd integer (e.g. 20240101); TIMESTAMP: milliseconds since epoch

IoTDB to JavaScript

IoTDB TypeJavaScript TypeNotes
BOOLEANbooleantrue/false
INT32number32-bit integer
INT64bigint64-bit integer (may lose precision if converted to number)
FLOATnumberSingle precision
DOUBLEnumberDouble precision
TEXTstringUTF-8 decoded
BLOBBufferRaw binary data
STRINGstringUTF-8 decoded
DATEDateyyyyMMdd integer (e.g. 20240101) converted to Date at UTC midnight
TIMESTAMPDateMilliseconds since epoch

Null Values

All data types support null values. Null values are represented using a bitmap in the binary protocol:

// Query results may contain null valuesconstresult=awaitsession.executeQueryStatement('SELECT * FROM root.test.device1');for(constrowofresult.rows){if(row[1]===null){console.log('Value is null');}}

Best Practices

  1. Use appropriate data types: Choose the smallest type that fits your data to optimize storage
  2. INT64 for large integers: Use bigint in JavaScript for values that exceed Number.MAX_SAFE_INTEGER
  3. FLOAT vs DOUBLE: Use FLOAT (4 bytes) for sensor data where precision is less critical
  4. TEXT vs STRING: Both are UTF-8 strings; use based on IoTDB version compatibility
  5. DATE for dates only: Use DATE type when you only need date precision (not time of day)
  6. TIMESTAMP for full datetime: Use TIMESTAMP when you need millisecond precision

Encoding Options

Different data types support different encoding methods for compression:

  • BOOLEAN: PLAIN, RLE
  • INT32/INT64: PLAIN, RLE, TS_2DIFF, GORILLA
  • FLOAT/DOUBLE: PLAIN, RLE, TS_2DIFF, GORILLA
  • TEXT/STRING: PLAIN
  • BLOB: PLAIN

Example:

awaitsession.executeNonQueryStatement('CREATE TIMESERIES root.test.device1.sensor WITH DATATYPE=INT32, ENCODING=RLE');

Testing

A comprehensive test suite covering all data types is available in tests/e2e/AllDataTypes.test.ts. This test:

  • Creates timeseries with all data types
  • Inserts data with proper type conversions
  • Queries and validates returned data types
  • Tests null value handling
  • Verifies aggregation queries work with different types

Run the test with:

npm run test:e2e -- --testPathPattern=AllDataTypes

Compatibility

This client supports IoTDB versions that include these data types. For older IoTDB versions:

  • Types 0-5 (BOOLEAN through TEXT) are universally supported
  • Types 6-9 (BLOB, STRING, DATE, TIMESTAMP) require newer IoTDB versions (check your IoTDB version)

If you use unsupported types, you'll receive an error from the IoTDB server during timeseries creation.