Quick Start

Get started with Timeplus Proton in under 5 minutes

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:

   Single Binary (Recommended)

   curl https://install.timeplus.com/oss | sh
   

   This downloads and installs the latest Proton binary to your system.

   Homebrew (macOS)

   brew install timeplus-io/timeplus/proton
   

   Docker

   docker run -d --pull always \
     -p 8123:8123 -p 8463:8463 \
     --name proton \
     d.timeplus.com/timeplus-io/proton:latest
   
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