メインコンテンツまでスキップ
バージョン: 3.2

Use S3 for shared-data

This topic describes how to deploy and use a shared-data StarRocks cluster. This feature is supported from v3.0 for S3 compatible storage and v3.1 for Azure Blob Storage.

NOTE

  • StarRocks version 3.1 brings some changes to the shared-data deployment and configuration. Please use this document if you are running version 3.1 or higher.
  • If you are running version 3.0 please use the 3.0 documentation.
  • Shared-data StarRocks clusters do not support data BACKUP and RESTORE.

The shared-data StarRocks cluster is specifically engineered for the cloud on the premise of separation of storage and compute. It allows data to be stored in object storage (for example, AWS S3, Google GCS, Azure Blob Storage, and MinIO). You can achieve not only cheaper storage and better resource isolation, but elastic scalability for your cluster. The query performance of the shared-data StarRocks cluster aligns with that of a shared-nothing StarRocks cluster when the local disk cache is hit.

In version 3.1 and higher the StarRocks shared-data cluster is made up of Frontend Engines (FEs) and Compute Nodes (CNs). The CNs replace the classic Backend Engines (BEs) in shared-data clusters.

Compared to the classic shared-nothing StarRocks architecture, separation of storage and compute offers a wide range of benefits. By decoupling these components, StarRocks provides:

  • Inexpensive and seamlessly scalable storage.
  • Elastic scalable compute. Because data is not stored in Compute Nodes (CNs), scaling can be done without data migration or shuffling across nodes.
  • Local disk cache for hot data to boost query performance.
  • Asynchronous data ingestion into object storage, allowing a significant improvement in loading performance.

アーキテクチャ​

Shared-data Architecture

共有データ StarRocks クラスタをデプロイする​

共有データ StarRocks クラスタのデプロイは、共有なし StarRocks クラスタのデプロイと似ています。唯一の違いは、共有データクラスタでは BEs の代わりに CNs をデプロイする必要があることです。このセクションでは、共有データ StarRocks クラスタをデプロイする際に、FE と CN の構成ファイル fe.conf と cn.conf に追加する必要がある追加の FE と CN の構成項目のみをリストします。StarRocks クラスタのデプロイに関する詳細な手順については、 Deploy StarRocks を参照してください。

NOTE

このドキュメントの次のセクションで共有ストレージ用に構成されるまで、クラスタを開始しないでください。

共有データ StarRocks 用の FE ノードを構成する​

クラスタを開始する前に、FEs と CNs を構成します。以下に例として構成を示し、各パラメータの詳細を提供します。

S3 用の FE 構成例​

以下は、各 FE ノードの fe.conf ファイルに追加する共有データの例です。例は、使用される AWS 認証方法に基づいて異なります。

デフォルトの認証資格情報​

run_mode = shared_data
cloud_native_meta_port = <meta_port>
cloud_native_storage_type = S3

# 例: testbucket/subpath
aws_s3_path = <s3_path>

# 例: us-west-2
aws_s3_region = <region>

# 例: https://s3.us-west-2.amazonaws.com
aws_s3_endpoint = <endpoint_url>

aws_s3_use_aws_sdk_default_behavior = true

# 上記の詳細を使用してオブジェクトストレージにデフォルトのストレージを作成したくない場合は false に設定します
enable_load_volume_from_conf = true

IAM ユーザーに基づく資格情報​

run_mode = shared_data
cloud_native_meta_port = <meta_port>
cloud_native_storage_type = S3

# 例: testbucket/subpath
aws_s3_path = <s3_path>

# 例: us-west-2
aws_s3_region = <region>

# S3 オブジェクトの読み書き用の資格情報
aws_s3_access_key = <access_key>
aws_s3_secret_key = <secret_key>

# 上記の詳細を使用してオブジェクトストレージにデフォルトのストレージを作成したくない場合は false に設定します
enable_load_volume_from_conf = true

インスタンスプロファイル​

run_mode = shared_data
cloud_native_meta_port = <meta_port>
cloud_native_storage_type = S3

# 例: testbucket/subpath
aws_s3_path = <s3_path>

# 例: us-west-2
aws_s3_region = <region>

# 例: https://s3.us-west-2.amazonaws.com
aws_s3_endpoint = <endpoint_url>

aws_s3_use_instance_profile = true

# 上記の詳細を使用してオブジェクトストレージにデフォルトのストレージを作成したくない場合は false に設定します
enable_load_volume_from_conf = true
注記

クラスタ内の FE ノードと CN ノードの両方にアクセス権を付与していることを確認してください。FE ノードは CN ノードへのアクセスを委任できません。

アサインされたロール​

run_mode = shared_data
cloud_native_meta_port = <meta_port>
cloud_native_storage_type = S3

