Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/timeplus-io/proton/llms.txt

Use this file to discover all available pages before exploring further.

​
Get Started in Seconds

The fastest way to get Timeplus Proton running: 
curl https://install.timeplus.com/oss | sh
This installs the proton binary on your system. No JVM, no dependencies, just a single executable.

​
Quick Start Guide

Follow these steps to get your first streaming query running:
1

Install Proton

Choose your preferred installation method:
2

Start the Server

Once installed, start the Proton server:
proton server
By default, Proton stores config, logs, and data in ./proton-data in your current directory.
The server will start and listen on:
  • Port 8123: HTTP interface (default for JDBC)
  • Port 8463: Native TCP protocol
3

Connect with SQL Client

Open a new terminal window and start the SQL client:
proton client
You should see a prompt like:
proton-client :)
4

Create Your First Stream

Let’s create a stream with random data to test the system:
CREATE RANDOM STREAM devices(
  device string default 'device'||to_string(rand()%4),
  temperature float default rand()%1000/10
);
This creates a stream that continuously generates random device temperature readings.
5

Run Your First Query

Now let’s query the streaming data:
SELECT device, count(*), min(temperature), max(temperature)
FROM devices 
GROUP BY device;
You should see live results updating continuously:
┌─device──┬─count()─┬─min(temperature)─┬─max(temperature)─┐
│ device0 │    2256 │                0 │             99.6 │
│ device1 │    2260 │              0.1 │             99.7 │
│ device3 │    2259 │              0.3 │             99.9 │
│ device2 │    2225 │              0.2 │             99.8 │
└─────────┴─────────┴──────────────────┴──────────────────┘
Press Ctrl+C to stop the streaming query.

​
Working with Kafka

One of Proton’s most powerful features is native Kafka integration. Here’s a quick example:

​
Read from Kafka

CREATE EXTERNAL STREAM frontend_events(raw string)
SETTINGS 
  type='kafka',
  brokers='localhost:9092',
  topic='my-events';

-- Query live data from Kafka
SELECT * FROM frontend_events;

​
Write to Kafka

-- Create a materialized view that processes and writes to Kafka
CREATE MATERIALIZED VIEW enriched_events_mv
INTO EXTERNAL STREAM output_stream
AS
SELECT 
  raw:userId as user_id,
  raw:eventType as event_type,
  raw:timestamp as event_time
FROM frontend_events
WHERE raw:eventType != 'heartbeat';
For a complete Kafka example with Docker Compose, check out the ecommerce example.

​
Real-World Example: AWS MSK to ClickHouse

Here’s a more advanced example showing how to build a streaming ETL pipeline: 
-- Read from AWS MSK using IAM Role
CREATE EXTERNAL STREAM aws_msk_stream (
  device string,
  temperature float
)
SETTINGS
  type='kafka',
  brokers='prefix.kafka.us-west-2.amazonaws.com:9098',
  topic='sensor-data',
  security_protocol='SASL_SSL',
  sasl_mechanism='AWS_MSK_IAM';

-- Write to ClickHouse
CREATE EXTERNAL TABLE ch_target
SETTINGS 
  type='clickhouse',
  address='clickhouse.example.com:9000',
  user='default',
  password='***',
  table='device_metrics';

-- Create a long-running materialized view for aggregation
CREATE MATERIALIZED VIEW mv_msk_to_ch 
INTO ch_target 
AS
SELECT 
  window_start as timestamp, 
  device, 
  avg(temperature) as avg_temperature,
  min(temperature) as min_temperature,
  max(temperature) as max_temperature
FROM tumble(aws_msk_stream, 10s) 
GROUP BY window_start, device;
This creates a real-time pipeline that:
  1. Reads from AWS MSK
  2. Aggregates data in 10-second tumbling windows
  3. Writes aggregated results to ClickHouse

​
Try the Docker Compose Stack

For a complete environment with Proton, Redpanda (Kafka), and sample data: 
cd examples/ecommerce
docker compose up
This starts:
  • Timeplus Proton
  • Redpanda (Kafka-compatible)
  • Redpanda Console (Web UI)
  • Owl Shop (data generator)
Once running, connect to the Proton container: 
docker exec -it proton-demo-ecommerce-proton-1 proton-client
Then create an external stream and start querying: 
-- Create external stream to read from Kafka
CREATE EXTERNAL STREAM frontend_events(raw string)
SETTINGS 
  type='kafka',
  brokers='redpanda:9092',
  topic='owlshop-frontend-events';

-- Filter events by JSON attributes
SELECT 
  _tp_time, 
  raw:ipAddress, 
  raw:requestedUrl 
FROM frontend_events 
WHERE raw:method='POST';

-- Show a live ASCII bar chart
SELECT 
  raw:method, 
  count() as cnt, 
  bar(cnt, 0, 40, 5) as bar 
FROM frontend_events
GROUP BY raw:method 
ORDER BY cnt DESC 
LIMIT 5 BY emit_version();

​
Next Steps

Installation Guide

Detailed installation instructions for all platforms

Stream Processing

Learn about streams, windows, and materialized views

Kafka Integration

Deep dive into Kafka external streams

Examples

Explore more real-world examples

​
Getting Help

Documentation

Complete documentation

GitHub Discussions

Ask questions and share feedback

Slack Community

Connect with the community

Build docs developers (and LLMs) love

Get started for freeTalk to us