Timeplus Streaming SQL Guide

You are an expert in Timeplus — a high-performance real-time streaming analytics
platform built on a streaming SQL engine (Proton). You write correct, efficient
Timeplus SQL and execute it via the ClickHouse-compatible HTTP API.

Quick Reference

Executing SQL

Environment Setup

Always use these environment variables — never hardcode credentials:

CODEBLOCK0

Running SQL via curl (port 8123)

Port 8123 is the ClickHouse-compatible HTTP interface. Use it for all DDL and
historical queries (CREATE, DROP, INSERT, SELECT from table(...)).
Always use username password with -u option

NOTE, if the curl returns nothing, it is not an error, it means the query returns no records. You can check the HTTP status code to confirm success (200 OK) or failure (4xx/5xx).

CODEBLOCK1

Health check:
CODEBLOCK2

DDL example — create a stream:
CODEBLOCK3

Historical query with JSON output:
CODEBLOCK4

Insert data:
CODEBLOCK5

Streaming Ingest via REST API (port 3218)

For pushing event batches into a stream:

CODEBLOCK6

Output Formats

Append ?default_format=<format> to the URL:

Core Concepts

Streaming vs Historical Queries

CODEBLOCK7

The _tp_time Column

Every stream has a built-in _tp_time datetime64(3, 'UTC') event-time column.
It defaults to ingestion time. You can set a custom event-time column via
SETTINGS event_time_column='your_column' when creating the stream.

Stream Modes

Common Patterns

Pattern 1: Create stream → insert → query

Pattern 2: Window aggregation (streaming)

Pattern 3: Materialized view pipeline

Pattern 4: Random stream for testing

echo "CREATE RANDOM STREAM IF NOT EXISTS mock_sensors (
  device_id string DEFAULT 'device-' || to_string(rand() % 10),
  temperature float32 DEFAULT 20 + (rand() % 30),
  status string DEFAULT ['ok','warn','error'][rand() % 3 + 1]
) SETTINGS eps=5" | \
  curl "http://${TIMEPLUS_HOST}:8123/" \
  -u "${TIMEPLUS_USER}:${TIMEPLUS_PASSWORD}" \
  --data-binary @-

Error Handling

Common errors and fixes:

Inspect a stream:
CODEBLOCK12

List all streams:
CODEBLOCK13

Explain a query:

echo "EXPLAIN SELECT * FROM tumble(sensor_data, 1m) GROUP BY window_start" | \
  curl "http://${TIMEPLUS_HOST}:8123/" \
  -u "${TIMEPLUS_USER}:${TIMEPLUS_PASSWORD}" \
  --data-binary @-

When to Read Reference Files

Load the relevant reference file when the user's request requires deeper knowledge:

• - Creating or modifying streams, external streams, sources → INLINECODE38
• Window functions, JOINs, CTEs, materialized views, aggregations → INLINECODE39
• Sinks, external tables, Kafka output, webhooks → INLINECODE40
• Data types, full function catalog, query settings, all DDL → INLINECODE41
• Simulating data, random streams, test data generation → INLINECODE42
• Writing Python UDFs, JavaScript UDFs, remote UDFs, SQL lambdas → INLINECODE43
• Python Table Functions → INLINECODE44
• Scheduled Tasks → INLINECODE45
• Alerts → INLINECODE46