# 例: testbucket/subpath
aws_s3_path = <s3_path>

# 例: us-west-2
aws_s3_region = <region>

# 例: https://s3.us-west-2.amazonaws.com
aws_s3_endpoint = <endpoint_url>

aws_s3_use_instance_profile = true
aws_s3_iam_role_arn = <role_arn>

# 上記の詳細を使用してオブジェクトストレージにデフォルトのストレージを作成したくない場合は false に設定します
enable_load_volume_from_conf = true
注記

クラスタ内の FE ノードと CN ノードの両方にアクセス権を付与していることを確認してください。FE ノードは CN ノードへのアクセスを委任できません。

外部アカウントからのアサインされたロール​

run_mode = shared_data
cloud_native_meta_port = <meta_port>
cloud_native_storage_type = S3

# 例: testbucket/subpath
aws_s3_path = <s3_path>

# 例: us-west-2
aws_s3_region = <region>

# 例: https://s3.us-west-2.amazonaws.com
aws_s3_endpoint = <endpoint_url>

aws_s3_use_instance_profile = true
aws_s3_iam_role_arn = <role_arn>
aws_s3_external_id = <external_id>

# 上記の詳細を使用してオブジェクトストレージにデフォルトのストレージを作成したくない場合は false に設定します
enable_load_volume_from_conf = true
注記

クラスタ内の FE ノードと CN ノードの両方にアクセス権を付与していることを確認してください。FE ノードは CN ノードへのアクセスを委任できません。

S3 を使用した共有ストレージに関連するすべての FE パラメータ​

run_mode​

StarRocks クラスタの実行モード。有効な値:

  • shared_data
  • shared_nothing (デフォルト)

NOTE

  • StarRocks クラスタに対して shared_data と shared_nothing モードを同時に採用することはできません。混在したデプロイはサポートされていません。
  • クラスタがデプロイされた後に run_mode を変更しないでください。そうしないと、クラスタが再起動に失敗します。共有なしクラスタから共有データクラスタへの変換、またはその逆はサポートされていません。

cloud_native_meta_port​

クラウドネイティブメタサービスの RPC ポート。

  • デフォルト: 6090

enable_load_volume_from_conf​

FE 構成ファイルに指定されたオブジェクトストレージ関連のプロパティを使用して、StarRocks がデフォルトのストレージボリュームを作成するかどうか。有効な値:

  • true (デフォルト) 新しい共有データクラスタを作成する際にこの項目を true に指定すると、StarRocks は FE 構成ファイルのオブジェクトストレージ関連のプロパティを使用して組み込みストレージボリューム builtin_storage_volume を作成し、デフォルトのストレージボリュームとして設定します。ただし、オブジェクトストレージ関連のプロパティを指定していない場合、StarRocks は起動に失敗します。
  • false 新しい共有データクラスタを作成する際にこの項目を false に指定すると、StarRocks は組み込みストレージボリュームを作成せずに直接起動します。StarRocks でオブジェクトを作成する前に、手動でストレージボリュームを作成し、デフォルトのストレージボリュームとして設定する必要があります。詳細については、 Create the default storage volume を参照してください。

v3.1.0 からサポートされています。

CAUTION

v3.0 から既存の共有データクラスタをアップグレードする際には、この項目を true のままにしておくことを強くお勧めします。この項目を false に指定すると、アップグレード前に作成したデータベースとテーブルが読み取り専用になり、それらにデータをロードすることができなくなります。

cloud_native_storage_type​

使用するオブジェクトストレージのタイプ。共有データモードでは、StarRocks は Azure Blob (v3.1.1 以降でサポート) と、S3 プロトコルと互換性のあるオブジェクトストレージ (AWS S3、Google GCP、MinIO など) にデータを保存することをサポートしています。有効な値:

  • S3 (デフォルト)
  • AZBLOB
  • HDFS

NOTE

  • このパラメータを S3 に指定した場合、aws_s3 で始まるパラメータを追加する必要があります。
  • このパラメータを AZBLOB に指定した場合、azure_blob で始まるパラメータを追加する必要があります。
  • このパラメータを HDFS に指定した場合、cloud_native_hdfs_url パラメータを追加する必要があります。

aws_s3_path​

データを保存するために使用される S3 パス。S3 バケットの名前と、その下のサブパス (存在する場合) で構成されます。例: testbucket/subpath。

aws_s3_endpoint​

S3 バケットにアクセスするために使用されるエンドポイント。例: https://s3.us-west-2.amazonaws.com。

aws_s3_region​

S3 バケットが存在するリージョン。例: us-west-2。

aws_s3_use_aws_sdk_default_behavior​

AWS SDK デフォルトの資格情報プロバイダーチェーン を使用するかどうか。有効な値:

  • true
  • false (デフォルト)

