starrocks-expert

StarRocks エキスパート

StarRocks は、多次元分析、リアルタイム分析、アドホッククエリなど、あらゆる分析シナリオに対応する次世代のサブ秒 MPP OLAP データベースです。

クイックリファレンス

一般的な操作

テーブル構造を確認する：

SHOW CREATE TABLE database_name.table_name;
DESC database_name.table_name;

パーティションを表示する：

SHOW PARTITIONS FROM database_name.table_name;

データロードの状態を確認する：

SHOW LOAD WHERE label = 'your_load_label';
SHOW STREAM LOAD;

クエリ実行を分析する：

EXPLAIN VERBOSE SELECT ...;
SHOW QUERY PROFILE '<query_id>';

主な概念

テーブルの種類：

• 重複キー：一意制約がなく、生データのログ記録に最適です
• 集計キー：データの取り込み時に事前集計します
• 一意キー：一意性を適用し、アップサートに対応します
• 主キー：一意キーと似ていますが、更新性能に優れています

データロード方法：

• ストリームロード：HTTP ベースのリアルタイムロード
• ブローカーロード：外部ストレージ（S3、HDFS）からのバッチロード
• ルーティンロード：Kafka からの継続的なロード
• INSERT INTO：SQL による直接挿入

マテリアライズドビュー：

• 非同期 MV：スケジュールに基づく更新、複雑な変換に対応
• 同期ロールアップ：集計を自動的に維持します

このスキルを使用する場面

次のような場合にこのスキルを使用します：

• StarRocks のテーブルスキーマを作成または変更する
• S3、HDFS、Kafka からのデータロードパイプラインを設定する
• 遅いクエリを最適化する、またはクエリプランを分析する
• パーティショニングとバケット化の戦略を設定する
• データロードの失敗をトラブルシューティングする
• マテリアライズドビューやロールアップを設定する
• クラスターのリソースと設定を管理する

主なセクション

1. テーブル設計

テーブル設計の詳細については、TABLE.md を参照してください：

• テーブルの種類（重複キー、集計キー、一意キー、主キー）
• date_trunc() 式を使用したパーティショニング戦略
• バケット化と分散
• インデックス（プレフィックス、ブルームフィルター、ビットマップ、ngram）

2. インフラストラクチャの設定と管理

インフラストラクチャの詳細については、INFRA.md を参照してください：

• クラスターのセットアップと設定（FE/BE/Broker）
• リソース管理とリソースグループ
• 監視とメンテナンス
• バックアップと復旧

3. クエリとタスクのスキル

クエリ最適化の詳細については、QUERY.md を参照してください：

• データロードのパターン（ストリームロード、ブローカーロード、ルーティンロード）
• クエリ最適化の手法
• マテリアライズドビューの設計
• ETL パイプラインのパターン
• パフォーマンスのトラブルシューティング
• 一般的なアンチパターン

テーブル作成パターン

CREATE TABLE IF NOT EXISTS database_name.table_name (
    event_time DATETIME NOT NULL COMMENT 'Event timestamp',
    id BIGINT NOT NULL COMMENT 'Business ID',
    amount DECIMAL(18, 2) COMMENT 'Transaction amount',
    status VARCHAR(50) COMMENT 'Status code',
    created_at DATETIME COMMENT 'Creation timestamp'
)
DUPLICATE KEY (event_time, id)
PARTITION BY date_trunc('day', event_time)  -- Expression-based partitioning
DISTRIBUTED BY HASH(id) BUCKETS 16
PROPERTIES (
    "replication_num" = "3",
    "storage_medium" = "SSD",
    "storage_cooldown_time" = "2024-12-31 23:59:59"
);

テーブルの種類、パーティショニング戦略、インデックスの選択について詳しくは、TABLE.md を参照してください。

データロードのパターン

ストリームロード（HTTP ベース）

