Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

clickhouse-local

View as MarkdownEdit this pageReport an issueSet up docs MCP

clickhouse-local と ClickHouse の使い分け

clickhouse-local は、完全なデータベースサーバーをインストールしなくても、ローカルやリモートのファイルに対して SQL で高速に処理を行いたい開発者に最適な、手軽に使える ClickHouse のバージョンです。clickhouse-local では、開発者はコマンドラインから直接 SQL コマンド (ClickHouse SQL dialect を使用) を実行できるため、完全な ClickHouse 環境をインストールしなくても、ClickHouse の機能をシンプルかつ効率的に利用できます。clickhouse-local の主な利点の 1 つは、clickhouse-client のインストール時にすでに含まれていることです。つまり、複雑なインストール作業を行わなくても、開発者はすぐに clickhouse-local を使い始められます。

clickhouse-local は、開発やテスト、ファイル処理には非常に便利なツールですが、エンドユーザーやアプリケーション向けの提供には適していません。このような用途では、オープンソースの ClickHouse を使用することを推奨します。ClickHouse は、大規模な分析ワークロードを処理するよう設計された強力な OLAP データベースです。大規模なデータセットに対する複雑なクエリを高速かつ効率的に処理できるため、高いパフォーマンスが求められる本番環境に最適です。さらに、ClickHouse は、レプリケーション、シャーディング、高可用性など、アプリケーションの提供や大規模データセットの処理に向けてスケールするうえで不可欠な幅広い機能を備えています。より大きなデータセットを扱う必要がある場合や、エンドユーザーやアプリケーション向けに提供する必要がある場合は、clickhouse-local ではなくオープンソースの ClickHouse を使用することを推奨します。

以下のドキュメントでは、ローカルファイルへのクエリ や S3 上の Parquet ファイルの読み取り など、clickhouse-local の使用例を紹介しています。ぜひご覧ください。

clickhouse-local をダウンロードする

clickhouse-local は、ClickHouseサーバーや clickhouse-client と同じ clickhouse バイナリを使って実行されます。最新バージョンをダウンロードする最も簡単な方法は、次のコマンドを使用することです。

curl https://clickhouse.com/ | sh

SQL を使用してファイル内のデータをクエリする

clickhouse-local の一般的な用途の 1 つは、ファイルに対してアドホッククエリを実行することです。つまり、データをテーブルに挿入する必要はありません。clickhouse-local はファイルから一時テーブルにデータをストリーミングし、SQL を実行できます。

ファイルが clickhouse-local と同じマシン上にある場合は、読み込むファイルを指定するだけです。次の reviews.tsv ファイルには、Amazon 製品レビューのサンプルが含まれています。

./clickhouse local -q "SELECT * FROM 'reviews.tsv'"

このコマンドは、次のコマンドのショートカットです。

./clickhouse local -q "SELECT * FROM file('reviews.tsv')"

ClickHouse は、ファイル名の拡張子から、そのファイルがタブ区切りフォーマットであることを認識します。フォーマットを明示的に指定する必要がある場合は、多くの ClickHouse 入力フォーマットのいずれかを追加するだけです。

./clickhouse local -q "SELECT * FROM file('reviews.tsv', 'TabSeparated')"

fileテーブル関数はテーブルを作成し、DESCRIBEを使うと推定したスキーマを確認できます：

./clickhouse local -q "DESCRIBE file('reviews.tsv')"