aws_s3_use_instance_profile​

S3 へのアクセスのための資格情報メソッドとしてインスタンスプロファイルとアサインされたロールを使用するかどうか。有効な値:

  • true
  • false (デフォルト)

IAM ユーザーに基づく資格情報 (アクセスキーとシークレットキー) を使用して S3 にアクセスする場合、この項目を false に指定し、aws_s3_access_key と aws_s3_secret_key を指定する必要があります。

インスタンスプロファイルを使用して S3 にアクセスする場合、この項目を true に指定する必要があります。

アサインされたロールを使用して S3 にアクセスする場合、この項目を true に指定し、aws_s3_iam_role_arn を指定する必要があります。

外部 AWS アカウントを使用する場合、aws_s3_external_id も指定する必要があります。

aws_s3_access_key​

S3 バケットにアクセスするために使用されるアクセスキー ID。

aws_s3_secret_key​

S3 バケットにアクセスするために使用されるシークレットアクセスキー。

aws_s3_iam_role_arn​

データファイルが保存されている S3 バケットに対する権限を持つ IAM ロールの ARN。

aws_s3_external_id​

S3 バケットへのクロスアカウントアクセスに使用される AWS アカウントの外部 ID。

NOTE

共有データ StarRocks クラスタが作成された後に変更できるのは、資格情報に関連する構成項目のみです。元のストレージパスに関連する構成項目を変更した場合、変更前に作成したデータベースとテーブルが読み取り専用になり、それらにデータをロードすることができなくなります。

クラスタが作成された後にデフォルトのストレージボリュームを手動で作成したい場合、次の構成項目のみを追加する必要があります。

run_mode = shared_data
cloud_native_meta_port = <meta_port>
enable_load_volume_from_conf = false

共有データ StarRocks 用の CN ノードを構成する​

Before starting CNs, add the following configuration items in the CN configuration file cn.conf:

starlet_port = <starlet_port>
storage_root_path = <storage_root_path>

starlet_port​

The CN heartbeat service port for the StarRocks shared-data cluster. Default value: 9070.

storage_root_path​

The storage volume directory that the local cached data depends on. Multiple volumes are separated by semicolon (;). Example: /data1;/data2.

The default value for storage_root_path is ${STARROCKS_HOME}/storage.

Local cache is effective when queries are frequent and the data being queried is recent, but there are cases that you may wish to turn off the local cache completely.

  • In a Kubernetes environment with CN pods that scale up and down in number on demand, the pods may not have storage volumes attached.
  • When the data being queried is in a data lake in remote storage and most of it is archive (old) data. If the queries are infrequent the data cache will have a low hit ratio and the benefit may not be worth having the cache.

To turn off the data cache set:

storage_root_path =

NOTE

The data is cached under the directory <storage_root_path>/starlet_cache.

共有データ StarRocks クラスタを使用する​

The usage of shared-data StarRocks clusters is also similar to that of a classic shared-nothing StarRocks cluster, except that the shared-data cluster uses storage volumes and cloud-native tables to store data in object storage.

Create default storage volume​

You can use the built-in storage volumes that StarRocks automatically creates, or you can manually create and set the default storage volume. This section describes how to manually create and set the default storage volume.

NOTE

If your shared-data StarRocks cluster is upgraded from v3.0, you do not need to define a default storage volume because StarRocks created one with the object storage-related properties you specified in the FE configuration file fe.conf. You can still create new storage volumes with other object storage resources and set the default storage volume differently.

To give your shared-data StarRocks cluster permission to store data in your object storage, you must reference a storage volume when you create databases or cloud-native tables. A storage volume consists of the properties and credential information of the remote data storage. If you have deployed a new shared-data StarRocks cluster and disallow StarRocks to create a built-in storage volume (by specifying enable_load_volume_from_conf as false), you must define a default storage volume before you can create databases and tables in the cluster.

次の例では、IAM ユーザーに基づく資格情報 (アクセスキーとシークレットキー) を使用して AWS S3 バケット defaultbucket のためのストレージボリューム def_volume を作成し、 Partitioned Prefix 機能を有効にし、それをデフォルトのストレージボリュームとして設定します。

CREATE STORAGE VOLUME def_volume
TYPE = S3
LOCATIONS = ("s3://defaultbucket")
PROPERTIES
(
    "enabled" = "true",
    "aws.s3.region" = "us-west-2",
    "aws.s3.endpoint" = "https://s3.us-west-2.amazonaws.com",
    "aws.s3.use_aws_sdk_default_behavior" = "false",
    "aws.s3.use_instance_profile" = "false",
    "aws.s3.access_key" = "xxxxxxxxxx",
    "aws.s3.secret_key" = "yyyyyyyyyy",
    "aws.s3.enable_partitioned_prefix" = "true"
);