curl --location-trusted -u user:password \
    -H "label:load_label_$(date +%s)" \
    -H "column_separator:," \
    -H "columns:date_col,id,amount,status,created_at" \
    -T data.csv \
    http://fe_host:8030/api/database_name/table_name/_stream_load

ブローカーロード（S3）

LOAD LABEL database_name.load_label_20240101
(
    DATA INFILE("s3://bucket/path/data_*.parquet")
    INTO TABLE table_name
    FORMAT AS "parquet"
)
WITH BROKER
(
    "aws.s3.access_key" = "your_access_key",
    "aws.s3.secret_key" = "your_secret_key",
    "aws.s3.region" = "us-east-1"
)
PROPERTIES (
    "timeout" = "3600"
);

クエリ最適化チェックリスト

クエリを最適化する際は、次の点を確認します：

• パーティションプルーニングが機能しているか確認する（EXPLAIN で検証）
• 適切なインデックスが存在することを確認する（プレフィックスブルームフィルター、ビットマップ）
• JOIN の順序を検証する（ブロードキャスト JOIN では右側に小さいテーブルを配置）
• マテリアライズドビューを使用できるか確認する
• データ分布を分析する（データスキューを回避）
• バケット数を確認する（最適値：BE コアあたり 2～8）
• 頻繁に JOIN する場合は、コロケートグループの使用を検討する

パーティション管理

式ベースのパーティショニング（モダンな方法、推奨）

データに基づいてパーティションが自動的に作成されます：

-- Partitions auto-created on INSERT
CREATE TABLE events (
    event_time DATETIME,
    user_id BIGINT
)
DUPLICATE KEY (event_time)
PARTITION BY date_trunc('day', event_time)  -- Auto-creates daily partitions
DISTRIBUTED BY HASH(user_id) BUCKETS 16;

-- Hourly granularity for high-frequency data
PARTITION BY date_trunc('hour', event_time)

-- Monthly for long-term storage
PARTITION BY date_trunc('month', event_time)

複合パーティショニング（マルチテナント）

CREATE TABLE metrics (
    tenant_id INT,
    dt DATETIME,
    metric_name STRING,
    value DOUBLE
)
PRIMARY KEY (tenant_id, dt, metric_name)
PARTITION BY tenant_id, date_trunc('day', dt)
DISTRIBUTED BY HASH(tenant_id) BUCKETS 16;

古いパーティションを削除する

-- Show partitions first
SHOW PARTITIONS FROM table_name;

-- Drop specific partition by name
ALTER TABLE table_name DROP PARTITION p20230101_10001;

マテリアライズドビューのパターン

CREATE MATERIALIZED VIEW mv_daily_summary
BUILD IMMEDIATE
REFRESH ASYNC START('2024-01-01 00:00:00') EVERY(INTERVAL 1 DAY)
AS
SELECT
    date_col,
    status,
    COUNT(*) as total_count,
    SUM(amount) as total_amount,
    AVG(amount) as avg_amount
FROM database_name.table_name
GROUP BY date_col, status;

トラブルシューティングのクイックガイド

データロードに失敗する

1. エラーメッセージを確認します：SHOW LOAD WHERE label = 'your_label'
2. データ形式が列の定義と一致していることを確認します
3. ブローカーへの接続を確認します（ブローカーロードの場合）
4. リソースが利用可能であることを確認します：SHOW PROC '/backends'

クエリが遅い

1. EXPLAIN VERBOSE を実行して実行計画を確認します
2. パーティションプルーニングが有効であることを確認します
3. 分散におけるデータスキューを確認します
4. JOIN 戦略（ブロードキャストまたはシャッフル）を見直します
5. マテリアライズドビューの作成を検討します

コンパクションの問題

-- Check compaction status
SHOW PROC '/backends';
SHOW TABLET STATUS FROM table_name;

-- Trigger manual compaction if needed
ALTER TABLE table_name COMPACT;

ベストプラクティス

テーブル設計