データはローカルに存在する必要はありません。ファイル名の代わりに URL を使用でき、URL スキームに応じて対応するテーブルエンジンが選択されます (http:// と https:// は url 関数のように読み取られ、s3:// は s3 関数のように、file:// は file 関数のように読み取られます) ：

./clickhouse local -q "SELECT * FROM 'https://datasets-documentation.s3.eu-west-3.amazonaws.com/aapl_stock.csv' LIMIT 3"
./clickhouse local -q "SELECT count() FROM 's3://clickhouse-public-datasets/hits_compatible/athena_partitioned/hits_1.parquet'"
marketplace    Nullable(String)
customer_id    Nullable(Int64)
review_id    Nullable(String)
product_id    Nullable(String)
product_parent    Nullable(Int64)
product_title    Nullable(String)
product_category    Nullable(String)
star_rating    Nullable(Int64)
helpful_votes    Nullable(Int64)
total_votes    Nullable(Int64)
vine    Nullable(String)
verified_purchase    Nullable(String)
review_headline    Nullable(String)
review_body    Nullable(String)
review_date    Nullable(Date)

評価が最も高い製品を見つけてみましょう：

./clickhouse local -q "SELECT
    argMax(product_title,star_rating),
    max(star_rating)
FROM file('reviews.tsv')"
Monopoly Junior Board Game    5

AWS S3 内の Parquet ファイル内のデータをクエリする

S3 にファイルがある場合は、clickhouse-local と s3 テーブル関数を使って、そのファイルをその場でクエリできます (データを ClickHouse テーブルに挿入する必要はありません) 。ここでは、公開バケット内にある house_0.parquet というファイルを使用します。このファイルには、英国で売却された住宅の価格が含まれています。では、行数を見てみましょう。

./clickhouse local -q "
SELECT count()
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"

このファイルには270万行あります:

2772030

ClickHouse がファイルから推定したスキーマを確認しておくと便利です。

./clickhouse local -q "DESCRIBE s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"
price    Nullable(Int64)
date    Nullable(UInt16)
postcode1    Nullable(String)
postcode2    Nullable(String)
type    Nullable(String)
is_new    Nullable(UInt8)
duration    Nullable(String)
addr1    Nullable(String)
addr2    Nullable(String)
street    Nullable(String)
locality    Nullable(String)
town    Nullable(String)
district    Nullable(String)
county    Nullable(String)

最も高額な地区がどこなのか見てみましょう。

./clickhouse local -q "
SELECT
    town,
    district,
    count() AS c,
    round(avg(price)) AS price,
    bar(price, 0, 5000000, 100)
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')
GROUP BY
    town,
    district
HAVING c >= 100
ORDER BY price DESC
LIMIT 10"
LONDON    CITY OF LONDON    886    2271305    █████████████████████████████████████████████▍
LEATHERHEAD    ELMBRIDGE    206    1176680    ███████████████████████▌
LONDON    CITY OF WESTMINSTER    12577    1108221    ██████████████████████▏
LONDON    KENSINGTON AND CHELSEA    8728    1094496    █████████████████████▉
HYTHE    FOLKESTONE AND HYTHE    130    1023980    ████████████████████▍
CHALFONT ST GILES    CHILTERN    113    835754    ████████████████▋
AMERSHAM    BUCKINGHAMSHIRE    113    799596    ███████████████▉
VIRGINIA WATER    RUNNYMEDE    356    789301    ███████████████▊
BARNET    ENFIELD    282    740514    ██████████████▊
NORTHWOOD    THREE RIVERS    184    731609    ██████████████▋

フォーマット変換

異なるフォーマット間でデータを変換するには、clickhouse-local を利用できます。例:

$ clickhouse-local --input-format JSONLines --output-format CSV --query "SELECT * FROM table" < data.json > data.csv

フォーマットはファイル拡張子から自動的に判別されます:

$ clickhouse-local --query "SELECT * FROM table" < data.json > data.csv

手軽な方法として、--copy 引数を使って記述することもできます。

$ clickhouse-local --copy < data.json > data.csv

使い方

デフォルトでは、clickhouse-local は同じホスト上の ClickHouseサーバーのデータにアクセスでき、サーバー設定には依存しません。また、--config-file 引数を使用してサーバー設定を読み込むこともできます。一時データ用には、デフォルトで一意の一時データディレクトリが作成されます。

基本的な使い方 (Linux) :

$ clickhouse-local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

基本的な使い方 (Mac) ：

$ ./clickhouse local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

引数:

  • -S, --structure — 入力データのテーブル構造。
  • --input-format — 入力フォーマット。デフォルトは TSV です。
  • -F, --file — データへのパス。デフォルトは stdin です。
  • -q, --query — ; を区切り文字として実行するクエリ。--query は複数回指定できます。例: --query "SELECT 1" --query "SELECT 2"。--queries-file と同時には使用できません。
  • --queries-file - 実行するクエリが含まれたファイルのパス。--queries-file は複数回指定できます。例: --query queries1.sql --query queries2.sql。--query と同時には使用できません。
  • --multiquery, -n – 指定すると、--query オプションの後にセミコロン区切りで複数のクエリを指定できます。利便性のため、--query を省略して --multiquery の後にクエリを直接渡すこともできます。
  • -N, --table — 出力データの格納先となるテーブル名。デフォルトは table です。
  • --f, --format, --output-format — 出力フォーマット。デフォルトは TSV です。
  • -d, --database — デフォルトのデータベース。デフォルトは _local です。
  • --stacktrace — 例外発生時にデバッグ出力をダンプするかどうか。
  • --echo [ <bool> ] — 実行前に各クエリを表示します。省略可能なブール値を取ります。対話型モードではデフォルトで有効、バッチモードでは無効です。注意: --echo は省略可能な値を取るようになったため、値を指定しない --echo の直後に置かれた位置引数のクエリはその値として解釈されます。代わりに --echo --query "..."、--echo -q "..."、--echo=false、またはパイプされた stdin を使用してください。
  • --echo-formatted [ <bool> ] — 表示するクエリをフォーマットします。省略可能なブール値を取ります。対話型モードではデフォルトで有効、バッチモードでは無効です。
  • --echo-query-id [ <bool> ] — 実行前に query_id を表示します。省略可能なブール値を取ります。対話型モードではデフォルトで有効、バッチモードでは無効です。
  • --echo-query-separator <string> — フォーマット済みで表示されるクエリの前にこの区切り文字を表示します (--echo-formatted が必要)。これにより、入力したクエリと整形後に表示されるクエリを区別しやすくなります。デフォルトは空 (無効) です。
  • --highlight, --hilite <bool> — コマンドプロンプトと表示されるクエリのシンタックスハイライトを切り替えます。デフォルトで有効です。ハイライトは端末への出力時にのみ適用されます。
  • --hints <bool> — カーソルが入力末尾にあるとき、最もよく一致する候補について、入力に応じた自動補完ヒント (インラインの "ghost" テキスト) を表示します。Up/Down (または Ctrl-Up/Ctrl-Down) でヒントを移動し、Tab または Right でインラインヒントを受け入れます。Enter はヒントが明示的に選択されている場合にのみそのヒントを受け入れ、それ以外の場合はクエリを実行します。Tab は従来の補完リストも開きます。--highlight が必要です (ヒントの表示に色が必要) 。候補ヒントには候補提示機能も必要なため、--disable_suggestion を指定するとそれらは無効になります。クライアントの / コマンド は静的なリストであり、--hints と --highlight が有効である限りヒントとして表示されます。ヒントが無効でも、Tab で / コマンドを補完できます。デフォルトで有効です。
  • --verbose — クエリ実行の詳細を表示します。
  • --logger.console — コンソールにログを出力します。
  • --logger.log — ログファイル名。
  • --logger.level — ログレベル。
  • --ignore-error — クエリが失敗しても処理を停止しません。
  • -c, --config-file — ClickHouseサーバー と同じ形式の設定ファイルへのパス。デフォルトでは設定は空です。
  • --no-system-tables — システムテーブルをアタッチしません。
  • --help — clickhouse-local の引数リファレンス。
  • -V, --version — バージョン情報を表示して終了します。

また、--config-file の代わりに、各 ClickHouse 設定変数に対応する引数を使用するほうが一般的です。

コマンド

LS コマンド

clickhouse-local がアクセスできる現在の作業ディレクトリ内のすべてのファイルを一覧表示します。

次のように対話型モードで実行できます。

Querysql
ClickHouse local version 26.3.1.1.

:) ls

