Timeplus Proton Documentation

repository·develop·Indexed 25 days ago

https://github.com/timeplus-io/proton

A high-performance, single-binary SQL engine for stream processing and real-time analytics. It serves as a lightweight, dependency-free alternative to Flink and ksqlDB, leveraging the ClickHouse engine. The documentation covers building Proton and ClickHouse via Docker, using the packager tool for .deb and binary packages, and includes details on integrated libraries such as MetroHash, pdqsort, and POCO C++ libraries.

Tokens
252.3K
Snippets
573
Records
1.3K
Agent score
80%

What's inside Timeplus Proton

  1. Overview of MetroHash capabilities

    develop

    MetroHash is a collection of high-performance, non-cryptographic hash functions optimized for modern x86-64 microarchitectures.

    Key features include:

    • Performance: Designed for both bulk hashing and small, variable-length keys.
    • Statistical Robustness: Maintains a statistical bias profile similar to the MD5 cryptographic hash.
    • Incremental Construction: Supports building hashes from data streams via Update and Finalize.
    • Variants: Provides 64-bit, 128-bit, and 128-bit CRC variants.
    • Statistical Uniqueness: Functions within the same family (e.g., metrohash64_1 and metrohash64_2) are statistically unique, making them suitable for use together in structures like Bloom filters.
  2. Overview of the GitHub Events Dataset

    develop

    The GitHub Events dataset is a large-scale dataset containing all GitHub events from 2011 to December 6, 2020. It consists of approximately 3.1 billion records.

    Storage Requirements:

    • Download size: ~75 GB
    • Disk space required: Up to 200 GB (when stored in a table using lz4 compression).

    For full dataset descriptions, insights, download instructions, and interactive queries, visit the official documentation at https://ghe.clickhouse.tech/.

  3. What is Timeplus Proton?

    develop

    Timeplus Proton is a high-performance SQL pipeline engine designed for stream processing, analytics, observability, and AI. It serves as a lightweight, C++ based alternative to Apache Flink and ksqlDB.

    Key features include:

    • Native Source/Sink Support: Connects to Kafka, ClickHouse, MySQL, Postgres, MongoDB, S3/Iceberg, OpenSearch, etc.
    • Streaming Capabilities: Supports streaming ingestion, multi-stream JOINs, incremental materialized views, and watermarks.
    • Extensibility: Supports User Defined Functions (UDF) in Python and JS.
    • Zero Dependencies: No JVM or ZooKeeper required; it is distributed as a single binary (<500MB).
  4. Use clickhouse-local for fast local file processing

    develop

    The clickhouse-local program allows you to perform high-speed data processing on local files using the ClickHouse SQL dialect without deploying a full ClickHouse server. It supports most ClickHouse features, formats, and table engines.

    By default, it uses a unique temporary data directory. While it supports loading server configurations via --config-file, it is not recommended to load production server configurations into clickhouse-local as it may lead to accidental data damage.

  5. Use proton-dwal-benchmark for performance testing and Kafka offset experiments

    develop
    The proton-dwal-benchmark tool is used for basic performance testing of KafkaWAL, KafkaWALSimpleConsumer, and KafkaWALConsumer. It also allows developers to experiment with librdkafka and Kafka-like consumer group behaviors, specifically regarding how offsets are committed and replayed.
  6. Visual Interfaces for ClickHouse/Proton

    develop

    A variety of third-party tools provide graphical user interfaces (GUIs) for interacting with the database, ranging from open-source web interfaces to commercial BI platforms.

    Open-Source Tools

    • Tabix: A web interface for direct browser-based querying with syntax highlighting and command auto-completion.
    • HouseOps: A cross-platform (OSX, Linux, Windows) IDE featuring a query builder, database graph, and process management (including KILL capability).
    • LightHouse: A lightweight web interface for table listing, filtering, and read-only queries.
    • Redash: A data visualization platform that supports joining results from multiple data sources, including ClickHouse.
    • Grafana: A monitoring and visualization platform using the ClickHouse datasource plugin.
    • DBeaver: A universal desktop client supporting syntax highlighting, autocompletion, and metadata search.
    • clickhouse-cli: A Python 3-based command-line client with autocompletion and syntax highlighting.
    • clickhouse-flamegraph: A tool to visualize system.trace_log as flamegraphs.
    • clickhouse-plantuml: A script to generate PlantUML diagrams of table schemas.
    • xeus-clickhouse: A Jupyter kernel for running SQL queries against ClickHouse data in Jupyter notebooks.
    • MindsDB Studio: A GUI for developing and deploying machine learning models using database data.
    • DBM: A visual management tool supporting query history, table/database management, and data migration.
    • Bytebase: A web-based schema change and version control tool supporting Database-as-Code workflows.

    Commercial Tools

    • DataGrip: A JetBrains IDE with dedicated support for ClickHouse features like nested columns and table engines.
    • Yandex DataLens: A cloud-based service for data visualization and analytics.
    • Holistics: A full-stack BI platform with automated report scheduling and SQL data modeling.
    • Looker: A business intelligence platform using LookML for curated data modeling.
    • SeekTable: A self-service BI tool for exploration and operational reporting.
    • Chadmin: A simple UI to visualize and terminate running queries.
    • TABLUM.IO: An online ETL and visualization tool with a versatile SQL console and data pipelining via API.
  7. Use clickhouse-odbc-bridge as an ODBC proxy

    develop

    clickhouse-odbc-bridge is an HTTP server that acts as a proxy for ODBC drivers. It is designed to prevent ODBC implementation faults (like segfaults) from crashing the main clickhouse-server process by isolating the ODBC driver execution within this separate process.

    While typically used internally by clickhouse-server via the odbc table function or StorageODBC, it can be run as a standalone tool. It accepts queries via HTTP POST requests and returns results in RowBinary format.

  8. What is HTAP (Hybrid Transactional/Analytical Processing)?

    develop

    HTAP refers to the trend of modern database systems attempting to handle both transactional (OLTP) and analytical (OLAP) workloads equally well within a single system.

    Historically, businesses had to operate multiple integrated storage systems to satisfy both needs, which increased maintenance costs. HTAP aims to reduce this complexity by providing a single system that can manage continuous transaction streams while also supporting high-performance analytical reporting.

  9. Overview of the MergeTree table engine family

    develop

    The MergeTree engine and its derivatives (the *MergeTree family) are designed for high-performance ingestion of very large datasets. Instead of rewriting existing data during every insert, data is written to the table in parts, and background processes apply merging rules to these parts to optimize storage and performance.

    Key capabilities include:

    • Primary Key Sorting: Data is stored sorted by a primary key, enabling the creation of a sparse index for fast data retrieval.
    • Partitioning: If a partitioning key is specified, data can be organized into partitions, allowing for more efficient operations and automatic data pruning during queries.
    • Data Replication: The ReplicatedMergeTree variant provides support for data replication across nodes.
    • Data Sampling: Supports setting specific data sampling methods at the table level.
  10. What is a 'first significant subdomain' and how to use it

    develop

    A "first significant subdomain" is a non-standard concept used to identify the core part of a domain. By default, if a second-level domain is com, net, org, or co, the first significant subdomain is that second-level domain; otherwise, it is the third-level domain.

    Standard Functions

    • firstSignificantSubdomain(url): Returns the first significant subdomain.
    • cutToFirstSignificantSubdomain(url): Returns the domain part including top-level subdomains up to the first significant subdomain (e.g., news.yandex.com.tr $\rightarrow$ yandex.com.tr).
    • cutToFirstSignificantSubdomainWithWWW(url): Same as above, but does not strip the www prefix.
    • domainWithoutWWW(url): Returns the domain after removing at most one www. from the beginning.
  11. What is SummingMergeTree and how does it work?

    develop

    The SummingMergeTree engine is a variant of the MergeTree engine designed to reduce storage volume and speed up data selection by summarizing rows.

    When the engine merges data parts, it identifies rows with the same sorting key (primary key) and replaces them with a single row containing the summarized values of numeric columns.

    Key Behaviors:

    • Incomplete Summation: Summation happens during background merges. Because merges are periodic and happen per data part, a single query might see multiple rows for the same key that haven't been merged yet. Always use an aggregate function (like sum()) and a GROUP BY clause when querying to ensure you get the final correct totals.
    • Column Selection: By default, it summarizes all numeric columns not included in the primary key. You can explicitly specify which columns to summarize using the columns parameter.
    • Zero Values: If the summation results in 0 for all specified summation columns, the row is deleted.
    • Non-summarized Columns: If a column is not in the primary key and is not part of the summation set, an arbitrary value is selected from the existing rows during a merge.
    • Recommendation: Use MergeTree to store complete, raw data and SummingMergeTree for storing aggregated data (e.g., for reports) to prevent data loss from incorrectly composed primary keys.