• ユースケースに基づいて適切なテーブルタイプを選択します
• 時間ベースのパーティショニングには date_trunc() 式を使用します
• クラスターの規模に基づいて replication_num を設定します（通常は 3）
• バケット数 = BE のコア数 × 2～8
• パーティションの総数は 100k 未満にします（複合パーティションに注意してください）

クエリパフォーマンス

• 可能な場合は必ずパーティションキーでフィルタリングします
• カーディナリティの高い文字列列にはプレフィックスブルームフィルターを使用します
• 本番クエリで SELECT * を使用しないでください
• 適切な JOIN タイプを使用します（可能な場合は INNER JOIN を優先します）

データ読み込み

• リアルタイムの小規模バッチ（<10GB）には Stream Load を使用します
• オブジェクトストレージからの大規模なバッチ読み込みには Broker Load を使用します
• データ量に応じて適切なタイムアウトを設定します
• 読み込みジョブのステータスを監視し、失敗に対処します

メンテナンス

• 時系列テーブルでは動的パーティショニングを有効にします
• ストレージを管理するため、古いパーティションを定期的に削除します
• BE 間のタブレット分散を監視します
• 読み込みの失敗とクエリタイムアウトに対するアラートを設定します

避けるべき一般的なアンチパターン

❌ しないでください パーティション分割する時間列に VARCHAR を使用する ❌ しないでください WHERE 句でパーティション列に関数を適用する（プルーニングが機能しなくなります） ❌ しないでください バケットを多く作りすぎる（小さなファイルが発生します） ❌ しないでください バケットを少なく作りすぎる（データの偏りが発生します） ❌ しないでください パーティションプルーニング述語を省略する ❌ しないでください 重複排除だけが必要な場合に UNIQUE KEY を使用する（DUPLICATE + GROUP BY を使用してください） ❌ しないでください ラベルなしでデータを読み込む（重複検出ができなくなります） ❌ しないでください 合計パーティション数が 100k を超える複合パーティションを作成する

追加リソース

• インフラストラクチャの詳細：INFRA.md を参照し、クラスターのセットアップ、テーブル設計パターン、リソース管理について確認してください
• クエリの最適化：QUERY.md を参照し、高度なクエリチューニング、読み込みパターン、ETL ワークフローについて確認してください

主な設定プロパティ

テーブルプロパティ

"replication_num" = "3"                      # Number of replicas
"storage_medium" = "SSD"                     # Storage type (SSD/HDD)
"enable_persistent_index" = "true"           # For primary key tables
"bloom_filter_columns" = "id,email"          # Bloom filter index
"colocate_with" = "group_name"              # Colocate tables

セッション変数

SET enable_pipeline_engine = true;           # Enable vectorized execution
SET pipeline_dop = 0;                        # Parallelism (0 = auto)
SET query_timeout = 300;                     # Query timeout in seconds
SET enable_spill = true;                     # Enable disk spill for large joins

はじめ方のワークフロー

新しい StarRocks プロジェクトに取り組む場合：

1. ユースケースを理解する

   • OLAP 分析かリアルタイムレポートか
   • クエリパターン（集計、結合、フィルター）
   • データ量と保持要件

2. テーブルスキーマを設計する

   • 適切なキータイプ（Duplicate／Aggregate／Unique／Primary）を選択します
   • パーティション戦略を定義します（日付による範囲分割）
   • データ量に基づいてバケット数を計算します
   • 詳細なガイダンスについては INFRA.md をお読みください

3. データパイプラインを設定する

   • 読み込み方法（Stream／Broker／Routine Load）を選択します
   • エラー処理と再試行ロジックを設定します
   • 読み込みパターンについては QUERY.md をお読みください

4. クエリを最適化する

   • クエリパターンを分析します
   • 一般的な集計用にマテリアライズドビューを作成します
   • パーティションとバケットの戦略を調整します
   • 最適化手法については QUERY.md をお読みください

5. 監視とメンテナンスを行う

   • 読み込みジョブとクエリパフォーマンスの監視を設定します
   • パーティション管理を自動化するよう設定します
   • データの保持とアーカイブを計画します