ClickHouse OSS クイックスタート

このクイックスタートチュートリアルでは、OSS ClickHouse を 8 ステップでセットアップします。適切なバイナリをダウンロードし、ClickHouse サーバーを実行し、ClickHouse クライアントを使用してテーブルを作成し、データを挿入してクエリを実行してそのデータを選択します。

ClickHouse をダウンロード

ClickHouse は Linux、FreeBSD と macOS 上でネイティブに動作し、Windows では WSL を介して実行されます。ClickHouse をローカルにダウンロードする最も簡単な方法は、次の curl コマンドを実行することです。このコマンドは、オペレーティングシステムがサポートされているかどうかを判断し、適切な ClickHouse バイナリをダウンロードします。

注記

バイナリがあるディレクトリに最初に ClickHouse サーバーを実行する際にいくつかの構成ファイルが作成されるため、新しい空のサブディレクトリで下のコマンドを実行することをお勧めします。

curl https://clickhouse.com/ | sh

これにより次のように表示されるはずです：

Successfully downloaded the ClickHouse binary, you can run it as:
    ./clickhouse

You can also install it:
sudo ./clickhouse install

この段階では、install コマンドを実行するように言われても無視して構いません。

注記

Mac ユーザーへ：バイナリの開発者を確認できないというエラーが表示される場合は、"MacOS の開発者検証エラーを修正する"を参照してください。

サーバーを起動

次のコマンドを実行して、ClickHouse サーバーを起動します：

./clickhouse server

ターミナルがログ記録で埋まるのを見るはずです。これは予期されることです。ClickHouse では、デフォルトのログレベルが trace に設定されています。

クライアントを起動

clickhouse-client を使用して ClickHouse サービスに接続します。新しいターミナルを開き、clickhouse バイナリが保存されているディレクトリに移動し、次のコマンドを実行します：

./clickhouse client

サービスが localhost で実行されていると接続され、笑顔の顔が表示されるはずです：

my-host :)

テーブルを作成

CREATE TABLE を使用して新しいテーブルを定義します。一般的な SQL DDL コマンドは、ClickHouse でも動作しますが、1 つの追加が必要です - ClickHouse のテーブルには ENGINE 句が必要です。ClickHouse のパフォーマンスの利点を活かすために MergeTree を使用します：

CREATE TABLE my_first_table
(
    user_id UInt32,
    message String,
    timestamp DateTime,
    metric Float32
)
ENGINE = MergeTree
PRIMARY KEY (user_id, timestamp)

データを挿入

ClickHouse では、慣れ親しんだ INSERT INTO TABLE コマンドを使用できますが、MergeTree テーブルに挿入するたびに ClickHouse で part がストレージに作成されることを理解することが重要です。これらの ^^parts^^ は後で ClickHouse によってバックグラウンドでマージされます。

ClickHouse では、行を一度に多数（数万行または数百万行）バルク挿入することを試み、バックグラウンドプロセスでマージする必要がある parts の数を最小限に抑えます。

このガイドでは、まだそのことを心配する必要はありません。次のコマンドを実行して、テーブルにいくつかの行のデータを挿入します：

INSERT INTO my_first_table (user_id, message, timestamp, metric) VALUES
    (101, 'Hello, ClickHouse!',                                 now(),       -1.0    ),
    (102, 'Insert a lot of rows per batch',                     yesterday(), 1.41421 ),
    (102, 'Sort your data based on your commonly-used queries', today(),     2.718   ),
    (101, 'Granules are the smallest chunks of data read',      now() + 5,   3.14159 )

新しいテーブルをクエリ

SQL データベースと同様に SELECT クエリを記述できます：

SELECT *
FROM my_first_table
ORDER BY timestamp

レスポンスが見やすいテーブル形式で返ってくることに注意してください：

┌─user_id─┬─message────────────────────────────────────────────┬───────────timestamp─┬──metric─┐
│     102 │ Insert a lot of rows per batch                     │ 2022-03-21 00:00:00 │ 1.41421 │
│     102 │ Sort your data based on your commonly-used queries │ 2022-03-22 00:00:00 │   2.718 │
│     101 │ Hello, ClickHouse!                                 │ 2022-03-22 14:04:09 │      -1 │
│     101 │ Granules are the smallest chunks of data read      │ 2022-03-22 14:04:14 │ 3.14159 │
└─────────┴────────────────────────────────────────────────────┴─────────────────────┴─────────┘

4 rows in set. Elapsed: 0.008 sec.

自分のデータを挿入

次のステップは、自分のデータを ClickHouse に取り込むことです。table functions や integrations が多数あり、データを取り込むためのサポートがあります。次のタブにいくつかの例がありますが、ClickHouse と統合されている技術の長いリストについては、Integrations ページを確認できます。

S3

s3 table function を使用して S3 のファイルを読み取ります。これはテーブル関数です - 結果はテーブルであり、次のことができます：

1. SELECT クエリのソースとして使用する（データを S3 に残しながら任意のクエリを実行できます）、または...
2. MergeTree テーブルに結果のテーブルを挿入する（データを ClickHouse に移動する準備ができたとき）

任意のクエリは次のようになります：

SELECT
passenger_count,
avg(toFloat32(total_amount))
FROM s3(
'https://datasets-documentation.s3.eu-west-3.amazonaws.com/nyc-taxi/trips_0.gz',
'TabSeparatedWithNames'
)
GROUP BY passenger_count
ORDER BY passenger_count;