SELECT _file AS file
FROM file('*', 'One')
ORDER BY file ASC
Responsetext
┌─file────────┐
│ file1.csv   │
│ file2.json  │
│ file3.xml   │
└─────────────┘

引数 -q を使って、クエリとして実行することもできます:

./clickhouse-local -q ls
Responsetext
file1.csv
file2.json
file3.xml

CLEAR コマンド

端末画面を消去します (Linux の clear コマンドや、多くの端末での Ctrl+L と同様です) 。これはクライアント側の動作であり、SQL エンジンには送信されません。

clickhouse-local では、このメタコマンドは 対話 モード、および -q と --queries-file の入力で認識されます (-q と同じクライアント経路で、考え方は ls と同じです) 。そのため、clear 単体では UNKNOWN_IDENTIFIER エラーは発生しません。リモートの clickhouse-client --queries-file は変更されていません。ファイルの内容は SQL としてのみ実行されます (テキストレベルのメタコマンドはありません) 。

clickhouse-client では、対話 モードでのみ認識されます。-q やクエリファイルでは、clear は引き続き SQL として解析されるため、自動化では、タイプミスが無言の no-op になるのではなく、従来どおりエラーになる動作が維持されます。

サポートされる形式: clear、CLEAR、/clear (末尾の任意の ; は無視されます) 。標準出力が端末ではない場合 (たとえば出力をパイプしている場合) 、このメタコマンドは認識されれば受け付けられますが、制御シーケンスは出力されません。