SET def_volume AS DEFAULT STORAGE VOLUME;

For more information on how to create a storage volume for other object storages and set the default storage volume, see CREATE STORAGE VOLUME and SET DEFAULT STORAGE VOLUME.

Create a database and a cloud-native table​

After you create a default storage volume, you can then create a database and a cloud-native table using this storage volume.

Shared-data StarRocks clusters support all StarRocks table types.

The following example creates a database cloud_db and a table detail_demo based on Duplicate Key table type, enables the local disk cache, sets the hot data validity duration to one month, and disables asynchronous data ingestion into object storage:

CREATE DATABASE cloud_db;
USE cloud_db;
CREATE TABLE IF NOT EXISTS detail_demo (
    recruit_date  DATE           NOT NULL COMMENT "YYYY-MM-DD",
    region_num    TINYINT        COMMENT "range [-128, 127]",
    num_plate     SMALLINT       COMMENT "range [-32768, 32767] ",
    tel           INT            COMMENT "range [-2147483648, 2147483647]",
    id            BIGINT         COMMENT "range [-2^63 + 1 ~ 2^63 - 1]",
    password      LARGEINT       COMMENT "range [-2^127 + 1 ~ 2^127 - 1]",
    name          CHAR(20)       NOT NULL COMMENT "range char(m),m in (1-255) ",
    profile       VARCHAR(500)   NOT NULL COMMENT "upper limit value 65533 bytes",
    ispass        BOOLEAN        COMMENT "true/false")
DUPLICATE KEY(recruit_date, region_num)
DISTRIBUTED BY HASH(recruit_date, region_num)
PROPERTIES (
    "storage_volume" = "def_volume",
    "datacache.enable" = "true",
    "datacache.partition_duration" = "1 MONTH"
);

NOTE

The default storage volume is used when you create a database or a cloud-native table in a shared-data StarRocks cluster if no storage volume is specified.

In addition to the regular table PROPERTIES, you need to specify the following PROPERTIES when creating a table for shared-data StarRocks cluster:

datacache.enable​

Whether to enable the local disk cache.

  • true (Default) When this property is set to true, the data to be loaded is simultaneously written into the object storage and the local disk (as the cache for query acceleration).
  • false When this property is set to false, the data is loaded only into the object storage.

NOTE

In version 3.0 this property was named enable_storage_cache.

To enable the local disk cache, you must specify the directory of the disk in the CN configuration item storage_root_path.

datacache.partition_duration​

The validity duration of the hot data. When the local disk cache is enabled, all data is loaded into the cache. When the cache is full, StarRocks deletes the less recently used data from the cache. When a query needs to scan the deleted data, StarRocks checks if the data is within the duration of validity starting from the current time. If the data is within the duration, StarRocks loads the data into the cache again. If the data is not within the duration, StarRocks does not load it into the cache. This property is a string value that can be specified with the following units: YEAR, MONTH, DAY, and HOUR, for example, 7 DAY and 12 HOUR. If it is not specified, all data is cached as the hot data.

NOTE

In version 3.0 this property was named storage_cache_ttl.

This property is available only when datacache.enable is set to true.

View table information​

You can view the information of tables in a specific database using SHOW PROC "/dbs/<db_id>". See SHOW PROC for more information.

Example:

mysql> SHOW PROC "/dbs/xxxxx";
+---------+-------------+----------+---------------------+--------------+--------+--------------+--------------------------+--------------+---------------+------------------------------+
| TableId | TableName   | IndexNum | PartitionColumnName | PartitionNum | State  | Type         | LastConsistencyCheckTime | ReplicaCount | PartitionType | StoragePath                  |
+---------+-------------+----------+---------------------+--------------+--------+--------------+--------------------------+--------------+---------------+------------------------------+
| 12003   | detail_demo | 1        | NULL                | 1            | NORMAL | CLOUD_NATIVE | NULL                     | 8            | UNPARTITIONED | s3://xxxxxxxxxxxxxx/1/12003/ |
+---------+-------------+----------+---------------------+--------------+--------+--------------+--------------------------+--------------+---------------+------------------------------+

The Type of a table in shared-data StarRocks cluster is CLOUD_NATIVE. In the field StoragePath, StarRocks returns the object storage directory where the table is stored.

Load data into a shared-data StarRocks cluster​

Shared-data StarRocks clusters support all loading methods provided by StarRocks. See Loading options for more information.

Query in a shared-data StarRocks cluster​

Tables in a shared-data StarRocks cluster support all types of queries provided by StarRocks. See StarRocks SELECT for more information.

NOTE

Shared-data StarRocks clusters do not support synchronous materialized views.