データを ClickHouse テーブルに移動する場合は、次のようになります。ここで nyc_taxi は MergeTree テーブルです：

INSERT INTO nyc_taxi
SELECT * FROM s3(
'https://datasets-documentation.s3.eu-west-3.amazonaws.com/nyc-taxi/trips_0.gz',
'TabSeparatedWithNames'
)
SETTINGS input_format_allow_errors_num=25000;

S3 と ClickHouse を使用する際の詳細や例については、AWS S3 ドキュメントページのコレクションを参照してください。

GCS

AWS S3 でのデータの読み取りに使用される s3 table function は、Google Cloud Storage のファイルにも適用できます。

例えば：

SELECT
*
FROM s3(
'https://storage.googleapis.com/my-bucket/trips.parquet',
'MY_GCS_HMAC_KEY',
'MY_GCS_HMAC_SECRET_KEY',
'Parquet'
)
LIMIT 1000

s3 table function page で詳細を見つけてください。

Web

url table function は、ウェブからアクセス可能なファイルを読み取ります：

--By default, ClickHouse prevents redirects to protect from SSRF attacks.
--The URL below requires a redirect, so we must set max_http_get_redirects > 0.
SET max_http_get_redirects=10;

SELECT *
FROM url(
'http://prod2.publicdata.landregistry.gov.uk.s3-website-eu-west-1.amazonaws.com/pp-complete.csv',
'CSV'
);

url table function page で詳細を見つけてください。

Local

file table engine を使用してローカルファイルを読み取ります。簡単にするために、そのファイルを user_files ディレクトリにコピーしてください（これは ClickHouse バイナリをダウンロードしたディレクトリにあります）。

DESCRIBE TABLE file('comments.tsv')

Query id: 8ca9b2f9-65a2-4982-954a-890de710a336

┌─name──────┬─type────────────────────┐
│ id        │ Nullable(Int64)         │
│ type      │ Nullable(String)        │
│ author    │ Nullable(String)        │
│ timestamp │ Nullable(DateTime64(9)) │
│ comment   │ Nullable(String)        │
│ children  │ Array(Nullable(Int64))  │
└───────────┴─────────────────────────┘

ClickHouse は、大量の行を分析することでカラムの名前とデータ型を推測します。ClickHouse がファイル名からファイル形式を特定できない場合は、2 番目の引数として指定できます：

SELECT count()
FROM file(
'comments.tsv',
'TabSeparatedWithNames'
)

詳細については、file table function のドキュメントページを確認してください。

PostgreSQL

postgresql table function を使用して、PostgreSQL のテーブルからデータを読み取ります：

SELECT *
FROM
postgresql(
'localhost:5432',
'my_database',
'my_table',
'postgresql_user',
'password')
;

詳細については、postgresql table function のドキュメントページを参照してください。

MySQL

mysql table function を使用して MySQL のテーブルからデータを読み取ります：

SELECT *
FROM
mysql(
'localhost:3306',
'my_database',
'my_table',
'mysql_user',
'password')
;

詳細については、mysql table function のドキュメントページを参照してください。

ODBC/JDBC

ClickHouse は、任意の ODBC または JDBC データソースからデータを読み取ることができます：

SELECT *
FROM
odbc(
'DSN=mysqlconn',
'my_database',
'my_table'
);

詳細については、odbc table function と jdbc table function のドキュメントページを参照してください。

Message Queues

メッセージキューは、対応するテーブルエンジンを使用して ClickHouse にデータをストリーミングできます。これには以下が含まれます：

• Kafka: Kafka table engine を使用して Kafka と統合
• Amazon MSK: Amazon Managed Streaming for Apache Kafka (MSK) と統合
• RabbitMQ: RabbitMQ table engine を使用して RabbitMQ と統合

Data Lakes

ClickHouse には、以下のソースからデータを読み取るためのテーブル関数があります：

• Hadoop: hdfs table function を使用して Apache Hadoop と統合
• Hudi: hudi table function を使用して S3 の既存の Apache Hudi テーブルから読み取る
• Iceberg: iceberg table function を使用して S3 の既存の Apache Iceberg テーブルから読み取る
• DeltaLake: deltaLake table function を使用して S3 の既存の Delta Lake テーブルから読み取る

Other

お使いの既存のフレームワークやデータソースを ClickHouse に接続する方法については、ClickHouse 統合の長いリスト をチェックしてください。

探索

• Core Concepts セクションをチェックして、ClickHouse の内部がどのように動作するかの基本を学びましょう。
• Advanced Tutorial をチェックして、ClickHouse の主要な概念と機能をより深く掘り下げて理解しましょう。
• ClickHouse Academy で提供される無料のオンデマンドトレーニングコースを受けて学び続けてください。
• 挿入方法に関する説明と共に、example datasets のリストがあります。
• 外部ソースからデータが来る場合は、メッセージキュー、データベース、パイプラインなどへの接続に関する integration guides のコレクションを参照してください。
• UI/BI ビジュアライゼーションツールを使用している場合は、ClickHouse に UI を接続するための user guides をチェックしてください。
• primary keys に関するユーザーガイドは、主キーに関する必要なすべての情報を提供します。