5-Minute Quick Start with KWDB

This example will guide you through the basic features of KWDB. You will learn how to:

• Deploy KWDB quickly using Docker
• Connect to the KWDB database
• Create time-series databases and relational databases
• Insert sample data
• Execute cross-model queries

Through this example, you can understand how KWDB handles both time-series data and relational data simultaneously, and how to leverage its powerful cross-model query capabilities. The entire process takes only 5 minutes to complete.

Download and Installation

We recommend using Docker to quickly try KWDB

# Docker installation (recommended)
docker run -d --privileged --name kwdb   
  -p 26257:26257   
  -p 8080:8080   
  -v /var/lib/kaiwudb:/kaiwudb/deploy/kaiwudb-container   
  --ipc shareable   
  -w /kaiwudb/bin   
  kwdb/kwdb   
  ./kwbase start-single-node   
    --insecure   
    --listen-addr=0.0.0.0:26257   
    --http-addr=0.0.0.0:8080   
    --store=/kaiwudb/deploy/kaiwudb-container

Connect to the Database

Connect to KWDB using Docker

# Start interactive SQL Shell
docker exec -it kwdb ./kwbase sql --insecure --host=127.0.0.1

Create Databases

Create time-series database and relational database

-- Create time-series database
CREATE TS DATABASE sensor_data;

-- Create relational database
CREATE DATABASE device_management;

-- Create sensor readings table in time-series database
CREATE TABLE sensor_data.readings (
    ts TIMESTAMPTZ NOT NULL,         -- timestamp (primary column)
    temperature FLOAT,               -- temperature value
    humidity FLOAT                   -- humidity value
) TAGS (
    device_id INT NOT NULL,          -- device ID (tag)
    location VARCHAR(256) NOT NULL   -- device location (tag)
) PRIMARY TAGS(device_id);          -- set primary tag to device_id

-- Create device information table in relational database
CREATE TABLE device_management.devices (
    device_id INT PRIMARY KEY,       -- device ID (primary key)
    device_name VARCHAR(100),       -- device name
    device_type VARCHAR(50),        -- device type
    installation_date DATE,         -- installation date
    warranty_period INT             -- warranty period (months)
);

Insert Data

Start writing your time-series data and relational data

-- Insert device information into relational table
INSERT INTO device_management.devices VALUES
(101, 'Temperature Sensor-101', 'Temperature Sensor', '2023-01-15', 24),
(102, 'Humidity Sensor-102', 'Humidity Sensor', '2023-02-20', 36),
(103, 'Multi-Function Sensor-103', 'Composite Sensor', '2023-03-10', 12);

-- Insert sensor readings data into time-series table
INSERT INTO sensor_data.readings VALUES
('2025-08-15 13:00:00', 23.5, 45.2, 101, 'Server Room A'),
('2025-08-15 13:30:00', 24.1, 46.8, 101, 'Server Room A'),
('2025-08-15 14:00:00', 22.9, 47.5, 101, 'Server Room A'),
('2025-08-15 14:30:00', 19.8, 65.3, 102, 'Server Room B'),
('2025-08-15 15:00:00', 20.2, 64.7, 102, 'Server Room B'),
('2025-08-15 15:30:00', 20.5, 63.9, 102, 'Server Room B'),
('2025-08-15 16:00:00', 25.3, 42.1, 103, 'Corridor'),
('2025-08-15 16:30:00', 25.8, 41.7, 103, 'Corridor');

Query Data

Cross-model query data

-- Query latest device readings with detailed information
SELECT 
    r.ts AS timestamp,
    r.temperature,
    r.humidity,
    d.device_name,
    d.device_type,
    r.location
FROM 
    sensor_data.readings AS r
INNER JOIN 
    device_management.devices AS d 
ON 
    r.device_id = d.device_id
WHERE 
    r.ts > '2025-08-15 10:00:00'
ORDER BY 
    r.ts DESC;