clickhouse-local と -q を使用する場合:

./clickhouse-local -q clear

例

Querybash
$ echo -e "1,2\n3,4" | clickhouse-local --structure "a Int64, b Int64" \
    --input-format "CSV" --query "SELECT * FROM table"
Read 2 rows, 32.00 B in 0.000 sec., 5182 rows/sec., 80.97 KiB/sec.
1   2
3   4

前の例と同じです：

Querybash
$ echo -e "1,2\n3,4" | clickhouse-local -n --query "
    CREATE TABLE table (a Int64, b Int64) ENGINE = File(CSV, stdin);
    SELECT a, b FROM table;
    DROP TABLE table;"
Read 2 rows, 32.00 B in 0.000 sec., 4987 rows/sec., 77.93 KiB/sec.
1   2
3   4

stdin や --file 引数を使用する必要はなく、file テーブル関数を使って任意の数のファイルを開くことができます:

Querybash
$ echo 1 | tee 1.tsv
1

$ echo 2 | tee 2.tsv
2

$ clickhouse-local --query "
    select * from file('1.tsv', TSV, 'a int') t1
    cross join file('2.tsv', TSV, 'b int') t2"
1    2

それでは、各 Unix ユーザーごとに memory user を出力してみましょう:

Querybash
$ ps aux | tail -n +2 | awk '{ printf("%s\t%s\n", $1, $4) }' \
    | clickhouse-local --structure "user String, mem Float64" \
        --query "SELECT user, round(sum(mem), 2) as memTotal
            FROM table GROUP BY user ORDER BY memTotal DESC FORMAT Pretty"
Responsetext
Read 186 rows, 4.15 KiB in 0.035 sec., 5302 rows/sec., 118.34 KiB/sec.
┏━━━━━━━━━━┳━━━━━━━━━━┓
┃ user     ┃ memTotal ┃
┡━━━━━━━━━━╇━━━━━━━━━━┩
│ bayonet  │    113.5 │
├──────────┼──────────┤
│ root     │      8.8 │
├──────────┼──────────┤
...

TCP および HTTP リスナーの起動

clickhouse-local は、TCP (ネイティブプロトコル) および HTTP 接続を受け付ける軽量なサーバーとして動作させることができます。これは、実行中の clickhouse-local インスタンスのデータベースやテーブルに、他の ClickHouse ツールやアプリケーションからアクセスできるようにしたい場合に便利です。なお、受信した各接続にはそれぞれ独自のセッションが割り当てられます。つまり、対話型 clickhouse-local セッションの一時テーブルやセッションレベルの設定は、外部接続からは参照できません。

リスナーを開くには SYSTEM START LISTEN を、閉じるには SYSTEM STOP LISTEN を使用します。

clickhouse-local \
    --listen_host 127.0.0.1 \
    --tcp_port 9000 \
    --http_port 8123 \
    --query "
        SYSTEM START LISTEN TCP;
        SYSTEM START LISTEN HTTP;
        SELECT * FROM url('http://127.0.0.1:8123/?query=SELECT+42', LineAsString);
        SYSTEM STOP LISTEN TCP;
        SYSTEM STOP LISTEN HTTP;
    "

--listen_host、--tcp_port、--http_port オプションは、バインド先のアドレスとポートを設定します。デフォルトのポートは、TCP が 9000、HTTP が 8123 です。

HTTP リスナーは、デフォルトの clickhouse-server 設定と同じ許容的なヘッダーで CORS プリフライトリクエストに応答するため、Web アプリケーションはブラウザーからそのままクエリを実行できます。これには、オリジンが null である file:// URL から開かれた Web UI も含まれます。これを制限するには、--config-file で渡す設定ファイルで独自の http_options_response セクションを定義します。この設定はデフォルトを完全に置き換えます。

関連コンテンツ

Navigation