diff --git a/docs/en/introduction/Architecture.md b/docs/en/introduction/Architecture.md index 2dd28b5..f43627c 100644 --- a/docs/en/introduction/Architecture.md +++ b/docs/en/introduction/Architecture.md @@ -5,7 +5,7 @@ import QSOverview from '../_assets/commonMarkdown/quickstart-overview-tip.mdx' # Architecture -StarRocks has a simple architecture. The entire system consists of only two types of components; frontends and backends. The frontend nodes are called **FE**s. There are two types of backend nodes, **BE**s, and **CN**s (Compute Nodes). BEs are deployed when local storage for data is used, and CNs are deployed when data is stored on object storage or HDFS. StarRocks does not rely on any external components, simplifying deployment and maintenance. Nodes can be horizontally scaled without service downtime. In addition, StarRocks has a replica mechanism for metadata and service data, which increases data reliability and efficiently prevents single points of failure (SPOFs). +StarRocks has a robust architecture. The entire system consists of only two types of components; frontends and backends. The frontend nodes are called **FE**s. There are two types of backend nodes, **BE**s, and **CN**s (Compute Nodes). BEs are deployed when local storage for data is used, and CNs are deployed when data is stored on object storage or HDFS. StarRocks does not rely on any external components, simplifying deployment and maintenance. Nodes can be horizontally scaled without service downtime. In addition, StarRocks has a replica mechanism for metadata and service data, which increases data reliability and efficiently prevents single points of failure (SPOFs). StarRocks is compatible with MySQL protocols and supports standard SQL. Users can easily connect to StarRocks from MySQL clients to gain instant and valuable insights. diff --git a/docs/en/quick_start/routine-load.md b/docs/en/quick_start/routine-load.md index 3a4b17f..3faef04 100644 --- a/docs/en/quick_start/routine-load.md +++ b/docs/en/quick_start/routine-load.md @@ -10,8 +10,6 @@ description: Kafka routine load with shared-data storage import Clients from '../_assets/quick-start/_clientsCompose.mdx' import SQL from '../_assets/quick-start/_SQL.mdx' -## About Routine Load - Routine load is a method using Apache Kafka, or in this lab, Redpanda, to continuously stream data into StarRocks. The data is streamed into a Kafka topic, and a Routine Load job consumes the data into StarRocks. More details on Routine Load are provided at the end of the lab. ## About shared-data diff --git a/docs/en/sql-reference/sql-functions/dict-functions/dict_mapping.md b/docs/en/sql-reference/sql-functions/dict-functions/dict_mapping.md index 58e409e..c110abd 100644 --- a/docs/en/sql-reference/sql-functions/dict-functions/dict_mapping.md +++ b/docs/en/sql-reference/sql-functions/dict-functions/dict_mapping.md @@ -6,7 +6,7 @@ displayed_sidebar: docs Returns the value mapped to the specified key in a dictionary table. -This function is mainly used to simplify the application of a global dictionary table. During data loading into a target table, StarRocks automatically obtains the value mapped to the specified key from the dictionary table by using the input parameters in this function, and then loads the value into the target table. +`dict_mapping` simplifies the application of a global dictionary table. During data loading into a target table, StarRocks automatically obtains the value mapped to the specified key from the dictionary table by using the input parameters in this function, and then loads the value into the target table. Since v3.2.5, StarRocks supports this function. Also, note that currently StarRocks's shared-data mode does not support this function. diff --git a/docs/ja/introduction/Architecture.md b/docs/ja/introduction/Architecture.md new file mode 100644 index 0000000..1c6a57d --- /dev/null +++ b/docs/ja/introduction/Architecture.md @@ -0,0 +1,74 @@ +--- +displayed_sidebar: docs +--- +import QSOverview from '../_assets/commonMarkdown/quickstart-overview-tip.mdx' + +# アーキテクチャ + +StarRocks は、堅牢なアーキテクチャを備えています。システム全体は、フロントエンドとバックエンドの 2 種類のコンポーネントのみで構成されています。フロントエンドノードは **FE** と呼ばれます。バックエンドノードには、**BE** と **CN** (コンピュートノード) の 2 種類があります。BE はデータのローカルストレージが使用される場合にデプロイされ、CN はデータがオブジェクトストレージまたは HDFS に保存される場合にデプロイされます。StarRocks は外部コンポーネントに依存しないため、デプロイとメンテナンスが簡素化されます。ノードは、サービスを停止することなく水平方向に拡張できます。さらに、StarRocks にはメタデータとサービスデータのレプリカメカニズムがあり、データの信頼性を高め、シングルポイント障害 (SPOF) を効率的に防止します。 + +StarRocks は MySQL プロトコルと互換性があり、標準 SQL をサポートしています。ユーザーは MySQL クライアントから StarRocks に簡単に接続して、即座に価値のある洞察を得ることができます。 +## アーキテクチャの選択 + +StarRocks は、共有なし（各 BE はローカルストレージ上のデータの一部を持つ）と共有データ（すべてのデータはオブジェクトストレージまたは HDFS 上にあり、各 CN はローカルストレージ上にキャッシュのみを持つ）をサポートしています。必要に応じて、データの保存場所を決定できます。 + +![アーキテクチャの選択](../_assets/architecture_choices.png) +### 共有なし + +ローカルストレージは、リアルタイムクエリのクエリレイテンシを改善します。 + +一般的な超並列処理（MPP）データベースとして、StarRocks は共有なしアーキテクチャをサポートしています。このアーキテクチャでは、BE はデータストレージと計算の両方を担当します。BE モードでローカルデータに直接アクセスすることで、ローカルでの計算が可能になり、データ転送やデータコピーを回避し、超高速なクエリと分析パフォーマンスを提供します。このアーキテクチャは、マルチレプリカデータストレージをサポートし、クラスタの高い同時実行性クエリを処理する能力を高め、データの信頼性を確保します。最適なクエリパフォーマンスを追求するシナリオに最適です。 + +![shared-data-arch](../_assets/shared nothing.png) +#### ノード + +共有なしアーキテクチャにおいて、StarRocks は FE と BE という2種類のノードで構成されています。 + +- FE は、メタデータ管理と実行クエリプランの構築を担当します。 +- BE は、クエリプランを実行し、データを保存します。BE は、ローカルストレージを利用してクエリを高速化し、マルチレプリカメカニズムによって高いデータ可用性を確保します。 +##### FE + +FE は、メタデータ管理、クライアント接続管理、クエリプラン、およびクエリスケジューリングを担当します。各 FE は、BDB JE (Berkeley DB Java Edition) を使用して、メモリ内のメタデータの完全なコピーを保存および管理し、すべての FE で一貫したサービスを保証します。FE は、leader、follower、および observer として機能できます。leader ノードがクラッシュした場合、follower は Raft プロトコルに基づいて leader を選出します。 + +| **FE Role** | **Metadata management** | **Leader election** | +| ----------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------------------- | +| Leader | Leader FE は、メタデータの読み取りと書き込みを行います。Follower FE と Observer FE は、メタデータの読み取りのみ可能です。メタデータの書き込みリクエストを Leader FE にルーティングします。Leader FE はメタデータを更新し、Raft プロトコルを使用して、メタデータの変更を Follower FE と Observer FE に同期します。データの書き込みは、メタデータの変更が Follower FE の半数以上に同期された後にのみ成功とみなされます。 | Leader FE は、厳密に言うと、follower ノードでもあり、follower FE から選出されます。Leader 選出を実行するには、クラスタ内の Follower FE の半数以上がアクティブである必要があります。Leader FE に障害が発生すると、Follower FE は別の Leader 選出手順を開始します。 | +| Follower | Follower はメタデータの読み取りのみ可能です。Leader FE からログを同期および再生して、メタデータを更新します。 | Follower は Leader 選出に参加します。これには、クラスタ内の Follower の半数以上がアクティブである必要があります。 | +| Observer | Observer は Leader FE からログを同期および再生して、メタデータを更新します。 | Observer は主に、クラスタのクエリの同時実行性を高めるために使用されます。Observer は Leader 選出に参加しないため、クラスタに Leader 選出の負荷を追加することはありません。| +##### BE + +BEは、データストレージとSQL実行を担当します。 + +- データストレージ：BEは同等のデータストレージ機能を持ちます。FEは、事前定義されたルールに基づいてデータをBEに分散します。BEは取り込まれたデータを変換し、必要な形式でデータを書き込み、データのインデックスを生成します。 + +- SQL実行：FEは、各SQLクエリをクエリのセマンティクスに従って論理実行プランに解析し、次にその論理プランをBEで実行可能な物理実行プランに変換します。宛先データを格納するBEがクエリを実行します。これにより、データ伝送とコピーの必要がなくなり、高いクエリパフォーマンスを実現します。 +### 共有データ + +オブジェクトストレージとHDFSは、コスト、信頼性、および拡張性の利点を提供します。ストレージの拡張性に加えて、ストレージとコンピュートが分離されているため、データをリバランスすることなくCNノードを追加および削除できます。 + +共有データアーキテクチャでは、BEは「コンピュートノード（CN）」に置き換えられます。コンピュートノードは、データコンピュートタスクとホットデータのキャッシュのみを担当します。データは、Amazon S3、Google Cloud Storage、Azure Blob Storage、MinIOなどの低コストで信頼性の高いリモートストレージシステムに保存されます。キャッシュがヒットすると、クエリパフォーマンスは共有なしアーキテクチャのクエリパフォーマンスに匹敵します。CNノードは、必要に応じて数秒以内に追加または削除できます。このアーキテクチャにより、ストレージコストが削減され、より優れたリソース分離、高い弾力性と拡張性が確保されます。 + +共有データアーキテクチャは、共有なしアーキテクチャと同様にシンプルなアーキテクチャを維持します。FEとCNの2種類のノードのみで構成されています。唯一の違いは、ユーザーがバックエンドのオブジェクトストレージをプロビジョニングする必要があることです。 + +![shared-data-arch](../_assets/shared-data.png) +#### ノード + +共有データアーキテクチャにおけるコーディネーターノードは、共有なしアーキテクチャにおける FE と同じ機能を提供します。 + +BE は CN (コンピュートノード) に置き換えられ、ストレージ機能はオブジェクトストレージまたは HDFS にオフロードされます。CN はステートレスなコンピュートノードであり、データのストレージを除く BE のすべての機能を実行します。 +#### ストレージ + +StarRocks の共有データクラスタは、オブジェクトストレージ（例えば、AWS S3、Google GCS、Azure Blob Storage、または MinIO）と HDFS の2つのストレージソリューションをサポートしています。 + +共有データクラスタでは、データファイル形式は、（ストレージとコンピュートが結合された）共有なしクラスタと一貫性を保ちます。データはセグメントファイルに編成され、様々なインデックス技術がクラウドネイティブテーブルで再利用されます。クラウドネイティブテーブルは、共有データクラスタで特に使用されるテーブルです。 +#### キャッシュ + +StarRocks の共有データクラスタは、データストレージとコンピュートを分離し、それぞれが独立して拡張できるようにすることで、コストを削減し、弾力性を高めます。ただし、このアーキテクチャはクエリパフォーマンスに影響を与える可能性があります。 + +その影響を軽減するために、StarRocks は、さまざまなビジネスニーズにより良く対応するために、メモリ、ローカルディスク、およびリモートストレージを包含する多層データアクセスシステムを確立します。 + +ホットデータに対するクエリは、キャッシュを直接スキャンしてからローカルディスクをスキャンしますが、コールドデータは、後続のクエリを高速化するために、オブジェクトストレージからローカルキャッシュにロードする必要があります。ホットデータをコンピュートユニットの近くに保持することで、StarRocks は真に高性能なコンピュートと費用対効果の高いストレージを実現します。さらに、コールドデータへのアクセスは、データプリフェッチ戦略で最適化されており、クエリのパフォーマンス制限を効果的に排除します。 + +キャッシングは、テーブルの作成時に有効にできます。キャッシングが有効になっている場合、データはローカルディスクとバックエンドのオブジェクトストレージの両方に書き込まれます。クエリ中、CN ノードは最初にローカルディスクからデータを読み取ります。データが見つからない場合は、バックエンドのオブジェクトストレージから取得され、同時にローカルディスクにキャッシュされます。 + + \ No newline at end of file diff --git a/docs/ja/quick_start/routine-load.md b/docs/ja/quick_start/routine-load.md new file mode 100644 index 0000000..53c0a4a --- /dev/null +++ b/docs/ja/quick_start/routine-load.md @@ -0,0 +1,674 @@ +--- +displayed_sidebar: docs +sidebar_position: 2 +toc_max_heading_level: 2 +description: 共有データストレージを使用した Kafka routine load +--- + +# 共有データストレージを使用した StarRocks の Kafka routine load + +import Clients from '../_assets/quick-start/_clientsCompose.mdx' +import SQL from '../_assets/quick-start/_SQL.mdx' + +Routine Load は、Apache Kafka（またはこのラボでは Redpanda）を使用して、データを継続的に StarRocks にストリーミングする手法です。データは Kafka トピックにストリーミングされ、Routine Load ジョブがそのデータを StarRocks に取り込みます。Routine Load の詳細については、ラボの最後に記載されています。 +## 共有データについて + +ストレージとコンピュートを分離するシステムでは、データは Amazon S3、Google Cloud Storage、Azure Blob Storage、および MinIO のような他の S3 互換ストレージなどの低コストで信頼性の高いリモートストレージシステムに保存されます。ホットデータはローカルにキャッシュされ、キャッシュがヒットすると、クエリパフォーマンスはストレージとコンピュートが結合されたアーキテクチャと同等になります。コンピュートノード（CN）は、数秒以内にオンデマンドで追加または削除できます。このアーキテクチャは、ストレージコストを削減し、より優れたリソース分離を保証し、伸縮性と拡張性を提供します。 + +このチュートリアルでは、以下について説明します。 + +- Docker Compose を使用した StarRocks、Redpanda、および MinIO の実行 +- MinIO を StarRocks のストレージレイヤーとして使用 +- 共有データ用に StarRocks を構成 +- Redpanda からデータを取り込むための Routine Load ジョブの追加 + +使用されるデータは合成データです。 + +このドキュメントには多くの情報が含まれており、最初にステップごとのコンテンツが提示され、最後に技術的な詳細が記載されています。これは、次の目的をこの順序で果たすために行われます。 + +1. Routine Load を構成します。 +2. 読者が共有データデプロイメントでデータをロードし、そのデータを分析できるようにします。 +3. 共有データデプロイメントの構成の詳細を提供します。 + +--- +## 前提条件 +### Docker + +- [Docker](https://docs.docker.com/engine/install/) +- Docker に割り当てられた 4 GB の RAM +- Docker に割り当てられた 10 GB の空きディスク容量 +### SQL クライアント + +Docker 環境で提供されている SQL クライアントを使用するか、ご自身のシステム上のクライアントを使用できます。多くの MySQL 互換クライアントが動作し、このガイドでは DBeaver と MySQL Workbench の構成について説明します。 +### curl + +`curl` は、Compose ファイルとデータを生成するスクリプトをダウンロードするために使用されます。OS のプロンプトで `curl` または `curl.exe` を実行して、インストールされているかどうかを確認してください。`curl` がインストールされていない場合は、[こちらから curl を入手してください](https://curl.se/dlwiz/?type=bin) 。 +### Python + +Python 3 と Apache Kafka 用の Python クライアントである `kafka-python` が必要です。 + +- [Python](https://www.python.org/) +- [`kafka-python`](https://pypi.org/project/kafka-python/) + +--- +## 用語 +### FE + +FE （Frontend nodes）は、メタデータ管理、クライアント接続管理、クエリプラン、およびクエリスケジューリングを担当します。各 FE は、メタデータの完全なコピーをメモリに保存および保持し、FE 間で差別なくサービスを提供することを保証します。 +コンピュートノードは、共有データモードでのクエリプランの実行を担当します。 +### BE + +BE は、共有なしデプロイメントにおいて、データストレージとクエリプランの実行の両方を担うバックエンドノードです。 + +:::note +このガイドでは BE を使用しません。この情報は、BE と CN の違いを理解していただくために含まれています。 +::: + +--- +## StarRocks の起動 + +オブジェクトストレージを使用して共有データで StarRocks を実行するには、以下が必要です。 + +- フロントエンドエンジン (FE) +- コンピュートノード (CN) +- オブジェクトストレージ + +このガイドでは、S3 互換のオブジェクトストレージプロバイダーである MinIO を使用します。MinIO は GNU Affero General Public License の下で提供されています。 +### ラボファイルをダウンロードする +#### `docker-compose.yml` + +```bash +mkdir routineload +cd routineload +curl -O https://raw.githubusercontent.com/StarRocks/demo/master/documentation-samples/routine-load-shared-data/docker-compose.yml +``` +#### `gen.py` + +`gen.py` は、Apache Kafka 用の Python クライアントを使用して、Kafka トピックにデータをパブリッシュ（生成）するスクリプトです。このスクリプトは、Redpanda コンテナのアドレスとポートを使用して記述されています。 + +```bash +curl -O https://raw.githubusercontent.com/StarRocks/demo/master/documentation-samples/routine-load-shared-data/gen.py +``` +## StarRocks、MinIO、および Redpanda の起動 + +```bash +docker compose up --detach --wait --wait-timeout 120 +``` + +サービスの進捗状況を確認します。コンテナが正常になるまでには、30秒以上かかるはずです。`routineload-minio_mc-1` コンテナはヘルスインジケータを表示せず、StarRocks が使用するアクセスキーで MinIO を構成すると終了します。`routineload-minio_mc-1` がコード `0` で終了し、残りのサービスが `Healthy` になるまで待ちます。 + +サービスが正常になるまで `docker compose ps` を実行します。 + +```bash +docker compose ps +``` + +```plaintext +WARN[0000] /Users/droscign/routineload/docker-compose.yml: `version` is obsolete +[+] Running 6/7 + ✔ Network routineload_default Crea... 0.0s + ✔ Container minio Healthy 5.6s + ✔ Container redpanda Healthy 3.6s + ✔ Container redpanda-console Healt... 1.1s + ⠧ Container routineload-minio_mc-1 Waiting 23.1s + ✔ Container starrocks-fe Healthy 11.1s + ✔ Container starrocks-cn Healthy 23.0s +container routineload-minio_mc-1 exited (0) +``` + +--- +## MinIO の認証情報を確認する + +StarRocks でオブジェクトストレージに MinIO を使用するには、StarRocks に MinIO のアクセスキーが必要です。このアクセスキーは、Docker サービスの起動時に生成されました。StarRocks が MinIO に接続する方法をより良く理解するために、キーが存在することを確認する必要があります。 +### MinIO ウェブ UI を開く + +http://localhost:9001/access-keys を参照します。ユーザー名とパスワードは Docker compose ファイルで指定されており、`miniouser` と `miniopassword` です。アクセスキーが1つあることがわかります。キーは `AAAAAAAAAAAAAAAAAAAA` です。MinIO コンソールではシークレットを表示できませんが、Docker compose ファイルにあり、`BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB` です。 + +![MinIO アクセスキーの表示](../_assets/quick-start/MinIO-view-key.png) + +--- +### データのバケットを作成する + +StarRocks でストレージボリュームを作成する際、データの `LOCATION` を指定します。 + +```sh + LOCATIONS = ("s3://my-starrocks-bucket/") +``` + +[http://localhost:9001/buckets](http://localhost:9001/buckets) を開き、ストレージボリュームのバケットを追加します。バケットに `my-starrocks-bucket` という名前を付けます。リストされている3つのオプションのデフォルトを受け入れます。 +## SQL クライアント + + + +--- +## 共有データのためのStarRocksの設定 + +この時点で、StarRocksが実行されており、MinIOも実行されています。MinIOのアクセスキーは、StarRocksとMinIOを接続するために使用されます。 + +これは、StarRocksのデプロイメントが共有データを使用することを指定する`FE`構成の部分です。これは、Docker Composeがデプロイメントを作成したときにファイル`fe.conf`に追加されました。 + +```sh +# enable the shared data run mode +run_mode = shared_data +cloud_native_storage_type = S3 +``` + +:::info +`quickstart`ディレクトリからこのコマンドを実行し、ファイルの末尾を見ることで、これらの設定を確認できます。 +::: + +```sh +docker compose exec starrocks-fe \ + cat /opt/starrocks/fe/conf/fe.conf +``` +::: +### SQLクライアントでStarRocksに接続する + +:::tip + +このコマンドは、`docker-compose.yml`ファイルが含まれるディレクトリから実行してください。 + +mysql CLI以外のクライアントを使用している場合は、ここで開いてください。 +::: + +```sql +docker compose exec starrocks-fe \ +mysql -P9030 -h127.0.0.1 -uroot --prompt="StarRocks > " +``` +#### ストレージボリュームの確認 + +```sql +SHOW STORAGE VOLUMES; +``` + +:::tip +ストレージボリュームは存在しないはずです。次はストレージボリュームを作成します。 +::: + +```sh +Empty set (0.04 sec) +``` +#### 共有データストレージボリュームの作成 + +先ほど、`my-starrocks-volume` という名前のバケットを MinIO に作成し、MinIO に `AAAAAAAAAAAAAAAAAAAA` という名前のアクセスキーがあることを確認しました。次の SQL は、アクセスキーとシークレットを使用して、MionIO バケットにストレージボリュームを作成します。 + +```sql +CREATE STORAGE VOLUME s3_volume + TYPE = S3 + LOCATIONS = ("s3://my-starrocks-bucket/") + PROPERTIES + ( + "enabled" = "true", + "aws.s3.endpoint" = "minio:9000", + "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", + "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", + "aws.s3.use_instance_profile" = "false", + "aws.s3.use_aws_sdk_default_behavior" = "false" + ); +``` + +これで、ストレージボリュームがリストに表示されるはずです。以前は空のセットでした。 + +``` +SHOW STORAGE VOLUMES; +``` + +``` ++----------------+ +| Storage Volume | ++----------------+ +| s3_volume | ++----------------+ +1 row in set (0.02 sec) +``` + +ストレージボリュームの詳細を表示し、これがまだ default catalogボリュームではなく、バケットを使用するように構成されていることに注意してください。 + +``` +DESC STORAGE VOLUME s3_volume\G +``` + +:::tip +このドキュメント、および StarRocks ドキュメントの他の多くのドキュメントにある SQL の一部は、セミコロンの代わりに `\G` が使用されています。`\G` を使用すると、mysql CLI がクエリ結果を垂直方向にレンダリングします。 + +多くの SQL クライアントは垂直方向のフォーマット出力を解釈しないため、`\G` を `;` に置き換える必要があります。 +::: + +```sh +*************************** 1. row *************************** + Name: s3_volume + Type: S3 +# highlight-start +IsDefault: false + Location: s3://my-starrocks-bucket/ +# highlight-end + Params: {"aws.s3.access_key":"******","aws.s3.secret_key":"******","aws.s3.endpoint":"minio:9000","aws.s3.region":"us-east-1","aws.s3.use_instance_profile":"false","aws.s3.use_web_identity_token_file":"false","aws.s3.use_aws_sdk_default_behavior":"false"} + Enabled: true + Comment: +1 row in set (0.02 sec) +``` +## デフォルトのストレージボリュームを設定する + +``` +SET s3_volume AS DEFAULT STORAGE VOLUME; +``` + +``` +DESC STORAGE VOLUME s3_volume\G +``` + +```sh +*************************** 1. row *************************** + Name: s3_volume + Type: S3 +# highlight-next-line +IsDefault: true + Location: s3://my-starrocks-bucket/ + Params: {"aws.s3.access_key":"******","aws.s3.secret_key":"******","aws.s3.endpoint":"minio:9000","aws.s3.region":"us-east-1","aws.s3.use_instance_profile":"false","aws.s3.use_web_identity_token_file":"false","aws.s3.use_aws_sdk_default_behavior":"false"} + Enabled: true + Comment: +1 row in set (0.02 sec) +``` + +--- +## テーブルを作成する + +これらのSQLコマンドは、SQLクライアントで実行します。 + +```SQL +CREATE DATABASE IF NOT EXISTS quickstart; +``` + +データベース`quickstart`がストレージボリューム`s3_volume`を使用していることを確認します。 + +``` +SHOW CREATE DATABASE quickstart \G +``` + +```sh +*************************** 1. row *************************** + Database: quickstart +Create Database: CREATE DATABASE `quickstart` +# highlight-next-line +PROPERTIES ("storage_volume" = "s3_volume") +``` + +```SQL +USE quickstart; +``` + +```SQL +CREATE TABLE site_clicks ( + `uid` bigint NOT NULL COMMENT "uid", + `site` string NOT NULL COMMENT "site url", + `vtime` bigint NOT NULL COMMENT "vtime" +) +DISTRIBUTED BY HASH(`uid`) +PROPERTIES("replication_num"="1"); +``` +### Redpanda Consoleを開く + +まだトピックはありません。トピックは次のステップで作成します。 + +http://localhost:8080/overview +### Redpandaトピックへのデータ公開 + +`routineload/` フォルダーのコマンドシェルから、次のコマンドを実行してデータを生成します。 + +```python +python gen.py 5 +``` + +:::tip + +システムによっては、コマンドで `python` の代わりに `python3` を使用する必要がある場合があります。 + +`kafka-python` が見つからない場合は、以下を試してください。 + +``` +pip install kafka-python +``` +または +``` +pip3 install kafka-python +``` + +::: + +```plaintext +b'{ "uid": 6926, "site": "https://docs.starrocks.io/", "vtime": 1718034793 } ' +b'{ "uid": 3303, "site": "https://www.starrocks.io/product/community", "vtime": 1718034793 } ' +b'{ "uid": 227, "site": "https://docs.starrocks.io/", "vtime": 1718034243 } ' +b'{ "uid": 7273, "site": "https://docs.starrocks.io/", "vtime": 1718034794 } ' +b'{ "uid": 4666, "site": "https://www.starrocks.io/", "vtime": 1718034794 } ' +``` +### Redpanda Console での確認 + +Redpanda Console (http://localhost:8080/topics ) に移動すると、`test2` という名前のトピックが1つ表示されます。そのトピックを選択し、**Messages** タブを選択すると、`gen.py` の出力と一致する5つのメッセージが表示されます。 +## メッセージの消費 + +StarRocks で、以下の手順で Routine Load ジョブを作成します。 + +1. Redpanda トピック `test2` からメッセージを消費します。 +2. それらのメッセージをテーブル `site_clicks` にロードします。 + +StarRocks はストレージに MinIO を使用するように構成されているため、`site_clicks` テーブルに挿入されたデータは MinIO に保存されます。 +### Routine Load ジョブの作成 + +SQL クライアントで次のコマンドを実行して、Routine Load ジョブを作成します。コマンドの詳細については、ラボの最後で説明します。 + +```SQL +CREATE ROUTINE LOAD quickstart.clicks ON site_clicks +PROPERTIES +( + "format" = "JSON", + "jsonpaths" ="[\"$.uid\",\"$.site\",\"$.vtime\"]" +) +FROM KAFKA +( + "kafka_broker_list" = "redpanda:29092", + "kafka_topic" = "test2", + "kafka_partitions" = "0", + "kafka_offsets" = "OFFSET_BEGINNING" +); +``` +### Routine Load ジョブの確認 + +```SQL +SHOW ROUTINE LOAD\G +``` + +ハイライトされている3つの行を確認します。 + +1. 状態が `RUNNING` であること +2. トピックが `test2` で、ブローカーが `redpanda:2092` であること +3. 統計には、`SHOW ROUTINE LOAD` コマンドをいつ実行したかに応じて、ロードされた行数が0または5のいずれかで表示されるはずです。ロードされた行数が0の場合は、もう一度実行してください。 + +```SQL +*************************** 1. row *************************** + Id: 10078 + Name: clicks + CreateTime: 2024-06-12 15:51:12 + PauseTime: NULL + EndTime: NULL + DbName: quickstart + TableName: site_clicks + -- highlight-next-line + State: RUNNING + DataSourceType: KAFKA + CurrentTaskNum: 1 + JobProperties: {"partitions":"*","partial_update":"false","columnToColumnExpr":"*","maxBatchIntervalS":"10","partial_update_mode":"null","whereExpr":"*","dataFormat":"json","timezone":"Etc/UTC","format":"json","log_rejected_record_num":"0","taskTimeoutSecond":"60","json_root":"","maxFilterRatio":"1.0","strict_mode":"false","jsonpaths":"[\"$.uid\",\"$.site\",\"$.vtime\"]","taskConsumeSecond":"15","desireTaskConcurrentNum":"5","maxErrorNum":"0","strip_outer_array":"false","currentTaskConcurrentNum":"1","maxBatchRows":"200000"} + -- highlight-next-line +DataSourceProperties: {"topic":"test2","currentKafkaPartitions":"0","brokerList":"redpanda:29092"} + CustomProperties: {"group.id":"clicks_ea38a713-5a0f-4abe-9b11-ff4a241ccbbd"} + -- highlight-next-line + Statistic: {"receivedBytes":0,"errorRows":0,"committedTaskNum":0,"loadedRows":0,"loadRowsRate":0,"abortedTaskNum":0,"totalRows":0,"unselectedRows":0,"receivedBytesRate":0,"taskExecuteTimeMs":1} + Progress: {"0":"OFFSET_ZERO"} + TimestampProgress: {} +ReasonOfStateChanged: + ErrorLogUrls: + TrackingSQL: + OtherMsg: +LatestSourcePosition: {} +1 row in set (0.00 sec) +``` + +```SQL +SHOW ROUTINE LOAD\G +``` + +```SQL +*************************** 1. row *************************** + Id: 10076 + Name: clicks + CreateTime: 2024-06-12 18:40:53 + PauseTime: NULL + EndTime: NULL + DbName: quickstart + TableName: site_clicks + State: RUNNING + DataSourceType: KAFKA + CurrentTaskNum: 1 + JobProperties: {"partitions":"*","partial_update":"false","columnToColumnExpr":"*","maxBatchIntervalS":"10","partial_update_mode":"null","whereExpr":"*","dataFormat":"json","timezone":"Etc/UTC","format":"json","log_rejected_record_num":"0","taskTimeoutSecond":"60","json_root":"","maxFilterRatio":"1.0","strict_mode":"false","jsonpaths":"[\"$.uid\",\"$.site\",\"$.vtime\"]","taskConsumeSecond":"15","desireTaskConcurrentNum":"5","maxErrorNum":"0","strip_outer_array":"false","currentTaskConcurrentNum":"1","maxBatchRows":"200000"} +DataSourceProperties: {"topic":"test2","currentKafkaPartitions":"0","brokerList":"redpanda:29092"} + CustomProperties: {"group.id":"clicks_a9426fee-45bb-403a-a1a3-b3bc6c7aa685"} + -- highlight-next-line + Statistic: {"receivedBytes":372,"errorRows":0,"committedTaskNum":1,"loadedRows":5,"loadRowsRate":0,"abortedTaskNum":0,"totalRows":5,"unselectedRows":0,"receivedBytesRate":0,"taskExecuteTimeMs":519} + Progress: {"0":"4"} + TimestampProgress: {"0":"1718217035111"} +ReasonOfStateChanged: + ErrorLogUrls: + TrackingSQL: + OtherMsg: + -- highlight-next-line +LatestSourcePosition: {"0":"5"} +1 row in set (0.00 sec) +``` + +--- +## MinIO にデータが保存されていることを確認する + +MinIO [http://localhost:9001/browser/](http://localhost:9001/browser/) を開き、`my-starrocks-bucket` にオブジェクトが保存されていることを確認します。 +## StarRocks からのデータクエリ + +```SQL +USE quickstart; +SELECT * FROM site_clicks; +``` + +```SQL ++------+--------------------------------------------+------------+ +| uid | site | vtime | ++------+--------------------------------------------+------------+ +| 4607 | https://www.starrocks.io/blog | 1718031441 | +| 1575 | https://www.starrocks.io/ | 1718031523 | +| 2398 | https://docs.starrocks.io/ | 1718033630 | +| 3741 | https://www.starrocks.io/product/community | 1718030845 | +| 4792 | https://www.starrocks.io/ | 1718033413 | ++------+--------------------------------------------+------------+ +5 rows in set (0.07 sec) +``` +## 追加のデータをパブリッシュする + +`gen.py` を再度実行すると、さらに5つのレコードが Redpanda にパブリッシュされます。 + +```bash +python gen.py 5 +``` +### データが追加されたことの確認 + +Routine Loadジョブはスケジュールに基づいて実行されるため (デフォルトでは10秒ごと) 、データは数秒以内にロードされます。 + +```SQL +SELECT * FROM site_clicks; +```` + +``` ++------+--------------------------------------------+------------+ +| uid | site | vtime | ++------+--------------------------------------------+------------+ +| 6648 | https://www.starrocks.io/blog | 1718205970 | +| 7914 | https://www.starrocks.io/ | 1718206760 | +| 9854 | https://www.starrocks.io/blog | 1718205676 | +| 1186 | https://www.starrocks.io/ | 1718209083 | +| 3305 | https://docs.starrocks.io/ | 1718209083 | +| 2288 | https://www.starrocks.io/blog | 1718206759 | +| 7879 | https://www.starrocks.io/product/community | 1718204280 | +| 2666 | https://www.starrocks.io/ | 1718208842 | +| 5801 | https://www.starrocks.io/ | 1718208783 | +| 8409 | https://www.starrocks.io/ | 1718206889 | ++------+--------------------------------------------+------------+ +10 rows in set (0.02 sec) +``` + +--- +## 構成の詳細 + +共有データで StarRocks を使用した経験を踏まえ、構成を理解することが重要です。 +### CN configuration + +ここで使用されるCN構成はデフォルトです。CNは共有データでの使用を想定して設計されているためです。デフォルトの構成を以下に示します。変更を加える必要はありません。 + +```bash +sys_log_level = INFO + +# ports for admin, web, heartbeat service +be_port = 9060 +be_http_port = 8040 +heartbeat_service_port = 9050 +brpc_port = 8060 +starlet_port = 9070 +``` +### FE configuration + +FE の設定は、FE がデータを BE ノードのローカルディスクではなく、オブジェクトストレージに保存することを想定するように設定する必要があるため、デフォルトとは若干異なります。 + +`docker-compose.yml` ファイルは、`command` で FE の設定を生成します。 + +```plaintext +# enable shared data, set storage type, set endpoint +run_mode = shared_data +cloud_native_storage_type = S3 +``` + +:::note +この設定ファイルには、FE のデフォルトエントリは含まれていません。共有データの設定のみが表示されています。 +::: + +デフォルト以外の FE 設定： + +:::note +多くの設定パラメータには、`s3_` というプレフィックスが付いています。このプレフィックスは、Amazon S3 互換のすべてのストレージタイプ（例：S3、GCS、および MinIO）で使用されます。Azure Blob Storage を使用する場合、プレフィックスは `azure_` になります。 +::: +#### `run_mode=shared_data` + +これは、共有データモードの使用を有効にします。 +#### `cloud_native_storage_type=S3` + +これは、S3 互換ストレージまたは Azure Blob Storage のどちらを使用するかを指定します。 MinIO の場合、これは常に S3 です。 +### `CREATE storage volume` の詳細 + +```sql +CREATE STORAGE VOLUME s3_volume + TYPE = S3 + LOCATIONS = ("s3://my-starrocks-bucket/") + PROPERTIES + ( + "enabled" = "true", + "aws.s3.endpoint" = "minio:9000", + "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", + "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", + "aws.s3.use_instance_profile" = "false", + "aws.s3.use_aws_sdk_default_behavior" = "false" + ); +``` +#### `aws_s3_endpoint=minio:9000` + +ポート番号を含む、MinIO のエンドポイント。 +#### `aws_s3_path=starrocks` + +バケット名。 +#### `aws_s3_access_key=AAAAAAAAAAAAAAAAAAAA` + +MinIO のアクセスキーです。 +#### `aws_s3_secret_key=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB` + +MinIO のアクセスキーシークレットです。 +#### `aws_s3_use_instance_profile=false` + +MinIO を使用する場合、アクセスキーが使用されるため、インスタンスプロファイルは MinIO では使用されません。 +#### `aws_s3_use_aws_sdk_default_behavior=false` + +MinIO を使用する場合、このパラメータは常に false に設定されます。 +## Routine Load コマンドに関する注意点 + +StarRocks の Routine Load は多くの引数を取ります。このチュートリアルで使用されているものだけをここで説明し、残りは詳細情報のセクションにリンクします。 + +```SQL +CREATE ROUTINE LOAD quickstart.clicks ON site_clicks +PROPERTIES +( + "format" = "JSON", + "jsonpaths" ="[\"$.uid\",\"$.site\",\"$.vtime\"]" +) +FROM KAFKA +( + "kafka_broker_list" = "redpanda:29092", + "kafka_topic" = "test2", + "kafka_partitions" = "0", + "kafka_offsets" = "OFFSET_BEGINNING" +); +``` +### パラメータ + +``` +CREATE ROUTINE LOAD quickstart.clicks ON site_clicks +``` + +`CREATE ROUTINE LOAD ON` のパラメータは次のとおりです。 +- database_name.job_name +- table_name + +`database_name` はオプションです。このラボでは、`quickstart` であり、指定されています。 + +`job_name` は必須で、`clicks` です。 + +`table_name` は必須で、`site_clicks` です。 +### ジョブのプロパティ +#### プロパティ `format` + +``` +"format" = "JSON", +``` + +この場合、データは JSON 形式であるため、プロパティは `JSON` に設定されます。その他の有効な形式は、`CSV`、`JSON`、および `Avro` です。`CSV` がデフォルトです。 +#### プロパティ `jsonpaths` + +``` +"jsonpaths" ="[\"$.uid\",\"$.site\",\"$.vtime\"]" +``` + +JSON形式のデータからロードするフィールドの名前。このパラメータの値は、有効な JsonPath 式です。詳細については、このページの最後に記載されています。 +### データソースのプロパティ +#### `kafka_broker_list` + +``` +"kafka_broker_list" = "redpanda:29092", +``` + +Kafka の broker 接続情報です。形式は `:` です。複数の broker はカンマで区切られます。 +#### `kafka_topic` + +``` +"kafka_topic" = "test2", +``` + +消費元の Kafka トピック。 +#### `kafka_partitions` と `kafka_offsets` + +``` +"kafka_partitions" = "0", +"kafka_offsets" = "OFFSET_BEGINNING" +``` + +これらのプロパティは、`kafka_partitions` のエントリごとに1つの `kafka_offset` が必要であるため、一緒に提示されます。 + +`kafka_partitions` は、消費する1つ以上のパーティションのリストです。このプロパティが設定されていない場合、すべてのパーティションが消費されます。 + +`kafka_offsets` は、`kafka_partitions` にリストされている各パーティションに対して1つずつ、オフセットのリストです。この場合、値は `OFFSET_BEGINNING` であり、すべてのデータが消費されます。デフォルトでは、新しいデータのみが消費されます。 + +--- +## 概要 + +このチュートリアルでは、以下のことを行いました。 + +- StarRocks、Reedpanda、および MinIO を Docker にデプロイしました。 +- Kafka トピックからデータを取り込むための Routine Load ジョブを作成しました。 +- MinIO を使用する StarRocks ストレージボリュームを構成する方法を学びました。 +## 詳細情報 + +[StarRocksのアーキテクチャ](../introduction/Architecture.md) + +このラボで使用されているサンプルは非常に単純です。Routine Load には、さらに多くのオプションと機能があります。[詳細はこちら](../loading/RoutineLoad.md) をご覧ください。 + +[JSONPath](https://goessner.net/articles/JsonPath/) \ No newline at end of file diff --git a/docs/ja/sql-reference/sql-functions/dict-functions/dict_mapping.md b/docs/ja/sql-reference/sql-functions/dict-functions/dict_mapping.md new file mode 100644 index 0000000..b3f9ab7 --- /dev/null +++ b/docs/ja/sql-reference/sql-functions/dict-functions/dict_mapping.md @@ -0,0 +1,211 @@ +--- +displayed_sidebar: docs +--- + +# dict_mapping + +辞書テーブルで指定されたキーにマッピングされている値を返します。 + +`dict_mapping` は、グローバル辞書テーブルの適用を簡素化します。ターゲットテーブルへのデータロード中に、StarRocks はこの関数の入力パラメータを使用して、辞書テーブルから指定されたキーにマッピングされた値を自動的に取得し、その値をターゲットテーブルにロードします。 + +v3.2.5 以降、StarRocks はこの関数をサポートしています。また、現在の StarRocks の共有データモードでは、この関数はサポートされていないことに注意してください。 +## 構文 + +```SQL +dict_mapping("[.]", key_column_expr_list [, ] [, ] ) + +key_column_expr_list ::= key_column_expr [, key_column_expr ... ] + +key_column_expr ::= | +``` +## パラメータ + +- 必須パラメータ: + - `[.]`: ディクショナリテーブルの名前。主キーテーブルである必要があります。サポートされているデータ型は VARCHAR です。 + - `key_column_expr_list`: ディクショナリテーブルのキーカラムの式リスト。1つまたは複数の `key_column_exprs` が含まれます。 `key_column_expr` は、ディクショナリテーブルのキーカラムの名前、または特定のキーもしくはキー式にすることができます。 + + この式リストには、ディクショナリテーブルのすべての主キーカラムを含める必要があります。つまり、式の総数は、ディクショナリテーブルの主キーカラムの総数と一致する必要があります。したがって、ディクショナリテーブルが複合主キーを使用する場合、このリストの式は、テーブルスキーマで定義された主キーカラムに順番に対応する必要があります。このリストの複数の式は、カンマ (`,`) で区切られます。また、`key_column_expr` が特定のキーまたはキー式である場合、その型は、ディクショナリテーブル内の対応する主キーカラムの型と一致する必要があります。 + +- オプションのパラメータ: + - ``: 値カラムの名前。これはマッピングカラムでもあります。値カラムが指定されていない場合、デフォルトの値カラムはディクショナリテーブルの AUTO_INCREMENT カラムです。値カラムは、自動インクリメントカラムと主キーを除く、ディクショナリテーブルの任意のカラムとして定義することもできます。カラムのデータ型に制限はありません。 + - `` (オプション): キーがディクショナリテーブルに存在しない場合に NULL を返すかどうか。有効な値: + - `true`: キーが存在しない場合、NULL が返されます。 + - `false` (デフォルト): キーが存在しない場合、例外がスローされます。 +## 戻り値 + +戻り値のデータ型は、value カラムのデータ型と一致します。value カラムが辞書テーブルの自動増分カラムである場合、戻り値のデータ型は BIGINT になります。 + +ただし、指定されたキーにマッピングされた value が見つからない場合、`` パラメータが `true` に設定されていると、`NULL` が返されます。パラメータが `false` (デフォルト) に設定されている場合、エラー `query failed if record not exist in dict table` が返されます。 +## 例 + +**例1：辞書テーブルからキーにマッピングされた値を直接クエリする。** + +1. 辞書テーブルを作成し、シミュレートされたデータをロードします。 + + ```SQL + MySQL [test]> CREATE TABLE dict ( + order_uuid STRING, + order_id_int BIGINT AUTO_INCREMENT + ) + PRIMARY KEY (order_uuid) + DISTRIBUTED BY HASH (order_uuid); + Query OK, 0 rows affected (0.02 sec) + + MySQL [test]> INSERT INTO dict (order_uuid) VALUES ('a1'), ('a2'), ('a3'); + Query OK, 3 rows affected (0.12 sec) + {'label':'insert_9e60b0e4-89fa-11ee-a41f-b22a2c00f66b', 'status':'VISIBLE', 'txnId':'15029'} + + MySQL [test]> SELECT * FROM dict; + +------------+--------------+ + | order_uuid | order_id_int | + +------------+--------------+ + | a1 | 1 | + | a3 | 3 | + | a2 | 2 | + +------------+--------------+ + 3 rows in set (0.01 sec) + ``` + + > **注意** + > + > 現在、`INSERT INTO` ステートメントは部分的な更新をサポートしていません。したがって、`dict` のキーカラムに挿入される値が重複していないことを確認してください。そうしないと、同じキーカラムの値を辞書テーブルに複数回挿入すると、値カラム内のマッピングされた値が変更されます。 + +2. 辞書テーブル内のキー `a1` にマッピングされた値をクエリします。 + + ```SQL + MySQL [test]> SELECT dict_mapping('dict', 'a1'); + +----------------------------+ + | dict_mapping('dict', 'a1') | + +----------------------------+ + | 1 | + +----------------------------+ + 1 row in set (0.01 sec) + ``` + +**例2：テーブル内のマッピングカラムは、`dict_mapping` 関数を使用して生成されたカラムとして構成されています。したがって、StarRocks は、このテーブルにデータをロードする際に、キーにマッピングされた値を自動的に取得できます。** + +1. データテーブルを作成し、`dict_mapping('dict', order_uuid)` を使用してマッピングカラムを生成されたカラムとして構成します。 + + ```SQL + CREATE TABLE dest_table1 ( + id BIGINT, + -- このカラムは、例1の dict テーブルの order_uuid カラムに対応する、STRING 型の注文番号を記録します。 + order_uuid STRING, + batch int comment '異なるバッチロードを区別するために使用', + -- このカラムは、order_uuid カラムにマッピングされた BIGINT 型の注文番号を記録します。 + -- このカラムは dict_mapping で構成された生成されたカラムであるため、このカラムの値は、データロード中に例1の dict テーブルから自動的に取得されます。 + -- その後、このカラムは、重複排除および JOIN クエリに直接使用できます。 + order_id_int BIGINT AS dict_mapping('dict', order_uuid) + ) + DUPLICATE KEY (id, order_uuid) + DISTRIBUTED BY HASH(id); + ``` + +2. `order_id_int` カラムが `dict_mapping('dict', 'order_uuid')` として構成されているこのテーブルにシミュレートされたデータをロードすると、StarRocks は `dict` テーブル内のキーと値の間のマッピング関係に基づいて、`order_id_int` カラムに値を自動的にロードします。 + + ```SQL + MySQL [test]> INSERT INTO dest_table1(id, order_uuid, batch) VALUES (1, 'a1', 1), (2, 'a1', 1), (3, 'a3', 1), (4, 'a3', 1); + Query OK, 4 rows affected (0.05 sec) + {'label':'insert_e191b9e4-8a98-11ee-b29c-00163e03897d', 'status':'VISIBLE', 'txnId':'72'} + + MySQL [test]> SELECT * FROM dest_table1; + +------+------------+-------+--------------+ + | id | order_uuid | batch | order_id_int | + +------+------------+-------+--------------+ + | 1 | a1 | 1 | 1 | + | 4 | a3 | 1 | 3 | + | 2 | a1 | 1 | 1 | + | 3 | a3 | 1 | 3 | + +------+------------+-------+--------------+ + 4 rows in set (0.02 sec) + ``` + + この例での `dict_mapping` の使用は、[重複排除の計算と JOIN クエリ](../../../using_starrocks/query_acceleration_with_auto_increment.md) を高速化できます。正確な重複排除を高速化するためにグローバル辞書を構築するための以前のソリューションと比較して、`dict_mapping` を使用したソリューションは、より柔軟でユーザーフレンドリーです。マッピング値は、「キーと値の間のマッピング関係をテーブルにロードする」段階で辞書テーブルから直接取得されるためです。マッピング値を取得するために辞書テーブルをジョインするステートメントを作成する必要はありません。さらに、このソリューションはさまざまなデータロード方法をサポートしています。 + +**例3：テーブル内のマッピングカラムが生成されたカラムとして構成されていない場合は、テーブルにデータをロードするときに、マッピングカラムの `dict_mapping` 関数を明示的に構成し、キーにマッピングされた値を取得する必要があります。** + +> **注意** +> +> 例3と例2の違いは、データテーブルにインポートするときに、インポートコマンドを変更して、マッピングカラムの `dict_mapping` 式を明示的に構成する必要があることです。 + +1. テーブルを作成します。 + + ```SQL + CREATE TABLE dest_table2 ( + id BIGINT, + order_uuid STRING, + order_id_int BIGINT NULL, + batch int comment '異なるバッチロードを区別するために使用' + ) + DUPLICATE KEY (id, order_uuid, order_id_int) + DISTRIBUTED BY HASH(id); + ``` + +2. シミュレートされたデータがこのテーブルにロードされると、`dict_mapping` を構成することにより、辞書テーブルからマッピングされた値を取得します。 + + ```SQL + MySQL [test]> INSERT INTO dest_table2 VALUES (1, 'a1', dict_mapping('dict', 'a1'), 1); + Query OK, 1 row affected (0.35 sec) + {'label':'insert_19872ab6-8a96-11ee-b29c-00163e03897d', 'status':'VISIBLE', 'txnId':'42'} + + MySQL [test]> SELECT * FROM dest_table2; + +------+------------+--------------+-------+ + | id | order_uuid | order_id_int | batch | + +------+------------+--------------+-------+ + | 1 | a1 | 1 | 1 | + +------+------------+--------------+-------+ + 1 row in set (0.02 sec) + ``` + +**例4：null_if_not_exist モードを有効にする** + +`` モードが無効になっており、辞書テーブルに存在しないキーにマッピングされた値がクエリされると、`NULL` ではなくエラーが返されます。これにより、データ行のキーが最初に辞書テーブルにロードされ、そのマッピングされた値（辞書 ID）が、そのデータ行がターゲットテーブルにロードされる前に生成されるようになります。 + +```SQL +MySQL [test]> SELECT dict_mapping('dict', 'b1', true); +ERROR 1064 (HY000): Query failed if record not exist in dict table. +``` + +**例5：辞書テーブルが複合主キーを使用している場合は、クエリ時にすべての主キーを指定する必要があります。** + +1. 複合主キーを持つ辞書テーブルを作成し、シミュレートされたデータをロードします。 + + ```SQL + MySQL [test]> CREATE TABLE dict2 ( + order_uuid STRING, + order_date DATE, + order_id_int BIGINT AUTO_INCREMENT + ) + PRIMARY KEY (order_uuid,order_date) -- 複合主キー + DISTRIBUTED BY HASH (order_uuid,order_date) + ; + Query OK, 0 rows affected (0.02 sec) + + MySQL [test]> INSERT INTO dict2 VALUES ('a1','2023-11-22',default), ('a2','2023-11-22',default), ('a3','2023-11-22',default); + Query OK, 3 rows affected (0.12 sec) + {'label':'insert_9e60b0e4-89fa-11ee-a41f-b22a2c00f66b', 'status':'VISIBLE', 'txnId':'15029'} + + + MySQL [test]> select * from dict2; + +------------+------------+--------------+ + | order_uuid | order_date | order_id_int | + +------------+------------+--------------+ + | a1 | 2023-11-22 | 1 | + | a3 | 2023-11-22 | 3 | + | a2 | 2023-11-22 | 2 | + +------------+------------+--------------+ + 3 rows in set (0.01 sec) + ``` + +2. 辞書テーブル内のキーにマッピングされた値をクエリします。辞書テーブルには複合主キーがあるため、`dict_mapping` ですべての主キーを指定する必要があります。 + + ```SQL + SELECT dict_mapping('dict2', 'a1', cast('2023-11-22' as DATE)); + ``` + + 主キーが1つしか指定されていない場合、エラーが発生することに注意してください。 + + ```SQL + MySQL [test]> SELECT dict_mapping('dict2', 'a1'); + ERROR 1064 (HY000): Getting analyzing error. Detail message: dict_mapping function param size should be 3 - 5. + ``` \ No newline at end of file diff --git a/docs/zh/introduction/Architecture.md b/docs/zh/introduction/Architecture.md index 14b7899..1c4fe99 100644 --- a/docs/zh/introduction/Architecture.md +++ b/docs/zh/introduction/Architecture.md @@ -5,79 +5,70 @@ import QSOverview from '../_assets/commonMarkdown/quickstart-overview-tip.mdx' # 架构 -StarRocks 具有简单的架构。整个系统仅由两种类型的组件组成：前端和后端。前端节点称为 **FE**。后端节点有两种类型，**BE** 和 **CN** (计算节点)。当使用数据的本地存储时，将部署 BE；当数据存储在对象存储或 HDFS 上时，将部署 CN。StarRocks 不依赖于任何外部组件，从而简化了部署和维护。节点可以水平扩展，而不会导致服务中断。此外，StarRocks 具有元数据和服务数据的副本机制，从而提高了数据可靠性，并有效地防止了单点故障 (SPOF)。 - -StarRocks 兼容 MySQL 协议，并支持标准 SQL。用户可以轻松地从 MySQL 客户端连接到 StarRocks，以获得即时且有价值的见解。 +StarRocks 具有强大的架构。整个系统仅由两种类型的组件组成：前端和后端。前端节点称为 **FE**。后端节点有两种类型，**BE** 和 **CN**（计算节点）。当使用数据的本地磁盘时，将部署 BE；当数据存储在对象存储或 HDFS 上时，将部署 CN。StarRocks 不依赖任何外部组件，从而简化了部署和维护。节点可以水平扩展，而不会导致服务中断。此外，StarRocks 具有元数据和服务数据的副本机制，从而提高了数据可靠性并有效地防止了单点故障 (SPOF)。 +StarRocks 兼容 MySQL 协议并支持标准 SQL。用户可以轻松地从 MySQL 客户端连接到 StarRocks，以获得即时且有价值的见解。 ## 架构选择 -StarRocks 支持 shared-nothing (每个 BE 在其本地存储上都拥有一部分数据) 和 shared-data (所有数据都在对象存储或 HDFS 上，每个 CN 仅在本地存储上具有缓存)。您可以根据自己的需求决定数据的存储位置。 +StarRocks 支持存算一体（每个 BE 在其本地存储上拥有一部分数据）和存算分离（所有数据都在对象存储或 HDFS 上，每个 CN 仅在本地存储上具有缓存）。您可以根据您的需求决定数据的存储位置。 ![Architecture choices](../_assets/architecture_choices.png) +### 存算一体 -### Shared-nothing - -本地存储为实时查询提供了更高的查询延迟。 - -作为一种典型的海量并行处理 (MPP) 数据库，StarRocks 支持 shared-nothing 架构。在此架构中，BE 负责数据存储和计算。直接访问 BE 模式下的本地数据可以进行本地计算，避免了数据传输和数据复制，并提供了超快的查询和分析性能。此架构支持多副本数据存储，从而增强了集群处理高并发查询的能力并确保数据可靠性。它非常适合追求最佳查询性能的场景。 +本地存储可以优化实时查询的查询延迟。 -![shared-data-arch](../_assets/shared-nothing.png) +作为一个典型的MPP数据库，StarRocks 支持存算一体架构。在这种架构中，BE 负责数据存储和计算。直接访问 BE 上的本地数据可以进行本地计算，避免数据传输和数据复制，从而提供超快的查询和数据分析性能。这种架构支持多副本数据存储，增强了集群处理高并发查询的能力，并确保了数据的可靠性。它非常适合追求最佳查询性能的场景。 +![shared-data-arch](../_assets/shared nothing.png) #### 节点 -在 shared-nothing 架构中，StarRocks 由两种类型的节点组成：FE 和 BE。 +在存算一体架构中，StarRocks 由两种类型的节点组成：FE 和 BE。 - FE 负责元数据管理和构建执行计划。 -- BE 执行查询计划并存储数据。BE 利用本地存储来加速查询，并利用多副本机制来确保高数据可用性。 - +- BE 执行查询计划并存储数据。BE 利用本地存储来加速查询，并使用多副本机制来确保数据高可用。 ##### FE -FE 负责元数据管理、客户端连接管理、查询规划和查询调度。每个 FE 使用 BDB JE (Berkeley DB Java Edition) 来存储和维护其内存中元数据的完整副本，从而确保所有 FE 之间的一致服务。FE 可以充当 leader、follower 和 observer。如果 leader 节点崩溃，则 follower 基于 Raft 协议选举 leader。 +FE 负责元数据管理、客户端连接管理、查询计划和查询调度。每个 FE 使用 BDB JE (Berkeley DB Java Edition) 来存储和维护其内存中元数据的完整副本，从而确保所有 FE 之间服务的一致性。FE 可以充当 leader、follower 和 observer。如果 leader 节点崩溃，则 follower 基于 Raft 协议选举出一个 leader。 | **FE 角色** | **元数据管理** | **Leader 选举** | | ----------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------------------- | -| Leader | Leader FE 读取和写入元数据。Follower 和 observer FE 只能读取元数据。它们将元数据写入请求路由到 leader FE。Leader FE 更新元数据，然后使用 Raft 协议将元数据更改同步到 follower 和 observer FE。仅当元数据更改同步到超过一半的 follower FE 后，数据写入才被视为成功。 | 从技术上讲，leader FE 也是一个 follower 节点，并且是从 follower FE 中选出的。要执行 leader 选举，集群中必须有超过一半的 follower FE 处于活动状态。当 leader FE 发生故障时，follower FE 将启动另一轮 leader 选举。 | -| Follower | Follower 只能读取元数据。它们从 leader FE 同步和重放日志以更新元数据。 | Follower 参与 leader 选举，这要求集群中超过一半的 follower 处于活动状态。 | -| Observer | Observer 从 leader FE 同步和重放日志以更新元数据。 | Observer 主要用于增加集群的查询并发性。Observer 不参与 leader 选举，因此不会给集群增加 leader 选择压力。| - +| Leader | Leader FE 读取和写入元数据。Follower 和 Observer FE 只能读取元数据。它们将元数据写入请求路由到 Leader FE。Leader FE 更新元数据，然后使用 Raft 协议将元数据更改同步到 Follower 和 Observer FE。只有在元数据更改同步到超过一半的 Follower FE 后，数据写入才被认为是成功的。 | 从技术上讲，Leader FE 也是一个 Follower 节点，是从 Follower FE 中选举出来的。要执行 Leader 选举，集群中超过一半的 Follower FE 必须处于活动状态。当 Leader FE 发生故障时，Follower FE 将启动新一轮的 Leader 选举。 | +| Follower | Follower 只能读取元数据。它们从 Leader FE 同步和回放日志以更新元数据。 | Follower 参与 Leader 选举，这要求集群中超过一半的 Follower 处于活动状态。 | +| Observer | Observer 从 Leader FE 同步和回放日志以更新元数据。 | Observer 主要用于提高集群的查询并发性。Observer 不参与 Leader 选举，因此不会给集群增加 Leader 选择压力。| ##### BE BE 负责数据存储和 SQL 执行。 -- 数据存储：BE 具有等效的数据存储能力。FE 根据预定义的规则将数据分发到 BE。BE 转换摄取的数据，将数据写入所需的格式，并为数据生成索引。 +- 数据存储：BE 具有对等的数据存储能力。FE 基于预定义的规则将数据分发到 BE。BE 转换摄取的数据，将数据写入所需的格式，并为数据生成索引。 -- SQL 执行：FE 根据查询的语义将每个 SQL 查询解析为逻辑执行计划，然后将逻辑计划转换为可以在 BE 上执行的物理执行计划。存储目标数据的 BE 执行查询。这样就无需数据传输和复制，从而实现高查询性能。 +- SQL 执行：FE 根据 SQL 查询的语义将每个 SQL 查询解析为逻辑执行计划，然后将逻辑计划转换为可在 BE 上执行的物理执行计划。存储目标数据的 BE 执行查询。这无需数据传输和复制，从而实现高查询性能。 +### 存算分离 -### Shared-data +对象存储和 HDFS 提供了成本、可靠性和可扩展性优势。除了存储的可扩展性之外，由于存储和计算是分离的，因此可以添加和删除 CN 节点，而无需重新平衡数据。 -对象存储和 HDFS 提供了成本、可靠性和可扩展性优势。除了存储的可扩展性之外，由于存储和计算是分开的，因此可以添加和删除 CN 节点，而无需重新平衡数据。 +在存算分离架构中，BE 被“计算节点 (CN)”取代，计算节点仅负责数据计算任务和缓存热数据。数据存储在低成本且可靠的远端存储系统中，例如 Amazon S3、Google Cloud Storage、Azure Blob Storage、MinIO 等。当缓存命中时，查询性能与存算一体架构的查询性能相当。可以根据需要在几秒钟内添加或删除 CN 节点。这种架构降低了存储成本，确保了更好的资源隔离以及高弹性和高可扩展性。 -在 shared-data 架构中，BE 被“计算节点 (CN)”取代，后者仅负责数据计算任务和缓存热数据。数据存储在低成本且可靠的远程存储系统中，例如 Amazon S3、Google Cloud Storage、Azure Blob Storage、MinIO 等。当缓存命中时，查询性能与 shared-nothing 架构的查询性能相当。可以根据需要在几秒钟内添加或删除 CN 节点。此架构降低了存储成本，确保了更好的资源隔离以及高弹性和可扩展性。 - -shared-data 架构与其 shared-nothing 架构一样，保持了简单的架构。它仅由两种类型的节点组成：FE 和 CN。唯一的区别是用户必须配置后端对象存储。 +存算分离架构与其存算一体架构一样，保持了简单的架构。它仅包含两种类型的节点：FE 和 CN。唯一的区别是用户必须配置后端对象存储。 ![shared-data-arch](../_assets/shared-data.png) - #### 节点 -shared-data 架构中的 FE 提供与 shared-nothing 架构中相同的功能。 - -BE 被 CN (计算节点) 取代，并且存储功能被卸载到对象存储或 HDFS。CN 是无状态计算节点，可执行 BE 的所有功能，但存储数据除外。 +在存算分离架构中，协调节点提供的功能与存算一体架构中的 FEs 相同。 +BEs 被 CNs（计算节点）取代，存储功能被卸载到对象存储或 HDFS。CNs 是无状态的计算节点，执行 BEs 的所有功能，除了数据存储。 #### 存储 -StarRocks shared-data 集群支持两种存储解决方案：对象存储 (例如，AWS S3、Google GCS、Azure Blob Storage 或 MinIO) 和 HDFS。 - -在 shared-data 集群中，数据文件格式与 shared-nothing 集群 (具有耦合的存储和计算) 的数据文件格式保持一致。数据被组织成 Segment 文件，并且各种索引技术在云原生表中被重用，云原生表是专门在 shared-data 集群中使用的表。 +StarRocks 存算分离集群支持两种存储方案：对象存储（例如 AWS S3、Google GCS、Azure Blob Storage 或 MinIO）和 HDFS。 +在存算分离集群中，数据文件格式与存算一体集群（具有耦合的存储和计算）的数据文件格式保持一致。数据被组织成 Segment 文件，并且各种索引技术在 Cloud-native table 中被重复使用，Cloud-native table 是专门在存算分离集群中使用的表。 #### 缓存 -StarRocks shared-data 集群将数据存储和计算分离，从而允许每个组件独立扩展，从而降低了成本并提高了弹性。但是，此架构可能会影响查询性能。 +StarRocks 存算分离集群将数据存储和计算分离，从而允许两者独立扩展，进而降低成本并增强弹性。但是，这种架构可能会影响查询性能。 -为了减轻这种影响，StarRocks 建立了一个多层数据访问系统，包括内存、本地磁盘和远程存储，以更好地满足各种业务需求。 +为了减轻这种影响，StarRocks 建立了一个多层数据访问系统，包括内存、本地磁盘和远端存储，以更好地满足各种业务需求。 -针对热数据的查询直接扫描缓存，然后扫描本地磁盘，而冷数据需要从对象存储加载到本地缓存中，以加速后续查询。通过使热数据靠近计算单元，StarRocks 实现了真正的高性能计算和经济高效的存储。此外，通过数据预取策略优化了对冷数据的访问，从而有效地消除了查询的性能限制。 +对热数据的查询直接扫描缓存，然后扫描本地磁盘，而冷数据需要从对象存储加载到本地缓存中，以加速后续查询。通过使热数据靠近计算单元，StarRocks 实现了真正的高性能计算和经济高效的存储。此外，通过数据预取策略优化了对冷数据的访问，从而有效消除了查询的性能限制。 -创建表时可以启用缓存。如果启用了缓存，则数据将被写入本地磁盘和后端对象存储。在查询期间，CN 节点首先从本地磁盘读取数据。如果未找到数据，则将从后端对象存储中检索数据，并同时缓存在本地磁盘上。 +可以在创建表时启用缓存。如果启用了缓存，数据将被写入本地磁盘和后端对象存储。在查询期间，CN 节点首先从本地磁盘读取数据。如果未找到数据，则将从后端对象存储中检索数据，并同时缓存在本地磁盘上。 \ No newline at end of file diff --git a/docs/zh/loading/BrokerLoad.md b/docs/zh/loading/BrokerLoad.md deleted file mode 100644 index 0cab179..0000000 --- a/docs/zh/loading/BrokerLoad.md +++ /dev/null @@ -1,433 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 从 HDFS 或云存储加载数据 - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -StarRocks 提供了基于 MySQL 的 Broker Load 导入方法，可帮助您将大量数据从 HDFS 或云存储导入到 StarRocks 中。 - -Broker Load 在异步导入模式下运行。提交导入作业后，StarRocks 会异步运行该作业。您需要使用 [SHOW LOAD](../sql-reference/sql-statements/loading_unloading/SHOW_LOAD.md) 语句或 `curl` 命令来检查作业结果。 - -Broker Load 支持单表导入和多表导入。您可以通过运行一个 Broker Load 作业将一个或多个数据文件导入到一个或多个目标表中。Broker Load 确保每个运行的导入作业在导入多个数据文件时的事务原子性。原子性意味着一个导入作业中多个数据文件的导入必须全部成功或全部失败。不会发生某些数据文件导入成功而其他文件导入失败的情况。 - -Broker Load 支持在数据导入时进行数据转换，并支持在数据导入期间通过 UPSERT 和 DELETE 操作进行数据更改。有关详细信息，请参见 [在导入时转换数据](../loading/Etl_in_loading.md) 和 [通过导入更改数据](../loading/Load_to_Primary_Key_tables.md)。 - - - -## 背景信息 - -在 v2.4 及更早版本中，StarRocks 依赖 Broker 在 StarRocks 集群和外部存储系统之间建立连接，以运行 Broker Load 作业。因此，您需要在导入语句中输入 `WITH BROKER ""` 来指定要使用的 Broker。这被称为“基于 Broker 的导入”。Broker 是一种独立的无状态服务，与文件系统接口集成。借助 Broker，StarRocks 可以访问和读取存储在外部存储系统中的数据文件，并可以使用自己的计算资源来预处理和导入这些数据文件的数据。 - -从 v2.5 开始，StarRocks 在运行 Broker Load 作业时，不再依赖 Broker 在 StarRocks 集群和外部存储系统之间建立连接。因此，您不再需要在导入语句中指定 Broker，但仍需要保留 `WITH BROKER` 关键字。这被称为“无 Broker 导入”。 - -当您的数据存储在 HDFS 中时，您可能会遇到无 Broker 导入不起作用的情况。当您的数据存储在多个 HDFS 集群中或您配置了多个 Kerberos 用户时，可能会发生这种情况。在这些情况下，您可以改为使用基于 Broker 的导入。要成功执行此操作，请确保至少部署了一个独立的 Broker 组。有关如何在这些情况下指定身份验证配置和 HA 配置的信息，请参见 [HDFS](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md#hdfs)。 - -## 支持的数据文件格式 - -Broker Load 支持以下数据文件格式： - -- CSV - -- Parquet - -- ORC - -> **NOTE** -> -> 对于 CSV 数据，请注意以下几点： -> -> - 您可以使用 UTF-8 字符串（例如逗号 (,)、制表符或管道 (|)），其长度不超过 50 字节作为文本分隔符。 -> - 空值用 `\N` 表示。例如，一个数据文件包含三列，并且该数据文件中的一条记录在第一列和第三列中包含数据，但在第二列中没有数据。在这种情况下，您需要在第二列中使用 `\N` 来表示空值。这意味着该记录必须编译为 `a,\N,b` 而不是 `a,,b`。`a,,b` 表示该记录的第二列包含一个空字符串。 - -## 支持的存储系统 - -Broker Load 支持以下存储系统： - -- HDFS - -- AWS S3 - -- Google GCS - -- 其他 S3 兼容的存储系统，例如 MinIO - -- Microsoft Azure Storage - -## 工作原理 - -在您向 FE 提交导入作业后，FE 会生成一个查询计划，根据可用 BE 的数量和要导入的数据文件的大小将查询计划拆分为多个部分，然后将查询计划的每个部分分配给一个可用的 BE。在导入期间，每个涉及的 BE 从您的 HDFS 或云存储系统中提取数据文件的数据，预处理数据，然后将数据导入到您的 StarRocks 集群中。在所有 BE 完成其查询计划部分后，FE 确定导入作业是否成功。 - -下图显示了 Broker Load 作业的工作流程。 - -![Broker Load 的工作流程](../_assets/broker_load_how-to-work_en.png) - -## 基本操作 - -### 创建多表导入作业 - -本主题以 CSV 为例，介绍如何将多个数据文件导入到多个表中。有关如何导入其他文件格式的数据以及 Broker Load 的语法和参数说明，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -请注意，在 StarRocks 中，某些字面量被 SQL 语言用作保留关键字。请勿在 SQL 语句中直接使用这些关键字。如果要在 SQL 语句中使用此类关键字，请将其括在一对反引号 (`) 中。请参见 [关键字](../sql-reference/sql-statements/keywords.md)。 - -#### 数据示例 - -1. 在本地文件系统中创建 CSV 文件。 - - a. 创建一个名为 `file1.csv` 的 CSV 文件。该文件包含三列，依次表示用户 ID、用户名和用户分数。 - - ```Plain - 1,Lily,23 - 2,Rose,23 - 3,Alice,24 - 4,Julia,25 - ``` - - b. 创建一个名为 `file2.csv` 的 CSV 文件。该文件包含两列，依次表示城市 ID 和城市名称。 - - ```Plain - 200,'Beijing' - ``` - -2. 在 StarRocks 数据库 `test_db` 中创建 StarRocks 表。 - - > **NOTE** - > - > 从 v2.5.7 开始，StarRocks 可以在您创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - - a. 创建一个名为 `table1` 的主键表。该表包含三列：`id`、`name` 和 `score`，其中 `id` 是主键。 - - ```SQL - CREATE TABLE `table1` - ( - `id` int(11) NOT NULL COMMENT "user ID", - `name` varchar(65533) NULL DEFAULT "" COMMENT "user name", - `score` int(11) NOT NULL DEFAULT "0" COMMENT "user score" - ) - ENGINE=OLAP - PRIMARY KEY(`id`) - DISTRIBUTED BY HASH(`id`); - ``` - - b. 创建一个名为 `table2` 的主键表。该表包含两列：`id` 和 `city`，其中 `id` 是主键。 - - ```SQL - CREATE TABLE `table2` - ( - `id` int(11) NOT NULL COMMENT "city ID", - `city` varchar(65533) NULL DEFAULT "" COMMENT "city name" - ) - ENGINE=OLAP - PRIMARY KEY(`id`) - DISTRIBUTED BY HASH(`id`); - ``` - -3. 将 `file1.csv` 和 `file2.csv` 上传到 HDFS 集群的 `/user/starrocks/` 路径、AWS S3 bucket `bucket_s3` 的 `input` 文件夹、Google GCS bucket `bucket_gcs` 的 `input` 文件夹、MinIO bucket `bucket_minio` 的 `input` 文件夹以及 Azure Storage 的指定路径。 - -#### 从 HDFS 加载数据 - -执行以下语句，将 `file1.csv` 和 `file2.csv` 从 HDFS 集群的 `/user/starrocks` 路径分别加载到 `table1` 和 `table2` 中： - -```SQL -LOAD LABEL test_db.label1 -( - DATA INFILE("hdfs://:/user/starrocks/file1.csv") - INTO TABLE table1 - COLUMNS TERMINATED BY "," - (id, name, score) - , - DATA INFILE("hdfs://:/user/starrocks/file2.csv") - INTO TABLE table2 - COLUMNS TERMINATED BY "," - (id, city) -) -WITH BROKER -( - StorageCredentialParams -) -PROPERTIES -( - "timeout" = "3600" -); -``` - -在上面的示例中，`StorageCredentialParams` 表示一组身份验证参数，这些参数因您选择的身份验证方法而异。有关详细信息，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md#hdfs)。 - -#### 从 AWS S3 加载数据 - -执行以下语句，将 `file1.csv` 和 `file2.csv` 从 AWS S3 bucket `bucket_s3` 的 `input` 文件夹分别加载到 `table1` 和 `table2` 中： - -```SQL -LOAD LABEL test_db.label2 -( - DATA INFILE("s3a://bucket_s3/input/file1.csv") - INTO TABLE table1 - COLUMNS TERMINATED BY "," - (id, name, score) - , - DATA INFILE("s3a://bucket_s3/input/file2.csv") - INTO TABLE table2 - COLUMNS TERMINATED BY "," - (id, city) -) -WITH BROKER -( - StorageCredentialParams -); -``` - -> **NOTE** -> -> Broker Load 仅支持根据 S3A 协议访问 AWS S3。因此，当您从 AWS S3 加载数据时，必须将您作为文件路径传递的 S3 URI 中的 `s3://` 替换为 `s3a://`。 - -在上面的示例中，`StorageCredentialParams` 表示一组身份验证参数，这些参数因您选择的身份验证方法而异。有关详细信息，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md#aws-s3)。 - -从 v3.1 开始，StarRocks 支持通过使用 INSERT 命令和 TABLE 关键字直接从 AWS S3 加载 Parquet 格式或 ORC 格式的文件数据，从而省去了首先创建外部表的麻烦。有关详细信息，请参见 [使用 INSERT 加载数据 > 使用 TABLE 关键字直接从外部源的文件中插入数据](../loading/InsertInto.md#insert-data-directly-from-files-in-an-external-source-using-files)。 - -#### 从 Google GCS 加载数据 - -执行以下语句，将 `file1.csv` 和 `file2.csv` 从 Google GCS bucket `bucket_gcs` 的 `input` 文件夹分别加载到 `table1` 和 `table2` 中： - -```SQL -LOAD LABEL test_db.label3 -( - DATA INFILE("gs://bucket_gcs/input/file1.csv") - INTO TABLE table1 - COLUMNS TERMINATED BY "," - (id, name, score) - , - DATA INFILE("gs://bucket_gcs/input/file2.csv") - INTO TABLE table2 - COLUMNS TERMINATED BY "," - (id, city) -) -WITH BROKER -( - StorageCredentialParams -); -``` - -> **NOTE** -> -> Broker Load 仅支持根据 gs 协议访问 Google GCS。因此，当您从 Google GCS 加载数据时，必须在您作为文件路径传递的 GCS URI 中包含 `gs://` 作为前缀。 - -在上面的示例中，`StorageCredentialParams` 表示一组身份验证参数，这些参数因您选择的身份验证方法而异。有关详细信息，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md#google-gcs)。 - -#### 从其他 S3 兼容的存储系统加载数据 - -以 MinIO 为例。您可以执行以下语句，将 `file1.csv` 和 `file2.csv` 从 MinIO bucket `bucket_minio` 的 `input` 文件夹分别加载到 `table1` 和 `table2` 中： - -```SQL -LOAD LABEL test_db.label7 -( - DATA INFILE("s3://bucket_minio/input/file1.csv") - INTO TABLE table1 - COLUMNS TERMINATED BY "," - (id, name, score) - , - DATA INFILE("s3://bucket_minio/input/file2.csv") - INTO TABLE table2 - COLUMNS TERMINATED BY "," - (id, city) -) -WITH BROKER -( - StorageCredentialParams -); -``` - -在上面的示例中，`StorageCredentialParams` 表示一组身份验证参数，这些参数因您选择的身份验证方法而异。有关详细信息，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md#other-s3-compatible-storage-system)。 - -#### 从 Microsoft Azure Storage 加载数据 - -执行以下语句，将 `file1.csv` 和 `file2.csv` 从 Azure Storage 的指定路径加载： - -```SQL -LOAD LABEL test_db.label8 -( - DATA INFILE("wasb[s]://@.blob.core.windows.net//file1.csv") - INTO TABLE table1 - COLUMNS TERMINATED BY "," - (id, name, score) - , - DATA INFILE("wasb[s]://@.blob.core.windows.net//file2.csv") - INTO TABLE table2 - COLUMNS TERMINATED BY "," - (id, city) -) -WITH BROKER -( - StorageCredentialParams -); -``` - -> **NOTICE** - > - > 从 Azure Storage 加载数据时，您需要根据您使用的访问协议和特定存储服务来确定要使用的前缀。以下示例使用 Blob Storage 作为示例。 - > - > - 当您从 Blob Storage 加载数据时，您必须根据用于访问存储帐户的协议在文件路径中包含 `wasb://` 或 `wasbs://` 作为前缀： - > - 如果您的 Blob Storage 仅允许通过 HTTP 进行访问，请使用 `wasb://` 作为前缀，例如 `wasb://@.blob.core.windows.net///*`。 - > - 如果您的 Blob Storage 仅允许通过 HTTPS 进行访问，请使用 `wasbs://` 作为前缀，例如 `wasbs://@.blob.core.windows.net///*` - > - 当您从 Data Lake Storage Gen1 加载数据时，您必须在文件路径中包含 `adl://` 作为前缀，例如 `adl://.azuredatalakestore.net//`。 - > - 当您从 Data Lake Storage Gen2 加载数据时，您必须根据用于访问存储帐户的协议在文件路径中包含 `abfs://` 或 `abfss://` 作为前缀： - > - 如果您的 Data Lake Storage Gen2 仅允许通过 HTTP 进行访问，请使用 `abfs://` 作为前缀，例如 `abfs://@.dfs.core.windows.net/`。 - > - 如果您的 Data Lake Storage Gen2 仅允许通过 HTTPS 进行访问，请使用 `abfss://` 作为前缀，例如 `abfss://@.dfs.core.windows.net/`。 - -在上面的示例中，`StorageCredentialParams` 表示一组身份验证参数，这些参数因您选择的身份验证方法而异。有关详细信息，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md#microsoft-azure-storage)。 - -#### 查询数据 - -从 HDFS 集群、AWS S3 bucket 或 Google GCS bucket 加载数据完成后，您可以使用 SELECT 语句查询 StarRocks 表的数据，以验证加载是否成功。 - -1. 执行以下语句以查询 `table1` 的数据： - - ```SQL - MySQL [test_db]> SELECT * FROM table1; - +------+-------+-------+ - | id | name | score | - +------+-------+-------+ - | 1 | Lily | 23 | - | 2 | Rose | 23 | - | 3 | Alice | 24 | - | 4 | Julia | 25 | - +------+-------+-------+ - 4 rows in set (0.00 sec) - ``` - -2. 执行以下语句以查询 `table2` 的数据： - - ```SQL - MySQL [test_db]> SELECT * FROM table2; - +------+--------+ - | id | city | - +------+--------+ - | 200 | Beijing| - +------+--------+ - 4 rows in set (0.01 sec) - ``` - -### 创建单表导入作业 - -您还可以将单个数据文件或指定路径中的所有数据文件加载到单个目标表中。假设您的 AWS S3 bucket `bucket_s3` 包含一个名为 `input` 的文件夹。`input` 文件夹包含多个数据文件，其中一个名为 `file1.csv`。这些数据文件包含与 `table1` 相同的列数，并且来自每个数据文件的列可以按顺序一一映射到来自 `table1` 的列。 - -要将 `file1.csv` 加载到 `table1` 中，请执行以下语句： - -```SQL -LOAD LABEL test_db.label_7 -( - DATA INFILE("s3a://bucket_s3/input/file1.csv") - INTO TABLE table1 - COLUMNS TERMINATED BY "," - FORMAT AS "CSV" -) -WITH BROKER -( - StorageCredentialParams -); -``` - -要将 `input` 文件夹中的所有数据文件加载到 `table1` 中，请执行以下语句： - -```SQL -LOAD LABEL test_db.label_8 -( - DATA INFILE("s3a://bucket_s3/input/*") - INTO TABLE table1 - COLUMNS TERMINATED BY "," - FORMAT AS "CSV" -) -WITH BROKER -( - StorageCredentialParams -); -``` - -在上面的示例中，`StorageCredentialParams` 表示一组身份验证参数，这些参数因您选择的身份验证方法而异。有关详细信息，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md#aws-s3)。 - -### 查看导入作业 - -Broker Load 允许您使用 SHOW LOAD 语句或 `curl` 命令查看 lob 作业。 - -#### 使用 SHOW LOAD - -有关详细信息，请参见 [SHOW LOAD](../sql-reference/sql-statements/loading_unloading/SHOW_LOAD.md)。 - -#### 使用 curl - -语法如下： - -```Bash -curl --location-trusted -u : \ - 'http://:/api//_load_info?label=' -``` - -> **NOTE** -> -> 如果您使用的帐户未设置密码，则只需输入 `:`。 - -例如，您可以运行以下命令来查看 `test_db` 数据库中标签为 `label1` 的导入作业的信息： - -```Bash -curl --location-trusted -u : \ - 'http://:/api/test_db/_load_info?label=label1' -``` - -`curl` 命令以 JSON 对象 `jobInfo` 的形式返回有关具有指定标签的最近执行的导入作业的信息： - -```JSON -{"jobInfo":{"dbName":"default_cluster:test_db","tblNames":["table1_simple"],"label":"label1","state":"FINISHED","failMsg":"","trackingUrl":""},"status":"OK","msg":"Success"}% -``` - -下表描述了 `jobInfo` 中的参数。 - -| **参数** | **描述** | -| ------------- | ------------------------------------------------------------ | -| dbName | 要将数据加载到的数据库的名称。 | -| tblNames | 要将数据加载到的表的名称。 | -| label | 导入作业的标签。 | -| state | 导入作业的状态。有效值：
  • `PENDING`：导入作业正在队列中等待调度。
  • `QUEUEING`：导入作业正在队列中等待调度。
  • `LOADING`：导入作业正在运行。
  • `PREPARED`：事务已提交。
  • `FINISHED`：导入作业成功。
  • `CANCELLED`：导入作业失败。
有关详细信息，请参见 [导入概念](./loading_introduction/loading_concepts.md) 中的“异步导入”部分。 | -| failMsg | 导入作业失败的原因。如果导入作业的 `state` 值为 `PENDING`、`LOADING` 或 `FINISHED`，则为 `failMsg` 参数返回 `NULL`。如果导入作业的 `state` 值为 `CANCELLED`，则为 `failMsg` 参数返回的值由两部分组成：`type` 和 `msg`。
  • `type` 部分可以是以下任何值：
    • `USER_CANCEL`：导入作业已手动取消。
    • `ETL_SUBMIT_FAIL`：导入作业未能提交。
    • `ETL-QUALITY-UNSATISFIED`：导入作业失败，因为不合格数据的百分比超过了 `max-filter-ratio` 参数的值。
    • `LOAD-RUN-FAIL`：导入作业在 `LOADING` 阶段失败。
    • `TIMEOUT`：导入作业未在指定的超时时间内完成。
    • `UNKNOWN`：导入作业因未知错误而失败。
  • `msg` 部分提供了导入失败的详细原因。
| -| trackingUrl | 用于访问在导入作业中检测到的不合格数据的 URL。您可以使用 `curl` 或 `wget` 命令访问该 URL 并获取不合格数据。如果未检测到不合格数据，则为 `trackingUrl` 参数返回 `NULL`。 | -| status | 导入作业的 HTTP 请求的状态。有效值为：`OK` 和 `Fail`。 | -| msg | 导入作业的 HTTP 请求的错误信息。 | - -### 取消导入作业 - -当导入作业未处于 **CANCELLED** 或 **FINISHED** 阶段时，您可以使用 [CANCEL LOAD](../sql-reference/sql-statements/loading_unloading/CANCEL_LOAD.md) 语句取消该作业。 - -例如，您可以执行以下语句以取消数据库 `test_db` 中标签为 `label1` 的导入作业： - -```SQL -CANCEL LOAD -FROM test_db -WHERE LABEL = "label"; -``` - -## 作业拆分和并发运行 - -一个 Broker Load 作业可以拆分为一个或多个并发运行的任务。一个导入作业中的所有任务都在一个事务中运行。它们必须全部成功或全部失败。StarRocks 根据您在 `LOAD` 语句中如何声明 `data_desc` 来拆分每个导入作业： - -- 如果您声明了多个 `data_desc` 参数，每个参数指定一个不同的表，则会生成一个任务来加载每个表的数据。 - -- 如果您声明了多个 `data_desc` 参数，每个参数指定同一表的不同分区，则会生成一个任务来加载每个分区的数据。 - -此外，每个任务可以进一步拆分为一个或多个实例，这些实例均匀分布到 StarRocks 集群的 BE 上并并发运行。StarRocks 根据以下 [FE 配置](../administration/management/FE_configuration.md) 拆分每个任务： - -- `min_bytes_per_broker_scanner`：每个实例处理的最小数据量。默认量为 64 MB。 - -- `load_parallel_instance_num`：每个 BE 上每个导入作业中允许的并发实例数。默认数量为 1。 - - 您可以使用以下公式计算单个任务中的实例数： - - **单个任务中的实例数 = min(单个任务要加载的数据量/`min_bytes_per_broker_scanner`，`load_parallel_instance_num` x BE 数量)** - -在大多数情况下，每个导入作业只声明一个 `data_desc`，每个导入作业只拆分为一个任务，并且该任务拆分的实例数与 BE 的数量相同。 - -## 相关配置项 - -[FE 配置项](../administration/management/FE_configuration.md) `max_broker_load_job_concurrency` 指定了 StarRocks 集群中可以并发运行的最大 Broker Load 作业数。 - -在 StarRocks v2.4 及更早版本中，如果在特定时间段内提交的 Broker Load 作业总数超过最大数量，则会将过多的作业排队并根据其提交时间进行调度。 - -自 StarRocks v2.5 以来，如果在特定时间段内提交的 Broker Load 作业总数超过最大数量，则会将过多的作业排队并根据其优先级进行调度。您可以在创建作业时使用 `priority` 参数为作业指定优先级。请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md#opt_properties)。您还可以使用 [ALTER LOAD](../sql-reference/sql-statements/loading_unloading/ALTER_LOAD.md) 修改处于 **QUEUEING** 或 **LOADING** 状态的现有作业的优先级。 \ No newline at end of file diff --git a/docs/zh/loading/Etl_in_loading.md b/docs/zh/loading/Etl_in_loading.md deleted file mode 100644 index 1baded5..0000000 --- a/docs/zh/loading/Etl_in_loading.md +++ /dev/null @@ -1,452 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 数据导入时转换数据 - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -StarRocks 支持在数据导入时转换数据。 - -该功能支持 [Stream Load](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md) 、[Broker Load](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md) 和 [Routine Load](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md) ，但不支持 [Spark Load](../sql-reference/sql-statements/loading_unloading/SPARK_LOAD.md) 。 - - - -本文档以 CSV 数据为例，介绍如何在数据导入时提取和转换数据。支持的数据文件格式因您选择的导入方式而异。 - -> **NOTE** -> -> 对于 CSV 数据，您可以使用 UTF-8 字符串（例如逗号 (,)、制表符或管道 (|)）作为文本分隔符，其长度不超过 50 字节。 - -## 适用场景 - -当您将数据文件导入到 StarRocks 表中时，数据文件的数据可能无法完全映射到 StarRocks 表的数据。在这种情况下，您无需在将数据加载到 StarRocks 表之前提取或转换数据。StarRocks 可以帮助您在加载期间提取和转换数据： - -- 跳过不需要加载的列。 - - 您可以跳过不需要加载的列。此外，如果数据文件的列与 StarRocks 表的列顺序不同，则可以在数据文件和 StarRocks 表之间创建列映射。 - -- 过滤掉您不想加载的行。 - - 您可以指定过滤条件，StarRocks 会根据这些条件过滤掉您不想加载的行。 - -- 从原始列生成新列。 - - 生成的列是从数据文件的原始列计算得出的特殊列。您可以将生成的列映射到 StarRocks 表的列。 - -- 从文件路径提取分区字段值。 - - 如果数据文件是从 Apache Hive™ 生成的，则可以从文件路径提取分区字段值。 - -## 数据示例 - -1. 在本地文件系统中创建数据文件。 - - a. 创建一个名为 `file1.csv` 的数据文件。该文件由四列组成，依次表示用户 ID、用户性别、事件日期和事件类型。 - - ```Plain - 354,female,2020-05-20,1 - 465,male,2020-05-21,2 - 576,female,2020-05-22,1 - 687,male,2020-05-23,2 - ``` - - b. 创建一个名为 `file2.csv` 的数据文件。该文件仅由一列组成，表示日期。 - - ```Plain - 2020-05-20 - 2020-05-21 - 2020-05-22 - 2020-05-23 - ``` - -2. 在 StarRocks 数据库 `test_db` 中创建表。 - - > **NOTE** - > - > 从 v2.5.7 开始，StarRocks 可以在您创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - - a. 创建一个名为 `table1` 的表，该表由三列组成：`event_date`、`event_type` 和 `user_id`。 - - ```SQL - MySQL [test_db]> CREATE TABLE table1 - ( - `event_date` DATE COMMENT "event date", - `event_type` TINYINT COMMENT "event type", - `user_id` BIGINT COMMENT "user ID" - ) - DISTRIBUTED BY HASH(user_id); - ``` - - b. 创建一个名为 `table2` 的表，该表由四列组成：`date`、`year`、`month` 和 `day`。 - - ```SQL - MySQL [test_db]> CREATE TABLE table2 - ( - `date` DATE COMMENT "date", - `year` INT COMMENT "year", - `month` TINYINT COMMENT "month", - `day` TINYINT COMMENT "day" - ) - DISTRIBUTED BY HASH(date); - ``` - -3. 将 `file1.csv` 和 `file2.csv` 上传到 HDFS 集群的 `/user/starrocks/data/input/` 路径，将 `file1.csv` 的数据发布到 Kafka 集群的 `topic1`，并将 `file2.csv` 的数据发布到 Kafka 集群的 `topic2`。 - -## 跳过不需要加载的列 - -您要加载到 StarRocks 表中的数据文件可能包含一些无法映射到 StarRocks 表的任何列的列。在这种情况下，StarRocks 支持仅加载可以从数据文件映射到 StarRocks 表的列。 - -此功能支持从以下数据源加载数据： - -- 本地文件系统 - -- HDFS 和云存储 - - > **NOTE** - > - > 本节以 HDFS 为例。 - -- Kafka - -在大多数情况下，CSV 文件的列未命名。对于某些 CSV 文件，第一行由列名组成，但 StarRocks 将第一行的内容处理为普通数据，而不是列名。因此，当您加载 CSV 文件时，必须在作业创建语句或命令中**按顺序**临时命名 CSV 文件的列。这些临时命名的列**按名称**映射到 StarRocks 表的列。请注意以下关于数据文件列的几点： - -- 可以映射到 StarRocks 表的列，并通过使用 StarRocks 表中列的名称临时命名，这些列的数据将被直接加载。 - -- 无法映射到 StarRocks 表的列将被忽略，这些列的数据不会被加载。 - -- 如果某些列可以映射到 StarRocks 表的列，但在作业创建语句或命令中未临时命名，则加载作业会报告错误。 - -本节以 `file1.csv` 和 `table1` 为例。`file1.csv` 的四列依次临时命名为 `user_id`、`user_gender`、`event_date` 和 `event_type`。在 `file1.csv` 的临时命名列中，`user_id`、`event_date` 和 `event_type` 可以映射到 `table1` 的特定列，而 `user_gender` 无法映射到 `table1` 的任何列。因此，`user_id`、`event_date` 和 `event_type` 将被加载到 `table1` 中，但 `user_gender` 不会被加载。 - -### 导入数据 - -#### 从本地文件系统加载数据 - -如果 `file1.csv` 存储在您的本地文件系统中，请运行以下命令来创建 [Stream Load](../loading/StreamLoad.md) 作业： - -```Bash -curl --location-trusted -u : \ - -H "Expect:100-continue" \ - -H "column_separator:," \ - -H "columns: user_id, user_gender, event_date, event_type" \ - -T file1.csv -XPUT \ - http://:/api/test_db/table1/_stream_load -``` - -> **NOTE** -> -> 如果您选择 Stream Load，则必须使用 `columns` 参数临时命名数据文件的列，以在数据文件和 StarRocks 表之间创建列映射。 - -有关详细的语法和参数说明，请参见 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -#### 从 HDFS 集群加载数据 - -如果 `file1.csv` 存储在您的 HDFS 集群中，请执行以下语句来创建 [Broker Load](../loading/hdfs_load.md) 作业： - -```SQL -LOAD LABEL test_db.label1 -( - DATA INFILE("hdfs://:/user/starrocks/data/input/file1.csv") - INTO TABLE `table1` - FORMAT AS "csv" - COLUMNS TERMINATED BY "," - (user_id, user_gender, event_date, event_type) -) -WITH BROKER; -``` - -> **NOTE** -> -> 如果您选择 Broker Load，则必须使用 `column_list` 参数临时命名数据文件的列，以在数据文件和 StarRocks 表之间创建列映射。 - -有关详细的语法和参数说明，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -#### 从 Kafka 集群加载数据 - -如果 `file1.csv` 的数据发布到 Kafka 集群的 `topic1`，请执行以下语句来创建 [Routine Load](../loading/RoutineLoad.md) 作业： - -```SQL -CREATE ROUTINE LOAD test_db.table101 ON table1 - COLUMNS TERMINATED BY ",", - COLUMNS(user_id, user_gender, event_date, event_type) -FROM KAFKA -( - "kafka_broker_list" = ":", - "kafka_topic" = "topic1", - "property.kafka_default_offsets" = "OFFSET_BEGINNING" -); -``` - -> **NOTE** -> -> 如果您选择 Routine Load，则必须使用 `COLUMNS` 参数临时命名数据文件的列，以在数据文件和 StarRocks 表之间创建列映射。 - -有关详细的语法和参数说明，请参见 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。 - -### 查询数据 - -从本地文件系统、HDFS 集群或 Kafka 集群加载数据完成后，查询 `table1` 的数据以验证加载是否成功： - -```SQL -MySQL [test_db]> SELECT * FROM table1; -+------------+------------+---------+ -| event_date | event_type | user_id | -+------------+------------+---------+ -| 2020-05-22 | 1 | 576 | -| 2020-05-20 | 1 | 354 | -| 2020-05-21 | 2 | 465 | -| 2020-05-23 | 2 | 687 | -+------------+------------+---------+ -4 rows in set (0.01 sec) -``` - -## 过滤掉您不想加载的行 - -当您将数据文件加载到 StarRocks 表中时，您可能不想加载数据文件的特定行。在这种情况下，您可以使用 WHERE 子句来指定要加载的行。StarRocks 会过滤掉所有不满足 WHERE 子句中指定的过滤条件的行。 - -此功能支持从以下数据源加载数据： - -- 本地文件系统 - -- HDFS 和云存储 - > **NOTE** - > - > 本节以 HDFS 为例。 - -- Kafka - -本节以 `file1.csv` 和 `table1` 为例。如果您只想将 `file1.csv` 中事件类型为 `1` 的行加载到 `table1` 中，则可以使用 WHERE 子句来指定过滤条件 `event_type = 1`。 - -### 导入数据 - -#### 从本地文件系统加载数据 - -如果 `file1.csv` 存储在您的本地文件系统中，请运行以下命令来创建 [Stream Load](../loading/StreamLoad.md) 作业： - -```Bash -curl --location-trusted -u : \ - -H "Expect:100-continue" \ - -H "column_separator:," \ - -H "columns: user_id, user_gender, event_date, event_type" \ - -H "where: event_type=1" \ - -T file1.csv -XPUT \ - http://:/api/test_db/table1/_stream_load -``` - -有关详细的语法和参数说明，请参见 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -#### 从 HDFS 集群加载数据 - -如果 `file1.csv` 存储在您的 HDFS 集群中，请执行以下语句来创建 [Broker Load](../loading/hdfs_load.md) 作业： - -```SQL -LOAD LABEL test_db.label2 -( - DATA INFILE("hdfs://:/user/starrocks/data/input/file1.csv") - INTO TABLE `table1` - FORMAT AS "csv" - COLUMNS TERMINATED BY "," - (user_id, user_gender, event_date, event_type) - WHERE event_type = 1 -) -WITH BROKER; -``` - -有关详细的语法和参数说明，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -#### 从 Kafka 集群加载数据 - -如果 `file1.csv` 的数据发布到 Kafka 集群的 `topic1`，请执行以下语句来创建 [Routine Load](../loading/RoutineLoad.md) 作业： - -```SQL -CREATE ROUTINE LOAD test_db.table102 ON table1 -COLUMNS TERMINATED BY ",", -COLUMNS (user_id, user_gender, event_date, event_type), -WHERE event_type = 1 -FROM KAFKA -( - "kafka_broker_list" = ":", - "kafka_topic" = "topic1", - "property.kafka_default_offsets" = "OFFSET_BEGINNING" -); -``` - -有关详细的语法和参数说明，请参见 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。 - -### 查询数据 - -从本地文件系统、HDFS 集群或 Kafka 集群加载数据完成后，查询 `table1` 的数据以验证加载是否成功： - -```SQL -MySQL [test_db]> SELECT * FROM table1; -+------------+------------+---------+ -| event_date | event_type | user_id | -+------------+------------+---------+ -| 2020-05-20 | 1 | 354 | -| 2020-05-22 | 1 | 576 | -+------------+------------+---------+ -2 rows in set (0.01 sec) -``` - -## 从原始列生成新列 - -当您将数据文件加载到 StarRocks 表中时，数据文件的某些数据可能需要转换后才能加载到 StarRocks 表中。在这种情况下，您可以使用作业创建命令或语句中的函数或表达式来实现数据转换。 - -此功能支持从以下数据源加载数据： - -- 本地文件系统 - -- HDFS 和云存储 - > **NOTE** - > - > 本节以 HDFS 为例。 - -- Kafka - -本节以 `file2.csv` 和 `table2` 为例。`file2.csv` 仅由一列组成，表示日期。您可以使用 [year](../sql-reference/sql-functions/date-time-functions/year.md) 、[month](../sql-reference/sql-functions/date-time-functions/month.md) 和 [day](../sql-reference/sql-functions/date-time-functions/day.md) 函数从 `file2.csv` 中的每个日期提取年、月和日，并将提取的数据加载到 `table2` 的 `year`、`month` 和 `day` 列中。 - -### 导入数据 - -#### 从本地文件系统加载数据 - -如果 `file2.csv` 存储在您的本地文件系统中，请运行以下命令来创建 [Stream Load](../loading/StreamLoad.md) 作业： - -```Bash -curl --location-trusted -u : \ - -H "Expect:100-continue" \ - -H "column_separator:," \ - -H "columns:date,year=year(date),month=month(date),day=day(date)" \ - -T file2.csv -XPUT \ - http://:/api/test_db/table2/_stream_load -``` - -> **NOTE** -> -> - 在 `columns` 参数中，您必须首先临时命名数据文件的**所有列**，然后临时命名要从数据文件的原始列生成的新列。如前面的示例所示，`file2.csv` 的唯一列临时命名为 `date`，然后调用 `year=year(date)`、`month=month(date)` 和 `day=day(date)` 函数来生成三个新列，这些新列临时命名为 `year`、`month` 和 `day`。 -> -> - Stream Load 不支持 `column_name = function(column_name)`，但支持 `column_name = function(column_name)`。 - -有关详细的语法和参数说明，请参见 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -#### 从 HDFS 集群加载数据 - -如果 `file2.csv` 存储在您的 HDFS 集群中，请执行以下语句来创建 [Broker Load](../loading/hdfs_load.md) 作业： - -```SQL -LOAD LABEL test_db.label3 -( - DATA INFILE("hdfs://:/user/starrocks/data/input/file2.csv") - INTO TABLE `table2` - FORMAT AS "csv" - COLUMNS TERMINATED BY "," - (date) - SET(year=year(date), month=month(date), day=day(date)) -) -WITH BROKER; -``` - -> **NOTE** -> -> 您必须首先使用 `column_list` 参数临时命名数据文件的**所有列**，然后使用 SET 子句临时命名要从数据文件的原始列生成的新列。如前面的示例所示，`file2.csv` 的唯一列在 `column_list` 参数中临时命名为 `date`，然后在 SET 子句中调用 `year=year(date)`、`month=month(date)` 和 `day=day(date)` 函数来生成三个新列，这些新列临时命名为 `year`、`month` 和 `day`。 - -有关详细的语法和参数说明，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -#### 从 Kafka 集群加载数据 - -如果 `file2.csv` 的数据发布到 Kafka 集群的 `topic2`，请执行以下语句来创建 [Routine Load](../loading/RoutineLoad.md) 作业： - -```SQL -CREATE ROUTINE LOAD test_db.table201 ON table2 - COLUMNS TERMINATED BY ",", - COLUMNS(date,year=year(date),month=month(date),day=day(date)) -FROM KAFKA -( - "kafka_broker_list" = ":", - "kafka_topic" = "topic2", - "property.kafka_default_offsets" = "OFFSET_BEGINNING" -); -``` - -> **NOTE** -> -> 在 `COLUMNS` 参数中，您必须首先临时命名数据文件的**所有列**，然后临时命名要从数据文件的原始列生成的新列。如前面的示例所示，`file2.csv` 的唯一列临时命名为 `date`，然后调用 `year=year(date)`、`month=month(date)` 和 `day=day(date)` 函数来生成三个新列，这些新列临时命名为 `year`、`month` 和 `day`。 - -有关详细的语法和参数说明，请参见 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。 - -### 查询数据 - -从本地文件系统、HDFS 集群或 Kafka 集群加载数据完成后，查询 `table2` 的数据以验证加载是否成功： - -```SQL -MySQL [test_db]> SELECT * FROM table2; -+------------+------+-------+------+ -| date | year | month | day | -+------------+------+-------+------+ -| 2020-05-20 | 2020 | 5 | 20 | -| 2020-05-21 | 2020 | 5 | 21 | -| 2020-05-22 | 2020 | 5 | 22 | -| 2020-05-23 | 2020 | 5 | 23 | -+------------+------+-------+------+ -4 rows in set (0.01 sec) -``` - -## 从文件路径提取分区字段值 - -如果您指定的文件路径包含分区字段，则可以使用 `COLUMNS FROM PATH AS` 参数来指定要从文件路径提取的分区字段。文件路径中的分区字段等同于数据文件中的列。仅当您从 HDFS 集群加载数据时，才支持 `COLUMNS FROM PATH AS` 参数。 - -例如，您要加载以下四个从 Hive 生成的数据文件： - -```Plain -/user/starrocks/data/input/date=2020-05-20/data -1,354 -/user/starrocks/data/input/date=2020-05-21/data -2,465 -/user/starrocks/data/input/date=2020-05-22/data -1,576 -/user/starrocks/data/input/date=2020-05-23/data -2,687 -``` - -这四个数据文件存储在 HDFS 集群的 `/user/starrocks/data/input/` 路径中。这些数据文件中的每一个都按分区字段 `date` 分区，并由两列组成，依次表示事件类型和用户 ID。 - -### 从 HDFS 集群加载数据 - -执行以下语句以创建 [Broker Load](../loading/hdfs_load.md) 作业，该作业使您可以从 `/user/starrocks/data/input/` 文件路径提取 `date` 分区字段值，并使用通配符 (*) 来指定您要将文件路径中的所有数据文件加载到 `table1`： - -```SQL -LOAD LABEL test_db.label4 -( - DATA INFILE("hdfs://:/user/starrocks/data/input/date=*/*") - INTO TABLE `table1` - FORMAT AS "csv" - COLUMNS TERMINATED BY "," - (event_type, user_id) - COLUMNS FROM PATH AS (date) - SET(event_date = date) -) -WITH BROKER; -``` - -> **NOTE** -> -> 在前面的示例中，指定文件路径中的 `date` 分区字段等同于 `table1` 的 `event_date` 列。因此，您需要使用 SET 子句将 `date` 分区字段映射到 `event_date` 列。如果指定文件路径中的分区字段与 StarRocks 表的列同名，则无需使用 SET 子句创建映射。 - -有关详细的语法和参数说明，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -### 查询数据 - -从 HDFS 集群加载数据完成后，查询 `table1` 的数据以验证加载是否成功： - -```SQL -MySQL [test_db]> SELECT * FROM table1; -+------------+------------+---------+ -| event_date | event_type | user_id | -+------------+------------+---------+ -| 2020-05-22 | 1 | 576 | -| 2020-05-20 | 1 | 354 | -| 2020-05-21 | 2 | 465 | -| 2020-05-23 | 2 | 687 | -+------------+------------+---------+ -4 rows in set (0.01 sec) -``` \ No newline at end of file diff --git a/docs/zh/loading/Flink-connector-starrocks.md b/docs/zh/loading/Flink-connector-starrocks.md deleted file mode 100644 index f058908..0000000 --- a/docs/zh/loading/Flink-connector-starrocks.md +++ /dev/null @@ -1,572 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 从 Apache Flink® 持续导入数据 - -StarRocks 提供了一个自主开发的连接器，名为 StarRocks Connector for Apache Flink® (简称为 Flink connector)，以帮助您使用 Flink 将数据导入到 StarRocks 表中。其基本原理是先积累数据，然后通过 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md) 将数据一次性导入到 StarRocks 中。 - -Flink connector 支持 DataStream API、Table API & SQL 和 Python API。与 Apache Flink® 提供的 [flink-connector-jdbc](https://nightlies.apache.org/flink/flink-docs-master/docs/connectors/table/jdbc/) 相比，它具有更高且更稳定的性能。 - -> **注意** -> -> 使用 Flink connector 将数据导入到 StarRocks 表中，需要对目标 StarRocks 表具有 SELECT 和 INSERT 权限。如果您没有这些权限，请按照 [GRANT](../sql-reference/sql-statements/account-management/GRANT.md) 中提供的说明，将这些权限授予用于连接 StarRocks 集群的用户。 - -## 版本要求 - -| Connector | Flink | StarRocks | Java | Scala | -|-----------|-------------------------------|---------------| ---- |-----------| -| 1.2.11 | 1.15,1.16,1.17,1.18,1.19,1.20 | 2.1 and later | 8 | 2.11,2.12 | -| 1.2.10 | 1.15,1.16,1.17,1.18,1.19 | 2.1 and later | 8 | 2.11,2.12 | -| 1.2.9 | 1.15,1.16,1.17,1.18 | 2.1 and later | 8 | 2.11,2.12 | -| 1.2.8 | 1.13,1.14,1.15,1.16,1.17 | 2.1 and later | 8 | 2.11,2.12 | -| 1.2.7 | 1.11,1.12,1.13,1.14,1.15 | 2.1 and later | 8 | 2.11,2.12 | - -## 获取 Flink connector - -您可以通过以下方式获取 Flink connector JAR 文件： - -- 直接下载已编译的 Flink connector JAR 文件。 -- 在您的 Maven 项目中添加 Flink connector 作为依赖项，然后下载 JAR 文件。 -- 自己将 Flink connector 的源代码编译为 JAR 文件。 - -Flink connector JAR 文件的命名格式如下： - -- 从 Flink 1.15 开始，命名格式为 `flink-connector-starrocks-${connector_version}_flink-${flink_version}.jar`。例如，如果您安装了 Flink 1.15 并且想要使用 Flink connector 1.2.7，则可以使用 `flink-connector-starrocks-1.2.7_flink-1.15.jar`。 - -- 在 Flink 1.15 之前，命名格式为 `flink-connector-starrocks-${connector_version}_flink-${flink_version}_${scala_version}.jar`。例如，如果您的环境中安装了 Flink 1.14 和 Scala 2.12，并且想要使用 Flink connector 1.2.7，则可以使用 `flink-connector-starrocks-1.2.7_flink-1.14_2.12.jar`。 - -> **注意** -> -> 通常，最新版本的 Flink connector 仅保持与 Flink 的三个最新版本的兼容性。 - -### 下载已编译的 Jar 文件 - -从 [Maven Central Repository](https://repo1.maven.org/maven2/com/starrocks) 直接下载相应版本的 Flink connector Jar 文件。 - -### Maven 依赖 - -在您的 Maven 项目的 `pom.xml` 文件中，按照以下格式添加 Flink connector 作为依赖项。将 `flink_version`、`scala_version` 和 `connector_version` 替换为相应的版本。 - -- 在 Flink 1.15 及更高版本中 - - ```xml - - com.starrocks - flink-connector-starrocks - ${connector_version}_flink-${flink_version} - - ``` - -- 在低于 Flink 1.15 的版本中 - - ```xml - - com.starrocks - flink-connector-starrocks - ${connector_version}_flink-${flink_version}_${scala_version} - - ``` - -### 自行编译 - -1. 下载 [Flink connector 源代码](https://github.com/StarRocks/starrocks-connector-for-apache-flink)。 -2. 执行以下命令，将 Flink connector 的源代码编译为 JAR 文件。请注意，`flink_version` 替换为相应的 Flink 版本。 - - ```bash - sh build.sh - ``` - - 例如，如果您的环境中的 Flink 版本为 1.15，则需要执行以下命令： - - ```bash - sh build.sh 1.15 - ``` - -3. 进入 `target/` 目录以查找 Flink connector JAR 文件，例如编译后生成的 `flink-connector-starrocks-1.2.7_flink-1.15-SNAPSHOT.jar`。 - -> **注意** -> -> 非正式发布的 Flink connector 的名称包含 `SNAPSHOT` 后缀。 - -## Options - -### connector - -**是否必须**: 是
-**默认值**: NONE
-**描述**: 您要使用的连接器。该值必须为 "starrocks"。 - -### jdbc-url - -**是否必须**: 是
-**默认值**: NONE
-**描述**: 用于连接 FE 的 MySQL 服务器的地址。您可以指定多个地址，这些地址必须用逗号 (,) 分隔。格式：`jdbc:mysql://:,:,:`。 - -### load-url - -**是否必须**: 是
-**默认值**: NONE
-**描述**: 用于连接 FE 的 HTTP 服务器的地址。您可以指定多个地址，这些地址必须用分号 (;) 分隔。格式：`:;:`。 - -### database-name - -**是否必须**: 是
-**默认值**: NONE
-**描述**: 您要将数据加载到的 StarRocks 数据库的名称。 - -### table-name - -**是否必须**: 是
-**默认值**: NONE
-**描述**: 您要用于将数据加载到 StarRocks 中的表的名称。 - -### username - -**是否必须**: 是
-**默认值**: NONE
-**描述**: 您要用于将数据加载到 StarRocks 中的帐户的用户名。该帐户需要对目标 StarRocks 表具有 [SELECT 和 INSERT 权限](../sql-reference/sql-statements/account-management/GRANT.md)。 - -### password - -**是否必须**: 是
-**默认值**: NONE
-**描述**: 上述帐户的密码。 - -### sink.version - -**是否必须**: 否
-**默认值**: AUTO
-**描述**: 用于加载数据的接口。从 Flink connector 1.2.4 版本开始支持此参数。
  • `V1`: 使用 [Stream Load](../loading/StreamLoad.md) 接口加载数据。1.2.4 之前的连接器仅支持此模式。
  • `V2`: 使用 [Stream Load 事务](./Stream_Load_transaction_interface.md) 接口加载数据。它要求 StarRocks 至少为 2.4 版本。推荐使用 `V2`，因为它优化了内存使用并提供了更稳定的 exactly-once 实现。
  • `AUTO`: 如果 StarRocks 的版本支持事务 Stream Load，将自动选择 `V2`，否则选择 `V1`。
- -### sink.label-prefix - -**是否必须**: 否
-**默认值**: NONE
-**描述**: Stream Load 使用的标签前缀。如果您正在使用 1.2.8 及更高版本的连接器进行 exactly-once，建议配置此参数。请参阅 [exactly-once 使用说明](#exactly-once)。 - -### sink.semantic - -**是否必须**: 否
-**默认值**: at-least-once
-**描述**: sink 保证的语义。有效值：**at-least-once** 和 **exactly-once**。 - -### sink.buffer-flush.max-bytes - -**是否必须**: 否
-**默认值**: 94371840(90M)
-**描述**: 在一次发送到 StarRocks 之前，可以在内存中累积的最大数据量。最大值范围为 64 MB 到 10 GB。将此参数设置为较大的值可以提高导入性能，但可能会增加导入延迟。此参数仅在 `sink.semantic` 设置为 `at-least-once` 时生效。如果 `sink.semantic` 设置为 `exactly-once`，则在触发 Flink checkpoint 时刷新内存中的数据。在这种情况下，此参数不生效。 - -### sink.buffer-flush.max-rows - -**是否必须**: 否
-**默认值**: 500000
-**描述**: 在一次发送到 StarRocks 之前，可以在内存中累积的最大行数。此参数仅在 `sink.version` 为 `V1` 且 `sink.semantic` 为 `at-least-once` 时可用。有效值：64000 到 5000000。 - -### sink.buffer-flush.interval-ms - -**是否必须**: 否
-**默认值**: 300000
-**描述**: 刷新数据的间隔。此参数仅在 `sink.semantic` 为 `at-least-once` 时可用。有效值：1000 到 3600000。单位：毫秒。 - -### sink.max-retries - -**是否必须**: 否
-**默认值**: 3
-**描述**: 系统重试执行 Stream Load 作业的次数。仅当您将 `sink.version` 设置为 `V1` 时，此参数才可用。有效值：0 到 10。 - -### sink.connect.timeout-ms - -**是否必须**: 否
-**默认值**: 30000
-**描述**: 建立 HTTP 连接的超时时间。有效值：100 到 60000。单位：毫秒。在 Flink connector v1.2.9 之前，默认值为 `1000`。 - -### sink.socket.timeout-ms - -**是否必须**: 否
-**默认值**: -1
-**描述**: 自 1.2.10 起支持。HTTP 客户端等待数据的时间。单位：毫秒。默认值 `-1` 表示没有超时。 - -### sink.sanitize-error-log - -**是否必须**: 否
-**默认值**: false
-**描述**: 自 1.2.12 起支持。是否对生产安全错误日志中的敏感数据进行清理。当此项设置为 `true` 时，连接器和 SDK 日志中的 Stream Load 错误日志中的敏感行数据和列值将被编辑。为了向后兼容，该值默认为 `false`。 - -### sink.wait-for-continue.timeout-ms - -**是否必须**: 否
-**默认值**: 10000
-**描述**: 自 1.2.7 起支持。等待来自 FE 的 HTTP 100-continue 响应的超时时间。有效值：`3000` 到 `60000`。单位：毫秒。 - -### sink.ignore.update-before - -**是否必须**: 否
-**默认值**: true
-**描述**: 自 1.2.8 版本起支持。将数据加载到主键表时，是否忽略来自 Flink 的 `UPDATE_BEFORE` 记录。如果此参数设置为 false，则该记录将被视为对 StarRocks 表的删除操作。 - -### sink.parallelism - -**是否必须**: 否
-**默认值**: NONE
-**描述**: 导入的并行度。仅适用于 Flink SQL。如果未指定此参数，则 Flink planner 决定并行度。**在多并行度的情况下，用户需要保证数据以正确的顺序写入。** - -### sink.properties.* - -**是否必须**: 否
-**默认值**: NONE
-**描述**: 用于控制 Stream Load 行为的参数。例如，参数 `sink.properties.format` 指定用于 Stream Load 的格式，例如 CSV 或 JSON。有关支持的参数及其描述的列表，请参阅 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -### sink.properties.format - -**是否必须**: 否
-**默认值**: csv
-**描述**: 用于 Stream Load 的格式。Flink connector 将在将每批数据发送到 StarRocks 之前将其转换为该格式。有效值：`csv` 和 `json`。 - -### sink.properties.column_separator - -**是否必须**: 否
-**默认值**: \t
-**描述**: CSV 格式数据的列分隔符。 - -### sink.properties.row_delimiter - -**是否必须**: 否
-**默认值**: \n
-**描述**: CSV 格式数据的行分隔符。 - -### sink.properties.max_filter_ratio - -**是否必须**: 否
-**默认值**: 0
-**描述**: Stream Load 的最大错误容忍度。它是由于数据质量不足而被过滤掉的数据记录的最大百分比。有效值：`0` 到 `1`。默认值：`0`。有关详细信息，请参阅 [Stream Load](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -### sink.properties.partial_update - -**是否必须**: 否
-**默认值**: `FALSE`
-**描述**: 是否使用部分更新。有效值：`TRUE` 和 `FALSE`。默认值为 `FALSE`，表示禁用此功能。 - -### sink.properties.partial_update_mode - -**是否必须**: 否
-**默认值**: `row`
-**描述**: 指定部分更新的模式。有效值：`row` 和 `column`。
  • 值 `row` (默认) 表示行模式下的部分更新，更适合于具有许多列和小批量的实时更新。
  • 值 `column` 表示列模式下的部分更新，更适合于具有少量列和许多行的批量更新。在这种情况下，启用列模式可以提供更快的更新速度。例如，在一个具有 100 列的表中，如果仅更新所有行的 10 列（总数的 10%），则列模式的更新速度比行模式快 10 倍。
- -### sink.properties.strict_mode - -**是否必须**: 否
-**默认值**: false
-**描述**: 指定是否为 Stream Load 启用严格模式。它会影响存在不合格行（例如，列值不一致）时的加载行为。有效值：`true` 和 `false`。默认值：`false`。有关详细信息，请参阅 [Stream Load](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -### sink.properties.compression - -**是否必须**: 否
-**默认值**: NONE
-**描述**: 用于 Stream Load 的压缩算法。有效值：`lz4_frame`。JSON 格式的压缩需要 Flink connector 1.2.10+ 和 StarRocks v3.2.7+。CSV 格式的压缩仅需要 Flink connector 1.2.11+。 - -### sink.properties.prepared_timeout - -**是否必须**: 否
-**默认值**: NONE
-**描述**: 自 1.2.12 起支持，并且仅在 `sink.version` 设置为 `V2` 时有效。需要 StarRocks 3.5.4 或更高版本。设置从 `PREPARED` 到 `COMMITTED` 的事务 Stream Load 阶段的超时时间（以秒为单位）。通常，仅 exactly-once 需要此设置；at-least-once 通常不需要设置此项（连接器默认为 300 秒）。如果未在 exactly-once 中设置，则应用 StarRocks FE 配置 `prepared_transaction_default_timeout_second`（默认为 86400 秒）。请参阅 [StarRocks 事务超时管理](./Stream_Load_transaction_interface.md#transaction-timeout-management)。 - -## Flink 和 StarRocks 之间的数据类型映射 - -| Flink 数据类型 | StarRocks 数据类型 | -|-----------------------------------|-----------------------| -| BOOLEAN | BOOLEAN | -| TINYINT | TINYINT | -| SMALLINT | SMALLINT | -| INTEGER | INTEGER | -| BIGINT | BIGINT | -| FLOAT | FLOAT | -| DOUBLE | DOUBLE | -| DECIMAL | DECIMAL | -| BINARY | INT | -| CHAR | STRING | -| VARCHAR | STRING | -| STRING | STRING | -| DATE | DATE | -| TIMESTAMP_WITHOUT_TIME_ZONE(N) | DATETIME | -| TIMESTAMP_WITH_LOCAL_TIME_ZONE(N) | DATETIME | -| ARRAY<T> | ARRAY<T> | -| MAP<KT,VT> | JSON STRING | -| ROW<arg T...> | JSON STRING | - -## 使用说明 - -### Exactly Once - -- 如果您希望 sink 保证 exactly-once 语义，我们建议您将 StarRocks 升级到 2.5 或更高版本，并将 Flink connector 升级到 1.2.4 或更高版本。 - - 自 Flink connector 1.2.4 起，exactly-once 基于 StarRocks 自 2.4 起提供的 [Stream Load 事务接口](./Stream_Load_transaction_interface.md) 重新设计。与之前基于非事务 Stream Load 接口的实现相比，新实现减少了内存使用和 checkpoint 开销，从而提高了实时性能和加载稳定性。 - - - 如果 StarRocks 的版本早于 2.4 或 Flink connector 的版本早于 1.2.4，则 sink 将自动选择基于 Stream Load 非事务接口的实现。 - -- 保证 exactly-once 的配置 - - - `sink.semantic` 的值需要为 `exactly-once`。 - - - 如果 Flink connector 的版本为 1.2.8 及更高版本，建议指定 `sink.label-prefix` 的值。请注意，标签前缀在 StarRocks 中的所有类型的加载（例如 Flink 作业、Routine Load 和 Broker Load）中必须是唯一的。 - - - 如果指定了标签前缀，Flink connector 将使用该标签前缀来清理在某些 Flink 故障场景中可能生成的长期存在的事务，例如当 checkpoint 仍在进行中时 Flink 作业失败。如果您使用 `SHOW PROC '/transactions//running';` 在 StarRocks 中查看这些长期存在的事务，它们通常处于 `PREPARED` 状态。当 Flink 作业从 checkpoint 恢复时，Flink connector 将根据标签前缀和 checkpoint 中的一些信息找到这些长期存在的事务，并中止它们。由于用于实现 exactly-once 的两阶段提交机制，Flink connector 无法在 Flink 作业退出时中止它们。当 Flink 作业退出时，Flink connector 尚未收到来自 Flink checkpoint 协调器的通知，说明是否应将事务包含在成功的 checkpoint 中，如果无论如何都中止这些事务，可能会导致数据丢失。您可以在此 [博客文章](https://flink.apache.org/2018/02/28/an-overview-of-end-to-end-exactly-once-processing-in-apache-flink-with-apache-kafka-too/) 中大致了解如何在 Flink 中实现端到端 exactly-once。 - - - 如果未指定标签前缀，则仅在长期存在的事务超时后，StarRocks 才会清理它们。但是，如果在事务超时之前 Flink 作业频繁失败，则正在运行的事务数可能会达到 StarRocks `max_running_txn_num_per_db` 的限制。您可以为 `PREPARED` 事务设置较小的超时时间，以便在未指定标签前缀时更快地过期。请参阅以下有关如何设置 prepared 超时的信息。 - -- 如果您确定 Flink 作业在因停止或持续故障转移而长时间停机后最终将从 checkpoint 或 savepoint 恢复，请相应地调整以下 StarRocks 配置，以避免数据丢失。 - - - 调整 `PREPARED` 事务超时。请参阅以下有关如何设置超时的信息。 - - 超时时间需要大于 Flink 作业的停机时间。否则，包含在成功的 checkpoint 中的长期存在的事务可能会因超时而在您重新启动 Flink 作业之前中止，从而导致数据丢失。 - - 请注意，当您为此配置设置较大的值时，最好指定 `sink.label-prefix` 的值，以便可以根据标签前缀和 checkpoint 中的一些信息清理长期存在的事务，而不是由于超时（这可能会导致数据丢失）。 - - - `label_keep_max_second` 和 `label_keep_max_num`：StarRocks FE 配置，默认值分别为 `259200` 和 `1000`。有关详细信息，请参阅 [FE 配置](./loading_introduction/loading_considerations.md#fe-configurations)。`label_keep_max_second` 的值需要大于 Flink 作业的停机时间。否则，Flink connector 无法通过使用保存在 Flink 的 savepoint 或 checkpoint 中的事务标签来检查 StarRocks 中事务的状态，并确定这些事务是否已提交，这最终可能会导致数据丢失。 - -- 如何设置 PREPARED 事务的超时时间 - - - 对于 Connector 1.2.12+ 和 StarRocks 3.5.4+，您可以通过配置连接器参数 `sink.properties.prepared_timeout` 来设置超时时间。默认情况下，该值未设置，并且会回退到 StarRocks FE 的全局配置 `prepared_transaction_default_timeout_second`（默认值为 `86400`）。 - - - 对于其他版本的 Connector 或 StarRocks，您可以通过配置 StarRocks FE 的全局配置 `prepared_transaction_default_timeout_second`（默认值为 `86400`）来设置超时时间。 - -### Flush 策略 - -Flink connector 将在内存中缓冲数据，并通过 Stream Load 将它们批量刷新到 StarRocks。在 at-least-once 和 exactly-once 之间，触发刷新的方式有所不同。 - -对于 at-least-once，当满足以下任何条件时，将触发刷新： - -- 缓冲行的字节数达到限制 `sink.buffer-flush.max-bytes` -- 缓冲行的数量达到限制 `sink.buffer-flush.max-rows`。（仅对 sink 版本 V1 有效） -- 自上次刷新以来经过的时间达到限制 `sink.buffer-flush.interval-ms` -- 触发 checkpoint - -对于 exactly-once，仅当触发 checkpoint 时才会发生刷新。 - -### 监控导入指标 - -Flink connector 提供了以下指标来监控导入。 - -| 指标 | 类型 | 描述 | -|--------------------------|---------|------------------------------------------------------------| -| totalFlushBytes | counter | 成功刷新的字节数。 | -| totalFlushRows | counter | 成功刷新的行数。 | -| totalFlushSucceededTimes | counter | 成功刷新数据的次数。 | -| totalFlushFailedTimes | counter | 数据刷新失败的次数。 | -| totalFilteredRows | counter | 过滤的行数，也包含在 totalFlushRows 中。 | - -## 示例 - -以下示例展示了如何使用 Flink connector 通过 Flink SQL 或 Flink DataStream 将数据加载到 StarRocks 表中。 - -### 准备工作 - -#### 创建 StarRocks 表 - -创建一个数据库 `test` 并创建一个主键表 `score_board`。 - -```sql -CREATE DATABASE `test`; - -CREATE TABLE `test`.`score_board` -( - `id` int(11) NOT NULL COMMENT "", - `name` varchar(65533) NULL DEFAULT "" COMMENT "", - `score` int(11) NOT NULL DEFAULT "0" COMMENT "" -) -ENGINE=OLAP -PRIMARY KEY(`id`) -COMMENT "OLAP" -DISTRIBUTED BY HASH(`id`); -``` - -#### 设置 Flink 环境 - -- 下载 Flink 二进制文件 [Flink 1.15.2](https://archive.apache.org/dist/flink/flink-1.15.2/flink-1.15.2-bin-scala_2.12.tgz)，并将其解压缩到目录 `flink-1.15.2`。 -- 下载 [Flink connector 1.2.7](https://repo1.maven.org/maven2/com/starrocks/flink-connector-starrocks/1.2.7_flink-1.15/flink-connector-starrocks-1.2.7_flink-1.15.jar)，并将其放入目录 `flink-1.15.2/lib`。 -- 运行以下命令以启动 Flink 集群： - - ```shell - cd flink-1.15.2 - ./bin/start-cluster.sh - ``` - -#### 网络配置 - -确保 Flink 所在的机器可以通过 [`http_port`](../administration/management/FE_configuration.md#http_port)（默认：`8030`）和 [`query_port`](../administration/management/FE_configuration.md#query_port)（默认：`9030`）访问 StarRocks 集群的 FE 节点，并通过 [`be_http_port`](../administration/management/BE_configuration.md#be_http_port)（默认：`8040`）访问 BE 节点。 - -### 使用 Flink SQL 运行 - -- 运行以下命令以启动 Flink SQL 客户端。 - - ```shell - ./bin/sql-client.sh - ``` - -- 创建一个 Flink 表 `score_board`，并通过 Flink SQL 客户端将值插入到该表中。请注意，如果要将数据加载到 StarRocks 的主键表中，则必须在 Flink DDL 中定义主键。对于其他类型的 StarRocks 表，这是可选的。 - - ```SQL - CREATE TABLE `score_board` ( - `id` INT, - `name` STRING, - `score` INT, - PRIMARY KEY (id) NOT ENFORCED - ) WITH ( - 'connector' = 'starrocks', - 'jdbc-url' = 'jdbc:mysql://127.0.0.1:9030', - 'load-url' = '127.0.0.1:8030', - 'database-name' = 'test', - - 'table-name' = 'score_board', - 'username' = 'root', - 'password' = '' - ); - - INSERT INTO `score_board` VALUES (1, 'starrocks', 100), (2, 'flink', 100); - ``` - -### 使用 Flink DataStream 运行 - -根据输入记录的类型（例如 CSV Java `String`、JSON Java `String` 或自定义 Java 对象），有几种方法可以实现 Flink DataStream 作业。 - -- 输入记录是 CSV 格式的 `String`。有关完整示例，请参阅 [LoadCsvRecords](https://github.com/StarRocks/starrocks-connector-for-apache-flink/tree/cd8086cfedc64d5181785bdf5e89a847dc294c1d/examples/src/main/java/com/starrocks/connector/flink/examples/datastream)。 - - ```java - /** - * Generate CSV-format records. Each record has three values separated by "\t". - * These values will be loaded to the columns `id`, `name`, and `score` in the StarRocks table. - */ - String[] records = new String[]{ - "1\tstarrocks-csv\t100", - "2\tflink-csv\t100" - }; - DataStream source = env.fromElements(records); - - /** - * Configure the connector with the required properties. - * You also need to add properties "sink.properties.format" and "sink.properties.column_separator" - * to tell the connector the input records are CSV-format, and the column separator is "\t". - * You can also use other column separators in the CSV-format records, - * but remember to modify the "sink.properties.column_separator" correspondingly. - */ - StarRocksSinkOptions options = StarRocksSinkOptions.builder() - .withProperty("jdbc-url", jdbcUrl) - .withProperty("load-url", loadUrl) - .withProperty("database-name", "test") - .withProperty("table-name", "score_board") - .withProperty("username", "root") - .withProperty("password", "") - .withProperty("sink.properties.format", "csv") - .withProperty("sink.properties.column_separator", "\t") - .build(); - // Create the sink with the options. - SinkFunction starRockSink = StarRocksSink.sink(options); - source.addSink(starRockSink); - ``` - -- 输入记录是 JSON 格式的 `String`。有关完整示例，请参阅 [LoadJsonRecords](https://github.com/StarRocks/starrocks-connector-for-apache-flink/tree/cd8086cfedc64d5181785bdf5e89a847dc294c1d/examples/src/main/java/com/starrocks/connector/flink/examples/datastream)。 - - ```java - /** - * Generate JSON-format records. - * Each record has three key-value pairs corresponding to the columns `id`, `name`, and `score` in the StarRocks table. - */ - String[] records = new String[]{ - "{\"id\":1, \"name\":\"starrocks-json\", \"score\":100}", - "{\"id\":2, \"name\":\"flink-json\", \"score\":100}", - }; - DataStream source = env.fromElements(records); - - /** - * Configure the connector with the required properties. - * You also need to add properties "sink.properties.format" and "sink.properties.strip_outer_array" - * to tell the connector the input records are JSON-format and to strip the outermost array structure. - */ - StarRocksSinkOptions options = StarRocksSinkOptions.builder() - .withProperty("jdbc-url", jdbcUrl) - .withProperty("load-url", loadUrl) - .withProperty("database-name", "test") - .withProperty("table-name", "score_board") - .withProperty("username", "root") - .withProperty("password", "") - .withProperty("sink.properties.format", "json") - .withProperty("sink.properties.strip_outer_array", "true") - .build(); - // Create the sink with the options. - SinkFunction starRockSink = StarRocksSink.sink(options); - source.addSink(starRockSink); - ``` - -- 输入记录是自定义 Java 对象。有关完整示例，请参阅 [LoadCustomJavaRecords](https://github.com/StarRocks/starrocks-connector-for-apache-flink/tree/cd8086cfedc64d5181785bdf5e89a847dc294c1d/examples/src/main/java/com/starrocks/connector/flink/examples/datastream)。 - - - 在此示例中，输入记录是一个简单的 POJO `RowData`。 - - ```java - public static class RowData { - public int id; - public String name; - public int score; - - public RowData() {} - - public RowData(int id, String name, int score) { - this.id = id; - this.name = name; - this.score = score; - } - } - ``` - - - 主程序如下： - - ```java - // Generate records which use RowData as the container. - RowData[] records = new RowData[]{ - new RowData(1, "starrocks-rowdata", 100), - new RowData(2, "flink-rowdata", 100), - }; - DataStream source = env.fromElements(records); - - // Configure the connector with the required properties. - StarRocksSinkOptions options = StarRocksSinkOptions.builder() - .withProperty("jdbc-url", jdbcUrl) - .withProperty("load-url", loadUrl) - .withProperty("database-name", "test") - .withProperty("table-name", "score_board") - .withProperty("username", "root") - .withProperty("password", "") - .build(); - - /** - * The Flink connector will use a Java object array (Object[]) to represent a row to be loaded into the StarRocks table, - * and each element is the value for a column. - * You need to define the schema of the Object[] which matches that of the StarRocks table. - */ - TableSchema schema = TableSchema.builder() - .field("id", DataTypes.INT().notNull()) - .field("name", DataTypes.STRING()) - .field("score", DataTypes.INT()) - // When the StarRocks table is a Primary Key table, you must specify notNull(), for example, DataTypes.INT().notNull(), for the primary key `id`. - .primaryKey("id") - .build(); - // Transform the RowData to the Object[] according to the schema. - RowDataTransformer transformer = new RowDataTransformer(); - // Create the sink with the schema, options, and transformer. - SinkFunction starRockSink = StarRocksSink.sink(schema, options, transformer); - source.addSink(starRockSink); - ``` - - - 主程序中的 `RowDataTransformer` 定义如下： - - ```java - private static class RowDataTransformer implements StarRocksSinkRowBuilder { - - /** - * Set each element of the object array according to the input RowData. - * The schema of the array matches that of the StarRocks table. - */ - @Override - public void accept(Object[] internalRow, RowData rowData) { - internalRow[0] = rowData.id; - internalRow[1] = rowData.name; - internalRow[2] = rowData.score; - // When the StarRocks table is a Primary Key table, you need to set the last element to indicate whether \ No newline at end of file diff --git a/docs/zh/loading/Flink_cdc_load.md b/docs/zh/loading/Flink_cdc_load.md deleted file mode 100644 index ced3f4f..0000000 --- a/docs/zh/loading/Flink_cdc_load.md +++ /dev/null @@ -1,532 +0,0 @@ ---- -displayed_sidebar: docs -keywords: - - MySql - - mysql - - sync - - Flink CDC ---- - -# 从 MySQL 实时同步 - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -StarRocks 支持多种方法将数据从 MySQL 实时同步到 StarRocks，从而实现海量数据的低延迟实时分析。 - -本主题介绍如何通过 Apache Flink® 将数据从 MySQL 实时同步到 StarRocks（在几秒钟内）。 - - - -## 原理 - -:::tip - -Flink CDC 用于从 MySQL 到 Flink 的同步。本主题使用版本低于 3.0 的 Flink CDC，因此使用 SMT 来同步表结构。但是，如果使用 Flink CDC 3.0，则无需使用 SMT 将表结构同步到 StarRocks。Flink CDC 3.0 甚至可以同步整个 MySQL 数据库的 schema、分片数据库和表，并且还支持 schema 变更同步。有关详细用法，请参见 [Streaming ELT from MySQL to StarRocks](https://nightlies.apache.org/flink/flink-cdc-docs-stable/docs/get-started/quickstart/mysql-to-starrocks)。 - -::: - -下图说明了整个同步过程。 - -![img](../_assets/4.9.2.png) - -通过 Flink 将 MySQL 实时同步到 StarRocks 分为两个阶段实现：同步数据库和表结构以及同步数据。首先，SMT 将 MySQL 数据库和表结构转换为 StarRocks 的表创建语句。然后，Flink 集群运行 Flink 作业，将 MySQL 的完整数据和增量数据同步到 StarRocks。 - -:::info - -同步过程保证了 exactly-once 语义。 - -::: - -**同步过程**： - -1. 同步数据库和表结构。 - - SMT 读取要同步的 MySQL 数据库和表的 schema，并生成用于在 StarRocks 中创建目标数据库和表的 SQL 文件。此操作基于 SMT 配置文件中的 MySQL 和 StarRocks 信息。 - -2. 同步数据。 - - a. Flink SQL 客户端执行数据导入语句 `INSERT INTO SELECT`，以将一个或多个 Flink 作业提交到 Flink 集群。 - - b. Flink 集群运行 Flink 作业以获取数据。Flink CDC 连接器首先从源数据库读取完整的历史数据，然后无缝切换到增量读取，并将数据发送到 flink-connector-starrocks。 - - c. flink-connector-starrocks 在 mini-batch 中累积数据，并将每批数据同步到 StarRocks。 - - :::info - - 只有 MySQL 中的数据操作语言 (DML) 操作可以同步到 StarRocks。数据定义语言 (DDL) 操作无法同步。 - - ::: - -## 适用场景 - -从 MySQL 实时同步具有广泛的用例，其中数据不断变化。以“商品销售实时排名”的实际用例为例。 - -Flink 基于 MySQL 中原始订单表计算商品销售的实时排名，并将排名实时同步到 StarRocks 的主键表。用户可以将可视化工具连接到 StarRocks，以实时查看排名，从而获得按需运营洞察。 - -## 前提条件 - -### 下载并安装同步工具 - -要从 MySQL 同步数据，您需要安装以下工具：SMT、Flink、Flink CDC 连接器和 flink-connector-starrocks。 - -1. 下载并安装 Flink，然后启动 Flink 集群。您也可以按照 [Flink 官方文档](https://nightlies.apache.org/flink/flink-docs-release-1.13/docs/try-flink/local_installation/) 中的说明执行此步骤。 - - a. 在运行 Flink 之前，请在操作系统中安装 Java 8 或 Java 11。您可以运行以下命令来检查已安装的 Java 版本。 - - ```Bash - # 查看 Java 版本。 - java -version - - # 如果返回以下输出，则表示已安装 Java 8。 - java version "1.8.0_301" - Java(TM) SE Runtime Environment (build 1.8.0_301-b09) - Java HotSpot(TM) 64-Bit Server VM (build 25.301-b09, mixed mode) - ``` - - b. 下载 [Flink 安装包](https://flink.apache.org/downloads.html) 并解压缩。建议您使用 Flink 1.14 或更高版本。允许的最低版本为 Flink 1.11。本主题使用 Flink 1.14.5。 - - ```Bash - # 下载 Flink。 - wget https://archive.apache.org/dist/flink/flink-1.14.5/flink-1.14.5-bin-scala_2.11.tgz - # 解压缩 Flink。 - tar -xzf flink-1.14.5-bin-scala_2.11.tgz - # 进入 Flink 目录。 - cd flink-1.14.5 - ``` - - c. 启动 Flink 集群。 - - ```Bash - # 启动 Flink 集群。 - ./bin/start-cluster.sh - - # 如果返回以下输出，则表示已启动 Flink 集群。 - Starting cluster. - Starting standalonesession daemon on host. - Starting taskexecutor daemon on host. - ``` - -2. 下载 [Flink CDC connector](https://github.com/ververica/flink-cdc-connectors/releases)。本主题使用 MySQL 作为数据源，因此下载 `flink-sql-connector-mysql-cdc-x.x.x.jar`。连接器版本必须与 [Flink](https://github.com/ververica/flink-cdc-connectors/releases) 版本匹配。本主题使用 Flink 1.14.5，您可以下载 `flink-sql-connector-mysql-cdc-2.2.0.jar`。 - - ```Bash - wget https://repo1.maven.org/maven2/com/ververica/flink-sql-connector-mysql-cdc/2.1.1/flink-sql-connector-mysql-cdc-2.2.0.jar - ``` - -3. 下载 [flink-connector-starrocks](https://search.maven.org/artifact/com.starrocks/flink-connector-starrocks)。该版本必须与 Flink 版本匹配。 - - > flink-connector-starrocks 包 `x.x.x_flink-y.yy _ z.zz.jar` 包含三个版本号： - > - > - `x.x.x` 是 flink-connector-starrocks 的版本号。 - > - `y.yy` 是支持的 Flink 版本。 - > - `z.zz` 是 Flink 支持的 Scala 版本。如果 Flink 版本为 1.14.x 或更早版本，则必须下载具有 Scala 版本的包。 - > - > 本主题使用 Flink 1.14.5 和 Scala 2.11。因此，您可以下载以下包：`1.2.3_flink-14_2.11.jar`。 - -4. 将 Flink CDC 连接器 (`flink-sql-connector-mysql-cdc-2.2.0.jar`) 和 flink-connector-starrocks (`1.2.3_flink-1.14_2.11.jar`) 的 JAR 包移动到 Flink 的 `lib` 目录。 - - > **注意** - > - > 如果您的系统中已在运行 Flink 集群，则必须停止 Flink 集群并重新启动它才能加载和验证 JAR 包。 - > - > ```Bash - > $ ./bin/stop-cluster.sh - > $ ./bin/start-cluster.sh - > ``` - -5. 下载并解压缩 [SMT 包](https://www.starrocks.io/download/community)，并将其放置在 `flink-1.14.5` 目录中。StarRocks 提供适用于 Linux x86 和 macos ARM64 的 SMT 包。您可以根据您的操作系统和 CPU 选择一个。 - - ```Bash - # for Linux x86 - wget https://releases.starrocks.io/resources/smt.tar.gz - # for macOS ARM64 - wget https://releases.starrocks.io/resources/smt_darwin_arm64.tar.gz - ``` - -### 启用 MySQL 二进制日志 - -要从 MySQL 实时同步数据，系统需要从 MySQL 二进制日志 (binlog) 中读取数据，解析数据，然后将数据同步到 StarRocks。确保已启用 MySQL 二进制日志。 - -1. 编辑 MySQL 配置文件 `my.cnf`（默认路径：`/etc/my.cnf`）以启用 MySQL 二进制日志。 - - ```Bash - # 启用 MySQL Binlog。 - log_bin = ON - # 配置 Binlog 的保存路径。 - log_bin =/var/lib/mysql/mysql-bin - # 配置 server_id。 - # 如果未为 MySQL 5.7.3 或更高版本配置 server_id，则无法使用 MySQL 服务。 - server_id = 1 - # 将 Binlog 格式设置为 ROW。 - binlog_format = ROW - # Binlog 文件的基本名称。附加一个标识符以标识每个 Binlog 文件。 - log_bin_basename =/var/lib/mysql/mysql-bin - # Binlog 文件的索引文件，用于管理所有 Binlog 文件的目录。 - log_bin_index =/var/lib/mysql/mysql-bin.index - ``` - -2. 运行以下命令之一以重新启动 MySQL，以使修改后的配置文件生效。 - - ```Bash - # 使用 service 重新启动 MySQL。 - service mysqld restart - # 使用 mysqld 脚本重新启动 MySQL。 - /etc/init.d/mysqld restart - ``` - -3. 连接到 MySQL 并检查是否已启用 MySQL 二进制日志。 - - ```Plain - -- 连接到 MySQL。 - mysql -h xxx.xx.xxx.xx -P 3306 -u root -pxxxxxx - - -- 检查是否已启用 MySQL 二进制日志。 - mysql> SHOW VARIABLES LIKE 'log_bin'; - +---------------+-------+ - | Variable_name | Value | - +---------------+-------+ - | log_bin | ON | - +---------------+-------+ - 1 row in set (0.00 sec) - ``` - -## 同步数据库和表结构 - -1. 编辑 SMT 配置文件。 - 转到 SMT `conf` 目录并编辑配置文件 `config_prod.conf`，例如 MySQL 连接信息、要同步的数据库和表的匹配规则以及 flink-connector-starrocks 的配置信息。 - - ```Bash - [db] - type = mysql - host = xxx.xx.xxx.xx - port = 3306 - user = user1 - password = xxxxxx - - [other] - # StarRocks 中 BE 的数量 - be_num = 3 - # StarRocks-1.18.1 及更高版本支持 `decimal_v3`。 - use_decimal_v3 = true - # 用于保存转换后的 DDL SQL 的文件 - output_dir = ./result - - [table-rule.1] - # 用于匹配数据库以设置属性的模式 - database = ^demo.*$ - # 用于匹配表以设置属性的模式 - table = ^.*$ - - ############################################ - ### Flink sink configurations - ### DO NOT set `connector`, `table-name`, `database-name`. They are auto-generated. - ############################################ - flink.starrocks.jdbc-url=jdbc:mysql://: - flink.starrocks.load-url= : - flink.starrocks.username=user2 - flink.starrocks.password=xxxxxx - flink.starrocks.sink.properties.format=csv - flink.starrocks.sink.properties.column_separator=\x01 - flink.starrocks.sink.properties.row_delimiter=\x02 - flink.starrocks.sink.buffer-flush.interval-ms=15000 - ``` - - - `[db]`: 用于访问源数据库的信息。 - - `type`: 源数据库的类型。在本主题中，源数据库为 `mysql`。 - - `host`: MySQL 服务器的 IP 地址。 - - `port`: MySQL 数据库的端口号，默认为 `3306` - - `user`: 用于访问 MySQL 数据库的用户名 - - `password`: 用户名的密码 - - - `[table-rule]`: 数据库和表匹配规则以及相应的 flink-connector-starrocks 配置。 - - - `Database`、`table`: MySQL 中数据库和表的名称。支持正则表达式。 - - `flink.starrocks.*`: flink-connector-starrocks 的配置信息。有关更多配置和信息，请参见 [flink-connector-starrocks](../loading/Flink-connector-starrocks.md)。 - - > 如果您需要为不同的表使用不同的 flink-connector-starrocks 配置。例如，如果某些表经常更新，并且您需要加速数据导入，请参见 [为不同的表使用不同的 flink-connector-starrocks 配置](#use-different-flink-connector-starrocks-configurations-for-different-tables)。如果您需要将从 MySQL 分片获得的多个表加载到同一个 StarRocks 表中，请参见 [将 MySQL 分片后的多个表同步到一个 StarRocks 表中](#synchronize-multiple-tables-after-mysql-sharding-to-one-table-in-starrocks)。 - - - `[other]`: 其他信息 - - `be_num`: StarRocks 集群中 BE 的数量（此参数将用于在后续 StarRocks 表创建中设置合理的 tablet 数量）。 - - `use_decimal_v3`: 是否启用 [Decimal V3](../sql-reference/data-types/numeric/DECIMAL.md)。启用 Decimal V3 后，将数据同步到 StarRocks 时，MySQL decimal 数据将转换为 Decimal V3 数据。 - - `output_dir`: 用于保存要生成的 SQL 文件的路径。SQL 文件将用于在 StarRocks 中创建数据库和表，并将 Flink 作业提交到 Flink 集群。默认路径为 `./result`，建议您保留默认设置。 - -2. 运行 SMT 以读取 MySQL 中的数据库和表结构，并根据配置文件在 `./result` 目录中生成 SQL 文件。`starrocks-create.all.sql` 文件用于在 StarRocks 中创建数据库和表，`flink-create.all.sql` 文件用于将 Flink 作业提交到 Flink 集群。 - - ```Bash - # 运行 SMT。 - ./starrocks-migrate-tool - - # 转到 result 目录并检查此目录中的文件。 - cd result - ls result - flink-create.1.sql smt.tar.gz starrocks-create.all.sql - flink-create.all.sql starrocks-create.1.sql - ``` - -3. 运行以下命令以连接到 StarRocks 并执行 `starrocks-create.all.sql` 文件，以在 StarRocks 中创建数据库和表。建议您使用 SQL 文件中的默认表创建语句来创建 [主键表](../table_design/table_types/primary_key_table.md)。 - - > **注意** - > - > 您还可以根据您的业务需求修改表创建语句，并创建一个不使用主键表的表。但是，源 MySQL 数据库中的 DELETE 操作无法同步到非主键表。创建此类表时请谨慎。 - - ```Bash - mysql -h -P -u user2 -pxxxxxx < starrocks-create.all.sql - ``` - - 如果数据需要在写入目标 StarRocks 表之前由 Flink 处理，则源表和目标表之间的表结构将不同。在这种情况下，您必须修改表创建语句。在此示例中，目标表仅需要 `product_id` 和 `product_name` 列以及商品销售的实时排名。您可以使用以下表创建语句。 - - ```Bash - CREATE DATABASE IF NOT EXISTS `demo`; - - CREATE TABLE IF NOT EXISTS `demo`.`orders` ( - `product_id` INT(11) NOT NULL COMMENT "", - `product_name` STRING NOT NULL COMMENT "", - `sales_cnt` BIGINT NOT NULL COMMENT "" - ) ENGINE=olap - PRIMARY KEY(`product_id`) - DISTRIBUTED BY HASH(`product_id`) - PROPERTIES ( - "replication_num" = "3" - ); - ``` - - > **注意** - > - > 从 v2.5.7 开始，StarRocks 可以在您创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - -## 同步数据 - -运行 Flink 集群并提交 Flink 作业，以将 MySQL 中的完整数据和增量数据持续同步到 StarRocks。 - -1. 转到 Flink 目录并运行以下命令，以在 Flink SQL 客户端上运行 `flink-create.all.sql` 文件。 - - ```Bash - ./bin/sql-client.sh -f flink-create.all.sql - ``` - - 此 SQL 文件定义了动态表 `source table` 和 `sink table`、查询语句 `INSERT INTO SELECT`，并指定了连接器、源数据库和目标数据库。执行此文件后，会将 Flink 作业提交到 Flink 集群以启动数据同步。 - - > **注意** - > - > - 确保已启动 Flink 集群。您可以通过运行 `flink/bin/start-cluster.sh` 来启动 Flink 集群。 - > - 如果您的 Flink 版本早于 1.13，您可能无法直接运行 SQL 文件 `flink-create.all.sql`。您需要在 SQL 客户端的命令行界面 (CLI) 中逐个执行此文件中的 SQL 语句。您还需要转义 `\` 字符。 - > - > ```Bash - > 'sink.properties.column_separator' = '\\x01' - > 'sink.properties.row_delimiter' = '\\x02' - > ``` - - **在同步期间处理数据**： - - 如果您需要在同步期间处理数据，例如对数据执行 GROUP BY 或 JOIN，您可以修改 `flink-create.all.sql` 文件。以下示例通过执行 COUNT (*) 和 GROUP BY 来计算商品销售的实时排名。 - - ```Bash - $ ./bin/sql-client.sh -f flink-create.all.sql - No default environment is specified. - Searching for '/home/disk1/flink-1.13.6/conf/sql-client-defaults.yaml'...not found. - [INFO] Executing SQL from file. - - Flink SQL> CREATE DATABASE IF NOT EXISTS `default_catalog`.`demo`; - [INFO] Execute statement succeed. - - -- 基于 MySQL 中的 order 表创建一个动态表 `source table`。 - Flink SQL> - CREATE TABLE IF NOT EXISTS `default_catalog`.`demo`.`orders_src` (`order_id` BIGINT NOT NULL, - `product_id` INT NULL, - `order_date` TIMESTAMP NOT NULL, - `customer_name` STRING NOT NULL, - `product_name` STRING NOT NULL, - `price` DECIMAL(10, 5) NULL, - PRIMARY KEY(`order_id`) - NOT ENFORCED - ) with ('connector' = 'mysql-cdc', - 'hostname' = 'xxx.xx.xxx.xxx', - 'port' = '3306', - 'username' = 'root', - 'password' = '', - 'database-name' = 'demo', - 'table-name' = 'orders' - ); - [INFO] Execute statement succeed. - - -- 创建一个动态表 `sink table`。 - Flink SQL> - CREATE TABLE IF NOT EXISTS `default_catalog`.`demo`.`orders_sink` (`product_id` INT NOT NULL, - `product_name` STRING NOT NULL, - `sales_cnt` BIGINT NOT NULL, - PRIMARY KEY(`product_id`) - NOT ENFORCED - ) with ('sink.max-retries' = '10', - 'jdbc-url' = 'jdbc:mysql://:', - 'password' = '', - 'sink.properties.strip_outer_array' = 'true', - 'sink.properties.format' = 'json', - 'load-url' = ':', - 'username' = 'root', - 'sink.buffer-flush.interval-ms' = '15000', - 'connector' = 'starrocks', - 'database-name' = 'demo', - 'table-name' = 'orders' - ); - [INFO] Execute statement succeed. - - -- 实现商品销售的实时排名，其中 `sink table` 动态更新以反映 `source table` 中的数据更改。 - Flink SQL> - INSERT INTO `default_catalog`.`demo`.`orders_sink` select product_id,product_name, count(*) as cnt from `default_catalog`.`demo`.`orders_src` group by product_id,product_name; - [INFO] Submitting SQL update statement to the cluster... - [INFO] SQL update statement has been successfully submitted to the cluster: - Job ID: 5ae005c4b3425d8bb13fe660260a35da - ``` - - 如果您只需要同步一部分数据，例如付款时间晚于 2021 年 12 月 21 日的数据，您可以使用 `INSERT INTO SELECT` 中的 `WHERE` 子句来设置筛选条件，例如 `WHERE pay_dt > '2021-12-21'`。不满足此条件的数据将不会同步到 StarRocks。 - - 如果返回以下结果，则表示已提交 Flink 作业以进行完整和增量同步。 - - ```SQL - [INFO] Submitting SQL update statement to the cluster... - [INFO] SQL update statement has been successfully submitted to the cluster: - Job ID: 5ae005c4b3425d8bb13fe660260a35da - ``` - -2. 您可以使用 [Flink WebUI](https://nightlies.apache.org/flink/flink-docs-master/docs/try-flink/flink-operations-playground/#flink-webui) 或在 Flink SQL 客户端上运行 `bin/flink list -running` 命令，以查看 Flink 集群中正在运行的 Flink 作业和作业 ID。 - - - Flink WebUI - ![img](../_assets/4.9.3.png) - - - `bin/flink list -running` - - ```Bash - $ bin/flink list -running - Waiting for response... - ------------------ Running/Restarting Jobs ------------------- - 13.10.2022 15:03:54 : 040a846f8b58e82eb99c8663424294d5 : insert-into_default_catalog.lily.example_tbl1_sink (RUNNING) - -------------------------------------------------------------- - ``` - - > **注意** - > - > 如果作业异常，您可以使用 Flink WebUI 或通过查看 Flink 1.14.5 的 `/log` 目录中的日志文件来执行故障排除。 - -## 常见问题 - -### 为不同的表使用不同的 flink-connector-starrocks 配置 - -如果数据源中的某些表经常更新，并且您想要加速 flink-connector-starrocks 的加载速度，则必须在 SMT 配置文件 `config_prod.conf` 中为每个表设置单独的 flink-connector-starrocks 配置。 - -```Bash -[table-rule.1] -# 用于匹配数据库以设置属性的模式 -database = ^order.*$ -# 用于匹配表以设置属性的模式 -table = ^.*$ - -############################################ -### Flink sink configurations -### DO NOT set `connector`, `table-name`, `database-name`. They are auto-generated -############################################ -flink.starrocks.jdbc-url=jdbc:mysql://: -flink.starrocks.load-url= : -flink.starrocks.username=user2 -flink.starrocks.password=xxxxxx -flink.starrocks.sink.properties.format=csv -flink.starrocks.sink.properties.column_separator=\x01 -flink.starrocks.sink.properties.row_delimiter=\x02 -flink.starrocks.sink.buffer-flush.interval-ms=15000 - -[table-rule.2] -# 用于匹配数据库以设置属性的模式 -database = ^order2.*$ -# 用于匹配表以设置属性的模式 -table = ^.*$ - -############################################ -### Flink sink configurations -### DO NOT set `connector`, `table-name`, `database-name`. They are auto-generated -############################################ -flink.starrocks.jdbc-url=jdbc:mysql://: -flink.starrocks.load-url= : -flink.starrocks.username=user2 -flink.starrocks.password=xxxxxx -flink.starrocks.sink.properties.format=csv -flink.starrocks.sink.properties.column_separator=\x01 -flink.starrocks.sink.properties.row_delimiter=\x02 -flink.starrocks.sink.buffer-flush.interval-ms=10000 -``` - -### 将 MySQL 分片后的多个表同步到一个 StarRocks 表中 - -执行分片后，一个 MySQL 表中的数据可能会拆分为多个表，甚至分布到多个数据库中。所有表都具有相同的 schema。在这种情况下，您可以设置 `[table-rule]` 以将这些表同步到一个 StarRocks 表中。例如，MySQL 有两个数据库 `edu_db_1` 和 `edu_db_2`，每个数据库都有两个表 `course_1 和 course_2`，并且所有表的 schema 都相同。您可以使用以下 `[table-rule]` 配置将所有表同步到一个 StarRocks 表中。 - -> **注意** -> -> StarRocks 表的名称默认为 `course__auto_shard`。如果您需要使用其他名称，您可以在 SQL 文件 `starrocks-create.all.sql` 和 `flink-create.all.sql` 中修改它。 - -```Bash -[table-rule.1] -# 用于匹配数据库以设置属性的模式 -database = ^edu_db_[0-9]*$ -# 用于匹配表以设置属性的模式 -table = ^course_[0-9]*$ - -############################################ -### Flink sink configurations -### DO NOT set `connector`, `table-name`, `database-name`. They are auto-generated -############################################ -flink.starrocks.jdbc-url = jdbc: mysql://xxx.xxx.x.x:xxxx -flink.starrocks.load-url = xxx.xxx.x.x:xxxx -flink.starrocks.username = user2 -flink.starrocks.password = xxxxxx -flink.starrocks.sink.properties.format=csv -flink.starrocks.sink.properties.column_separator =\x01 -flink.starrocks.sink.properties.row_delimiter =\x02 -flink.starrocks.sink.buffer-flush.interval-ms = 5000 -``` - -### 导入 JSON 格式的数据 - -在前面的示例中，数据以 CSV 格式导入。如果您无法选择合适的分隔符，则需要替换 `[table-rule]` 中 `flink.starrocks.*` 的以下参数。 - -```Plain -flink.starrocks.sink.properties.format=csv -flink.starrocks.sink.properties.column_separator =\x01 -flink.starrocks.sink.properties.row_delimiter =\x02 -``` - -传入以下参数后，将以 JSON 格式导入数据。 - -```Plain -flink.starrocks.sink.properties.format=json -flink.starrocks.sink.properties.strip_outer_array=true -``` - -> **注意** -> -> 此方法会稍微降低加载速度。 - -### 将多个 INSERT INTO 语句作为一个 Flink 作业执行 - -您可以使用 `flink-create.all.sql` 文件中的 [STATEMENT SET](https://nightlies.apache.org/flink/flink-docs-master/docs/dev/table/sqlclient/#execute-a-set-of-sql-statements) 语法将多个 INSERT INTO 语句作为一个 Flink 作业执行，这可以防止多个语句占用过多的 Flink 作业资源，并提高执行多个查询的效率。 - -> **注意** -> -> Flink 从 1.13 开始支持 STATEMENT SET 语法。 - -1. 打开 `result/flink-create.all.sql` 文件。 - -2. 修改文件中的 SQL 语句。将所有 INSERT INTO 语句移动到文件末尾。将 `EXECUTE STATEMENT SET BEGIN` 放在第一个 INSERT INTO 语句之前，并将 `END;` 放在最后一个 INSERT INTO 语句之后。 - -> **注意** -> -> CREATE DATABASE 和 CREATE TABLE 的位置保持不变。 - -```SQL -CREATE DATABASE IF NOT EXISTS db; -CREATE TABLE IF NOT EXISTS db.a1; -CREATE TABLE IF NOT EXISTS db.b1; -CREATE TABLE IF NOT EXISTS db.a2; -CREATE TABLE IF NOT EXISTS db.b2; -EXECUTE STATEMENT SET -BEGIN-- one or more INSERT INTO statements -INSERT INTO db.a1 SELECT * FROM db.b1; -INSERT INTO db.a2 SELECT * FROM db.b2; -END; -``` \ No newline at end of file diff --git a/docs/zh/loading/InsertInto.md b/docs/zh/loading/InsertInto.md deleted file mode 100644 index a50ae35..0000000 --- a/docs/zh/loading/InsertInto.md +++ /dev/null @@ -1,642 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 使用 INSERT 导入数据 - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -本主题介绍如何使用 SQL 语句 INSERT 将数据导入到 StarRocks 中。 - -与 MySQL 和许多其他数据库管理系统类似，StarRocks 支持使用 INSERT 将数据导入到内表。您可以使用 VALUES 子句直接插入一行或多行，以测试函数或 DEMO。您还可以通过查询将数据从 [外部表](../data_source/External_table.md) 导入到内表。从 StarRocks v3.1 开始，您可以使用 INSERT 命令和表函数 [FILES()](../sql-reference/sql-functions/table-functions/files.md) 直接从云存储上的文件导入数据。 - -StarRocks v2.4 进一步支持使用 INSERT OVERWRITE 将数据覆盖到表中。INSERT OVERWRITE 语句集成了以下操作来实现覆盖功能： - -1. 根据存储原始数据的分区创建临时分区。 -2. 将数据插入到临时分区中。 -3. 将原始分区与临时分区交换。 - -> **NOTE** -> -> 如果您需要在覆盖数据之前验证数据，可以使用上述步骤覆盖数据，并在交换分区之前对其进行验证，而不是使用 INSERT OVERWRITE。 - -从 v3.4.0 开始，StarRocks 支持一种新的语义 - 用于分区表的 INSERT OVERWRITE 的动态覆盖。有关更多信息，请参见 [动态覆盖](#dynamic-overwrite)。 - -## 注意事项 - -- 您只能通过在 MySQL 客户端中按 **Ctrl** 和 **C** 键来取消同步 INSERT 事务。 -- 您可以使用 [SUBMIT TASK](../sql-reference/sql-statements/loading_unloading/ETL/SUBMIT_TASK.md) 提交异步 INSERT 任务。 -- 对于当前版本的 StarRocks，如果任何行的数据不符合表的 schema，则默认情况下 INSERT 事务将失败。例如，如果任何行中的字段长度超过表中映射字段的长度限制，则 INSERT 事务将失败。您可以将会话变量 `enable_insert_strict` 设置为 `false`，以允许事务通过过滤掉与表不匹配的行来继续执行。 -- 如果您频繁执行 INSERT 语句以将小批量数据导入到 StarRocks 中，则会生成过多的数据版本，严重影响查询性能。我们建议您在生产环境中不要过于频繁地使用 INSERT 命令导入数据，也不要将其用作日常数据导入的例程。如果您的应用程序或分析场景需要单独加载流式数据或小批量数据的解决方案，我们建议您使用 Apache Kafka® 作为数据源，并通过 Routine Load 导入数据。 -- 如果您执行 INSERT OVERWRITE 语句，StarRocks 会为存储原始数据的分区创建临时分区，将新数据插入到临时分区中，并将 [原始分区与临时分区交换](../sql-reference/sql-statements/table_bucket_part_index/ALTER_TABLE.md#use-a-temporary-partition-to-replace-the-current-partition)。所有这些操作都在 FE Leader 节点中执行。因此，如果在执行 INSERT OVERWRITE 命令时 FE Leader 节点崩溃，则整个导入事务将失败，并且临时分区将被截断。 - -## 准备工作 - -### 检查权限 - - - -### 创建对象 - -创建一个名为 `load_test` 的数据库，并创建一个表 `insert_wiki_edit` 作为目标表，并创建一个表 `source_wiki_edit` 作为源表。 - -> **NOTE** -> -> 本主题中演示的示例基于表 `insert_wiki_edit` 和表 `source_wiki_edit`。如果您喜欢使用自己的表和数据，则可以跳过准备工作并继续执行下一步。 - -```SQL -CREATE DATABASE IF NOT EXISTS load_test; -USE load_test; -CREATE TABLE insert_wiki_edit -( - event_time DATETIME, - channel VARCHAR(32) DEFAULT '', - user VARCHAR(128) DEFAULT '', - is_anonymous TINYINT DEFAULT '0', - is_minor TINYINT DEFAULT '0', - is_new TINYINT DEFAULT '0', - is_robot TINYINT DEFAULT '0', - is_unpatrolled TINYINT DEFAULT '0', - delta INT DEFAULT '0', - added INT DEFAULT '0', - deleted INT DEFAULT '0' -) -DUPLICATE KEY( - event_time, - channel, - user, - is_anonymous, - is_minor, - is_new, - is_robot, - is_unpatrolled -) -PARTITION BY RANGE(event_time)( - PARTITION p06 VALUES LESS THAN ('2015-09-12 06:00:00'), - PARTITION p12 VALUES LESS THAN ('2015-09-12 12:00:00'), - PARTITION p18 VALUES LESS THAN ('2015-09-12 18:00:00'), - PARTITION p24 VALUES LESS THAN ('2015-09-13 00:00:00') -) -DISTRIBUTED BY HASH(user); - -CREATE TABLE source_wiki_edit -( - event_time DATETIME, - channel VARCHAR(32) DEFAULT '', - user VARCHAR(128) DEFAULT '', - is_anonymous TINYINT DEFAULT '0', - is_minor TINYINT DEFAULT '0', - is_new TINYINT DEFAULT '0', - is_robot TINYINT DEFAULT '0', - is_unpatrolled TINYINT DEFAULT '0', - delta INT DEFAULT '0', - added INT DEFAULT '0', - deleted INT DEFAULT '0' -) -DUPLICATE KEY( - event_time, - channel,user, - is_anonymous, - is_minor, - is_new, - is_robot, - is_unpatrolled -) -PARTITION BY RANGE(event_time)( - PARTITION p06 VALUES LESS THAN ('2015-09-12 06:00:00'), - PARTITION p12 VALUES LESS THAN ('2015-09-12 12:00:00'), - PARTITION p18 VALUES LESS THAN ('2015-09-12 18:00:00'), - PARTITION p24 VALUES LESS THAN ('2015-09-13 00:00:00') -) -DISTRIBUTED BY HASH(user); -``` - -> **NOTICE** -> -> 从 v2.5.7 开始，当您创建表或添加分区时，StarRocks 可以自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - -## 通过 INSERT INTO VALUES 导入数据 - -您可以使用 INSERT INTO VALUES 命令将一行或多行追加到特定表中。多行用逗号 (,) 分隔。有关详细说明和参数参考，请参见 [SQL Reference - INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md)。 - -> **CAUTION** -> -> 通过 INSERT INTO VALUES 导入数据仅适用于需要使用小型数据集验证 DEMO 的情况。不建议用于大规模测试或生产环境。要将海量数据导入到 StarRocks 中，请参见 [导入选项](Loading_intro.md)，以获取适合您场景的其他选项。 - -以下示例使用标签 `insert_load_wikipedia` 将两行数据插入到数据源表 `source_wiki_edit` 中。标签是数据库中每个数据导入事务的唯一标识标签。 - -```SQL -INSERT INTO source_wiki_edit -WITH LABEL insert_load_wikipedia -VALUES - ("2015-09-12 00:00:00","#en.wikipedia","AustinFF",0,0,0,0,0,21,5,0), - ("2015-09-12 00:00:00","#ca.wikipedia","helloSR",0,1,0,1,0,3,23,0); -``` - -## 通过 INSERT INTO SELECT 导入数据 - -您可以通过 INSERT INTO SELECT 命令将对数据源表执行查询的结果加载到目标表中。INSERT INTO SELECT 命令对来自数据源表的数据执行 ETL 操作，并将数据加载到 StarRocks 的内表中。数据源可以是一个或多个内部或外部表，甚至是云存储上的数据文件。目标表必须是 StarRocks 中的内表。有关详细说明和参数参考，请参见 [SQL Reference - INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md)。 - -### 将数据从内部表或外部表导入到内部表 - -> **NOTE** -> -> 从外部表导入数据与从内部表导入数据相同。为简单起见，我们仅在以下示例中演示如何从内部表导入数据。 - -- 以下示例将数据从源表导入到目标表 `insert_wiki_edit`。 - -```SQL -INSERT INTO insert_wiki_edit -WITH LABEL insert_load_wikipedia_1 -SELECT * FROM source_wiki_edit; -``` - -- 以下示例将数据从源表导入到目标表 `insert_wiki_edit` 的 `p06` 和 `p12` 分区。如果未指定分区，则数据将导入到所有分区。否则，数据将仅导入到指定的分区中。 - -```SQL -INSERT INTO insert_wiki_edit PARTITION(p06, p12) -WITH LABEL insert_load_wikipedia_2 -SELECT * FROM source_wiki_edit; -``` - -查询目标表以确保其中有数据。 - -```Plain text -MySQL > select * from insert_wiki_edit; -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| event_time | channel | user | is_anonymous | is_minor | is_new | is_robot | is_unpatrolled | delta | added | deleted | -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| 2015-09-12 00:00:00 | #en.wikipedia | AustinFF | 0 | 0 | 0 | 0 | 0 | 21 | 5 | 0 | -| 2015-09-12 00:00:00 | #ca.wikipedia | helloSR | 0 | 1 | 0 | 1 | 0 | 3 | 23 | 0 | -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -2 rows in set (0.00 sec) -``` - -如果截断 `p06` 和 `p12` 分区，则查询中不会返回数据。 - -```Plain -MySQL > TRUNCATE TABLE insert_wiki_edit PARTITION(p06, p12); -Query OK, 0 rows affected (0.01 sec) - -MySQL > select * from insert_wiki_edit; -Empty set (0.00 sec) -``` - -- 以下示例将源表中的 `event_time` 和 `channel` 列导入到目标表 `insert_wiki_edit`。默认值用于此处未指定的列。 - -```SQL -INSERT INTO insert_wiki_edit -WITH LABEL insert_load_wikipedia_3 -( - event_time, - channel -) -SELECT event_time, channel FROM source_wiki_edit; -``` - -:::note -从 v3.3.1 开始，在主键表上使用 INSERT INTO 语句指定列列表将执行部分更新（而不是早期版本中的完全 Upsert）。如果未指定列列表，系统将执行完全 Upsert。 -::: - -### 使用 FILES() 直接从外部源的文件导入数据 - -从 v3.1 开始，StarRocks 支持使用 INSERT 命令和 [FILES()](../sql-reference/sql-functions/table-functions/files.md) 函数直接从云存储上的文件导入数据，因此您无需先创建 external catalog 或文件外部表。此外，FILES() 可以自动推断文件的表 schema，从而大大简化了数据导入过程。 - -以下示例将 AWS S3 bucket `inserttest` 中的 Parquet 文件 **parquet/insert_wiki_edit_append.parquet** 中的数据行插入到表 `insert_wiki_edit` 中： - -```Plain -INSERT INTO insert_wiki_edit - SELECT * FROM FILES( - "path" = "s3://inserttest/parquet/insert_wiki_edit_append.parquet", - "format" = "parquet", - "aws.s3.access_key" = "XXXXXXXXXX", - "aws.s3.secret_key" = "YYYYYYYYYY", - "aws.s3.region" = "us-west-2" -); -``` - -## 通过 INSERT OVERWRITE VALUES 覆盖数据 - -您可以使用 INSERT OVERWRITE VALUES 命令使用一行或多行覆盖特定表。多行用逗号 (,) 分隔。有关详细说明和参数参考，请参见 [SQL Reference - INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md)。 - -> **CAUTION** -> -> 通过 INSERT OVERWRITE VALUES 覆盖数据仅适用于需要使用小型数据集验证 DEMO 的情况。不建议用于大规模测试或生产环境。要将海量数据导入到 StarRocks 中，请参见 [导入选项](Loading_intro.md)，以获取适合您场景的其他选项。 - -查询源表和目标表以确保其中有数据。 - -```Plain -MySQL > SELECT * FROM source_wiki_edit; -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| event_time | channel | user | is_anonymous | is_minor | is_new | is_robot | is_unpatrolled | delta | added | deleted | -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| 2015-09-12 00:00:00 | #ca.wikipedia | helloSR | 0 | 1 | 0 | 1 | 0 | 3 | 23 | 0 | -| 2015-09-12 00:00:00 | #en.wikipedia | AustinFF | 0 | 0 | 0 | 0 | 0 | 21 | 5 | 0 | -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -2 rows in set (0.02 sec) - -MySQL > SELECT * FROM insert_wiki_edit; -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| event_time | channel | user | is_anonymous | is_minor | is_new | is_robot | is_unpatrolled | delta | added | deleted | -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| 2015-09-12 00:00:00 | #ca.wikipedia | helloSR | 0 | 1 | 0 | 1 | 0 | 3 | 23 | 0 | -| 2015-09-12 00:00:00 | #en.wikipedia | AustinFF | 0 | 0 | 0 | 0 | 0 | 21 | 5 | 0 | -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -2 rows in set (0.01 sec) -``` - -以下示例使用两个新行覆盖源表 `source_wiki_edit`。 - -```SQL -INSERT OVERWRITE source_wiki_edit -WITH LABEL insert_load_wikipedia_ow -VALUES - ("2015-09-12 00:00:00","#cn.wikipedia","GELongstreet",0,0,0,0,0,36,36,0), - ("2015-09-12 00:00:00","#fr.wikipedia","PereBot",0,1,0,1,0,17,17,0); -``` - -## 通过 INSERT OVERWRITE SELECT 覆盖数据 - -您可以使用 INSERT OVERWRITE SELECT 命令使用对数据源表执行查询的结果覆盖表。INSERT OVERWRITE SELECT 语句对来自一个或多个内部或外部表的数据执行 ETL 操作，并使用该数据覆盖内部表。有关详细说明和参数参考，请参见 [SQL Reference - INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md)。 - -> **NOTE** -> -> 从外部表导入数据与从内部表导入数据相同。为简单起见，我们仅在以下示例中演示如何使用来自内部表的数据覆盖目标表。 - -查询源表和目标表以确保它们包含不同的数据行。 - -```Plain -MySQL > SELECT * FROM source_wiki_edit; -+---------------------+---------------+--------------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| event_time | channel | user | is_anonymous | is_minor | is_new | is_robot | is_unpatrolled | delta | added | deleted | -+---------------------+---------------+--------------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| 2015-09-12 00:00:00 | #cn.wikipedia | GELongstreet | 0 | 0 | 0 | 0 | 0 | 36 | 36 | 0 | -| 2015-09-12 00:00:00 | #fr.wikipedia | PereBot | 0 | 1 | 0 | 1 | 0 | 17 | 17 | 0 | -+---------------------+---------------+--------------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -2 rows in set (0.02 sec) - -MySQL > SELECT * FROM insert_wiki_edit; -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| event_time | channel | user | is_anonymous | is_minor | is_new | is_robot | is_unpatrolled | delta | added | deleted | -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| 2015-09-12 00:00:00 | #en.wikipedia | AustinFF | 0 | 0 | 0 | 0 | 0 | 21 | 5 | 0 | -| 2015-09-12 00:00:00 | #ca.wikipedia | helloSR | 0 | 1 | 0 | 1 | 0 | 3 | 23 | 0 | -+---------------------+---------------+----------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -2 rows in set (0.01 sec) -``` - -- 以下示例使用来自源表的数据覆盖表 `insert_wiki_edit`。 - -```SQL -INSERT OVERWRITE insert_wiki_edit -WITH LABEL insert_load_wikipedia_ow_1 -SELECT * FROM source_wiki_edit; -``` - -- 以下示例使用来自源表的数据覆盖表 `insert_wiki_edit` 的 `p06` 和 `p12` 分区。 - -```SQL -INSERT OVERWRITE insert_wiki_edit PARTITION(p06, p12) -WITH LABEL insert_load_wikipedia_ow_2 -SELECT * FROM source_wiki_edit; -``` - -查询目标表以确保其中有数据。 - -```plain text -MySQL > select * from insert_wiki_edit; -+---------------------+---------------+--------------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| event_time | channel | user | is_anonymous | is_minor | is_new | is_robot | is_unpatrolled | delta | added | deleted | -+---------------------+---------------+--------------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -| 2015-09-12 00:00:00 | #fr.wikipedia | PereBot | 0 | 1 | 0 | 1 | 0 | 17 | 17 | 0 | -| 2015-09-12 00:00:00 | #cn.wikipedia | GELongstreet | 0 | 0 | 0 | 0 | 0 | 36 | 36 | 0 | -+---------------------+---------------+--------------+--------------+----------+--------+----------+----------------+-------+-------+---------+ -2 rows in set (0.01 sec) -``` - -如果截断 `p06` 和 `p12` 分区，则查询中不会返回数据。 - -```Plain -MySQL > TRUNCATE TABLE insert_wiki_edit PARTITION(p06, p12); -Query OK, 0 rows affected (0.01 sec) - -MySQL > select * from insert_wiki_edit; -Empty set (0.00 sec) -``` - -:::note -对于使用 `PARTITION BY column` 策略的表，INSERT OVERWRITE 支持通过指定分区键的值在目标表中创建新分区。现有分区照常覆盖。 - -以下示例创建分区表 `activity`，并在表中创建新分区，同时将数据插入到该分区中： - -```SQL -CREATE TABLE activity ( -id INT NOT NULL, -dt VARCHAR(10) NOT NULL -) ENGINE=OLAP -DUPLICATE KEY(`id`) -PARTITION BY (`id`, `dt`) -DISTRIBUTED BY HASH(`id`); - -INSERT OVERWRITE activity -PARTITION(id='4', dt='2022-01-01') -WITH LABEL insert_activity_auto_partition -VALUES ('4', '2022-01-01'); -``` - -::: - -- 以下示例使用来自源表的 `event_time` 和 `channel` 列覆盖目标表 `insert_wiki_edit`。默认值分配给未覆盖数据的列。 - -```SQL -INSERT OVERWRITE insert_wiki_edit -WITH LABEL insert_load_wikipedia_ow_3 -( - event_time, - channel -) -SELECT event_time, channel FROM source_wiki_edit; -``` - -### 动态覆盖 - -从 v3.4.0 开始，StarRocks 支持一种新的语义 - 用于分区表的 INSERT OVERWRITE 的动态覆盖。 - -目前，INSERT OVERWRITE 的默认行为如下： - -- 当覆盖整个分区表时（即，不指定 PARTITION 子句），新的数据记录将替换其相应分区中的数据。如果存在未涉及的分区，则这些分区将被截断，而其他分区将被覆盖。 -- 当覆盖空分区表（即，其中没有分区）并指定 PARTITION 子句时，系统会返回错误 `ERROR 1064 (HY000): Getting analyzing error. Detail message: Unknown partition 'xxx' in table 'yyy'`。 -- 当覆盖分区表并在 PARTITION 子句中指定不存在的分区时，系统会返回错误 `ERROR 1064 (HY000): Getting analyzing error. Detail message: Unknown partition 'xxx' in table 'yyy'`。 -- 当使用与 PARTITION 子句中指定的任何分区都不匹配的数据记录覆盖分区表时，系统要么返回错误 `ERROR 1064 (HY000): Insert has filtered data in strict mode`（如果启用了严格模式），要么过滤掉不合格的数据记录（如果禁用了严格模式）。 - -新的动态覆盖语义的行为大不相同： - -当覆盖整个分区表时，新的数据记录将替换其相应分区中的数据。如果存在未涉及的分区，则这些分区将被保留，而不是被截断或删除。并且如果存在与不存在的分区对应的新数据记录，系统将创建该分区。 - -默认情况下禁用动态覆盖语义。要启用它，您需要将系统变量 `dynamic_overwrite` 设置为 `true`。 - -在当前会话中启用动态覆盖： - -```SQL -SET dynamic_overwrite = true; -``` - -您也可以在 INSERT OVERWRITE 语句的 hint 中设置它，以使其仅对该语句生效： - -示例： - -```SQL -INSERT /*+set_var(dynamic_overwrite = true)*/ OVERWRITE insert_wiki_edit -SELECT * FROM source_wiki_edit; -``` - -## 将数据导入到具有生成列的表中 - -生成列是一种特殊的列，其值源自基于其他列的预定义表达式或评估。当您的查询请求涉及对昂贵表达式的评估时，生成列特别有用，例如，从 JSON 值查询某个字段或计算 ARRAY 数据。StarRocks 在将数据加载到表中的同时评估表达式并将结果存储在生成列中，从而避免了查询期间的表达式评估并提高了查询性能。 - -您可以使用 INSERT 将数据导入到具有生成列的表中。 - -以下示例创建一个表 `insert_generated_columns` 并向其中插入一行。该表包含两个生成列：`avg_array` 和 `get_string`。`avg_array` 计算 `data_array` 中 ARRAY 数据的平均值，`get_string` 从 `data_json` 中的 JSON 路径 `a` 提取字符串。 - -```SQL -CREATE TABLE insert_generated_columns ( - id INT(11) NOT NULL COMMENT "ID", - data_array ARRAY NOT NULL COMMENT "ARRAY", - data_json JSON NOT NULL COMMENT "JSON", - avg_array DOUBLE NULL - AS array_avg(data_array) COMMENT "Get the average of ARRAY", - get_string VARCHAR(65533) NULL - AS get_json_string(json_string(data_json), '$.a') COMMENT "Extract JSON string" -) ENGINE=OLAP -PRIMARY KEY(id) -DISTRIBUTED BY HASH(id); - -INSERT INTO insert_generated_columns -VALUES (1, [1,2], parse_json('{"a" : 1, "b" : 2}')); -``` - -> **NOTE** -> -> 不支持直接将数据加载到生成列中。 - -您可以查询该表以检查其中的数据。 - -```Plain -mysql> SELECT * FROM insert_generated_columns; -+------+------------+------------------+-----------+------------+ -| id | data_array | data_json | avg_array | get_string | -+------+------------+------------------+-----------+------------+ -| 1 | [1,2] | {"a": 1, "b": 2} | 1.5 | 1 | -+------+------------+------------------+-----------+------------+ -1 row in set (0.02 sec) -``` - -## 使用 PROPERTIES 的 INSERT 数据 - -从 v3.4.0 开始，INSERT 语句支持配置 PROPERTIES，它可以用于各种目的。PROPERTIES 会覆盖其相应的变量。 - -### 启用严格模式 - -从 v3.4.0 开始，您可以启用严格模式并为来自 FILES() 的 INSERT 设置 `max_filter_ratio`。来自 FILES() 的 INSERT 的严格模式与其他导入方法的行为相同。 - -如果要加载包含一些不合格行的数据集，您可以过滤掉这些不合格行，也可以加载它们并将 NULL 值分配给不合格的列。您可以使用属性 `strict_mode` 和 `max_filter_ratio` 来实现这些目的。 - -- 要过滤掉不合格的行：将 `strict_mode` 设置为 `true`，并将 `max_filter_ratio` 设置为所需的值。 -- 要加载所有具有 NULL 值的不合格行：将 `strict_mode` 设置为 `false`。 - -以下示例将 AWS S3 bucket `inserttest` 中的 Parquet 文件 **parquet/insert_wiki_edit_append.parquet** 中的数据行插入到表 `insert_wiki_edit` 中，启用严格模式以过滤掉不合格的数据记录，并容忍最多 10% 的错误数据： - -```SQL -INSERT INTO insert_wiki_edit -PROPERTIES( - "strict_mode" = "true", - "max_filter_ratio" = "0.1" -) -SELECT * FROM FILES( - "path" = "s3://inserttest/parquet/insert_wiki_edit_append.parquet", - "format" = "parquet", - "aws.s3.access_key" = "XXXXXXXXXX", - "aws.s3.secret_key" = "YYYYYYYYYY", - "aws.s3.region" = "us-west-2" -); -``` - -:::note - -`strict_mode` 和 `max_filter_ratio` 仅支持来自 FILES() 的 INSERT。来自表的 INSERT 不支持这些属性。 - -::: - -### 设置超时时长 - -从 v3.4.0 开始，您可以使用属性设置 INSERT 语句的超时时长。 - -以下示例将源表 `source_wiki_edit` 中的数据插入到目标表 `insert_wiki_edit` 中，并将超时时长设置为 `2` 秒。 - -```SQL -INSERT INTO insert_wiki_edit -PROPERTIES( - "timeout" = "2" -) -SELECT * FROM source_wiki_edit; -``` - -:::note - -从 v3.4.0 开始，您还可以使用系统变量 `insert_timeout` 设置 INSERT 超时时长，该变量适用于涉及 INSERT 的操作（例如，UPDATE、DELETE、CTAS、物化视图刷新、统计信息收集和 PIPE）。在早于 v3.4.0 的版本中，相应的变量是 `query_timeout`。 - -::: - -### 按名称匹配列 - -默认情况下，INSERT 按位置匹配源表和目标表中的列，即语句中列的映射。 - -以下示例通过位置显式匹配源表和目标表中的每个列： - -```SQL -INSERT INTO insert_wiki_edit ( - event_time, - channel, - user -) -SELECT event_time, channel, user FROM source_wiki_edit; -``` - -如果您更改列列表或 SELECT 语句中 `channel` 和 `user` 的顺序，则列映射将更改。 - -```SQL -INSERT INTO insert_wiki_edit ( - event_time, - channel, - user -) -SELECT event_time, user, channel FROM source_wiki_edit; -``` - -在这里，提取的数据可能不是您想要的，因为目标表 `insert_wiki_edit` 中的 `channel` 将填充来自源表 `source_wiki_edit` 中的 `user` 的数据。 - -通过在 INSERT 语句中添加 `BY NAME` 子句，系统将检测源表和目标表中的列名，并匹配具有相同名称的列。 - -:::note - -- 如果指定了 `BY NAME`，则不能指定列列表。 -- 如果未指定 `BY NAME`，则系统会按列列表和 SELECT 语句中列的位置匹配列。 - -::: - -以下示例按名称匹配源表和目标表中的每个列： - -```SQL -INSERT INTO insert_wiki_edit BY NAME -SELECT event_time, user, channel FROM source_wiki_edit; -``` - -在这种情况下，更改 `channel` 和 `user` 的顺序不会更改列映射。 - -## 使用 INSERT 异步导入数据 - -使用 INSERT 导入数据会提交一个同步事务，该事务可能会因会话中断或超时而失败。您可以使用 [SUBMIT TASK](../sql-reference/sql-statements/loading_unloading/ETL/SUBMIT_TASK.md) 提交异步 INSERT 事务。此功能自 StarRocks v2.5 起受支持。 - -- 以下示例异步地将数据从源表插入到目标表 `insert_wiki_edit`。 - -```SQL -SUBMIT TASK AS INSERT INTO insert_wiki_edit -SELECT * FROM source_wiki_edit; -``` - -- 以下示例使用源表中的数据异步覆盖表 `insert_wiki_edit`。 - -```SQL -SUBMIT TASK AS INSERT OVERWRITE insert_wiki_edit -SELECT * FROM source_wiki_edit; -``` - -- 以下示例使用源表中的数据异步覆盖表 `insert_wiki_edit`，并使用 hint 将查询超时延长至 `100000` 秒。 - -```SQL -SUBMIT /*+set_var(insert_timeout=100000)*/ TASK AS -INSERT OVERWRITE insert_wiki_edit -SELECT * FROM source_wiki_edit; -``` - -- 以下示例使用源表中的数据异步覆盖表 `insert_wiki_edit`，并将任务名称指定为 `async`。 - -```SQL -SUBMIT TASK async -AS INSERT OVERWRITE insert_wiki_edit -SELECT * FROM source_wiki_edit; -``` - -您可以通过查询 Information Schema 中的元数据视图 `task_runs` 来检查异步 INSERT 任务的状态。 - -以下示例检查 INSERT 任务 `async` 的状态。 - -```SQL -SELECT * FROM information_schema.task_runs WHERE task_name = 'async'; -``` - -## 检查 INSERT 作业状态 - -### 通过结果检查 - -同步 INSERT 事务根据事务的结果返回不同的状态。 - -- **事务成功** - -如果事务成功，StarRocks 将返回以下内容： - -```Plain -Query OK, 2 rows affected (0.05 sec) -{'label':'insert_load_wikipedia', 'status':'VISIBLE', 'txnId':'1006'} -``` - -- **事务失败** - -如果所有数据行都无法加载到目标表中，则 INSERT 事务将失败。如果事务失败，StarRocks 将返回以下内容： - -```Plain -ERROR 1064 (HY000): Insert has filtered data in strict mode, tracking_url=http://x.x.x.x:yyyy/api/_load_error_log?file=error_log_9f0a4fd0b64e11ec_906bbede076e9d08 -``` - -您可以通过使用 `tracking_url` 检查日志来找到问题。 - -### 通过 Information Schema 检查 - -您可以使用 [SELECT](../sql-reference/sql-statements/table_bucket_part_index/SELECT.md) 语句从 `information_schema` 数据库中的 `loads` 表中查询一个或多个导入作业的结果。此功能自 v3.1 起受支持。 - -示例 1：查询在 `load_test` 数据库上执行的导入作业的结果，按创建时间 (`CREATE_TIME`) 降序对结果进行排序，并且仅返回最上面的结果。 - -```SQL -SELECT * FROM information_schema.loads -WHERE database_name = 'load_test' -ORDER BY create_time DESC -LIMIT 1\G -``` - -示例 2：查询在 `load_test` 数据库上执行的导入作业（其标签为 `insert_load_wikipedia`）的结果： - -```SQL -SELECT * FROM information_schema.loads -WHERE database_name = 'load_test' and label = 'insert_load_wikipedia'\G -``` - -返回结果如下： - -```Plain -*************************** 1. row *************************** - JOB_ID: 21319 - LABEL: insert_load_wikipedia - DATABASE_NAME: load_test - STATE: FINISHED - PROGRESS: ETL:100%; LOAD:100% - TYPE: INSERT - PRIORITY: NORMAL - SCAN_ROWS: 0 - FILTERED_ROWS: 0 - UNSELECTED_ROWS: 0 - SINK_ROWS: 2 - ETL_INFO: - TASK_INFO: resource:N/A; timeout(s):300; max_filter_ratio:0.0 - CREATE_TIME: 2023-08-09 10:42:23 - ETL_START_TIME: 2023-08-09 10:42:23 - ETL_FINISH_TIME: 2023-08-09 \ No newline at end of file diff --git a/docs/zh/loading/Json_loading.md b/docs/zh/loading/Json_loading.md deleted file mode 100644 index 4915fcf..0000000 --- a/docs/zh/loading/Json_loading.md +++ /dev/null @@ -1,363 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 介绍 - -您可以使用 Stream Load 或 Routine Load 导入半结构化数据（例如 JSON）。 - -## 使用场景 - -* Stream Load：对于存储在文本文件中的 JSON 数据，使用 Stream Load 进行导入。 -* Routine Load：对于 Kafka 中的 JSON 数据，使用 Routine Load 进行导入。 - -### Stream Load 导入 - -示例数据： - -~~~json -{ "id": 123, "city" : "beijing"}, -{ "id": 456, "city" : "shanghai"}, - ... -~~~ - -示例： - -~~~shell -curl -v --location-trusted -u : \ - -H "format: json" -H "jsonpaths: [\"$.id\", \"$.city\"]" \ - -T example.json \ - http://FE_HOST:HTTP_PORT/api/DATABASE/TABLE/_stream_load -~~~ - -`format: json` 参数允许您执行导入数据的格式。`jsonpaths` 用于执行相应的数据导入路径。 - -相关参数： - -* jsonpaths: 选择每列的 JSON 路径 -* json\_root: 选择 JSON 开始解析的列 -* strip\_outer\_array: 裁剪最外层数组字段 -* strict\_mode: 在导入期间严格过滤列类型转换 - -当 JSON 数据模式和 StarRocks 数据模式不完全相同时，修改 `Jsonpath`。 - -示例数据： - -~~~json -{"k1": 1, "k2": 2} -~~~ - -导入示例： - -~~~bash -curl -v --location-trusted -u : \ - -H "format: json" -H "jsonpaths: [\"$.k2\", \"$.k1\"]" \ - -H "columns: k2, tmp_k1, k1 = tmp_k1 * 100" \ - -T example.json \ - http://127.0.0.1:8030/api/db1/tbl1/_stream_load -~~~ - -在导入期间执行将 k1 乘以 100 的 ETL 操作，并通过 `Jsonpath` 将列与原始数据匹配。 - -导入结果如下： - -~~~plain text -+------+------+ -| k1 | k2 | -+------+------+ -| 100 | 2 | -+------+------+ -~~~ - -对于缺少的列，如果列定义允许为空，则将添加 `NULL`，或者可以通过 `ifnull` 添加默认值。 - -示例数据： - -~~~json -[ - {"k1": 1, "k2": "a"}, - {"k1": 2}, - {"k1": 3, "k2": "c"}, -] -~~~ - -导入示例-1： - -~~~shell -curl -v --location-trusted -u : \ - -H "format: json" -H "strip_outer_array: true" \ - -T example.json \ - http://127.0.0.1:8030/api/db1/tbl1/_stream_load -~~~ - -导入结果如下： - -~~~plain text -+------+------+ -| k1 | k2 | -+------+------+ -| 1 | a | -+------+------+ -| 2 | NULL | -+------+------+ -| 3 | c | -+------+------+ -~~~ - -导入示例-2： - -~~~shell -curl -v --location-trusted -u : \ - -H "format: json" -H "strip_outer_array: true" \ - -H "jsonpaths: [\"$.k1\", \"$.k2\"]" \ - -H "columns: k1, tmp_k2, k2 = ifnull(tmp_k2, 'x')" \ - -T example.json \ - http://127.0.0.1:8030/api/db1/tbl1/_stream_load -~~~ - -导入结果如下： - -~~~plain text -+------+------+ -| k1 | k2 | -+------+------+ -| 1 | a | -+------+------+ -| 2 | x | -+------+------+ -| 3 | c | -+------+------+ -~~~ - -### Routine Load 导入 - -与 Stream Load 类似，Kafka 数据源的消息内容被视为完整的 JSON 数据。 - -1. 如果一条消息包含数组格式的多行数据，则将导入所有行，并且 Kafka 的 offset 将仅递增 1。 -2. 如果 Array 格式的 JSON 表示多行数据，但由于 JSON 格式错误导致 JSON 解析失败，则错误行将仅递增 1（鉴于解析失败，StarRocks 实际上无法确定它包含多少行数据，并且只能将错误数据记录为一行）。 - -### 使用 Canal 通过增量同步 binlog 将 MySQL 导入 StarRocks - -[Canal](https://github.com/alibaba/canal) 是阿里巴巴的开源 MySQL binlog 同步工具，通过它可以将 MySQL 数据同步到 Kafka。数据在 Kafka 中以 JSON 格式生成。以下演示如何使用 Routine Load 同步 Kafka 中的数据，以实现与 MySQL 的增量数据同步。 - -* 在 MySQL 中，我们有一个数据表，其表创建语句如下。 - -~~~sql -CREATE TABLE `query_record` ( - `query_id` varchar(64) NOT NULL, - `conn_id` int(11) DEFAULT NULL, - `fe_host` varchar(32) DEFAULT NULL, - `user` varchar(32) DEFAULT NULL, - `start_time` datetime NOT NULL, - `end_time` datetime DEFAULT NULL, - `time_used` double DEFAULT NULL, - `state` varchar(16) NOT NULL, - `error_message` text, - `sql` text NOT NULL, - `database` varchar(128) NOT NULL, - `profile` longtext, - `plan` longtext, - PRIMARY KEY (`query_id`), - KEY `idx_start_time` (`start_time`) USING BTREE -) ENGINE=InnoDB DEFAULT CHARSET=utf8 -~~~ - -* 前提条件：确保 MySQL 已启用 binlog 并且格式为 ROW。 - -~~~bash -[mysqld] -log-bin=mysql-bin # 启用 binlog -binlog-format=ROW # 选择 ROW 模式 -server_id=1 # 需要定义 MySQL 复制，并且不要复制 Canal 的 slaveId -~~~ - -* 创建一个帐户并授予辅助 MySQL 服务器权限： - -~~~sql -CREATE USER canal IDENTIFIED BY 'canal'; -GRANT SELECT, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'canal'@'%'; --- GRANT ALL PRIVILEGES ON *.* TO 'canal'@'%'; -FLUSH PRIVILEGES; -~~~ - -* 然后下载并安装 Canal。 - -~~~bash -wget https://github.com/alibaba/canal/releases/download/canal-1.0.17/canal.deployer-1.0.17.tar.gz - -mkdir /tmp/canal -tar zxvf canal.deployer-$version.tar.gz -C /tmp/canal -~~~ - -* 修改配置（MySQL 相关）。 - -`$ vi conf/example/instance.properties` - -~~~bash -## mysql serverId -canal.instance.mysql.slaveId = 1234 -#position info, need to change to your own database information -canal.instance.master.address = 127.0.0.1:3306 -canal.instance.master.journal.name = -canal.instance.master.position = -canal.instance.master.timestamp = -#canal.instance.standby.address = -#canal.instance.standby.journal.name = -#canal.instance.standby.position = -#canal.instance.standby.timestamp = -#username/password, need to change to your own database information -canal.instance.dbUsername = canal -canal.instance.dbPassword = canal -canal.instance.defaultDatabaseName = -canal.instance.connectionCharset = UTF-8 -#table regex -canal.instance.filter.regex = .\*\\\\..\* -# Select the name of the table to be synchronized and the partition name of the kafka target. -canal.mq.dynamicTopic=databasename.query_record -canal.mq.partitionHash= databasename.query_record:query_id -~~~ - -* 修改配置（Kafka 相关）。 - -`$ vi /usr/local/canal/conf/canal.properties` - -~~~bash -# Available options: tcp(by default), kafka, RocketMQ -canal.serverMode = kafka -# ... -# kafka/rocketmq Cluster Configuration: 192.168.1.117:9092,192.168.1.118:9092,192.168.1.119:9092 -canal.mq.servers = 127.0.0.1:6667 -canal.mq.retries = 0 -# This value can be increased in flagMessage mode, but do not exceed the maximum size of the MQ message. -canal.mq.batchSize = 16384 -canal.mq.maxRequestSize = 1048576 -# In flatMessage mode, please change this value to a larger value, 50-200 is recommended. -canal.mq.lingerMs = 1 -canal.mq.bufferMemory = 33554432 -# Canal's batch size with a default value of 50K. Please do not exceed 1M due to Kafka's maximum message size limit (under 900K) -canal.mq.canalBatchSize = 50 -# Timeout of `Canal get`, in milliseconds. Empty indicates unlimited timeout. -canal.mq.canalGetTimeout = 100 -# Whether the object is in flat json format -canal.mq.flatMessage = false -canal.mq.compressionType = none -canal.mq.acks = all -# Whether Kafka message delivery uses transactions -canal.mq.transaction = false -~~~ - -* 启动 - -`bin/startup.sh` - -相应的同步日志显示在 `logs/example/example.log` 和 Kafka 中，格式如下： - -~~~json -{ - "data": [{ - "query_id": "3c7ebee321e94773-b4d79cc3f08ca2ac", - "conn_id": "34434", - "fe_host": "172.26.34.139", - "user": "zhaoheng", - "start_time": "2020-10-19 20:40:10.578", - "end_time": "2020-10-19 20:40:10", - "time_used": "1.0", - "state": "FINISHED", - "error_message": "", - "sql": "COMMIT", - "database": "", - "profile": "", - "plan": "" - }, { - "query_id": "7ff2df7551d64f8e-804004341bfa63ad", - "conn_id": "34432", - "fe_host": "172.26.34.139", - "user": "zhaoheng", - "start_time": "2020-10-19 20:40:10.566", - "end_time": "2020-10-19 20:40:10", - "time_used": "0.0", - "state": "FINISHED", - "error_message": "", - "sql": "COMMIT", - "database": "", - "profile": "", - "plan": "" - }, { - "query_id": "3a4b35d1c1914748-be385f5067759134", - "conn_id": "34440", - "fe_host": "172.26.34.139", - "user": "zhaoheng", - "start_time": "2020-10-19 20:40:10.601", - "end_time": "1970-01-01 08:00:00", - "time_used": "-1.0", - "state": "RUNNING", - "error_message": "", - "sql": " SELECT SUM(length(lo_custkey)), SUM(length(c_custkey)) FROM lineorder_str INNER JOIN customer_str ON lo_custkey=c_custkey;", - "database": "ssb", - "profile": "", - "plan": "" - }], - "database": "center_service_lihailei", - "es": 1603111211000, - "id": 122, - "isDdl": false, - "mysqlType": { - "query_id": "varchar(64)", - "conn_id": "int(11)", - "fe_host": "varchar(32)", - "user": "varchar(32)", - "start_time": "datetime(3)", - "end_time": "datetime", - "time_used": "double", - "state": "varchar(16)", - "error_message": "text", - "sql": "text", - "database": "varchar(128)", - "profile": "longtext", - "plan": "longtext" - }, - "old": null, - "pkNames": ["query_id"], - "sql": "", - "sqlType": { - "query_id": 12, - "conn_id": 4, - "fe_host": 12, - "user": 12, - "start_time": 93, - "end_time": 93, - "time_used": 8, - "state": 12, - "error_message": 2005, - "sql": 2005, - "database": 12, - "profile": 2005, - "plan": 2005 - }, - "table": "query_record", - "ts": 1603111212015, - "type": "INSERT" -} -~~~ - -添加 `json_root` 和 `strip_outer_array = true` 以从 `data` 导入数据。 - -~~~sql -create routine load manual.query_job on query_record -columns (query_id,conn_id,fe_host,user,start_time,end_time,time_used,state,error_message,`sql`,`database`,profile,plan) -PROPERTIES ( - "format"="json", - "json_root"="$.data", - "desired_concurrent_number"="1", - "strip_outer_array" ="true", - "max_error_number"="1000" -) -FROM KAFKA ( - "kafka_broker_list"= "172.26.92.141:9092", - "kafka_topic" = "databasename.query_record" -); -~~~ - -这样就完成了从 MySQL 到 StarRocks 的近实时数据同步。 - -通过 `show routine load` 查看导入作业的状态和错误消息。 \ No newline at end of file diff --git a/docs/zh/loading/Kafka-connector-starrocks.md b/docs/zh/loading/Kafka-connector-starrocks.md deleted file mode 100644 index fc030a9..0000000 --- a/docs/zh/loading/Kafka-connector-starrocks.md +++ /dev/null @@ -1,829 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 使用 Kafka connector 导入数据 - -StarRocks 提供了一个自研的 connector，名为 Apache Kafka® connector (StarRocks Connector for Apache Kafka®，简称 Kafka connector)。作为一个 sink connector，它可以持续地从 Kafka 消费消息，并将消息导入到 StarRocks 中。 Kafka connector 保证至少一次 (at-least-once) 的语义。 - -Kafka connector 可以无缝集成到 Kafka Connect 中，这使得 StarRocks 能够更好地与 Kafka 生态系统集成。如果您想将实时数据导入到 StarRocks 中，这是一个明智的选择。与 Routine Load 相比，建议在以下场景中使用 Kafka connector： - -- Routine Load 仅支持导入 CSV、JSON 和 Avro 格式的数据，而 Kafka connector 可以导入更多格式的数据，例如 Protobuf。只要可以使用 Kafka Connect 的转换器将数据转换为 JSON 和 CSV 格式，就可以通过 Kafka connector 将数据导入到 StarRocks 中。 -- 自定义数据转换，例如 Debezium 格式的 CDC 数据。 -- 从多个 Kafka topic 导入数据。 -- 从 Confluent Cloud 导入数据。 -- 需要更精细地控制导入的批次大小、并行度和其他参数，以在导入速度和资源利用率之间取得平衡。 - -## 准备工作 - -### 版本要求 - -| Connector | Kafka | StarRocks | Java | -| --------- | --------- | ------------- | ---- | -| 1.0.6 | 3.4+/4.0+ | 2.5 及更高版本 | 8 | -| 1.0.5 | 3.4 | 2.5 及更高版本 | 8 | -| 1.0.4 | 3.4 | 2.5 及更高版本 | 8 | -| 1.0.3 | 3.4 | 2.5 及更高版本 | 8 | - -### 搭建 Kafka 环境 - -支持自管理的 Apache Kafka 集群和 Confluent Cloud。 - -- 对于自管理的 Apache Kafka 集群，您可以参考 [Apache Kafka quickstart](https://kafka.apache.org/quickstart) 快速部署 Kafka 集群。 Kafka Connect 已经集成到 Kafka 中。 -- 对于 Confluent Cloud，请确保您拥有 Confluent 帐户并已创建集群。 - -### 下载 Kafka connector - -将 Kafka connector 提交到 Kafka Connect： - -- 自管理的 Kafka 集群： - - 下载 [starrocks-connector-for-kafka-x.y.z-with-dependencies.jar](https://github.com/StarRocks/starrocks-connector-for-kafka/releases)。 - -- Confluent Cloud： - - 目前， Kafka connector 尚未上传到 Confluent Hub。您需要下载 [starrocks-connector-for-kafka-x.y.z-with-dependencies.jar](https://github.com/StarRocks/starrocks-connector-for-kafka/releases)，将其打包成 ZIP 文件，然后将 ZIP 文件上传到 Confluent Cloud。 - -### 网络配置 - -确保 Kafka 所在的机器可以通过 [`http_port`](../administration/management/FE_configuration.md#http_port) (默认值：`8030`) 和 [`query_port`](../administration/management/FE_configuration.md#query_port) (默认值：`9030`) 访问 StarRocks 集群的 FE 节点，并通过 [`be_http_port`](../administration/management/BE_configuration.md#be_http_port) (默认值：`8040`) 访问 BE 节点。 - -## 使用方法 - -本节以自管理的 Kafka 集群为例，介绍如何配置 Kafka connector 和 Kafka Connect，然后运行 Kafka Connect 将数据导入到 StarRocks 中。 - -### 准备数据集 - -假设 Kafka 集群的 topic `test` 中存在 JSON 格式的数据。 - -```JSON -{"id":1,"city":"New York"} -{"id":2,"city":"Los Angeles"} -{"id":3,"city":"Chicago"} -``` - -### 创建表 - -根据 JSON 格式数据的键，在 StarRocks 集群的数据库 `example_db` 中创建表 `test_tbl`。 - -```SQL -CREATE DATABASE example_db; -USE example_db; -CREATE TABLE test_tbl (id INT, city STRING); -``` - -### 配置 Kafka connector 和 Kafka Connect，然后运行 Kafka Connect 导入数据 - -#### 在独立模式下运行 Kafka Connect - -1. 配置 Kafka connector。在 Kafka 安装目录下的 **config** 目录中，为 Kafka connector 创建配置文件 **connect-StarRocks-sink.properties**，并配置以下参数。有关更多参数和说明，请参见 [参数](#参数)。 - - :::info - - - 在本示例中，StarRocks 提供的 Kafka connector 是一个 sink connector，可以持续地从 Kafka 消费数据，并将数据导入到 StarRocks 中。 - - 如果源数据是 CDC 数据，例如 Debezium 格式的数据，并且 StarRocks 表是 Primary Key 表，则还需要在 StarRocks 提供的 Kafka connector 的配置文件 **connect-StarRocks-sink.properties** 中[配置 `transform`](#load-debezium-formatted-cdc-data)，以将源数据的更改同步到 Primary Key 表。 - - ::: - - ```yaml - name=starrocks-kafka-connector - connector.class=com.starrocks.connector.kafka.StarRocksSinkConnector - topics=test - key.converter=org.apache.kafka.connect.json.JsonConverter - value.converter=org.apache.kafka.connect.json.JsonConverter - key.converter.schemas.enable=true - value.converter.schemas.enable=false - # StarRocks 集群中 FE 的 HTTP URL。默认端口为 8030。 - starrocks.http.url=192.168.xxx.xxx:8030 - # 如果 Kafka topic 名称与 StarRocks 表名不同，则需要配置它们之间的映射关系。 - starrocks.topic2table.map=test:test_tbl - # 输入 StarRocks 用户名。 - starrocks.username=user1 - # 输入 StarRocks 密码。 - starrocks.password=123456 - starrocks.database.name=example_db - sink.properties.strip_outer_array=true - ``` - -2. 配置并运行 Kafka Connect。 - - 1. 配置 Kafka Connect。在 **config** 目录下的配置文件 **config/connect-standalone.properties** 中，配置以下参数。有关更多参数和说明，请参见 [Running Kafka Connect](https://kafka.apache.org/documentation.html#connect_running)。 - - ```yaml - # Kafka brokers 的地址。多个 Kafka brokers 的地址需要用逗号 (,) 分隔。 - # 请注意，本示例使用 PLAINTEXT 作为访问 Kafka 集群的安全协议。如果您使用其他安全协议访问 Kafka 集群，则需要在本文件中配置相关信息。 - bootstrap.servers=:9092 - offset.storage.file.filename=/tmp/connect.offsets - offset.flush.interval.ms=10000 - key.converter=org.apache.kafka.connect.json.JsonConverter - value.converter=org.apache.kafka.connect.json.JsonConverter - key.converter.schemas.enable=true - value.converter.schemas.enable=false - # starrocks-connector-for-kafka-x.y.z-with-dependencies.jar 的绝对路径。 - plugin.path=/home/kafka-connect/starrocks-kafka-connector - ``` - - 2. 运行 Kafka Connect。 - - ```Bash - CLASSPATH=/home/kafka-connect/starrocks-kafka-connector/* bin/connect-standalone.sh config/connect-standalone.properties config/connect-starrocks-sink.properties - ``` - -#### 在分布式模式下运行 Kafka Connect - -1. 配置并运行 Kafka Connect。 - - 1. 配置 Kafka Connect。在 **config** 目录下的配置文件 `config/connect-distributed.properties` 中，配置以下参数。有关更多参数和说明，请参考 [Running Kafka Connect](https://kafka.apache.org/documentation.html#connect_running)。 - - ```yaml - # Kafka brokers 的地址。多个 Kafka brokers 的地址需要用逗号 (,) 分隔。 - # 请注意，本示例使用 PLAINTEXT 作为访问 Kafka 集群的安全协议。 - # 如果您使用其他安全协议访问 Kafka 集群，请在本文件中配置相关信息。 - bootstrap.servers=:9092 - offset.storage.file.filename=/tmp/connect.offsets - offset.flush.interval.ms=10000 - key.converter=org.apache.kafka.connect.json.JsonConverter - value.converter=org.apache.kafka.connect.json.JsonConverter - key.converter.schemas.enable=true - value.converter.schemas.enable=false - # starrocks-connector-for-kafka-x.y.z-with-dependencies.jar 的绝对路径。 - plugin.path=/home/kafka-connect/starrocks-kafka-connector - ``` - - 2. 运行 Kafka Connect。 - - ```BASH - CLASSPATH=/home/kafka-connect/starrocks-kafka-connector/* bin/connect-distributed.sh config/connect-distributed.properties - ``` - -2. 配置并创建 Kafka connector。请注意，在分布式模式下，您需要通过 REST API 配置和创建 Kafka connector。有关参数和说明，请参见 [参数](#参数)。 - - :::info - - - 在本示例中，StarRocks 提供的 Kafka connector 是一个 sink connector，可以持续地从 Kafka 消费数据，并将数据导入到 StarRocks 中。 - - 如果源数据是 CDC 数据，例如 Debezium 格式的数据，并且 StarRocks 表是 Primary Key 表，则还需要在 StarRocks 提供的 Kafka connector 的配置文件 **connect-StarRocks-sink.properties** 中[配置 `transform`](#load-debezium-formatted-cdc-data)，以将源数据的更改同步到 Primary Key 表。 - - ::: - - ```Shell - curl -i http://127.0.0.1:8083/connectors -H "Content-Type: application/json" -X POST -d '{ - "name":"starrocks-kafka-connector", - "config":{ - "connector.class":"com.starrocks.connector.kafka.StarRocksSinkConnector", - "topics":"test", - "key.converter":"org.apache.kafka.connect.json.JsonConverter", - "value.converter":"org.apache.kafka.connect.json.JsonConverter", - "key.converter.schemas.enable":"true", - "value.converter.schemas.enable":"false", - "starrocks.http.url":"192.168.xxx.xxx:8030", - "starrocks.topic2table.map":"test:test_tbl", - "starrocks.username":"user1", - "starrocks.password":"123456", - "starrocks.database.name":"example_db", - "sink.properties.strip_outer_array":"true" - } - }' - ``` - -#### 查询 StarRocks 表 - -查询目标 StarRocks 表 `test_tbl`。 - -```mysql -MySQL [example_db]> select * from test_tbl; - -+------+-------------+ -| id | city | -+------+-------------+ -| 1 | New York | -| 2 | Los Angeles | -| 3 | Chicago | -+------+-------------+ -3 rows in set (0.01 sec) -``` - -如果返回以上结果，则表示数据已成功导入。 - -## 参数 - -### name - -**是否必须**：是
-**默认值**：
-**描述**：此 Kafka connector 的名称。在 Kafka Connect 集群中的所有 Kafka connector 中，它必须是全局唯一的。例如，starrocks-kafka-connector。 - -### connector.class - -**是否必须**：是
-**默认值**：
-**描述**：此 Kafka connector 的 sink 使用的类。将值设置为 `com.starrocks.connector.kafka.StarRocksSinkConnector`。 - -### topics - -**是否必须**：
-**默认值**：
-**描述**：要订阅的一个或多个 topic，其中每个 topic 对应一个 StarRocks 表。默认情况下，StarRocks 假定 topic 名称与 StarRocks 表的名称匹配。因此，StarRocks 通过使用 topic 名称来确定目标 StarRocks 表。请选择填写 `topics` 或 `topics.regex` (如下)，但不能同时填写。但是，如果 StarRocks 表名与 topic 名称不同，则可以使用可选的 `starrocks.topic2table.map` 参数 (如下) 来指定从 topic 名称到表名称的映射。 - -### topics.regex - -**是否必须**：
-**默认值**： -**描述**：用于匹配要订阅的一个或多个 topic 的正则表达式。有关更多描述，请参见 `topics`。请选择填写 `topics.regex` 或 `topics` (如上)，但不能同时填写。
- -### starrocks.topic2table.map - -**是否必须**：否
-**默认值**：
-**描述**：当 topic 名称与 StarRocks 表名不同时，StarRocks 表名与 topic 名称的映射。格式为 `:,:,...`。 - -### starrocks.http.url - -**是否必须**：是
-**默认值**：
-**描述**：StarRocks 集群中 FE 的 HTTP URL。格式为 `:,:,...`。多个地址用逗号 (,) 分隔。例如，`192.168.xxx.xxx:8030,192.168.xxx.xxx:8030`。 - -### starrocks.database.name - -**是否必须**：是
-**默认值**：
-**描述**：StarRocks 数据库的名称。 - -### starrocks.username - -**是否必须**：是
-**默认值**：
-**描述**：您的 StarRocks 集群帐户的用户名。该用户需要对 StarRocks 表具有 [INSERT](../sql-reference/sql-statements/account-management/GRANT.md) 权限。 - -### starrocks.password - -**是否必须**：是
-**默认值**：
-**描述**：您的 StarRocks 集群帐户的密码。 - -### key.converter - -**是否必须**：否
-**默认值**：Kafka Connect 集群使用的 Key converter
-**描述**：此参数指定 sink connector (Kafka-connector-starrocks) 的 key converter，用于反序列化 Kafka 数据的键。默认的 key converter 是 Kafka Connect 集群使用的 key converter。 - -### value.converter - -**是否必须**：否
-**默认值**：Kafka Connect 集群使用的 Value converter
-**描述**：此参数指定 sink connector (Kafka-connector-starrocks) 的 value converter，用于反序列化 Kafka 数据的值。默认的 value converter 是 Kafka Connect 集群使用的 value converter。 - -### key.converter.schema.registry.url - -**是否必须**：否
-**默认值**：
-**描述**：Key converter 的 Schema registry URL。 - -### value.converter.schema.registry.url - -**是否必须**：否
-**默认值**：
-**描述**：Value converter 的 Schema registry URL。 - -### tasks.max - -**是否必须**：否
-**默认值**：1
-**描述**：Kafka connector 可以创建的任务线程数的上限，通常与 Kafka Connect 集群中 worker 节点上的 CPU 核心数相同。您可以调整此参数以控制导入性能。 - -### bufferflush.maxbytes - -**是否必须**：否
-**默认值**：94371840(90M)
-**描述**：在一次发送到 StarRocks 之前，可以在内存中累积的最大数据量。最大值范围为 64 MB 到 10 GB。请记住，Stream Load SDK 缓冲区可能会创建多个 Stream Load 作业来缓冲数据。因此，此处提到的阈值是指总数据大小。 - -### bufferflush.intervalms - -**是否必须**：否
-**默认值**：1000
-**描述**：发送一批数据的间隔，用于控制导入延迟。范围：[1000, 3600000]。 - -### connect.timeoutms - -**是否必须**：否
-**默认值**：1000
-**描述**：连接到 HTTP URL 的超时时间。范围：[100, 60000]。 - -### sink.properties.* - -**是否必须**：
-**默认值**：
-**描述**：用于控制导入行为的 Stream Load 参数。例如，参数 `sink.properties.format` 指定用于 Stream Load 的格式，例如 CSV 或 JSON。有关支持的参数及其描述的列表，请参见 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -### sink.properties.format - -**是否必须**：否
-**默认值**：json
-**描述**：用于 Stream Load 的格式。Kafka connector 会在将每批数据发送到 StarRocks 之前将其转换为该格式。有效值：`csv` 和 `json`。有关更多信息，请参见 [CSV 参数](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md#csv-parameters) 和 [JSON 参数](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md#json-parameters)。 - -### sink.properties.partial_update - -**是否必须**：否
-**默认值**：`FALSE`
-**描述**：是否使用部分更新。有效值：`TRUE` 和 `FALSE`。默认值：`FALSE`，表示禁用此功能。 - -### sink.properties.partial_update_mode - -**是否必须**：否
-**默认值**：`row`
-**描述**：指定部分更新的模式。有效值：`row` 和 `column`。
  • 值 `row` (默认) 表示行模式下的部分更新，更适合于具有许多列和小批量的实时更新。
  • 值 `column` 表示列模式下的部分更新，更适合于具有少量列和许多行的批量更新。在这种情况下，启用列模式可以提供更快的更新速度。例如，在一个具有 100 列的表中，如果仅更新所有行的 10 列 (占总数的 10%)，则列模式的更新速度将快 10 倍。
- -## 使用注意事项 - -### Flush 策略 - -Kafka connector 会将数据缓存在内存中，并通过 Stream Load 将它们批量刷新到 StarRocks。当满足以下任何条件时，将触发刷新： - -- 缓冲行的字节数达到限制 `bufferflush.maxbytes`。 -- 自上次刷新以来经过的时间达到限制 `bufferflush.intervalms`。 -- 达到 connector 尝试提交任务偏移量的间隔。该间隔由 Kafka Connect 配置 [`offset.flush.interval.ms`](https://docs.confluent.io/platform/current/connect/references/allconfigs.html) 控制，默认值为 `60000`。 - -为了降低数据延迟，请调整 Kafka connector 设置中的这些配置。但是，更频繁的刷新会增加 CPU 和 I/O 使用率。 - -### 限制 - -- 不支持将来自 Kafka topic 的单个消息展平为多个数据行并加载到 StarRocks 中。 -- StarRocks 提供的 Kafka connector 的 sink 保证至少一次 (at-least-once) 的语义。 - -## 最佳实践 - -### 导入 Debezium 格式的 CDC 数据 - -Debezium 是一种流行的变更数据捕获 (Change Data Capture, CDC) 工具，支持监视各种数据库系统中的数据更改，并将这些更改流式传输到 Kafka。以下示例演示了如何配置和使用 Kafka connector 将 PostgreSQL 更改写入 StarRocks 中的 **Primary Key 表**。 - -#### 步骤 1：安装并启动 Kafka - -> **注意** -> -> 如果您有自己的 Kafka 环境，则可以跳过此步骤。 - -1. 从官方网站 [下载](https://dlcdn.apache.org/kafka/) 最新的 Kafka 版本并解压该软件包。 - - ```Bash - tar -xzf kafka_2.13-3.7.0.tgz - cd kafka_2.13-3.7.0 - ``` - -2. 启动 Kafka 环境。 - - 生成 Kafka 集群 UUID。 - - ```Bash - KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)" - ``` - - 格式化日志目录。 - - ```Bash - bin/kafka-storage.sh format -t $KAFKA_CLUSTER_ID -c config/kraft/server.properties - ``` - - 启动 Kafka 服务器。 - - ```Bash - bin/kafka-server-start.sh config/kraft/server.properties - ``` - -#### 步骤 2：配置 PostgreSQL - -1. 确保 PostgreSQL 用户被授予 `REPLICATION` 权限。 - -2. 调整 PostgreSQL 配置。 - - 在 **postgresql.conf** 中将 `wal_level` 设置为 `logical`。 - - ```Properties - wal_level = logical - ``` - - 重新启动 PostgreSQL 服务器以应用更改。 - - ```Bash - pg_ctl restart - ``` - -3. 准备数据集。 - - 创建一个表并插入测试数据。 - - ```SQL - CREATE TABLE customers ( - id int primary key , - first_name varchar(65533) NULL, - last_name varchar(65533) NULL , - email varchar(65533) NULL - ); - - INSERT INTO customers VALUES (1,'a','a','a@a.com'); - ``` - -4. 验证 Kafka 中的 CDC 日志消息。 - - ```Json - { - "schema": { - "type": "struct", - "fields": [ - { - "type": "struct", - "fields": [ - { - "type": "int32", - "optional": false, - "field": "id" - }, - { - "type": "string", - "optional": true, - "field": "first_name" - }, - { - "type": "string", - "optional": true, - "field": "last_name" - }, - { - "type": "string", - "optional": true, - "field": "email" - } - ], - "optional": true, - "name": "test.public.customers.Value", - "field": "before" - }, - { - "type": "struct", - "fields": [ - { - "type": "int32", - "optional": false, - "field": "id" - }, - { - "type": "string", - "optional": true, - "field": "first_name" - }, - { - "type": "string", - "optional": true, - "field": "last_name" - }, - { - "type": "string", - "optional": true, - "field": "email" - } - ], - "optional": true, - "name": "test.public.customers.Value", - "field": "after" - }, - { - "type": "struct", - "fields": [ - { - "type": "string", - "optional": false, - "field": "version" - }, - { - "type": "string", - "optional": false, - "field": "connector" - }, - { - "type": "string", - "optional": false, - "field": "name" - }, - { - "type": "int64", - "optional": false, - "field": "ts_ms" - }, - { - "type": "string", - "optional": true, - "name": "io.debezium.data.Enum", - "version": 1, - "parameters": { - "allowed": "true,last,false,incremental" - }, - "default": "false", - "field": "snapshot" - }, - { - "type": "string", - "optional": false, - "field": "db" - }, - { - "type": "string", - "optional": true, - "field": "sequence" - }, - { - "type": "string", - "optional": false, - "field": "schema" - }, - { - "type": "string", - "optional": false, - "field": "table" - }, - { - "type": "int64", - "optional": true, - "field": "txId" - }, - { - "type": "int64", - "optional": true, - "field": "lsn" - }, - { - "type": "int64", - "optional": true, - "field": "xmin" - } - ], - "optional": false, - "name": "io.debezium.connector.postgresql.Source", - "field": "source" - }, - { - "type": "string", - "optional": false, - "field": "op" - }, - { - "type": "int64", - "optional": true, - "field": "ts_ms" - }, - { - "type": "struct", - "fields": [ - { - "type": "string", - "optional": false, - "field": "id" - }, - { - "type": "int64", - "optional": false, - "field": "total_order" - }, - { - "type": "int64", - "optional": false, - "field": "data_collection_order" - } - ], - "optional": true, - "name": "event.block", - "version": 1, - "field": "transaction" - } - ], - "optional": false, - "name": "test.public.customers.Envelope", - "version": 1 - }, - "payload": { - "before": null, - "after": { - "id": 1, - "first_name": "a", - "last_name": "a", - "email": "a@a.com" - }, - "source": { - "version": "2.5.3.Final", - "connector": "postgresql", - "name": "test", - "ts_ms": 1714283798721, - "snapshot": "false", - "db": "postgres", - "sequence": "[\"22910216\",\"22910504\"]", - "schema": "public", - "table": "customers", - "txId": 756, - "lsn": 22910504, - "xmin": null - }, - "op": "c", - "ts_ms": 1714283798790, - "transaction": null - } - } - ``` - -#### 步骤 3：配置 StarRocks - -在 StarRocks 中创建一个 Primary Key 表，其 schema 与 PostgreSQL 中的源表相同。 - -```SQL -CREATE TABLE `customers` ( - `id` int(11) COMMENT "", - `first_name` varchar(65533) NULL COMMENT "", - `last_name` varchar(65533) NULL COMMENT "", - `email` varchar(65533) NULL COMMENT "" -) ENGINE=OLAP -PRIMARY KEY(`id`) -DISTRIBUTED BY hash(id) buckets 1 -PROPERTIES ( -"bucket_size" = "4294967296", -"in_memory" = "false", -"enable_persistent_index" = "true", -"replicated_storage" = "true", -"fast_schema_evolution" = "true" -); -``` - -#### 步骤 4：安装 connector - -1. 下载 connectors 并在 **plugins** 目录中解压软件包。 - - ```Bash - mkdir plugins - tar -zxvf debezium-debezium-connector-postgresql-2.5.3.zip -C plugins - mv starrocks-connector-for-kafka-x.y.z-with-dependencies.jar plugins - ``` - - 此目录是 **config/connect-standalone.properties** 中配置项 `plugin.path` 的值。 - - ```Properties - plugin.path=/path/to/kafka_2.13-3.7.0/plugins - ``` - -2. 在 **pg-source.properties** 中配置 PostgreSQL 源 connector。 - - ```Json - { - "name": "inventory-connector", - "config": { - "connector.class": "io.debezium.connector.postgresql.PostgresConnector", - "plugin.name": "pgoutput", - "database.hostname": "localhost", - "database.port": "5432", - "database.user": "postgres", - "database.password": "", - "database.dbname" : "postgres", - "topic.prefix": "test" - } - } - ``` - -3. 在 **sr-sink.properties** 中配置 StarRocks sink connector。 - - ```Json - { - "name": "starrocks-kafka-connector", - "config": { - "connector.class": "com.starrocks.connector.kafka.StarRocksSinkConnector", - "tasks.max": "1", - "topics": "test.public.customers", - "starrocks.http.url": "172.26.195.69:28030", - "starrocks.database.name": "test", - "starrocks.username": "root", - "starrocks.password": "StarRocks@123", - "sink.properties.strip_outer_array": "true", - "connect.timeoutms": "3000", - "starrocks.topic2table.map": "test.public.customers:customers", - "transforms": "addfield,unwrap", - "transforms.addfield.type": "com.starrocks.connector.kafka.transforms.AddOpFieldForDebeziumRecord", - "transforms.unwrap.type": "io.debezium.transforms.ExtractNewRecordState", - "transforms.unwrap.drop.tombstones": "true", - "transforms.unwrap.delete.handling.mode": "rewrite" - } - } - ``` - - > **注意** - > - > - 如果 StarRocks 表不是 Primary Key 表，则无需指定 `addfield` 转换。 - > - unwrap 转换由 Debezium 提供，用于根据操作类型解包 Debezium 的复杂数据结构。有关更多信息，请参见 [New Record State Extraction](https://debezium.io/documentation/reference/stable/transformations/event-flattening.html)。 - -4. 配置 Kafka Connect。 - - 在 Kafka Connect 配置文件 **config/connect-standalone.properties** 中配置以下配置项。 - - ```Properties - # Kafka brokers 的地址。多个 Kafka brokers 的地址需要用逗号 (,) 分隔。 - # 请注意，本示例使用 PLAINTEXT 作为访问 Kafka 集群的安全协议。 - # 如果您使用其他安全协议访问 Kafka 集群，请在此部分配置相关信息。 - - bootstrap.servers=:9092 - offset.storage.file.filename=/tmp/connect.offsets - key.converter=org.apache.kafka.connect.json.JsonConverter - value.converter=org.apache.kafka.connect.json.JsonConverter - key.converter.schemas.enable=true - value.converter.schemas.enable=false - - # starrocks-connector-for-kafka-x.y.z-with-dependencies.jar 的绝对路径。 - plugin.path=/home/kafka-connect/starrocks-kafka-connector - - # 控制刷新策略的参数。有关更多信息，请参见“使用注意事项”部分。 - offset.flush.interval.ms=10000 - bufferflush.maxbytes = xxx - bufferflush.intervalms = xxx - ``` - - 有关更多参数的描述，请参见 [Running Kafka Connect](https://kafka.apache.org/documentation.html#connect_running)。 - -#### 步骤 5：在独立模式下启动 Kafka Connect - -在独立模式下运行 Kafka Connect 以启动 connectors。 - -```Bash -bin/connect-standalone.sh config/connect-standalone.properties config/pg-source.properties config/sr-sink.properties -``` - -#### 步骤 6：验证数据摄取 - -测试以下操作，并确保数据已正确摄取到 StarRocks 中。 - -##### INSERT - -- 在 PostgreSQL 中： - -```Plain -postgres=# insert into customers values (2,'b','b','b@b.com'); -INSERT 0 1 -postgres=# select * from customers; - id | first_name | last_name | email -----+------------+-----------+--------- - 1 | a | a | a@a.com - 2 | b | b | b@b.com -(2 rows) -``` - -- 在 StarRocks 中： - -```Plain -MySQL [test]> select * from customers; -+------+------------+-----------+---------+ -| id | first_name | last_name | email | -+------+------------+-----------+---------+ -| 1 | a | a | a@a.com | -| 2 | b | b | b@b.com | -+------+------------+-----------+---------+ -2 rows in set (0.01 sec) -``` - -##### UPDATE - -- 在 PostgreSQL 中： - -```Plain -postgres=# update customers set email='c@c.com'; -UPDATE 2 -postgres=# select * from customers; - id | first_name | last_name | email -----+------------+-----------+--------- - 1 | a | a | c@c.com - 2 | b | b | c@c.com -(2 rows) -``` - -- 在 StarRocks 中： - -```Plain -MySQL [test]> select * from customers; -+------+------------+-----------+---------+ -| id | first_name | last_name | email | -+------+------------+-----------+---------+ -| 1 | a | a | c@c.com | -| 2 | b | b | c@c.com | -+------+------------+-----------+---------+ -2 rows in set (0.00 sec) -``` - -##### DELETE - -- 在 PostgreSQL 中： - -```Plain -postgres=# delete from customers where id=1; -DELETE 1 -postgres=# select * from customers; - id | first_name | last_name | email -----+------------+-----------+--------- - 2 | b | b | c@c.com -(1 row) -``` - -- 在 StarRocks 中： - -```Plain -MySQL [test]> select * from customers; -+------+------------+-----------+---------+ -| id | first_name | last_ \ No newline at end of file diff --git a/docs/zh/loading/Load_to_Primary_Key_tables.md b/docs/zh/loading/Load_to_Primary_Key_tables.md deleted file mode 100644 index 152e81d..0000000 --- a/docs/zh/loading/Load_to_Primary_Key_tables.md +++ /dev/null @@ -1,709 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 通过导入更改数据 - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -StarRocks 提供的 [主键表](../table_design/table_types/primary_key_table.md) 允许您通过运行 [Stream Load](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md) 、[Broker Load](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md) 或 [Routine Load](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md) 作业来更改 StarRocks 表中的数据。这些数据更改包括插入、更新和删除。但是，主键表不支持使用 [Spark Load](../sql-reference/sql-statements/loading_unloading/SPARK_LOAD.md) 或 [INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md) 更改数据。 - -StarRocks 还支持部分更新和条件更新。 - - - -本主题以 CSV 数据为例，介绍如何通过导入更改 StarRocks 表中的数据。支持的数据文件格式因您选择的导入方法而异。 - -> **NOTE** -> -> 对于 CSV 数据，您可以使用 UTF-8 字符串（例如逗号 (,)、制表符或管道 (|)），其长度不超过 50 字节作为文本分隔符。 - -## 实现 - -StarRocks 提供的主键表支持 UPSERT 和 DELETE 操作，并且不区分 INSERT 操作和 UPDATE 操作。 - -创建导入作业时，StarRocks 支持向作业创建语句或命令添加名为 `__op` 的字段。 `__op` 字段用于指定要执行的操作类型。 - -> **NOTE** -> -> 创建表时，无需向该表添加名为 `__op` 的列。 - -定义 `__op` 字段的方法因您选择的导入方法而异： - -- 如果选择 Stream Load，请使用 `columns` 参数定义 `__op` 字段。 - -- 如果选择 Broker Load，请使用 SET 子句定义 `__op` 字段。 - -- 如果选择 Routine Load，请使用 `COLUMNS` 列定义 `__op` 字段。 - -您可以根据要进行的数据更改来决定是否添加 `__op` 字段。如果未添加 `__op` 字段，则操作类型默认为 UPSERT。主要的数据更改场景如下： - -- 如果要导入的数据文件仅涉及 UPSERT 操作，则无需添加 `__op` 字段。 - -- 如果要导入的数据文件仅涉及 DELETE 操作，则必须添加 `__op` 字段并将操作类型指定为 DELETE。 - -- 如果要导入的数据文件同时涉及 UPSERT 和 DELETE 操作，则必须添加 `__op` 字段，并确保数据文件包含一个列，其值为 `0` 或 `1`。值 `0` 表示 UPSERT 操作，值 `1` 表示 DELETE 操作。 - -## 使用说明 - -- 确保数据文件中的每一行都具有相同数量的列。 - -- 涉及数据更改的列必须包含主键列。 - -## 基本操作 - -本节提供有关如何通过导入更改 StarRocks 表中的数据的示例。有关详细的语法和参数说明，请参见 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md) 、[BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md) 和 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。 - -### UPSERT - -如果要导入的数据文件仅涉及 UPSERT 操作，则无需添加 `__op` 字段。 - -> **NOTE** -> -> 如果添加 `__op` 字段： -> -> - 可以将操作类型指定为 UPSERT。 -> -> - 可以将 `__op` 字段留空，因为操作类型默认为 UPSERT。 - -#### 数据示例 - -1. 准备数据文件。 - - a. 在本地文件系统中创建一个名为 `example1.csv` 的 CSV 文件。该文件由三列组成，依次表示用户 ID、用户名和用户分数。 - - ```Plain - 101,Lily,100 - 102,Rose,100 - ``` - - b. 将 `example1.csv` 的数据发布到 Kafka 集群的 `topic1`。 - -2. 准备 StarRocks 表。 - - a. 在 StarRocks 数据库 `test_db` 中创建一个名为 `table1` 的主键表。该表由三列组成：`id`、`name` 和 `score`，其中 `id` 是主键。 - - ```SQL - CREATE TABLE `table1` - ( - `id` int(11) NOT NULL COMMENT "user ID", - `name` varchar(65533) NOT NULL COMMENT "user name", - `score` int(11) NOT NULL COMMENT "user score" - ) - ENGINE=OLAP - PRIMARY KEY(`id`) - DISTRIBUTED BY HASH(`id`); - ``` - - > **NOTE** - > - > 从 v2.5.7 开始，StarRocks 可以在创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - - b. 将一条记录插入到 `table1` 中。 - - ```SQL - INSERT INTO table1 VALUES - (101, 'Lily',80); - ``` - -#### 导入数据 - -运行一个导入作业，以将 `example1.csv` 中 `id` 为 `101` 的记录更新到 `table1`，并将 `example1.csv` 中 `id` 为 `102` 的记录插入到 `table1`。 - -- 运行 Stream Load 作业。 - - - 如果不想包含 `__op` 字段，请运行以下命令： - - ```Bash - curl --location-trusted -u : \ - -H "Expect:100-continue" \ - -H "label:label1" \ - -H "column_separator:," \ - -T example1.csv -XPUT \ - http://:/api/test_db/table1/_stream_load - ``` - - - 如果想包含 `__op` 字段，请运行以下命令： - - ```Bash - curl --location-trusted -u : \ - -H "Expect:100-continue" \ - -H "label:label2" \ - -H "column_separator:," \ - -H "columns:__op ='upsert'" \ - -T example1.csv -XPUT \ - http://:/api/test_db/table1/_stream_load - ``` - -- 运行 Broker Load 作业。 - - - 如果不想包含 `__op` 字段，请运行以下命令： - - ```SQL - LOAD LABEL test_db.label1 - ( - data infile("hdfs://:/example1.csv") - into table table1 - columns terminated by "," - format as "csv" - ) - WITH BROKER; - ``` - - - 如果想包含 `__op` 字段，请运行以下命令： - - ```SQL - LOAD LABEL test_db.label2 - ( - data infile("hdfs://:/example1.csv") - into table table1 - columns terminated by "," - format as "csv" - set (__op = 'upsert') - ) - WITH BROKER; - ``` - -- 运行 Routine Load 作业。 - - - 如果不想包含 `__op` 字段，请运行以下命令： - - ```SQL - CREATE ROUTINE LOAD test_db.table1 ON table1 - COLUMNS TERMINATED BY ",", - COLUMNS (id, name, score) - PROPERTIES - ( - "desired_concurrent_number" = "3", - "max_batch_interval" = "20", - "max_batch_rows"= "250000", - "max_error_number" = "1000" - ) - FROM KAFKA - ( - "kafka_broker_list" =":", - "kafka_topic" = "test1", - "property.kafka_default_offsets" ="OFFSET_BEGINNING" - ); - ``` - - - 如果想包含 `__op` 字段，请运行以下命令： - - ```SQL - CREATE ROUTINE LOAD test_db.table1 ON table1 - COLUMNS TERMINATED BY ",", - COLUMNS (id, name, score, __op ='upsert') - PROPERTIES - ( - "desired_concurrent_number" = "3", - "max_batch_interval" = "20", - "max_batch_rows"= "250000", - "max_error_number" = "1000" - ) - FROM KAFKA - ( - "kafka_broker_list" =":", - "kafka_topic" = "test1", - "property.kafka_default_offsets" ="OFFSET_BEGINNING" - ); - ``` - -#### 查询数据 - -导入完成后，查询 `table1` 的数据以验证导入是否成功： - -```SQL -SELECT * FROM table1; -+------+------+-------+ -| id | name | score | -+------+------+-------+ -| 101 | Lily | 100 | -| 102 | Rose | 100 | -+------+------+-------+ -2 rows in set (0.02 sec) -``` - -如上述查询结果所示，`example1.csv` 中 `id` 为 `101` 的记录已更新到 `table1`，并且 `example1.csv` 中 `id` 为 `102` 的记录已插入到 `table1` 中。 - -### DELETE - -如果要导入的数据文件仅涉及 DELETE 操作，则必须添加 `__op` 字段并将操作类型指定为 DELETE。 - -#### 数据示例 - -1. 准备数据文件。 - - a. 在本地文件系统中创建一个名为 `example2.csv` 的 CSV 文件。该文件由三列组成，依次表示用户 ID、用户名和用户分数。 - - ```Plain - 101,Jack,100 - ``` - - b. 将 `example2.csv` 的数据发布到 Kafka 集群的 `topic2`。 - -2. 准备 StarRocks 表。 - - a. 在 StarRocks 数据库 `test_db` 中创建一个名为 `table2` 的主键表。该表由三列组成：`id`、`name` 和 `score`，其中 `id` 是主键。 - - ```SQL - CREATE TABLE `table2` - ( - `id` int(11) NOT NULL COMMENT "user ID", - `name` varchar(65533) NOT NULL COMMENT "user name", - `score` int(11) NOT NULL COMMENT "user score" - ) - ENGINE=OLAP - PRIMARY KEY(`id`) - DISTRIBUTED BY HASH(`id`); - ``` - - > **NOTE** - > - > 从 v2.5.7 开始，StarRocks 可以在创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - - b. 将两条记录插入到 `table2` 中。 - - ```SQL - INSERT INTO table2 VALUES - (101, 'Jack', 100), - (102, 'Bob', 90); - ``` - -#### 导入数据 - -运行一个导入作业，以从 `table2` 中删除 `example2.csv` 中 `id` 为 `101` 的记录。 - -- 运行 Stream Load 作业。 - - ```Bash - curl --location-trusted -u : \ - -H "Expect:100-continue" \ - -H "label:label3" \ - -H "column_separator:," \ - -H "columns:__op='delete'" \ - -T example2.csv -XPUT \ - http://:/api/test_db/table2/_stream_load - ``` - -- 运行 Broker Load 作业。 - - ```SQL - LOAD LABEL test_db.label3 - ( - data infile("hdfs://:/example2.csv") - into table table2 - columns terminated by "," - format as "csv" - set (__op = 'delete') - ) - WITH BROKER; - ``` - -- 运行 Routine Load 作业。 - - ```SQL - CREATE ROUTINE LOAD test_db.table2 ON table2 - COLUMNS(id, name, score, __op = 'delete') - PROPERTIES - ( - "desired_concurrent_number" = "3", - "max_batch_interval" = "20", - "max_batch_rows"= "250000", - "max_error_number" = "1000" - ) - FROM KAFKA - ( - "kafka_broker_list" =":", - "kafka_topic" = "test2", - "property.kafka_default_offsets" ="OFFSET_BEGINNING" - ); - ``` - -#### 查询数据 - -导入完成后，查询 `table2` 的数据以验证导入是否成功： - -```SQL -SELECT * FROM table2; -+------+------+-------+ -| id | name | score | -+------+------+-------+ -| 102 | Bob | 90 | -+------+------+-------+ -1 row in set (0.00 sec) -``` - -如上述查询结果所示，`example2.csv` 中 `id` 为 `101` 的记录已从 `table2` 中删除。 - -### UPSERT 和 DELETE - -如果要导入的数据文件同时涉及 UPSERT 和 DELETE 操作，则必须添加 `__op` 字段，并确保数据文件包含一个列，其值为 `0` 或 `1`。值 `0` 表示 UPSERT 操作，值 `1` 表示 DELETE 操作。 - -#### 数据示例 - -1. 准备数据文件。 - - a. 在本地文件系统中创建一个名为 `example3.csv` 的 CSV 文件。该文件由四列组成，依次表示用户 ID、用户名、用户分数和操作类型。 - - ```Plain - 101,Tom,100,1 - 102,Sam,70,0 - 103,Stan,80,0 - ``` - - b. 将 `example3.csv` 的数据发布到 Kafka 集群的 `topic3`。 - -2. 准备 StarRocks 表。 - - a. 在 StarRocks 数据库 `test_db` 中创建一个名为 `table3` 的主键表。该表由三列组成：`id`、`name` 和 `score`，其中 `id` 是主键。 - - ```SQL - CREATE TABLE `table3` - ( - `id` int(11) NOT NULL COMMENT "user ID", - `name` varchar(65533) NOT NULL COMMENT "user name", - `score` int(11) NOT NULL COMMENT "user score" - ) - ENGINE=OLAP - PRIMARY KEY(`id`) - DISTRIBUTED BY HASH(`id`); - ``` - - > **NOTE** - > - > 从 v2.5.7 开始，StarRocks 可以在创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - - b. 将两条记录插入到 `table3` 中。 - - ```SQL - INSERT INTO table3 VALUES - (101, 'Tom', 100), - (102, 'Sam', 90); - ``` - -#### 导入数据 - -运行一个导入作业，以从 `table3` 中删除 `example3.csv` 中 `id` 为 `101` 的记录，将 `example3.csv` 中 `id` 为 `102` 的记录更新到 `table3`，并将 `example3.csv` 中 `id` 为 `103` 的记录插入到 `table3`。 - -- 运行 Stream Load 作业： - - ```Bash - curl --location-trusted -u : \ - -H "Expect:100-continue" \ - -H "label:label4" \ - -H "column_separator:," \ - -H "columns: id, name, score, temp, __op = temp" \ - -T example3.csv -XPUT \ - http://:/api/test_db/table3/_stream_load - ``` - - > **NOTE** - > - > 在上面的示例中，`example3.csv` 中表示操作类型的第四列暂时命名为 `temp`，并且 `__op` 字段通过 `columns` 参数映射到 `temp` 列。这样，StarRocks 可以根据 `example3.csv` 的第四列中的值是 `0` 还是 `1` 来决定是执行 UPSERT 还是 DELETE 操作。 - -- 运行 Broker Load 作业： - - ```Bash - LOAD LABEL test_db.label4 - ( - data infile("hdfs://:/example1.csv") - into table table1 - columns terminated by "," - format as "csv" - (id, name, score, temp) - set (__op=temp) - ) - WITH BROKER; - ``` - -- 运行 Routine Load 作业： - - ```SQL - CREATE ROUTINE LOAD test_db.table3 ON table3 - COLUMNS(id, name, score, temp, __op = temp) - PROPERTIES - ( - "desired_concurrent_number" = "3", - "max_batch_interval" = "20", - "max_batch_rows"= "250000", - "max_error_number" = "1000" - ) - FROM KAFKA - ( - "kafka_broker_list" = ":", - "kafka_topic" = "test3", - "property.kafka_default_offsets" = "OFFSET_BEGINNING" - ); - ``` - -#### 查询数据 - -导入完成后，查询 `table3` 的数据以验证导入是否成功： - -```SQL -SELECT * FROM table3; -+------+------+-------+ -| id | name | score | -+------+------+-------+ -| 102 | Sam | 70 | -| 103 | Stan | 80 | -+------+------+-------+ -2 rows in set (0.01 sec) -``` - -如上述查询结果所示，`example3.csv` 中 `id` 为 `101` 的记录已从 `table3` 中删除，`example3.csv` 中 `id` 为 `102` 的记录已更新到 `table3`，并且 `example3.csv` 中 `id` 为 `103` 的记录已插入到 `table3` 中。 - -## 部分更新 - -主键表还支持部分更新，并为不同的数据更新场景提供两种部分更新模式：行模式和列模式。这两种部分更新模式可以在保证查询性能的同时，尽可能地减少部分更新的开销，从而确保实时更新。行模式更适合涉及许多列和小批量的实时更新场景。列模式适用于涉及少量列和大量行的批量处理更新场景。 - -> **NOTICE** -> -> 执行部分更新时，如果要更新的行不存在，StarRocks 会插入一个新行，并在由于没有数据更新插入而为空的字段中填充默认值。 - -本节以 CSV 为例，介绍如何执行部分更新。 - -### 数据示例 - -1. 准备数据文件。 - - a. 在本地文件系统中创建一个名为 `example4.csv` 的 CSV 文件。该文件由两列组成，依次表示用户 ID 和用户名。 - - ```Plain - 101,Lily - 102,Rose - 103,Alice - ``` - - b. 将 `example4.csv` 的数据发布到 Kafka 集群的 `topic4`。 - -2. 准备 StarRocks 表。 - - a. 在 StarRocks 数据库 `test_db` 中创建一个名为 `table4` 的主键表。该表由三列组成：`id`、`name` 和 `score`，其中 `id` 是主键。 - - ```SQL - CREATE TABLE `table4` - ( - `id` int(11) NOT NULL COMMENT "user ID", - `name` varchar(65533) NOT NULL COMMENT "user name", - `score` int(11) NOT NULL COMMENT "user score" - ) - ENGINE=OLAP - PRIMARY KEY(`id`) - DISTRIBUTED BY HASH(`id`); - ``` - - > **NOTE** - > - > 从 v2.5.7 开始，StarRocks 可以在创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - - b. 将一条记录插入到 `table4` 中。 - - ```SQL - INSERT INTO table4 VALUES - (101, 'Tom',80); - ``` - -### 导入数据 - -运行一个导入作业，以将 `example4.csv` 中两列的数据更新到 `table4` 的 `id` 和 `name` 列。 - -- 运行 Stream Load 作业： - - ```Bash - curl --location-trusted -u : \ - -H "Expect:100-continue" \ - -H "label:label7" -H "column_separator:," \ - -H "partial_update:true" \ - -H "columns:id,name" \ - -T example4.csv -XPUT \ - http://:/api/test_db/table4/_stream_load - ``` - - > **NOTE** - > - > 如果选择 Stream Load，则必须将 `partial_update` 参数设置为 `true` 才能启用部分更新功能。默认情况下，是行模式下的部分更新。如果需要执行列模式下的部分更新，则需要将 `partial_update_mode` 设置为 `column`。此外，必须使用 `columns` 参数指定要更新的列。 - -- 运行 Broker Load 作业： - - ```SQL - LOAD LABEL test_db.table4 - ( - data infile("hdfs://:/example4.csv") - into table table4 - format as "csv" - (id, name) - ) - WITH BROKER - PROPERTIES - ( - "partial_update" = "true" - ); - ``` - - > **NOTE** - > - > 如果选择 Broker Load，则必须将 `partial_update` 参数设置为 `true` 才能启用部分更新功能。默认情况下，是行模式下的部分更新。如果需要执行列模式下的部分更新，则需要将 `partial_update_mode` 设置为 `column`。此外，必须使用 `column_list` 参数指定要更新的列。 - -- 运行 Routine Load 作业： - - ```SQL - CREATE ROUTINE LOAD test_db.table4 on table4 - COLUMNS (id, name), - COLUMNS TERMINATED BY ',' - PROPERTIES - ( - "partial_update" = "true" - ) - FROM KAFKA - ( - "kafka_broker_list" =":", - "kafka_topic" = "test4", - "property.kafka_default_offsets" ="OFFSET_BEGINNING" - ); - ``` - - > **NOTE** - > - > - 如果选择 Routine Load，则必须将 `partial_update` 参数设置为 `true` 才能启用部分更新功能。此外，必须使用 `COLUMNS` 参数指定要更新的列。 - > - Routine Load 仅支持行模式下的部分更新，不支持列模式下的部分更新。 - -### 查询数据 - -导入完成后，查询 `table4` 的数据以验证导入是否成功： - -```SQL -SELECT * FROM table4; -+------+-------+-------+ -| id | name | score | -+------+-------+-------+ -| 102 | Rose | 0 | -| 101 | Lily | 80 | -| 103 | Alice | 0 | -+------+-------+-------+ -3 rows in set (0.01 sec) -``` - -如上述查询结果所示，`example4.csv` 中 `id` 为 `101` 的记录已更新到 `table4`，并且 `example4.csv` 中 `id` 为 `102` 和 `103` 的记录已插入到 `table4`。 - -## 条件更新 - -从 StarRocks v2.5 开始，主键表支持条件更新。您可以指定一个非主键列作为条件，以确定更新是否可以生效。这样，仅当源数据记录在指定列中具有大于或等于目标数据记录的值时，从源记录到目标记录的更新才会生效。 - -条件更新功能旨在解决数据无序问题。如果源数据是无序的，则可以使用此功能来确保新数据不会被旧数据覆盖。 - -> **NOTICE** -> -> - 不能为同一批数据指定不同的列作为更新条件。 -> - DELETE 操作不支持条件更新。 -> - 在低于 v3.1.3 的版本中，部分更新和条件更新不能同时使用。从 v3.1.3 开始，StarRocks 支持将部分更新与条件更新一起使用。 - -### 数据示例 - -1. 准备数据文件。 - - a. 在本地文件系统中创建一个名为 `example5.csv` 的 CSV 文件。该文件由三列组成，依次表示用户 ID、版本和用户分数。 - - ```Plain - 101,1,100 - 102,3,100 - ``` - - b. 将 `example5.csv` 的数据发布到 Kafka 集群的 `topic5`。 - -2. 准备 StarRocks 表。 - - a. 在 StarRocks 数据库 `test_db` 中创建一个名为 `table5` 的主键表。该表由三列组成：`id`、`version` 和 `score`，其中 `id` 是主键。 - - ```SQL - CREATE TABLE `table5` - ( - `id` int(11) NOT NULL COMMENT "user ID", - `version` int NOT NULL COMMENT "version", - `score` int(11) NOT NULL COMMENT "user score" - ) - ENGINE=OLAP - PRIMARY KEY(`id`) DISTRIBUTED BY HASH(`id`); - ``` - - > **NOTE** - > - > 从 v2.5.7 开始，StarRocks 可以在创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - - b. 将一条记录插入到 `table5` 中。 - - ```SQL - INSERT INTO table5 VALUES - (101, 2, 80), - (102, 2, 90); - ``` - -### 导入数据 - -运行一个导入作业，以将 `example5.csv` 中 `id` 值分别为 `101` 和 `102` 的记录更新到 `table5`，并指定仅当两条记录中的 `version` 值大于或等于其当前的 `version` 值时，更新才会生效。 - -- 运行 Stream Load 作业： - - ```Bash - curl --location-trusted -u : \ - -H "Expect:100-continue" \ - -H "label:label10" \ - -H "column_separator:," \ - -H "merge_condition:version" \ - -T example5.csv -XPUT \ - http://:/api/test_db/table5/_stream_load - ``` -- 运行 Insert Load 作业: - ```SQL - INSERT INTO test_db.table5 properties("merge_condition" = "version") - VALUES (101, 2, 70), (102, 3, 100); - ``` - -- 运行 Routine Load 作业： - - ```SQL - CREATE ROUTINE LOAD test_db.table5 on table5 - COLUMNS (id, version, score), - COLUMNS TERMINATED BY ',' - PROPERTIES - ( - "merge_condition" = "version" - ) - FROM KAFKA - ( - "kafka_broker_list" =":", - "kafka_topic" = "topic5", - "property.kafka_default_offsets" ="OFFSET_BEGINNING" - ); - ``` - -- 运行 Broker Load 作业： - - ```SQL - LOAD LABEL test_db.table5 - ( DATA INFILE ("s3://xxx.csv") - INTO TABLE table5 COLUMNS TERMINATED BY "," FORMAT AS "CSV" - ) - WITH BROKER - PROPERTIES - ( - "merge_condition" = "version" - ); - ``` - -### 查询数据 - -导入完成后，查询 `table5` 的数据以验证导入是否成功： - -```SQL -SELECT * FROM table5; -+------+------+-------+ -| id | version | score | -+------+------+-------+ -| 101 | 2 | 80 | -| 102 | 3 | 100 | -+------+------+-------+ -2 rows in set (0.02 sec) -``` - -如上述查询结果所示，`example5.csv` 中 `id` 为 `101` 的记录未更新到 `table5`，并且 `example5.csv` 中 `id` 为 `102` 的记录已插入到 `table5`。 \ No newline at end of file diff --git a/docs/zh/loading/Loading_data_template.md b/docs/zh/loading/Loading_data_template.md deleted file mode 100644 index 1e51707..0000000 --- a/docs/zh/loading/Loading_data_template.md +++ /dev/null @@ -1,399 +0,0 @@ ---- -displayed_sidebar: docs -unlisted: true ---- - -# 从 \ 模板加载数据 - -## 模板说明 - -### 关于样式的说明 - -技术文档通常包含指向各处其他文档的链接。查看此文档时，您可能会注意到页面上的链接很少，几乎所有链接都位于文档底部的**更多信息**部分。并非每个关键字都需要链接到另一个页面，请假定读者知道 `CREATE TABLE` 的含义，如果他们不知道，他们可以点击搜索栏来查找。可以在文档中添加注释，告诉读者还有其他选项，详细信息在**更多信息**部分中进行了描述；这可以让需要信息的人知道他们可以在完成手头的任务后***稍后***阅读它。 - -### 模板 - -此模板基于从 Amazon S3 加载数据的过程，其中的某些部分不适用于从其他来源加载数据。请专注于此模板的流程，不要担心包含每个部分；流程应为： - -#### 简介 - -介绍性文字，让读者知道如果他们遵循本指南，最终结果会是什么。对于 S3 文档，最终结果是“以异步或同步方式从 S3 加载数据”。 - -#### 为什么？ - -- 对使用该技术解决的业务问题的描述 -- 所描述方法（如果存在）的优点和缺点 - -#### 数据流或其他图表 - -图表或图像可能会有所帮助。如果您描述的技术很复杂并且图像有帮助，请使用一个。如果您描述的技术会产生一些可视化的东西（例如，使用 Superset 分析数据），那么一定要包含最终产品的图像。 - -如果流程不明显，请使用数据流图。当命令导致 StarRocks 运行多个进程并组合这些进程的输出，然后操作数据时，可能需要描述数据流。在此模板中，描述了两种加载数据的方法。其中一种很简单，没有数据流部分；另一种更复杂（StarRocks 正在处理复杂的工作，而不是用户！），并且复杂的选项包括数据流部分。 - -#### 带有验证部分的示例 - -请注意，示例应位于语法详细信息和其他深入的技术详细信息之前。许多读者会来阅读文档以查找他们可以复制、粘贴和修改的特定技术。 - -如果可能，请提供一个可以工作的示例，并包含要使用的数据集。此模板中的示例使用存储在 S3 中的数据集，任何拥有 AWS 账户并且可以使用密钥和密码进行身份验证的人都可以使用该数据集。通过提供数据集，示例对读者更有价值，因为他们可以充分体验所描述的技术。 - -确保示例按编写方式工作。这意味着两件事： - -1. 您已按呈现的顺序运行命令 -2. 您已包含必要的先决条件。例如，如果您的示例引用数据库 `foo`，那么您可能需要以 `CREATE DATABASE foo;`、`USE foo;` 作为前缀。 - -验证非常重要。如果您描述的过程包括多个步骤，那么每当应该完成某些事情时，都包含一个验证步骤；这有助于避免读者到达终点并意识到他们在第 10 步中存在拼写错误。在此示例中，“检查进度”和 `DESCRIBE user_behavior_inferred;` 步骤用于验证。 - -#### 更多信息 - -在模板的末尾，有一个位置可以放置指向相关信息的链接，包括您在正文中提到的可选信息的链接。 - -### 嵌入在模板中的注释 - -模板注释的格式与我们格式化文档注释的方式有意不同，以便在您处理模板时引起您的注意。请删除粗体斜体注释： - -```markdown -***Note: descriptive text*** -``` - -## 最后，模板的开始 - -***Note: If there are multiple recommended choices, tell the -reader this in the intro. For example, when loading from S3, -there is an option for synchronous loading, and asynchronous loading:*** - -StarRocks 提供了两种从 S3 加载数据的选项： - -1. 使用 Broker Load 进行异步加载 -2. 使用 `FILES()` 表函数进行同步加载 - -***Note: Tell the reader WHY they would choose one choice over the other:*** - -小型数据集通常使用 `FILES()` 表函数同步加载，大型数据集通常使用 Broker Load 异步加载。这两种方法各有优点，如下所述。 - -> **NOTE** -> -> 只有对 StarRocks 表具有 INSERT 权限的用户才能将数据加载到 StarRocks 表中。如果您没有 INSERT 权限，请按照 [GRANT](../sql-reference/sql-statements/account-management/GRANT.md) 中提供的说明，将 INSERT 权限授予用于连接到 StarRocks 集群的用户。 - -## 使用 Broker Load - -异步 Broker Load 进程处理与 S3 的连接、提取数据以及将数据存储在 StarRocks 中。 - -### Broker Load 的优点 - -- Broker Load 支持在加载期间进行数据转换、UPSERT 和 DELETE 操作。 -- Broker Load 在后台运行，客户端无需保持连接即可继续作业。 -- Broker Load 是长时间运行作业的首选，默认超时时间为 4 小时。 -- 除了 Parquet 和 ORC 文件格式外，Broker Load 还支持 CSV 文件。 - -### 数据流 - -***Note: Processes that involve multiple components or steps may be easier to understand with a diagram. This example includes a diagram that helps describe the steps that happen when a user chooses the Broker Load option.*** - -![Broker Load 的工作流程](../_assets/broker_load_how-to-work_en.png) - -1. 用户创建一个 load job。 -2. 前端 (FE) 创建一个查询计划并将该计划分发到后端节点 (BE)。 -3. 后端 (BE) 节点从源提取数据并将数据加载到 StarRocks 中。 - -### 典型示例 - -创建一个表，启动一个从 S3 提取 Parquet 文件的 load 进程，并验证数据加载的进度和成功。 - -> **NOTE** -> -> 这些示例使用 Parquet 格式的示例数据集，如果您想加载 CSV 或 ORC 文件，该信息链接在此页面的底部。 - -#### 创建表 - -为您的表创建一个数据库： - -```SQL -CREATE DATABASE IF NOT EXISTS project; -USE project; -``` - -创建表。此 schema 匹配 StarRocks 账户中托管的 S3 bucket 中的示例数据集。 - -```SQL -DROP TABLE IF EXISTS user_behavior; - -CREATE TABLE `user_behavior` ( - `UserID` int(11), - `ItemID` int(11), - `CategoryID` int(11), - `BehaviorType` varchar(65533), - `Timestamp` datetime -) ENGINE=OLAP -DUPLICATE KEY(`UserID`) -DISTRIBUTED BY HASH(`UserID`) -PROPERTIES ( - "replication_num" = "1" -); -``` - -#### 收集连接详细信息 - -> **NOTE** -> -> 这些示例使用基于 IAM 用户的身份验证。其他身份验证方法可用，并链接在此页面的底部。 - -从 S3 加载数据需要具有： - -- S3 bucket -- S3 对象键（对象名称），如果访问 bucket 中的特定对象。请注意，如果您的 S3 对象存储在子文件夹中，则对象键可以包含前缀。完整语法链接在**更多信息**中。 -- S3 区域 -- 访问密钥和密码 - -#### 启动 Broker Load - -此作业有四个主要部分： - -- `LABEL`：查询 `LOAD` 作业状态时使用的字符串。 -- `LOAD` 声明：源 URI、目标表和源数据格式。 -- `BROKER`：源的连接详细信息。 -- `PROPERTIES`：超时值和应用于此作业的任何其他属性。 - -> **NOTE** -> -> 这些示例中使用的数据集托管在 StarRocks 账户的 S3 bucket 中。可以使用任何有效的 `aws.s3.access_key` 和 `aws.s3.secret_key`，因为任何 AWS 身份验证用户都可以读取该对象。在下面的命令中，将您的凭据替换为 `AAA` 和 `BBB`。 - -```SQL -LOAD LABEL user_behavior -( - DATA INFILE("s3://starrocks-examples/user_behavior_sample_data.parquet") - INTO TABLE user_behavior - FORMAT AS "parquet" - ) - WITH BROKER - ( - "aws.s3.enable_ssl" = "true", - "aws.s3.use_instance_profile" = "false", - "aws.s3.region" = "us-east-1", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" - ) -PROPERTIES -( - "timeout" = "72000" -); -``` - -#### 检查进度 - -查询 `information_schema.loads` 表以跟踪进度。如果您有多个 `LOAD` 作业正在运行，则可以按与该作业关联的 `LABEL` 进行过滤。在下面的输出中，load job `user_behavior` 有两个条目。第一个记录显示 `CANCELLED` 状态；滚动到输出的末尾，您会看到 `listPath failed`。第二个记录显示使用有效的 AWS IAM 访问密钥和密码成功。 - -```SQL -SELECT * FROM information_schema.loads; -``` - -```SQL -SELECT * FROM information_schema.loads WHERE LABEL = 'user_behavior'; -``` - -```plaintext -JOB_ID|LABEL |DATABASE_NAME|STATE |PROGRESS |TYPE |PRIORITY|SCAN_ROWS|FILTERED_ROWS|UNSELECTED_ROWS|SINK_ROWS|ETL_INFO|TASK_INFO |CREATE_TIME |ETL_START_TIME |ETL_FINISH_TIME |LOAD_START_TIME |LOAD_FINISH_TIME |JOB_DETAILS |ERROR_MSG |TRACKING_URL|TRACKING_SQL|REJECTED_RECORD_PATH| -------+-------------------------------------------+-------------+---------+-------------------+------+--------+---------+-------------+---------------+---------+--------+----------------------------------------------------+-------------------+-------------------+-------------------+-------------------+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------+------------+------------+--------------------+ - 10121|user_behavior |project |CANCELLED|ETL:N/A; LOAD:N/A |BROKER|NORMAL | 0| 0| 0| 0| |resource:N/A; timeout(s):72000; max_filter_ratio:0.0|2023-08-10 14:59:30| | | |2023-08-10 14:59:34|{"All backends":{},"FileNumber":0,"FileSize":0,"InternalTableLoadBytes":0,"InternalTableLoadRows":0,"ScanBytes":0,"ScanRows":0,"TaskNumber":0,"Unfinished backends":{}} |type:ETL_RUN_FAIL; msg:listPath failed| | | | - 10106|user_behavior |project |FINISHED |ETL:100%; LOAD:100%|BROKER|NORMAL | 86953525| 0| 0| 86953525| |resource:N/A; timeout(s):72000; max_filter_ratio:0.0|2023-08-10 14:50:15|2023-08-10 14:50:19|2023-08-10 14:50:19|2023-08-10 14:50:19|2023-08-10 14:55:10|{"All backends":{"a5fe5e1d-d7d0-4826-ba99-c7348f9a5f2f":[10004]},"FileNumber":1,"FileSize":1225637388,"InternalTableLoadBytes":2710603082,"InternalTableLoadRows":86953525,"ScanBytes":1225637388,"ScanRows":86953525,"TaskNumber":1,"Unfinished backends":{"a5| | | | | -``` - -您也可以在此处检查数据的子集。 - -```SQL -SELECT * from user_behavior LIMIT 10; -``` - -```plaintext -UserID|ItemID|CategoryID|BehaviorType|Timestamp | -------+------+----------+------------+-------------------+ -171146| 68873| 3002561|pv |2017-11-30 07:11:14| -171146|146539| 4672807|pv |2017-11-27 09:51:41| -171146|146539| 4672807|pv |2017-11-27 14:08:33| -171146|214198| 1320293|pv |2017-11-25 22:38:27| -171146|260659| 4756105|pv |2017-11-30 05:11:25| -171146|267617| 4565874|pv |2017-11-27 14:01:25| -171146|329115| 2858794|pv |2017-12-01 02:10:51| -171146|458604| 1349561|pv |2017-11-25 22:49:39| -171146|458604| 1349561|pv |2017-11-27 14:03:44| -171146|478802| 541347|pv |2017-12-02 04:52:39| -``` - -## 使用 `FILES()` 表函数 - -### `FILES()` 的优点 - -`FILES()` 可以推断 Parquet 数据列的数据类型，并为 StarRocks 表生成 schema。这提供了使用 `SELECT` 直接从 S3 查询文件，或者让 StarRocks 根据 Parquet 文件 schema 自动为您创建表的能力。 - -> **NOTE** -> -> Schema 推断是 3.1 版本中的一项新功能，仅适用于 Parquet 格式，并且尚不支持嵌套类型。 - -### 典型示例 - -有三个使用 `FILES()` 表函数的示例： - -- 直接从 S3 查询数据 -- 使用 schema 推断创建和加载表 -- 手动创建表，然后加载数据 - -> **NOTE** -> -> 这些示例中使用的数据集托管在 StarRocks 账户的 S3 bucket 中。可以使用任何有效的 `aws.s3.access_key` 和 `aws.s3.secret_key`，因为任何 AWS 身份验证用户都可以读取该对象。在下面的命令中，将您的凭据替换为 `AAA` 和 `BBB`。 - -#### 直接从 S3 查询 - -使用 `FILES()` 直接从 S3 查询可以在创建表之前很好地预览数据集的内容。例如： - -- 获取数据集的预览，而无需存储数据。 -- 查询最小值和最大值，并确定要使用的数据类型。 -- 检查 null 值。 - -```sql -SELECT * FROM FILES( - "path" = "s3://starrocks-examples/user_behavior_sample_data.parquet", - "format" = "parquet", - "aws.s3.region" = "us-east-1", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" -) LIMIT 10; -``` - -> **NOTE** -> -> 请注意，列名由 Parquet 文件提供。 - -```plaintext -UserID|ItemID |CategoryID|BehaviorType|Timestamp | -------+-------+----------+------------+-------------------+ - 1|2576651| 149192|pv |2017-11-25 01:21:25| - 1|3830808| 4181361|pv |2017-11-25 07:04:53| - 1|4365585| 2520377|pv |2017-11-25 07:49:06| - 1|4606018| 2735466|pv |2017-11-25 13:28:01| - 1| 230380| 411153|pv |2017-11-25 21:22:22| - 1|3827899| 2920476|pv |2017-11-26 16:24:33| - 1|3745169| 2891509|pv |2017-11-26 19:44:31| - 1|1531036| 2920476|pv |2017-11-26 22:02:12| - 1|2266567| 4145813|pv |2017-11-27 00:11:11| - 1|2951368| 1080785|pv |2017-11-27 02:47:08| -``` - -#### 使用 schema 推断创建表 - -这是前一个示例的延续；之前的查询包装在 `CREATE TABLE` 中，以使用 schema 推断自动创建表。使用带有 Parquet 文件的 `FILES()` 表函数时，不需要列名和类型来创建表，因为 Parquet 格式包括列名和类型，StarRocks 将推断 schema。 - -> **NOTE** -> -> 使用 schema 推断时，`CREATE TABLE` 的语法不允许设置副本数，因此请在创建表之前设置它。以下示例适用于具有单个副本的系统： -> -> `ADMIN SET FRONTEND CONFIG ('default_replication_num' ="1");` - -```sql -CREATE DATABASE IF NOT EXISTS project; -USE project; - -CREATE TABLE `user_behavior_inferred` AS -SELECT * FROM FILES( - "path" = "s3://starrocks-examples/user_behavior_sample_data.parquet", - "format" = "parquet", - "aws.s3.region" = "us-east-1", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" -); -``` - -```SQL -DESCRIBE user_behavior_inferred; -``` - -```plaintext -Field |Type |Null|Key |Default|Extra| -------------+----------------+----+-----+-------+-----+ -UserID |bigint |YES |true | | | -ItemID |bigint |YES |true | | | -CategoryID |bigint |YES |true | | | -BehaviorType|varchar(1048576)|YES |false| | | -Timestamp |varchar(1048576)|YES |false| | | -``` - -> **NOTE** -> -> 将推断的 schema 与手动创建的 schema 进行比较： -> -> - 数据类型 -> - 可为空 -> - 键字段 - -```SQL -SELECT * from user_behavior_inferred LIMIT 10; -``` - -```plaintext -UserID|ItemID|CategoryID|BehaviorType|Timestamp | -------+------+----------+------------+-------------------+ -171146| 68873| 3002561|pv |2017-11-30 07:11:14| -171146|146539| 4672807|pv |2017-11-27 09:51:41| -171146|146539| 4672807|pv |2017-11-27 14:08:33| -171146|214198| 1320293|pv |2017-11-25 22:38:27| -171146|260659| 4756105|pv |2017-11-30 05:11:25| -171146|267617| 4565874|pv |2017-11-27 14:01:25| -171146|329115| 2858794|pv |2017-12-01 02:10:51| -171146|458604| 1349561|pv |2017-11-25 22:49:39| -171146|458604| 1349561|pv |2017-11-27 14:03:44| -171146|478802| 541347|pv |2017-12-02 04:52:39| -``` - -#### 加载到现有表 - -您可能想要自定义要插入的表，例如： - -- 列数据类型、可为空设置或默认值 -- 键类型和列 -- 分布 -- 等等。 - -> **NOTE** -> -> 创建最有效的表结构需要了解数据的使用方式和列的内容。本文档不涵盖表设计，在页面末尾的**更多信息**中有一个链接。 - -在此示例中，我们基于对表查询方式和 Parquet 文件中数据的了解来创建表。可以通过直接在 S3 中查询文件来获得对 Parquet 文件中数据的了解。 - -- 由于 S3 中文件的查询表明 `Timestamp` 列包含与 `datetime` 数据类型匹配的数据，因此在以下 DDL 中指定了列类型。 -- 通过查询 S3 中的数据，您可以发现数据集中没有空值，因此 DDL 不会将任何列设置为可为空。 -- 根据对预期查询类型的了解，排序键和分桶列设置为列 `UserID`（您的用例可能对此数据有所不同，您可能会决定除了 `UserID` 之外或代替 `UserID` 使用 `ItemID` 作为排序键： - -```SQL -CREATE TABLE `user_behavior_declared` ( - `UserID` int(11), - `ItemID` int(11), - `CategoryID` int(11), - `BehaviorType` varchar(65533), - `Timestamp` datetime -) ENGINE=OLAP -DUPLICATE KEY(`UserID`) -DISTRIBUTED BY HASH(`UserID`) -PROPERTIES ( - "replication_num" = "1" -); -``` - -创建表后，您可以使用 `INSERT INTO` … `SELECT FROM FILES()` 加载它： - -```SQL -INSERT INTO user_behavior_declared - SELECT * FROM FILES( - "path" = "s3://starrocks-examples/user_behavior_sample_data.parquet", - "format" = "parquet", - "aws.s3.region" = "us-east-1", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" -); -``` - -## 更多信息 - -- 有关同步和异步数据加载的更多详细信息，请参见 [加载概念](./loading_introduction/loading_concepts.md)。 -- 了解 Broker Load 如何在加载期间支持数据转换，请参见 [加载时转换数据](../loading/Etl_in_loading.md) 和 [通过加载更改数据](../loading/Load_to_Primary_Key_tables.md)。 -- 本文档仅涵盖基于 IAM 用户的身份验证。有关其他选项，请参见 [验证到 AWS 资源的身份](../integrations/authenticate_to_aws_resources.md)。 -- [AWS CLI 命令参考](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/index.html) 详细介绍了 S3 URI。 -- 了解有关 [表设计](../table_design/StarRocks_table_design.md) 的更多信息。 -- Broker Load 提供了比上述示例更多的配置和使用选项，详细信息请参见 [Broker Load](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md) \ No newline at end of file diff --git a/docs/zh/loading/Loading_intro.md b/docs/zh/loading/Loading_intro.md deleted file mode 100644 index 0acc5c2..0000000 --- a/docs/zh/loading/Loading_intro.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -displayed_sidebar: docs -toc_max_heading_level: 3 -keywords: - - load - - Insert - - Stream Load - - Broker Load - - Pipe - - Routine Load - - Spark Load ---- - - - -# 数据导入选项 - -数据导入是从各种数据源中清理和转换原始数据，并根据您的业务需求将结果数据加载到 StarRocks 中，以方便分析的过程。 - -StarRocks 提供了多种数据导入选项： - -- 导入方法：Insert、Stream Load、Broker Load、Pipe、Routine Load 和 Spark Load -- 生态系统工具：StarRocks Connector for Apache Kafka®（简称 Kafka connector）、StarRocks Connector for Apache Spark™（简称 Spark connector）、StarRocks Connector for Apache Flink®（简称 Flink connector）以及其他工具，如 SMT、DataX、CloudCanal 和 Kettle Connector -- API：Stream Load 事务接口 - -这些选项各有优势，并支持各自的数据源系统。 - -本主题概述了这些选项，并对它们进行了比较，以帮助您根据数据源、业务场景、数据量、数据文件格式和导入频率来确定您选择的导入选项。 - -## 数据导入选项简介 - -本节主要介绍 StarRocks 中可用的数据导入选项的特性和业务场景。 - -![Loading options overview](../_assets/loading_intro_overview.png) - -:::note - -在以下各节中，“批量”或“批量导入”指的是一次性将大量数据从指定源加载到 StarRocks 中，而“流式”或“流式导入”指的是连续实时地加载数据。 - -::: - -## 导入方法 - -### [Insert](InsertInto.md) - -**业务场景：** - -- INSERT INTO VALUES：向内表追加少量数据。 -- INSERT INTO SELECT： - - INSERT INTO SELECT FROM ``：将对内表或外部表的查询结果追加到表中。 - - INSERT INTO SELECT FROM FILES()：将对远端存储中的数据文件的查询结果追加到表中。 - - :::note - - 对于 AWS S3，从 v3.1 开始支持此功能。对于 HDFS、Microsoft Azure Storage、Google GCS 和 S3 兼容存储（如 MinIO），从 v3.2 开始支持此功能。 - - ::: - -**文件格式：** - -- INSERT INTO VALUES：SQL -- INSERT INTO SELECT： - - INSERT INTO SELECT FROM ``：StarRocks 表 - - INSERT INTO SELECT FROM FILES()：Parquet 和 ORC - -**数据量：** 不固定（数据量根据内存大小而变化。） - -### [Stream Load](StreamLoad.md) - -**业务场景：** 从本地文件系统批量导入数据。 - -**文件格式：** CSV 和 JSON - -**数据量：** 10 GB 或更少 - -### [Broker Load](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md) - -**业务场景：** - -- 从 HDFS 或云存储（如 AWS S3、Microsoft Azure Storage、Google GCS 和 S3 兼容存储（如 MinIO））批量导入数据。 -- 从本地文件系统或 NAS 批量导入数据。 - -**文件格式：** CSV、Parquet、ORC 和 JSON（自 v3.2.3 起支持） - -**数据量：** 几十 GB 到数百 GB - -### [Pipe](../sql-reference/sql-statements/loading_unloading/pipe/CREATE_PIPE.md) - -**业务场景：** 从 HDFS 或 AWS S3 批量导入或流式导入数据。 - -:::note - -从 v3.2 开始支持此导入方法。 - -::: - -**文件格式：** Parquet 和 ORC - -**数据量：** 100 GB 到 1 TB 或更多 - -### [Routine Load](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md) - -**业务场景：** 从 Kafka 流式导入数据。 - -**文件格式：** CSV、JSON 和 Avro（自 v3.0.1 起支持） - -**数据量：** 以小批量形式导入 MB 到 GB 级别的数据 - -### [Spark Load](../sql-reference/sql-statements/loading_unloading/SPARK_LOAD.md) - -**业务场景：** 使用 Spark 集群批量导入存储在 HDFS 中的 Apache Hive™ 表的数据。 - -**文件格式：** CSV、Parquet（自 v2.0 起支持）和 ORC（自 v2.0 起支持） - -**数据量：** 几十 GB 到 TB - -## 生态系统工具 - -### [Kafka connector](Kafka-connector-starrocks.md) - -**业务场景：** 从 Kafka 流式导入数据。 - -### [Spark connector](Spark-connector-starrocks.md) - -**业务场景：** 从 Spark 批量导入数据。 - -### [Flink connector](Flink-connector-starrocks.md) - -**业务场景：** 从 Flink 流式导入数据。 - -### [SMT](../integrations/loading_tools/SMT.md) - -**业务场景：** 通过 Flink 从 MySQL、PostgreSQL、SQL Server、Oracle、Hive、ClickHouse 和 TiDB 等数据源加载数据。 - -### [DataX](../integrations/loading_tools/DataX-starrocks-writer.md) - -**业务场景：** 在各种异构数据源（包括关系数据库（例如 MySQL 和 Oracle）、HDFS 和 Hive）之间同步数据。 - -### [CloudCanal](../integrations/loading_tools/CloudCanal.md) - -**业务场景：** 将数据从源数据库（例如 MySQL、Oracle 和 PostgreSQL）迁移或同步到 StarRocks。 - -### [Kettle Connector](https://github.com/StarRocks/starrocks-connector-for-kettle) - -**业务场景：** 与 Kettle 集成。通过将 Kettle 强大的数据处理和转换能力与 StarRocks 的高性能数据存储和分析能力相结合，可以实现更灵活高效的数据处理工作流程。 - -## API - -### [Stream Load transaction interface](Stream_Load_transaction_interface.md) - -**业务场景：** 为从 Flink 和 Kafka 等外部系统加载数据而运行的事务实现两阶段提交 (2PC)，同时提高高并发流式导入的性能。从 v2.4 开始支持此功能。 - -**文件格式：** CSV 和 JSON - -**数据量：** 10 GB 或更少 - -## 数据导入选项的选择 - -本节列出了可用于常见数据源的导入选项，帮助您选择最适合您情况的选项。 - -### 对象存储 - -| **数据源** | **可用的数据导入选项** that is displayed on the left navigation bar. - -Data loading is the process of cleansing and transforming raw data from various data sources based on your business requirements and loading the resulting data into StarRocks to facilitate analysis. - -StarRocks provides a variety of options for data loading: - -1. [**Insert**](InsertInto.md): Append to an internal table with small amounts of data. -2. [**Stream Load**](StreamLoad.md): Batch load data from a local file system. -3. [**Broker Load**](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md): Batch load data from HDFS or cloud storage like AWS S3, Microsoft Azure Storage, Google GCS, and S3-compatible storage (such as MinIO). -4. [**Pipe**](../sql-reference/sql-statements/loading_unloading/pipe/CREATE_PIPE.md): Batch load or stream data from HDFS or AWS S3. -5. [**Routine Load**](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md): Stream data from Kafka. -6. [**Spark Load**](../sql-reference/sql-statements/loading_unloading/SPARK_LOAD.md): Batch load data of Apache Hive™ tables stored in HDFS by using Spark clusters. -7. [**Kafka connector**](Kafka-connector-starrocks.md): Stream data from Kafka. -8. [**Spark connector**](Spark-connector-starrocks.md): Batch load data from Spark. -9. [**Flink connector**](Flink-connector-starrocks.md): Stream data from Flink. -10. [**SMT**](../integrations/loading_tools/SMT.md): Load data from data sources such as MySQL, PostgreSQL, SQL Server, Oracle, Hive, ClickHouse, and TiDB through Flink. -11. [**DataX**](../integrations/loading_tools/DataX-starrocks-writer.md): Synchronize data between various heterogeneous data sources, including relational databases (for example, MySQL and Oracle), HDFS, and Hive. -12. [**CloudCanal**](../integrations/loading_tools/CloudCanal.md): Migrate or synchronize data from source databases (for example, MySQL, Oracle, and PostgreSQL) to StarRocks. -13. [**Kettle Connector**](https://github.com/StarRocks/starrocks-connector-for-kettle): Integrate with Kettle. By combining Kettle's robust data processing and transformation capabilities with StarRocks's high-performance data storage and analytical abilities, more flexible and efficient data processing workflows can be achieved. -14. [**Stream Load transaction interface**](Stream_Load_transaction_interface.md): Implement two-phase commit (2PC) for transactions that are run to load data from external systems such as Flink and Kafka, while improving the performance of highly concurrent stream loads. - -These options each have its own advantages and support its own set of data source systems to pull from. - -This topic provides an overview of these options, along with comparisons between them to help you determine the loading option of your choice based on your data source, business scenario, data volume, data file format, and loading frequency. \ No newline at end of file diff --git a/docs/zh/loading/RoutineLoad.md b/docs/zh/loading/RoutineLoad.md deleted file mode 100644 index 5a1644e..0000000 --- a/docs/zh/loading/RoutineLoad.md +++ /dev/null @@ -1,530 +0,0 @@ ---- -displayed_sidebar: docs -keywords: ['Routine Load'] ---- - -# 使用 Routine Load 导入数据 - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' -import QSTip from '../_assets/commonMarkdown/quickstart-routine-load-tip.mdx' - - - -本文介绍如何创建 Routine Load 作业，将 Kafka 消息（事件）流式传输到 StarRocks 中，并帮助您熟悉 Routine Load 的一些基本概念。 - -要将消息流持续不断地导入到 StarRocks 中，您可以将消息流存储在 Kafka topic 中，并创建一个 Routine Load 作业来消费这些消息。Routine Load 作业在 StarRocks 中持久存在，生成一系列导入任务，以消费 topic 中全部或部分分区中的消息，并将消息导入到 StarRocks 中。 - -Routine Load 作业支持精确一次 (exactly-once) 的交付语义，以保证导入到 StarRocks 中的数据既不会丢失也不会重复。 - -Routine Load 支持在数据导入时进行数据转换，并支持在数据导入期间通过 UPSERT 和 DELETE 操作进行数据更改。更多信息，请参见 [在导入时转换数据](../loading/Etl_in_loading.md) 和 [通过导入更改数据](../loading/Load_to_Primary_Key_tables.md)。 - - - -## 支持的数据格式 - -Routine Load 现在支持从 Kafka 集群消费 CSV、JSON 和 Avro (v3.0.1 起支持) 格式的数据。 - -> **NOTE** -> -> 对于 CSV 数据，请注意以下几点： -> -> - 您可以使用 UTF-8 字符串，例如逗号 (,)、制表符或管道 (|)，其长度不超过 50 字节作为文本分隔符。 -> - 空值用 `\N` 表示。例如，一个数据文件包含三列，该数据文件中的一条记录在第一列和第三列中包含数据，但在第二列中没有数据。在这种情况下，您需要在第二列中使用 `\N` 来表示空值。这意味着该记录必须编译为 `a,\N,b` 而不是 `a,,b`。`a,,b` 表示该记录的第二列包含一个空字符串。 - -## 基本概念 - -![routine load](../_assets/4.5.2-1.png) - -### 术语 - -- **导入作业** - - Routine Load 作业是一个长时间运行的作业。只要其状态为 RUNNING，导入作业就会持续生成一个或多个并发导入任务，这些任务消费 Kafka 集群 topic 中的消息并将数据导入到 StarRocks 中。 - -- **导入任务** - - 一个导入作业通过一定的规则被拆分为多个导入任务。导入任务是数据导入的基本单元。作为一个独立的事件，一个导入任务基于 [Stream Load](../loading/StreamLoad.md) 实现导入机制。多个导入任务并发地消费来自 topic 不同分区的消息，并将数据导入到 StarRocks 中。 - -### 工作流程 - -1. **创建一个 Routine Load 作业。** - 要从 Kafka 导入数据，您需要通过运行 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md) 语句来创建一个 Routine Load 作业。FE 解析该语句，并根据您指定的属性创建该作业。 - -2. **FE 将作业拆分为多个导入任务。** - - FE 基于一定的规则将作业拆分为多个导入任务。每个导入任务都是一个独立的事务。 - 拆分规则如下： - - FE 根据所需的并发数 `desired_concurrent_number`、Kafka topic 中的分区数以及处于活动状态的 BE 节点数来计算导入任务的实际并发数。 - - FE 基于计算出的实际并发数将作业拆分为导入任务，并将这些任务排列在任务队列中。 - - 每个 Kafka topic 由多个分区组成。Topic 分区和导入任务之间的关系如下： - - 一个分区唯一地分配给一个导入任务，并且来自该分区的所有消息都由该导入任务消费。 - - 一个导入任务可以消费来自一个或多个分区的消息。 - - 所有分区均匀地分配给导入任务。 - -3. **多个导入任务并发运行，以消费来自多个 Kafka topic 分区的消息，并将数据导入到 StarRocks 中。** - - 1. **FE 调度和提交导入任务**：FE 及时调度队列中的导入任务，并将它们分配给选定的 Coordinator BE 节点。导入任务之间的时间间隔由配置项 `max_batch_interval` 定义。FE 将导入任务均匀地分配给所有 BE 节点。有关 `max_batch_interval` 的更多信息，请参见 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md#examples)。 - - 2. Coordinator BE 启动导入任务，消费分区中的消息，解析和过滤数据。一个导入任务持续到消费了预定义数量的消息或达到预定义的时间限制为止。消息批处理大小和时间限制在 FE 配置 `max_routine_load_batch_size` 和 `routine_load_task_consume_second` 中定义。有关详细信息，请参见 [FE 配置](../administration/management/FE_configuration.md)。然后，Coordinator BE 将消息分发给 Executor BE。Executor BE 将消息写入磁盘。 - - > **NOTE** - > - > StarRocks 支持通过包括 SASL_SSL、SAS_PLAINTEXT、SSL 和 PLAINTEXT 在内的安全协议访问 Kafka。本主题以通过 PLAINTEXT 连接到 Kafka 为例。如果您需要通过其他安全协议连接到 Kafka，请参见 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。 - -4. **FE 生成新的导入任务以持续导入数据。** - 在 Executor BE 将数据写入磁盘后，Coordinator BE 将导入任务的结果报告给 FE。基于该结果，FE 然后生成新的导入任务以持续导入数据。或者，FE 重试失败的任务以确保导入到 StarRocks 中的数据既不会丢失也不会重复。 - -## 创建 Routine Load 作业 - -以下三个示例描述了如何消费 Kafka 中的 CSV 格式、JSON 格式和 Avro 格式的数据，并通过创建 Routine Load 作业将数据导入到 StarRocks 中。有关详细的语法和参数描述，请参见 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。 - -### 导入 CSV 格式的数据 - -本节介绍如何创建一个 Routine Load 作业，以消费 Kafka 集群中的 CSV 格式数据，并将数据导入到 StarRocks 中。 - -#### 准备数据集 - -假设 Kafka 集群的 topic `ordertest1` 中有一个 CSV 格式的数据集。数据集中的每条消息都包含六个字段：订单 ID、支付日期、客户姓名、国籍、性别和价格。 - -```Plain -2020050802,2020-05-08,Johann Georg Faust,Deutschland,male,895 -2020050802,2020-05-08,Julien Sorel,France,male,893 -2020050803,2020-05-08,Dorian Grey,UK,male,1262 -2020050901,2020-05-09,Anna Karenina",Russia,female,175 -2020051001,2020-05-10,Tess Durbeyfield,US,female,986 -2020051101,2020-05-11,Edogawa Conan,japan,male,8924 -``` - -#### 创建表 - -根据 CSV 格式数据的字段，在数据库 `example_db` 中创建表 `example_tbl1`。以下示例创建一个包含 5 个字段的表，不包括 CSV 格式数据中的客户性别字段。 - -```SQL -CREATE TABLE example_db.example_tbl1 ( - `order_id` bigint NOT NULL COMMENT "Order ID", - `pay_dt` date NOT NULL COMMENT "Payment date", - `customer_name` varchar(26) NULL COMMENT "Customer name", - `nationality` varchar(26) NULL COMMENT "Nationality", - `price`double NULL COMMENT "Price" -) -ENGINE=OLAP -DUPLICATE KEY (order_id,pay_dt) -DISTRIBUTED BY HASH(`order_id`); -``` - -> **NOTICE** -> -> 从 v2.5.7 开始，StarRocks 可以在您创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - -#### 提交 Routine Load 作业 - -执行以下语句以提交一个名为 `example_tbl1_ordertest1` 的 Routine Load 作业，以消费 topic `ordertest1` 中的消息并将数据导入到表 `example_tbl1` 中。导入任务从 topic 的指定分区中的初始 offset 消费消息。 - -```SQL -CREATE ROUTINE LOAD example_db.example_tbl1_ordertest1 ON example_tbl1 -COLUMNS TERMINATED BY ",", -COLUMNS (order_id, pay_dt, customer_name, nationality, temp_gender, price) -PROPERTIES -( - "desired_concurrent_number" = "5" -) -FROM KAFKA -( - "kafka_broker_list" = ":,:", - "kafka_topic" = "ordertest1", - "kafka_partitions" = "0,1,2,3,4", - "property.kafka_default_offsets" = "OFFSET_BEGINNING" -); -``` - -提交导入作业后，您可以执行 [SHOW ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD.md) 语句来检查导入作业的状态。 - -- **导入作业名称** - - 一个表上可能有多个导入作业。因此，我们建议您使用相应的 Kafka topic 和提交导入作业的时间来命名导入作业。这有助于您区分每个表上的导入作业。 - -- **列分隔符** - - 属性 `COLUMN TERMINATED BY` 定义 CSV 格式数据的列分隔符。默认为 `\t`。 - -- **Kafka topic 分区和 offset** - - 您可以指定属性 `kafka_partitions` 和 `kafka_offsets` 来指定要消费消息的分区和 offset。例如，如果您希望导入作业消费 topic `ordertest1` 的 Kafka 分区 `"0,1,2,3,4"` 中的消息，并且所有消息都具有初始 offset，则可以按如下方式指定属性：如果您希望导入作业消费 Kafka 分区 `"0,1,2,3,4"` 中的消息，并且需要为每个分区指定单独的起始 offset，则可以按如下方式配置： - - ```SQL - "kafka_partitions" ="0,1,2,3,4", - "kafka_offsets" = "OFFSET_BEGINNING, OFFSET_END, 1000, 2000, 3000" - ``` - - 您还可以使用属性 `property.kafka_default_offsets` 设置所有分区的默认 offset。 - - ```SQL - "kafka_partitions" ="0,1,2,3,4", - "property.kafka_default_offsets" = "OFFSET_BEGINNING" - ``` - - 有关详细信息，请参见 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。 - -- **数据映射和转换** - - 要指定 CSV 格式数据和 StarRocks 表之间的映射和转换关系，您需要使用 `COLUMNS` 参数。 - - **数据映射：** - - - StarRocks 提取 CSV 格式数据中的列，并按照**顺序**将它们映射到 `COLUMNS` 参数中声明的字段。 - - - StarRocks 提取 `COLUMNS` 参数中声明的字段，并按照**名称**将它们映射到 StarRocks 表的列。 - - **数据转换：** - - 并且由于该示例排除了 CSV 格式数据中的客户性别列，因此 `COLUMNS` 参数中的字段 `temp_gender` 用作此字段的占位符。其他字段直接映射到 StarRocks 表 `example_tbl1` 的列。 - - 有关数据转换的更多信息，请参见 [在导入时转换数据](./Etl_in_loading.md)。 - - > **NOTE** - > - > 如果 CSV 格式数据中列的名称、数量和顺序与 StarRocks 表中的列完全对应，则无需指定 `COLUMNS` 参数。 - -- **任务并发** - - 当 Kafka topic 分区很多且 BE 节点足够时，您可以通过增加任务并发来加速导入。 - - 要增加实际的导入任务并发，您可以在创建 Routine Load 作业时增加所需的导入任务并发 `desired_concurrent_number`。您还可以将 FE 的动态配置项 `max_routine_load_task_concurrent_num`（默认的最大导入任务并发数）设置为更大的值。有关 `max_routine_load_task_concurrent_num` 的更多信息，请参见 [FE 配置项](../administration/management/FE_configuration.md)。 - - 实际的任务并发由处于活动状态的 BE 节点数、预先指定的 Kafka topic 分区数以及 `desired_concurrent_number` 和 `max_routine_load_task_concurrent_num` 的值中的最小值定义。 - - 在该示例中，处于活动状态的 BE 节点数为 `5`，预先指定的 Kafka topic 分区数为 `5`，并且 `max_routine_load_task_concurrent_num` 的值为 `5`。要增加实际的导入任务并发，您可以将 `desired_concurrent_number` 从默认值 `3` 增加到 `5`。 - - 有关属性的更多信息，请参见 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。 - -### 导入 JSON 格式的数据 - -本节介绍如何创建一个 Routine Load 作业，以消费 Kafka 集群中的 JSON 格式数据，并将数据导入到 StarRocks 中。 - -#### 准备数据集 - -假设 Kafka 集群的 topic `ordertest2` 中有一个 JSON 格式的数据集。该数据集包括六个键：商品 ID、客户姓名、国籍、支付时间和价格。此外，您希望将支付时间列转换为 DATE 类型，并将其导入到 StarRocks 表中的 `pay_dt` 列。 - -```JSON -{"commodity_id": "1", "customer_name": "Mark Twain", "country": "US","pay_time": 1589191487,"price": 875} -{"commodity_id": "2", "customer_name": "Oscar Wilde", "country": "UK","pay_time": 1589191487,"price": 895} -{"commodity_id": "3", "customer_name": "Antoine de Saint-Exupéry","country": "France","pay_time": 1589191487,"price": 895} -``` - -> **CAUTION** 一行中的每个 JSON 对象必须位于一条 Kafka 消息中，否则将返回 JSON 解析错误。 - -#### 创建表 - -根据 JSON 格式数据的键，在数据库 `example_db` 中创建表 `example_tbl2`。 - -```SQL -CREATE TABLE `example_tbl2` ( - `commodity_id` varchar(26) NULL COMMENT "Commodity ID", - `customer_name` varchar(26) NULL COMMENT "Customer name", - `country` varchar(26) NULL COMMENT "Country", - `pay_time` bigint(20) NULL COMMENT "Payment time", - `pay_dt` date NULL COMMENT "Payment date", - `price`double SUM NULL COMMENT "Price" -) -ENGINE=OLAP -AGGREGATE KEY(`commodity_id`,`customer_name`,`country`,`pay_time`,`pay_dt`) -DISTRIBUTED BY HASH(`commodity_id`); -``` - -> **NOTICE** -> -> 从 v2.5.7 开始，StarRocks 可以在您创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - -#### 提交 Routine Load 作业 - -执行以下语句以提交一个名为 `example_tbl2_ordertest2` 的 Routine Load 作业，以消费 topic `ordertest2` 中的消息并将数据导入到表 `example_tbl2` 中。导入任务从 topic 的指定分区中的初始 offset 消费消息。 - -```SQL -CREATE ROUTINE LOAD example_db.example_tbl2_ordertest2 ON example_tbl2 -COLUMNS(commodity_id, customer_name, country, pay_time, price, pay_dt=from_unixtime(pay_time, '%Y%m%d')) -PROPERTIES -( - "desired_concurrent_number" = "5", - "format" = "json", - "jsonpaths" = "[\"$.commodity_id\",\"$.customer_name\",\"$.country\",\"$.pay_time\",\"$.price\"]" - ) -FROM KAFKA -( - "kafka_broker_list" =":,:", - "kafka_topic" = "ordertest2", - "kafka_partitions" ="0,1,2,3,4", - "property.kafka_default_offsets" = "OFFSET_BEGINNING" -); -``` - -提交导入作业后，您可以执行 [SHOW ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD.md) 语句来检查导入作业的状态。 - -- **数据格式** - - 您需要在 `PROPERTIES` 子句中指定 `"format" = "json"`，以定义数据格式为 JSON。 - -- **数据映射和转换** - - 要指定 JSON 格式数据和 StarRocks 表之间的映射和转换关系，您需要指定参数 `COLUMNS` 和属性 `jsonpaths`。`COLUMNS` 参数中指定的字段顺序必须与 JSON 格式数据的顺序匹配，并且字段名称必须与 StarRocks 表的名称匹配。属性 `jsonpaths` 用于从 JSON 数据中提取所需的字段。然后，这些字段由属性 `COLUMNS` 命名。 - - 因为该示例需要将支付时间字段转换为 DATE 数据类型，并将数据导入到 StarRocks 表中的 `pay_dt` 列，所以您需要使用 from_unixtime 函数。其他字段直接映射到表 `example_tbl2` 的字段。 - - **数据映射：** - - - StarRocks 提取 JSON 格式数据的 `name` 和 `code` 键，并将它们映射到 `jsonpaths` 属性中声明的键。 - - - StarRocks 提取 `jsonpaths` 属性中声明的键，并按照**顺序**将它们映射到 `COLUMNS` 参数中声明的字段。 - - - StarRocks 提取 `COLUMNS` 参数中声明的字段，并按照**名称**将它们映射到 StarRocks 表的列。 - - **数据转换**： - - - 因为该示例需要将键 `pay_time` 转换为 DATE 数据类型，并将数据导入到 StarRocks 表中的 `pay_dt` 列，所以您需要在 `COLUMNS` 参数中使用 from_unixtime 函数。其他字段直接映射到表 `example_tbl2` 的字段。 - - - 并且由于该示例排除了 JSON 格式数据中的客户性别列，因此 `COLUMNS` 参数中的字段 `temp_gender` 用作此字段的占位符。其他字段直接映射到 StarRocks 表 `example_tbl1` 的列。 - - 有关数据转换的更多信息，请参见 [在导入时转换数据](./Etl_in_loading.md)。 - - > **NOTE** - > - > 如果 JSON 对象中键的名称和数量与 StarRocks 表中字段的名称和数量完全匹配，则无需指定 `COLUMNS` 参数。 - -### 导入 Avro 格式的数据 - -从 v3.0.1 开始，StarRocks 支持使用 Routine Load 导入 Avro 数据。 - -#### 准备数据集 - -##### Avro schema - -1. 创建以下 Avro schema 文件 `avro_schema.avsc`： - - ```JSON - { - "type": "record", - "name": "sensor_log", - "fields" : [ - {"name": "id", "type": "long"}, - {"name": "name", "type": "string"}, - {"name": "checked", "type" : "boolean"}, - {"name": "data", "type": "double"}, - {"name": "sensor_type", "type": {"type": "enum", "name": "sensor_type_enum", "symbols" : ["TEMPERATURE", "HUMIDITY", "AIR-PRESSURE"]}} - ] - } - ``` - -2. 在 [Schema Registry](https://docs.confluent.io/cloud/current/get-started/schema-registry.html#create-a-schema) 中注册 Avro schema。 - -##### Avro 数据 - -准备 Avro 数据并将其发送到 Kafka topic `topic_0`。 - -#### 创建表 - -根据 Avro 数据的字段，在 StarRocks 集群的目标数据库 `example_db` 中创建一个表 `sensor_log`。表的列名必须与 Avro 数据中的字段名匹配。有关表列和 Avro 数据字段之间的数据类型映射，请参见 [数据类型映射](#Data types mapping)。 - -```SQL -CREATE TABLE example_db.sensor_log ( - `id` bigint NOT NULL COMMENT "sensor id", - `name` varchar(26) NOT NULL COMMENT "sensor name", - `checked` boolean NOT NULL COMMENT "checked", - `data` double NULL COMMENT "sensor data", - `sensor_type` varchar(26) NOT NULL COMMENT "sensor type" -) -ENGINE=OLAP -DUPLICATE KEY (id) -DISTRIBUTED BY HASH(`id`); -``` - -> **NOTICE** -> -> 从 v2.5.7 开始，StarRocks 可以在您创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - -#### 提交 Routine Load 作业 - -执行以下语句以提交一个名为 `sensor_log_load_job` 的 Routine Load 作业，以消费 Kafka topic `topic_0` 中的 Avro 消息并将数据导入到数据库 `sensor` 中的表 `sensor_log` 中。导入作业从 topic 的指定分区中的初始 offset 消费消息。 - -```SQL -CREATE ROUTINE LOAD example_db.sensor_log_load_job ON sensor_log -PROPERTIES -( - "format" = "avro" -) -FROM KAFKA -( - "kafka_broker_list" = ":,:,...", - "confluent.schema.registry.url" = "http://172.xx.xxx.xxx:8081", - "kafka_topic" = "topic_0", - "kafka_partitions" = "0,1,2,3,4,5", - "property.kafka_default_offsets" = "OFFSET_BEGINNING" -); -``` - -- 数据格式 - - 您需要在 `PROPERTIES` 子句中指定 `"format = "avro"`，以定义数据格式为 Avro。 - -- Schema Registry - - 您需要配置 `confluent.schema.registry.url` 以指定注册 Avro schema 的 Schema Registry 的 URL。StarRocks 使用此 URL 检索 Avro schema。格式如下： - - ```Plaintext - confluent.schema.registry.url = http[s]://[:@][:] - ``` - -- 数据映射和转换 - - 要指定 Avro 格式数据和 StarRocks 表之间的映射和转换关系，您需要指定参数 `COLUMNS` 和属性 `jsonpaths`。`COLUMNS` 参数中指定的字段顺序必须与属性 `jsonpaths` 中字段的顺序匹配，并且字段名称必须与 StarRocks 表的名称匹配。属性 `jsonpaths` 用于从 Avro 数据中提取所需的字段。然后，这些字段由属性 `COLUMNS` 命名。 - - 有关数据转换的更多信息，请参见 [在导入时转换数据](./Etl_in_loading.md)。 - - > NOTE - > - > 如果 Avro 记录中字段的名称和数量与 StarRocks 表中列的名称和数量完全匹配，则无需指定 `COLUMNS` 参数。 - -提交导入作业后，您可以执行 [SHOW ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD.md) 语句来检查导入作业的状态。 - -#### 数据类型映射 - -您要导入的 Avro 数据字段与 StarRocks 表列之间的数据类型映射如下： - -##### 原始类型 - -| Avro | StarRocks | -| ------- | --------- | -| nul | NULL | -| boolean | BOOLEAN | -| int | INT | -| long | BIGINT | -| float | FLOAT | -| double | DOUBLE | -| bytes | STRING | -| string | STRING | - -##### 复杂类型 - -| Avro | StarRocks | -| -------------- | ------------------------------------------------------------ | -| record | 将整个 RECORD 或其子字段作为 JSON 导入到 StarRocks 中。 | -| enums | STRING | -| arrays | ARRAY | -| maps | JSON | -| union(T, null) | NULLABLE(T) | -| fixed | STRING | - -#### 限制 - -- 目前，StarRocks 不支持 schema evolution。 -- 每条 Kafka 消息必须仅包含一条 Avro 数据记录。 - -## 检查导入作业和任务 - -### 检查导入作业 - -执行 [SHOW ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD.md) 语句以检查导入作业 `example_tbl2_ordertest2` 的状态。StarRocks 返回执行状态 `State`、统计信息（包括消费的总行数和导入的总行数）`Statistics` 以及导入作业的进度 `progress`。 - -如果导入作业的状态自动更改为 **PAUSED**，则可能是因为错误行数已超过阈值。有关设置此阈值的详细说明，请参见 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。您可以检查文件 `ReasonOfStateChanged` 和 `ErrorLogUrls` 以识别和解决问题。解决问题后，您可以执行 [RESUME ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/RESUME_ROUTINE_LOAD.md) 语句以恢复 **PAUSED** 导入作业。 - -如果导入作业的状态为 **CANCELLED**，则可能是因为导入作业遇到异常（例如，表已被删除）。您可以检查文件 `ReasonOfStateChanged` 和 `ErrorLogUrls` 以识别和解决问题。但是，您无法恢复 **CANCELLED** 导入作业。 - -```SQL -MySQL [example_db]> SHOW ROUTINE LOAD FOR example_tbl2_ordertest2 \G -*************************** 1. row *************************** - Id: 63013 - Name: example_tbl2_ordertest2 - CreateTime: 2022-08-10 17:09:00 - PauseTime: NULL - EndTime: NULL - DbName: default_cluster:example_db - TableName: example_tbl2 - State: RUNNING - DataSourceType: KAFKA - CurrentTaskNum: 3 - JobProperties: {"partitions":"*","partial_update":"false","columnToColumnExpr":"commodity_id,customer_name,country,pay_time,pay_dt=from_unixtime(`pay_time`, '%Y%m%d'),price","maxBatchIntervalS":"20","whereExpr":"*","dataFormat":"json","timezone":"Asia/Shanghai","format":"json","json_root":"","strict_mode":"false","jsonpaths":"[\"$.commodity_id\",\"$.customer_name\",\"$.country\",\"$.pay_time\",\"$.price\"]","desireTaskConcurrentNum":"3","maxErrorNum":"0","strip_outer_array":"false","currentTaskConcurrentNum":"3","maxBatchRows":"200000"} -DataSourceProperties: {"topic":"ordertest2","currentKafkaPartitions":"0,1,2,3,4","brokerList":":,:"} - CustomProperties: {"kafka_default_offsets":"OFFSET_BEGINNING"} - Statistic: {"receivedBytes":230,"errorRows":0,"committedTaskNum":1,"loadedRows":2,"loadRowsRate":0,"abortedTaskNum":0,"totalRows":2,"unselectedRows":0,"receivedBytesRate":0,"taskExecuteTimeMs":522} - Progress: {"0":"1","1":"OFFSET_ZERO","2":"OFFSET_ZERO","3":"OFFSET_ZERO","4":"OFFSET_ZERO"} -ReasonOfStateChanged: - ErrorLogUrls: - OtherMsg: -``` - -> **CAUTION** -> -> 您无法检查已停止或尚未启动的导入作业。 - -### 检查导入任务 - -执行 [SHOW ROUTINE LOAD TASK](../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD_TASK.md) 语句以检查导入作业 `example_tbl2_ordertest2` 的导入任务，例如当前正在运行的任务数、正在消费的 Kafka topic 分区和消费进度 `DataSourceProperties` 以及相应的 Coordinator BE 节点 `BeId`。 - -```SQL -MySQL [example_db]> SHOW ROUTINE LOAD TASK WHERE JobName = "example_tbl2_ordertest2" \G -*************************** 1. row *************************** - TaskId: 18c3a823-d73e-4a64-b9cb-b9eced026753 - TxnId: -1 - TxnStatus: UNKNOWN - JobId: 63013 - CreateTime: 2022-08-10 17:09:05 - LastScheduledTime: 2022-08-10 17:47:27 - ExecuteStartTime: NULL - Timeout: 60 - BeId: -1 -DataSourceProperties: {"1":0,"4":0} - Message: there is no new data in kafka, wait for 20 seconds to schedule again -*************************** 2. row *************************** - TaskId: f76c97ac-26aa-4b41-8194-a8ba2063eb00 - TxnId: -1 - TxnStatus: UNKNOWN - JobId: 63013 - CreateTime: 2022-08-10 17:09:05 - LastScheduledTime: 2022-08-10 17:47:26 - ExecuteStartTime: NULL - Timeout: 60 - BeId: -1 -DataSourceProperties: {"2":0} - Message: there is no new data in kafka, wait for 20 seconds to schedule again -*************************** 3. row *************************** - TaskId: 1a327a34-99f4-4f8d-8014-3cd38db99ec6 - TxnId: -1 - TxnStatus: UNKNOWN - JobId: 63013 - CreateTime: 2022-08-10 17:09:26 - LastScheduledTime: 2022-08-10 17:47:27 - ExecuteStartTime: NULL - Timeout: 60 - BeId: -1 -DataSourceProperties: {"0":2,"3":0} - Message: there is no new data in kafka, wait for 20 seconds to schedule again -``` - -## 暂停导入作业 - -您可以执行 [PAUSE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/PAUSE_ROUTINE_LOAD.md) 语句以暂停导入作业。执行该语句后，导入作业的状态将为 **PAUSED**。但是，它尚未停止。您可以执行 [RESUME ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/RESUME_ROUTINE_LOAD.md) 语句以恢复它。您还可以使用 [SHOW ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD.md) 语句检查其状态。 - -以下示例暂停导入作业 `example_tbl2_ordertest2`： - -```SQL -PAUSE ROUTINE LOAD FOR example_tbl2_ordertest2; -``` - -## 恢复导入作业 - -您可以执行 [RESUME ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/RESUME_ROUTINE_LOAD.md) 语句以恢复已暂停的导入作业。导入作业的状态将暂时为 **NEED_SCHEDULE**（因为正在重新调度导入作业），然后变为 **RUNNING**。您可以使用 [SHOW ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD.md) 语句检查其状态。 - -以下示例恢复已暂停的导入作业 `example_tbl2_ordertest2`： - -```SQL -RESUME ROUTINE LOAD FOR example_tbl2_ordertest2; -``` - -## 更改导入作业 - -在更改导入作业之前，您必须使用 [PAUSE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/PAUSE_ROUTINE_LOAD.md) 语句暂停它。然后，您可以执行 [ALTER ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/ALTER_ROUTINE_LOAD.md)。更改后，您可以执行 [RESUME ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/RESUME_ROUTINE_LOAD.md) 语句以恢复它，并使用 [SHOW ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD.md) 语句检查其状态。 - -假设处于活动状态的 BE 节点数增加到 `6`，并且要消费的 Kafka topic 分区为 `"0,1,2,3,4,5,6,7"`。如果您想增加实际的导入任务并发，您可以执行以下语句来将所需的任务并发数 `desired_concurrent_number` 增加到 `6`（大于或等于处于活动状态的 BE 节点数），并指定 Kafka topic 分区和初始 offset。 - -> **NOTE** -> -> 因为实际的任务并发由多个参数的最小值决定，所以您必须确保 FE 动态参数 `max_routine_load_task_concurrent_num` 的值大于或 \ No newline at end of file diff --git a/docs/zh/loading/SQL_transaction.md b/docs/zh/loading/SQL_transaction.md deleted file mode 100644 index d1be8ee..0000000 --- a/docs/zh/loading/SQL_transaction.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -displayed_sidebar: docs ---- - -import Beta from '../_assets/commonMarkdown/_beta.mdx' - -# SQL 事务 - - - -启动一个简单的 SQL 事务，以批量提交多个 DML 语句。 - -## 概述 - -自 v3.5.0 起，StarRocks 支持 SQL 事务，以确保在多个表中操作数据时，更新表的原子性。 - -事务由在同一原子单元中处理的多个 SQL 语句组成。 事务中的语句要么一起应用，要么一起撤消，从而保证了事务的 ACID（原子性、一致性、隔离性和持久性）属性。 - -目前，StarRocks 中的 SQL 事务支持以下操作： -- INSERT INTO -- UPDATE -- DELETE - -:::note - -- 目前不支持 INSERT OVERWRITE。 -- 从 v4.0 开始，只有在存算分离集群中才支持在事务中对同一表执行多个 INSERT 语句。 -- 从 v4.0 开始，只有在存算分离集群中才支持 UPDATE 和 DELETE。 - -::: - -从 v4.0 开始，在一个 SQL 事务中： -- 支持对一个表执行**多个 INSERT 语句**。 -- 允许对一个表执行**仅一个 UPDATE *或* DELETE** 语句。 -- **不允许**在对同一表执行 INSERT 语句**之后**执行 **UPDATE *或* DELETE** 语句。 - -事务的 ACID 属性仅在有限的 READ COMMITTED 隔离级别上得到保证，即： -- 语句仅对在该语句开始之前已提交的数据进行操作。 -- 如果在第一个语句和第二个语句的执行之间提交了另一个事务，则同一事务中的两个连续语句可以对不同的数据进行操作。 -- 前面的 DML 语句带来的数据更改对于同一事务中的后续语句是不可见的。 - -一个事务与一个会话相关联。 多个会话不能共享同一个事务。 - -## 用法 - -1. 必须通过执行 START TRANSACTION 语句来启动事务。 StarRocks 还支持同义词 BEGIN。 - - ```SQL - { START TRANSACTION | BEGIN [ WORK ] } - ``` - -2. 启动事务后，您可以在事务中定义多个 DML 语句。 有关详细信息，请参见 [使用说明](#usage-notes)。 - -3. 必须通过执行 `COMMIT` 或 `ROLLBACK` 显式结束事务。 - - - 要应用（提交）事务，请使用以下语法： - - ```SQL - COMMIT [ WORK ] - ``` - - - 要撤消（回滚）事务，请使用以下语法： - - ```SQL - ROLLBACK [ WORK ] - ``` - -## 示例 - -1. 在存算分离集群中创建演示表 `desT`，并将数据加载到其中。 - - :::note - 如果您想在存算一体集群中尝试此示例，则必须跳过步骤 3，并且在步骤 4 中仅定义一个 INSERT 语句。 - ::: - - ```SQL - CREATE TABLE desT ( - k int, - v int - ) PRIMARY KEY(k); - - INSERT INTO desT VALUES - (1,1), - (2,2), - (3,3); - ``` - -2. 启动一个事务。 - - ```SQL - START TRANSACTION; - ``` - - 或者 - - ```SQL - BEGIN WORK; - ``` - -3. 定义一个 UPDATE 或 DELETE 语句。 - - ```SQL - UPDATE desT SET v = v + 1 WHERE k = 1, - ``` - - 或者 - - ```SQL - DELETE FROM desT WHERE k = 1; - ``` - -4. 定义多个 INSERT 语句。 - - ```SQL - -- 插入具有指定值的数据。 - INSERT INTO desT VALUES (4,4); - -- 将数据从内表插入到另一个内表。 - INSERT INTO desT SELECT * FROM srcT; - -- 从远端存储插入数据。 - INSERT INTO desT - SELECT * FROM FILES( - "path" = "s3://inserttest/parquet/srcT.parquet", - "format" = "parquet", - "aws.s3.access_key" = "XXXXXXXXXX", - "aws.s3.secret_key" = "YYYYYYYYYY", - "aws.s3.region" = "us-west-2" - ); - ``` - -5. 应用或撤消事务。 - - - 要应用事务中的 SQL 语句。 - - ```SQL - COMMIT WORK; - ``` - - - 要撤消事务中的 SQL 语句。 - - ```SQL - ROLLBACK WORK; - ``` - -## 使用说明 - -- 目前，StarRocks 在 SQL 事务中支持 SELECT、INSERT、UPDATE 和 DELETE 语句。 从 v4.0 开始，只有在存算分离集群中才支持 UPDATE 和 DELETE。 -- 不允许对在同一事务中数据已更改的表执行 SELECT 语句。 -- 从 v4.0 开始，只有在存算分离集群中才支持在事务中对同一表执行多个 INSERT 语句。 -- 在一个事务中，您只能对每个表定义一个 UPDATE 或 DELETE 语句，并且它必须位于 INSERT 语句之前。 -- 后续 DML 语句无法读取同一事务中前面的语句带来的未提交更改。 例如，前面的 INSERT 语句的目标表不能是后续语句的源表。 否则，系统将返回错误。 -- 事务中 DML 语句的所有目标表必须位于同一数据库中。 不允许跨数据库操作。 -- 目前，不支持 INSERT OVERWRITE。 -- 不允许嵌套事务。 您不能在 BEGIN-COMMIT/ROLLBACK 对中指定 BEGIN WORK。 -- 如果正在进行的事务所属的会话终止或关闭，则该事务将自动回滚。 -- 如上所述，StarRock 仅支持事务隔离级别的有限 READ COMMITTED。 -- 不支持写入冲突检查。 当两个事务同时写入同一表时，两个事务都可以成功提交。 数据更改的可见性（顺序）取决于 COMMIT WORK 语句的执行顺序。 \ No newline at end of file diff --git a/docs/zh/loading/Spark-connector-starrocks.md b/docs/zh/loading/Spark-connector-starrocks.md deleted file mode 100644 index f2b66d6..0000000 --- a/docs/zh/loading/Spark-connector-starrocks.md +++ /dev/null @@ -1,682 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 使用 Spark Connector 导入数据 (推荐) - -StarRocks 提供了一个自主开发的 Connector，名为 StarRocks Connector for Apache Spark™ (简称 Spark Connector)，以帮助您使用 Spark 将数据导入到 StarRocks 表中。其基本原理是先积累数据，然后通过 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md) 一次性将所有数据导入到 StarRocks 中。Spark Connector 基于 Spark DataSource V2 实现。DataSource 可以使用 Spark DataFrames 或 Spark SQL 创建。同时支持批量和结构化流模式。 - -> **注意** -> -> 只有对 StarRocks 表具有 SELECT 和 INSERT 权限的用户才能将数据导入到该表。您可以按照 [GRANT](../sql-reference/sql-statements/account-management/GRANT.md) 中提供的说明，将这些权限授予用户。 - -## 版本要求 - -| Spark connector | Spark | StarRocks | Java | Scala | -| --------------- | ---------------- | ------------- | ---- | ----- | -| 1.1.2 | 3.2, 3.3, 3.4, 3.5 | 2.5 及更高版本 | 8 | 2.12 | -| 1.1.1 | 3.2, 3.3, or 3.4 | 2.5 及更高版本 | 8 | 2.12 | -| 1.1.0 | 3.2, 3.3, or 3.4 | 2.5 及更高版本 | 8 | 2.12 | - -> **注意** -> -> - 请参阅 [升级 Spark connector](#upgrade-spark-connector) 以了解不同版本的 Spark Connector 之间的行为变更。 -> - 从 1.1.1 版本开始，Spark Connector 不提供 MySQL JDBC 驱动程序，您需要手动将驱动程序导入到 Spark classpath 中。您可以在 [MySQL site](https://dev.mysql.com/downloads/connector/j/) 或 [Maven Central](https://repo1.maven.org/maven2/mysql/mysql-connector-java/) 上找到该驱动程序。 - -## 获取 Spark connector - -您可以通过以下方式获取 Spark Connector JAR 文件： - -- 直接下载已编译的 Spark Connector JAR 文件。 -- 在您的 Maven 项目中添加 Spark Connector 作为依赖项，然后下载 JAR 文件。 -- 自行将 Spark Connector 的源代码编译为 JAR 文件。 - -Spark Connector JAR 文件的命名格式为 `starrocks-spark-connector-${spark_version}_${scala_version}-${connector_version}.jar`。 - -例如，如果您在您的环境中安装了 Spark 3.2 和 Scala 2.12，并且您想使用 Spark Connector 1.1.0，您可以使用 `starrocks-spark-connector-3.2_2.12-1.1.0.jar`。 - -> **注意** -> -> 通常，最新版本的 Spark Connector 仅保持与最近三个版本的 Spark 的兼容性。 - -### 下载已编译的 Jar 文件 - -直接从 [Maven Central Repository](https://repo1.maven.org/maven2/com/starrocks) 下载相应版本的 Spark Connector JAR。 - -### Maven 依赖 - -1. 在您的 Maven 项目的 `pom.xml` 文件中，按照以下格式添加 Spark Connector 作为依赖项。将 `spark_version`、`scala_version` 和 `connector_version` 替换为相应的版本。 - - ```xml - - com.starrocks - starrocks-spark-connector-${spark_version}_${scala_version} - ${connector_version} - - ``` - -2. 例如，如果您的环境中的 Spark 版本是 3.2，Scala 版本是 2.12，并且您选择 Spark Connector 1.1.0，您需要添加以下依赖项： - - ```xml - - com.starrocks - starrocks-spark-connector-3.2_2.12 - 1.1.0 - - ``` - -### 自行编译 - -1. 下载 [Spark connector package](https://github.com/StarRocks/starrocks-connector-for-apache-spark)。 -2. 执行以下命令将 Spark Connector 的源代码编译为 JAR 文件。请注意，`spark_version` 替换为相应的 Spark 版本。 - - ```bash - sh build.sh - ``` - - 例如，如果您的环境中的 Spark 版本是 3.2，您需要执行以下命令： - - ```bash - sh build.sh 3.2 - ``` - -3. 转到 `target/` 目录以查找 Spark Connector JAR 文件，例如编译后生成的 `starrocks-spark-connector-3.2_2.12-1.1.0-SNAPSHOT.jar`。 - -> **注意** -> -> 非正式发布的 Spark Connector 的名称包含 `SNAPSHOT` 后缀。 - -## 参数 - -### starrocks.fe.http.url - -**是否必须**: 是
-**默认值**: 无
-**描述**: StarRocks 集群中 FE 的 HTTP URL。您可以指定多个 URL，这些 URL 必须用逗号 (,) 分隔。格式：`:,:`。从 1.1.1 版本开始，您还可以向 URL 添加 `http://` 前缀，例如 `http://:,http://:`。 - -### starrocks.fe.jdbc.url - -**是否必须**: 是
-**默认值**: 无
-**描述**: 用于连接到 FE 的 MySQL 服务器的地址。格式：`jdbc:mysql://:`。 - -### starrocks.table.identifier - -**是否必须**: 是
-**默认值**: 无
-**描述**: StarRocks 表的名称。格式：`.`。 - -### starrocks.user - -**是否必须**: 是
-**默认值**: 无
-**描述**: StarRocks 集群帐户的用户名。该用户需要对 StarRocks 表具有 [SELECT 和 INSERT 权限](../sql-reference/sql-statements/account-management/GRANT.md)。 - -### starrocks.password - -**是否必须**: 是
-**默认值**: 无
-**描述**: StarRocks 集群帐户的密码。 - -### starrocks.write.label.prefix - -**是否必须**: 否
-**默认值**: spark-
-**描述**: Stream Load 使用的 Label 前缀。 - -### starrocks.write.enable.transaction-stream-load - -**是否必须**: 否
-**默认值**: TRUE
-**描述**: 是否使用 [Stream Load 事务接口](../loading/Stream_Load_transaction_interface.md) 加载数据。它需要 StarRocks v2.5 或更高版本。此功能可以在事务中加载更多数据，同时减少内存使用，并提高性能。
**注意：** 从 1.1.1 开始，此参数仅当 `starrocks.write.max.retries` 的值为非正数时才生效，因为 Stream Load 事务接口不支持重试。 - -### starrocks.write.buffer.size - -**是否必须**: 否
-**默认值**: 104857600
-**描述**: 在一次发送到 StarRocks 之前可以在内存中累积的最大数据量。将此参数设置为较大的值可以提高加载性能，但可能会增加加载延迟。 - -### starrocks.write.buffer.rows - -**是否必须**: 否
-**默认值**: Integer.MAX_VALUE
-**描述**: 自 1.1.1 版本起支持。在一次发送到 StarRocks 之前可以在内存中累积的最大行数。 - -### starrocks.write.flush.interval.ms - -**是否必须**: 否
-**默认值**: 300000
-**描述**: 将数据发送到 StarRocks 的间隔。此参数用于控制加载延迟。 - -### starrocks.write.max.retries - -**是否必须**: 否
-**默认值**: 3
-**描述**: 自 1.1.1 版本起支持。如果加载失败，Connector 重试对同一批数据执行 Stream Load 的次数。
**注意：** 因为 Stream Load 事务接口不支持重试。如果此参数为正数，则 Connector 始终使用 Stream Load 接口并忽略 `starrocks.write.enable.transaction-stream-load` 的值。 - -### starrocks.write.retry.interval.ms - -**是否必须**: 否
-**默认值**: 10000
-**描述**: 自 1.1.1 版本起支持。如果加载失败，重试对同一批数据执行 Stream Load 的间隔。 - -### starrocks.columns - -**是否必须**: 否
-**默认值**: 无
-**描述**: 您要将数据加载到的 StarRocks 表列。您可以指定多个列，这些列必须用逗号 (,) 分隔，例如 `"col0,col1,col2"`。 - -### starrocks.column.types - -**是否必须**: 否
-**默认值**: 无
-**描述**: 自 1.1.1 版本起支持。自定义 Spark 的列数据类型，而不是使用从 StarRocks 表和 [默认映射](#data-type-mapping-between-spark-and-starrocks) 推断的默认值。参数值是 DDL 格式的 Schema，与 Spark [StructType#toDDL](https://github.com/apache/spark/blob/master/sql/api/src/main/scala/org/apache/spark/sql/types/StructType.scala#L449) 的输出相同，例如 `col0 INT, col1 STRING, col2 BIGINT`。请注意，您只需要指定需要自定义的列。一个用例是将数据加载到 [BITMAP](#load-data-into-columns-of-bitmap-type) 或 [HLL](#load-data-into-columns-of-hll-type) 类型的列中。 - -### starrocks.write.properties.* - -**是否必须**: 否
-**默认值**: 无
-**描述**: 用于控制 Stream Load 行为的参数。例如，参数 `starrocks.write.properties.format` 指定要加载的数据的格式，例如 CSV 或 JSON。有关支持的参数及其描述的列表，请参阅 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -### starrocks.write.properties.format - -**是否必须**: 否
-**默认值**: CSV
-**描述**: Spark Connector 在将每批数据发送到 StarRocks 之前转换数据的基于的文件格式。有效值：CSV 和 JSON。 - -### starrocks.write.properties.row_delimiter - -**是否必须**: 否
-**默认值**: \n
-**描述**: CSV 格式数据的行分隔符。 - -### starrocks.write.properties.column_separator - -**是否必须**: 否
-**默认值**: \t
-**描述**: CSV 格式数据的列分隔符。 - -### starrocks.write.properties.partial_update - -**是否必须**: 否
-**默认值**: `FALSE`
-**描述**: 是否使用部分更新。有效值：`TRUE` 和 `FALSE`。默认值：`FALSE`，表示禁用此功能。 - -### starrocks.write.properties.partial_update_mode - -**是否必须**: 否
-**默认值**: `row`
-**描述**: 指定部分更新的模式。有效值：`row` 和 `column`。
  • 值 `row` (默认) 表示行模式下的部分更新，更适合于具有许多列和小批量的实时更新。
  • 值 `column` 表示列模式下的部分更新，更适合于具有少量列和许多行的批量更新。在这种情况下，启用列模式可以提供更快的更新速度。例如，在一个具有 100 列的表中，如果仅更新所有行的 10 列（总数的 10%），则列模式的更新速度快 10 倍。
- -### starrocks.write.num.partitions - -**是否必须**: 否
-**默认值**: 无
-**描述**: Spark 可以并行写入数据的分区数。当数据量较小时，您可以减少分区数以降低加载并发和频率。此参数的默认值由 Spark 确定。但是，此方法可能会导致 Spark Shuffle 成本。 - -### starrocks.write.partition.columns - -**是否必须**: 否
-**默认值**: 无
-**描述**: Spark 中的分区列。该参数仅当指定了 `starrocks.write.num.partitions` 时才生效。如果未指定此参数，则所有正在写入的列都用于分区。 - -### starrocks.timezone - -**是否必须**: 否
-**默认值**: JVM 的默认时区
-**描述**: 自 1.1.1 起支持。用于将 Spark `TimestampType` 转换为 StarRocks `DATETIME` 的时区。默认值是由 `ZoneId#systemDefault()` 返回的 JVM 时区。格式可以是时区名称，例如 `Asia/Shanghai`，或时区偏移量，例如 `+08:00`。 - -## Spark 和 StarRocks 之间的数据类型映射 - -- 默认数据类型映射如下： - - | Spark 数据类型 | StarRocks 数据类型 | - | --------------- | ------------------------------------------------------------ | - | BooleanType | BOOLEAN | - | ByteType | TINYINT | - | ShortType | SMALLINT | - | IntegerType | INT | - | LongType | BIGINT | - | StringType | LARGEINT | - | FloatType | FLOAT | - | DoubleType | DOUBLE | - | DecimalType | DECIMAL | - | StringType | CHAR | - | StringType | VARCHAR | - | StringType | STRING | - | StringType | JSON | - | DateType | DATE | - | TimestampType | DATETIME | - | ArrayType | ARRAY
**注意：**
**自 1.1.1 版本起支持**。有关详细步骤，请参阅 [将数据加载到 ARRAY 类型的列中](#load-data-into-columns-of-array-type)。 | - -- 您还可以自定义数据类型映射。 - - 例如，StarRocks 表包含 BITMAP 和 HLL 列，但 Spark 不支持这两种数据类型。您需要在 Spark 中自定义相应的数据类型。有关详细步骤，请参阅将数据加载到 [BITMAP](#load-data-into-columns-of-bitmap-type) 和 [HLL](#load-data-into-columns-of-hll-type) 列中。**自 1.1.1 版本起支持 BITMAP 和 HLL**。 - -## 升级 Spark connector - -### 从 1.1.0 版本升级到 1.1.1 版本 - -- 从 1.1.1 版本开始，Spark Connector 不提供 `mysql-connector-java`，它是 MySQL 的官方 JDBC 驱动程序，因为 `mysql-connector-java` 使用的 GPL 许可存在限制。 - 但是，Spark Connector 仍然需要 MySQL JDBC 驱动程序来连接到 StarRocks 以获取表元数据，因此您需要手动将驱动程序添加到 Spark classpath 中。您可以在 [MySQL site](https://dev.mysql.com/downloads/connector/j/) 或 [Maven Central](https://repo1.maven.org/maven2/mysql/mysql-connector-java/) 上找到该驱动程序。 -- 从 1.1.1 版本开始，Connector 默认使用 Stream Load 接口，而不是 1.1.0 版本中的 Stream Load 事务接口。如果您仍然想使用 Stream Load 事务接口，您可以 - 将选项 `starrocks.write.max.retries` 设置为 `0`。有关详细信息，请参阅 `starrocks.write.enable.transaction-stream-load` 和 `starrocks.write.max.retries` 的描述。 - -## 示例 - -以下示例展示了如何使用 Spark Connector 通过 Spark DataFrames 或 Spark SQL 将数据加载到 StarRocks 表中。Spark DataFrames 支持批量和结构化流模式。 - -有关更多示例，请参阅 [Spark Connector Examples](https://github.com/StarRocks/starrocks-connector-for-apache-spark/tree/main/src/test/java/com/starrocks/connector/spark/examples)。 - -### 准备工作 - -#### 创建 StarRocks 表 - -创建一个数据库 `test` 并创建一个主键表 `score_board`。 - -```sql -CREATE DATABASE `test`; - -CREATE TABLE `test`.`score_board` -( - `id` int(11) NOT NULL COMMENT "", - `name` varchar(65533) NULL DEFAULT "" COMMENT "", - `score` int(11) NOT NULL DEFAULT "0" COMMENT "" -) -ENGINE=OLAP -PRIMARY KEY(`id`) -COMMENT "OLAP" -DISTRIBUTED BY HASH(`id`); -``` - -#### 网络配置 - -确保 Spark 所在的机器可以通过 [`http_port`](../administration/management/FE_configuration.md#http_port) (默认值：`8030`) 和 [`query_port`](../administration/management/FE_configuration.md#query_port) (默认值：`9030`) 访问 StarRocks 集群的 FE 节点，并通过 [`be_http_port`](../administration/management/BE_configuration.md#be_http_port) (默认值：`8040`) 访问 BE 节点。 - -#### 设置您的 Spark 环境 - -请注意，以下示例在 Spark 3.2.4 中运行，并使用 `spark-shell`、`pyspark` 和 `spark-sql`。在运行示例之前，请确保将 Spark Connector JAR 文件放在 `$SPARK_HOME/jars` 目录中。 - -### 使用 Spark DataFrames 加载数据 - -以下两个示例说明了如何使用 Spark DataFrames 批量或结构化流模式加载数据。 - -#### 批量 - -在内存中构造数据并将数据加载到 StarRocks 表中。 - -1. 您可以使用 Scala 或 Python 编写 Spark 应用程序。 - - 对于 Scala，在 `spark-shell` 中运行以下代码片段： - - ```Scala - // 1. 从序列创建 DataFrame。 - val data = Seq((1, "starrocks", 100), (2, "spark", 100)) - val df = data.toDF("id", "name", "score") - - // 2. 通过将格式配置为 "starrocks" 和以下选项来写入 StarRocks。 - // 您需要根据自己的环境修改选项。 - df.write.format("starrocks") - .option("starrocks.fe.http.url", "127.0.0.1:8030") - .option("starrocks.fe.jdbc.url", "jdbc:mysql://127.0.0.1:9030") - .option("starrocks.table.identifier", "test.score_board") - .option("starrocks.user", "root") - .option("starrocks.password", "") - .mode("append") - .save() - ``` - - 对于 Python，在 `pyspark` 中运行以下代码片段： - - ```python - from pyspark.sql import SparkSession - - spark = SparkSession \ - .builder \ - .appName("StarRocks Example") \ - .getOrCreate() - - # 1. 从序列创建 DataFrame。 - data = [(1, "starrocks", 100), (2, "spark", 100)] - df = spark.sparkContext.parallelize(data) \ - .toDF(["id", "name", "score"]) - - # 2. 通过将格式配置为 "starrocks" 和以下选项来写入 StarRocks。 - # 您需要根据自己的环境修改选项。 - df.write.format("starrocks") \ - .option("starrocks.fe.http.url", "127.0.0.1:8030") \ - .option("starrocks.fe.jdbc.url", "jdbc:mysql://127.0.0.1:9030") \ - .option("starrocks.table.identifier", "test.score_board") \ - .option("starrocks.user", "root") \ - .option("starrocks.password", "") \ - .mode("append") \ - .save() - ``` - -2. 在 StarRocks 表中查询数据。 - - ```sql - MySQL [test]> SELECT * FROM `score_board`; - +------+-----------+-------+ - | id | name | score | - +------+-----------+-------+ - | 1 | starrocks | 100 | - | 2 | spark | 100 | - +------+-----------+-------+ - 2 rows in set (0.00 sec) - ``` - -#### 结构化流 - -构造从 CSV 文件读取数据的流，并将数据加载到 StarRocks 表中。 - -1. 在目录 `csv-data` 中，创建一个包含以下数据的 CSV 文件 `test.csv`： - - ```csv - 3,starrocks,100 - 4,spark,100 - ``` - -2. 您可以使用 Scala 或 Python 编写 Spark 应用程序。 - - 对于 Scala，在 `spark-shell` 中运行以下代码片段： - - ```Scala - import org.apache.spark.sql.types.StructType - - // 1. 从 CSV 创建 DataFrame。 - val schema = (new StructType() - .add("id", "integer") - .add("name", "string") - .add("score", "integer") - ) - val df = (spark.readStream - .option("sep", ",") - .schema(schema) - .format("csv") - // 将其替换为您的目录 "csv-data" 的路径。 - .load("/path/to/csv-data") - ) - - // 2. 通过将格式配置为 "starrocks" 和以下选项来写入 StarRocks。 - // 您需要根据自己的环境修改选项。 - val query = (df.writeStream.format("starrocks") - .option("starrocks.fe.http.url", "127.0.0.1:8030") - .option("starrocks.fe.jdbc.url", "jdbc:mysql://127.0.0.1:9030") - .option("starrocks.table.identifier", "test.score_board") - .option("starrocks.user", "root") - .option("starrocks.password", "") - // 将其替换为您的检查点目录 - .option("checkpointLocation", "/path/to/checkpoint") - .outputMode("append") - .start() - ) - ``` - - 对于 Python，在 `pyspark` 中运行以下代码片段： - - ```python - from pyspark.sql import SparkSession - from pyspark.sql.types import IntegerType, StringType, StructType, StructField - - spark = SparkSession \ - .builder \ - .appName("StarRocks SS Example") \ - .getOrCreate() - - # 1. 从 CSV 创建 DataFrame。 - schema = StructType([ - StructField("id", IntegerType()), - StructField("name", StringType()), - StructField("score", IntegerType()) - ]) - df = ( - spark.readStream - .option("sep", ",") - .schema(schema) - .format("csv") - # 将其替换为您的目录 "csv-data" 的路径。 - .load("/path/to/csv-data") - ) - - # 2. 通过将格式配置为 "starrocks" 和以下选项来写入 StarRocks。 - # 您需要根据自己的环境修改选项。 - query = ( - df.writeStream.format("starrocks") - .option("starrocks.fe.http.url", "127.0.0.1:8030") - .option("starrocks.fe.jdbc.url", "jdbc:mysql://127.0.0.1:9030") - .option("starrocks.table.identifier", "test.score_board") - .option("starrocks.user", "root") - .option("starrocks.password", "") - # 将其替换为您的检查点目录 - .option("checkpointLocation", "/path/to/checkpoint") - .outputMode("append") - .start() - ) - ``` - -3. 在 StarRocks 表中查询数据。 - - ```SQL - MySQL [test]> select * from score_board; - +------+-----------+-------+ - | id | name | score | - +------+-----------+-------+ - | 4 | spark | 100 | - | 3 | starrocks | 100 | - +------+-----------+-------+ - 2 rows in set (0.67 sec) - ``` - -### 使用 Spark SQL 加载数据 - -以下示例说明了如何通过使用 [Spark SQL CLI](https://spark.apache.org/docs/latest/sql-distributed-sql-engine-spark-sql-cli.html) 中的 `INSERT INTO` 语句使用 Spark SQL 加载数据。 - -1. 在 `spark-sql` 中执行以下 SQL 语句： - - ```SQL - -- 1. 通过将数据源配置为 `starrocks` 和以下选项来创建表。 - -- 您需要根据自己的环境修改选项。 - CREATE TABLE `score_board` - USING starrocks - OPTIONS( - "starrocks.fe.http.url"="127.0.0.1:8030", - "starrocks.fe.jdbc.url"="jdbc:mysql://127.0.0.1:9030", - "starrocks.table.identifier"="test.score_board", - "starrocks.user"="root", - "starrocks.password"="" - ); - - -- 2. 将两行插入到表中。 - INSERT INTO `score_board` VALUES (5, "starrocks", 100), (6, "spark", 100); - ``` - -2. 在 StarRocks 表中查询数据。 - - ```SQL - MySQL [test]> select * from score_board; - +------+-----------+-------+ - | id | name | score | - +------+-----------+-------+ - | 6 | spark | 100 | - | 5 | starrocks | 100 | - +------+-----------+-------+ - 2 rows in set (0.00 sec) - ``` - -## 最佳实践 - -### 导入数据到主键表 - -本节将展示如何将数据导入到 StarRocks 主键表以实现部分更新和条件更新。 -您可以参阅 [通过导入更改数据](../loading/Load_to_Primary_Key_tables.md) 以获取这些功能的详细介绍。 -这些示例使用 Spark SQL。 - -#### 准备工作 - -在 StarRocks 中创建一个数据库 `test` 并创建一个主键表 `score_board`。 - -```SQL -CREATE DATABASE `test`; - -CREATE TABLE `test`.`score_board` -( - `id` int(11) NOT NULL COMMENT "", - `name` varchar(65533) NULL DEFAULT "" COMMENT "", - `score` int(11) NOT NULL DEFAULT "0" COMMENT "" -) -ENGINE=OLAP -PRIMARY KEY(`id`) -COMMENT "OLAP" -DISTRIBUTED BY HASH(`id`); -``` - -#### 部分更新 - -本示例将展示如何仅通过导入更新列 `name` 中的数据： - -1. 在 MySQL 客户端中将初始数据插入到 StarRocks 表中。 - - ```sql - mysql> INSERT INTO `score_board` VALUES (1, 'starrocks', 100), (2, 'spark', 100); - - mysql> select * from score_board; - +------+-----------+-------+ - | id | name | score | - +------+-----------+-------+ - | 1 | starrocks | 100 | - | 2 | spark | 100 | - +------+-----------+-------+ - 2 rows in set (0.02 sec) - ``` - -2. 在 Spark SQL 客户端中创建一个 Spark 表 `score_board`。 - - - 将选项 `starrocks.write.properties.partial_update` 设置为 `true`，这会告诉 Connector 执行部分更新。 - - 将选项 `starrocks.columns` 设置为 `"id,name"`，以告诉 Connector 要写入哪些列。 - - ```SQL - CREATE TABLE `score_board` - USING starrocks - OPTIONS( - "starrocks.fe.http.url"="127.0.0.1:8030", - "starrocks.fe.jdbc.url"="jdbc:mysql://127.0.0.1:9030", - "starrocks.table.identifier"="test.score_board", - "starrocks.user"="root", - "starrocks.password"="", - "starrocks.write.properties.partial_update"="true", - "starrocks.columns"="id,name" - ); - ``` - -3. 在 Spark SQL 客户端中将数据插入到表中，并且仅更新列 `name`。 - - ```SQL - INSERT INTO `score_board` VALUES (1, 'starrocks-update'), (2, 'spark-update'); - ``` - -4. 在 MySQL 客户端中查询 StarRocks 表。 - - 您可以看到只有 `name` 的值发生了变化，而 `score` 的值没有发生变化。 - - ```SQL - mysql> select * from score_board; - +------+------------------+-------+ - | id | name | score | - +------+------------------+-------+ - | 1 | starrocks-update | 100 | - | 2 | spark-update | 100 | - +------+------------------+-------+ - 2 rows in set (0.02 sec) - ``` - -#### 条件更新 - -本示例将展示如何根据列 `score` 的值执行条件更新。仅当 `score` 的新值大于或等于旧值时，对 `id` 的更新才会生效。 - -1. 在 MySQL 客户端中将初始数据插入到 StarRocks 表中。 - - ```SQL - mysql> INSERT INTO `score_board` VALUES (1, 'starrocks', 100), (2, 'spark', 100); - - mysql> select * from score_board; - +------+-----------+-------+ - | id | name | score | - +------+-----------+-------+ - | 1 | starrocks | 100 | - | 2 | spark | 100 | - +------+-----------+-------+ - 2 rows in set (0.02 sec) - ``` - -2. 通过以下方式创建一个 Spark 表 `score_board`。 - - - 将选项 `starrocks.write.properties.merge_condition` 设置为 `score`，这会告诉 Connector 使用列 `score` 作为条件。 - - 确保 Spark Connector 使用 Stream Load 接口加载数据，而不是 Stream Load 事务接口，因为后者不支持此功能。 - - ```SQL - CREATE TABLE `score_board` - USING starrocks - OPTIONS( - "starrocks.fe.http.url"="127.0.0.1:8030", - "starrocks.fe.jdbc.url"="jdbc:mysql://127.0.0.1:9030", - "starrocks.table.identifier"="test.score_board", - "starrocks.user"="root", - "starrocks.password"="", - "starrocks.write.properties.merge_condition"="score" - ); - ``` - -3. 将数据插入到 Spark SQL 客户端中的表中，并使用较小的 Score 值更新 `id` 为 1 的行，并使用较大的 Score 值更新 `id` 为 2 的行。 - - ```SQL - INSERT INTO `score_board` VALUES (1, 'starrocks-update', 99), (2, 'spark-update', 101); - ``` - -4. 在 MySQL 客户端中查询 StarRocks 表。 - - 您可以看到只有 `id` 为 2 的行发生了变化，而 `id` 为 1 的行没有发生变化。 - - ```SQL - mysql> select * from score_board; - +------+--------------+-------+ - | id | name | score | - +------+--------------+-------+ - | 1 | starrocks | 100 | - | 2 | spark-update | 101 | - +------+--------------+-------+ - 2 rows in set (0.03 sec) - ``` - -### 将数据加载到 BITMAP 类型的列中 - -[`BITMAP`](../sql-reference/data-types/other-data-types/BITMAP.md) 通常用于加速 Count Distinct，例如计算 UV，请参阅 [使用 Bitmap 进行精确的 Count Distinct](../using_starrocks/distinct_values/Using_bitmap.md)。 -这里我们以 UV 的计数为例，展示如何将数据加载到 `BITMAP` 类型的列中。**自 1.1.1 版本起支持 `BITMAP`**。 - -1. 创建一个 StarRocks 聚合表。 - - 在数据库 `test` 中，创建一个聚合表 `page_uv`，其中列 `visit_users` 定义为 `BITMAP` 类型，并配置了聚合函数 `BITMAP_UNION`。 - - ```SQL - CREATE TABLE `test`.`page_uv` ( - `page_id` INT NOT NULL COMMENT '页面 ID', - `visit_date` datetime NOT NULL COMMENT '访问时间', - `visit_users` BITMAP BITMAP_UNION NOT NULL COMMENT '用户 ID' - ) ENGINE=OLAP - AGGREGATE KEY(`page_id`, `visit_date`) - DISTRIBUTED BY HASH(`page_id`); - ``` - -2. 创建一个 Spark 表。 - - Spark 表的 Schema 是从 StarRocks 表推断出来的，并且 Spark 不支持 `BITMAP` 类型。因此，您需要在 Spark 中自定义相应的列数据类型，例如作为 `BIGINT`，通过配置选项 `"starrocks.column.types"="visit_users BIGINT"`。当使用 Stream Load 摄取数据时，Connector 使用 [`to_bitmap`](../sql-reference/sql-functions/bitmap-functions/to_bitmap.md) 函数将 `BIGINT` 类型的数据转换为 `BITMAP` 类型。 - - 在 `spark-sql` 中运行以下 DDL： - - ```SQL - CREATE TABLE `page_uv` - USING starrocks - OPTIONS( - "starrocks.fe.http.url"="127.0.0.1:8030", - "starrocks.fe.jdbc.url"="jdbc:mysql://127.0.0.1:9030", - "starrocks.table \ No newline at end of file diff --git a/docs/zh/loading/SparkLoad.md b/docs/zh/loading/SparkLoad.md deleted file mode 100644 index ca661d1..0000000 --- a/docs/zh/loading/SparkLoad.md +++ /dev/null @@ -1,537 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 使用 Spark Load 批量导入数据 - -Spark Load 使用外部 Apache Spark™ 资源来预处理导入的数据，从而提高导入性能并节省计算资源。它主要用于 **初始迁移** 和将 **大量数据导入** 到 StarRocks 中（数据量高达 TB 级别）。 - -Spark Load 是一种**异步**导入方法，用户需要通过 MySQL 协议创建 Spark 类型的导入作业，并使用 `SHOW LOAD` 查看导入结果。 - -> **注意** -> -> - 只有对 StarRocks 表具有 INSERT 权限的用户才能将数据导入到该表中。您可以按照 [GRANT](../sql-reference/sql-statements/account-management/GRANT.md) 中提供的说明授予所需的权限。 -> - Spark Load 不能用于将数据导入到主键表。 - -## 术语解释 - -- **Spark ETL**：主要负责导入过程中的数据 ETL，包括全局字典构建（BITMAP 类型）、分区、排序、聚合等。 -- **Broker**：Broker 是一个独立的无状态进程。它封装了文件系统接口，并为 StarRocks 提供了从远端存储系统读取文件的能力。 -- **Global Dictionary**：保存将数据从原始值映射到编码值的数据结构。原始值可以是任何数据类型，而编码值是整数。全局字典主要用于预计算精确去重的场景。 - -## 原理 - -用户通过 MySQL 客户端提交 Spark 类型的导入作业；FE 记录元数据并返回提交结果。 - -spark load 任务的执行分为以下几个主要阶段。 - -1. 用户将 spark load 作业提交给 FE。 -2. FE 调度提交 ETL 任务到 Apache Spark™ 集群执行。 -3. Apache Spark™ 集群执行 ETL 任务，包括全局字典构建（BITMAP 类型）、分区、排序、聚合等。 -4. ETL 任务完成后，FE 获取每个预处理切片的数据路径，并调度相关的 BE 执行 Push 任务。 -5. BE 通过 Broker 进程从 HDFS 读取数据，并将其转换为 StarRocks 存储格式。 - > 如果您选择不使用 Broker 进程，BE 将直接从 HDFS 读取数据。 -6. FE 调度生效版本并完成导入作业。 - -下图说明了 spark load 的主要流程。 - -![Spark load](../_assets/4.3.2-1.png) - ---- - -## Global Dictionary - -### 适用场景 - -目前，StarRocks 中的 BITMAP 列是使用 Roaringbitmap 实现的，它只接受整数作为输入数据类型。因此，如果您想在导入过程中为 BITMAP 列实现预计算，则需要将输入数据类型转换为整数。 - -在 StarRocks 现有的导入过程中，全局字典的数据结构是基于 Hive 表实现的，它保存了从原始值到编码值的映射。 - -### 构建过程 - -1. 从上游数据源读取数据，并生成一个临时 Hive 表，命名为 `hive-table`。 -2. 提取 `hive-table` 的非强调字段的值，以生成一个新的 Hive 表，命名为 `distinct-value-table`。 -3. 创建一个新的全局字典表，命名为 `dict-table`，其中一列用于原始值，一列用于编码值。 -4. 在 `distinct-value-table` 和 `dict-table` 之间进行左连接，然后使用窗口函数对该集合进行编码。最后，将去重列的原始值和编码值都写回 `dict-table`。 -5. 在 `dict-table` 和 `hive-table` 之间进行连接，以完成将 `hive-table` 中的原始值替换为整数编码值的工作。 -6. `hive-table` 将被下次数据预处理读取，然后在计算后导入到 StarRocks 中。 - -## 数据预处理 - -数据预处理的基本过程如下： - -1. 从上游数据源（HDFS 文件或 Hive 表）读取数据。 -2. 完成读取数据的字段映射和计算，然后基于分区信息生成 `bucket-id`。 -3. 基于 StarRocks 表的 Rollup 元数据生成 RollupTree。 -4. 迭代 RollupTree 并执行分层聚合操作。下一层级的 Rollup 可以从上一层级的 Rollup 计算得出。 -5. 每次完成聚合计算后，数据将根据 `bucket-id` 进行分桶，然后写入 HDFS。 -6. 后续的 Broker 进程将从 HDFS 拉取文件并将其导入到 StarRocks BE 节点。 - -## 基本操作 - -### 配置 ETL 集群 - -Apache Spark™ 在 StarRocks 中用作外部计算资源，用于 ETL 工作。可能还有其他外部资源添加到 StarRocks 中，例如用于查询的 Spark/GPU、用于外部存储的 HDFS/S3、用于 ETL 的 MapReduce 等。因此，我们引入了 `Resource Management` 来管理 StarRocks 使用的这些外部资源。 - -在提交 Apache Spark™ 导入作业之前，请配置 Apache Spark™ 集群以执行 ETL 任务。操作语法如下： - -~~~sql --- 创建 Apache Spark™ 资源 -CREATE EXTERNAL RESOURCE resource_name -PROPERTIES -( - type = spark, - spark_conf_key = spark_conf_value, - working_dir = path, - broker = broker_name, - broker.property_key = property_value -); - --- 删除 Apache Spark™ 资源 -DROP RESOURCE resource_name; - --- 显示资源 -SHOW RESOURCES -SHOW PROC "/resources"; - --- 权限 -GRANT USAGE_PRIV ON RESOURCE resource_name TO user_identityGRANT USAGE_PRIV ON RESOURCE resource_name TO ROLE role_name; -REVOKE USAGE_PRIV ON RESOURCE resource_name FROM user_identityREVOKE USAGE_PRIV ON RESOURCE resource_name FROM ROLE role_name; -~~~ - -- 创建资源 - -**例如**： - -~~~sql --- yarn 集群模式 -CREATE EXTERNAL RESOURCE "spark0" -PROPERTIES -( - "type" = "spark", - "spark.master" = "yarn", - "spark.submit.deployMode" = "cluster", - "spark.jars" = "xxx.jar,yyy.jar", - "spark.files" = "/tmp/aaa,/tmp/bbb", - "spark.executor.memory" = "1g", - "spark.yarn.queue" = "queue0", - "spark.hadoop.yarn.resourcemanager.address" = "127.0.0.1:9999", - "spark.hadoop.fs.defaultFS" = "hdfs://127.0.0.1:10000", - "working_dir" = "hdfs://127.0.0.1:10000/tmp/starrocks", - "broker" = "broker0", - "broker.username" = "user0", - "broker.password" = "password0" -); - --- yarn HA 集群模式 -CREATE EXTERNAL RESOURCE "spark1" -PROPERTIES -( - "type" = "spark", - "spark.master" = "yarn", - "spark.submit.deployMode" = "cluster", - "spark.hadoop.yarn.resourcemanager.ha.enabled" = "true", - "spark.hadoop.yarn.resourcemanager.ha.rm-ids" = "rm1,rm2", - "spark.hadoop.yarn.resourcemanager.hostname.rm1" = "host1", - "spark.hadoop.yarn.resourcemanager.hostname.rm2" = "host2", - "spark.hadoop.fs.defaultFS" = "hdfs://127.0.0.1:10000", - "working_dir" = "hdfs://127.0.0.1:10000/tmp/starrocks", - "broker" = "broker1" -); -~~~ - -`resource-name` 是在 StarRocks 中配置的 Apache Spark™ 资源的名称。 - -`PROPERTIES` 包括与 Apache Spark™ 资源相关的参数，如下所示： -> **注意** -> -> 有关 Apache Spark™ 资源 PROPERTIES 的详细说明，请参见 [CREATE RESOURCE](../sql-reference/sql-statements/Resource/CREATE_RESOURCE.md)。 - -- Spark 相关参数： - - `type`：资源类型，必需，目前仅支持 `spark`。 - - `spark.master`：必需，目前仅支持 `yarn`。 - - `spark.submit.deployMode`：Apache Spark™ 程序的部署模式，必需，目前支持 `cluster` 和 `client`。 - - `spark.hadoop.fs.defaultFS`：如果 master 是 yarn，则为必需。 - - 与 yarn 资源管理器相关的参数，必需。 - - 单个节点上的一个 ResourceManager - `spark.hadoop.yarn.resourcemanager.address`：单点资源管理器的地址。 - - ResourceManager HA - > 您可以选择指定 ResourceManager 的主机名或地址。 - - `spark.hadoop.yarn.resourcemanager.ha.enabled`：启用资源管理器 HA，设置为 `true`。 - - `spark.hadoop.yarn.resourcemanager.ha.rm-ids`：资源管理器逻辑 ID 列表。 - - `spark.hadoop.yarn.resourcemanager.hostname.rm-id`：对于每个 rm-id，指定与资源管理器对应的主机名。 - - `spark.hadoop.yarn.resourcemanager.address.rm-id`：对于每个 rm-id，指定客户端提交作业的 `host:port`。 - -- `*working_dir`：ETL 使用的目录。如果 Apache Spark™ 用作 ETL 资源，则为必需。例如：`hdfs://host:port/tmp/starrocks`。 - -- Broker 相关参数： - - `broker`：Broker 名称。如果 Apache Spark™ 用作 ETL 资源，则为必需。您需要提前使用 `ALTER SYSTEM ADD BROKER` 命令完成配置。 - - `broker.property_key`：Broker 进程读取 ETL 生成的中间文件时要指定的信息（例如，身份验证信息）。 - -**注意**： - -以上是通过 Broker 进程加载的参数说明。如果您打算在没有 Broker 进程的情况下加载数据，则应注意以下事项。 - -- 您无需指定 `broker`。 -- 如果您需要配置用户身份验证和 NameNode 节点的 HA，则需要在 HDFS 集群中的 hdfs-site.xml 文件中配置参数，有关参数的说明，请参见 [broker_properties](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md#hdfs)。并且您需要将 **hdfs-site.xml** 文件移动到每个 FE 的 **$FE_HOME/conf** 下和每个 BE 的 **$BE_HOME/conf** 下。 - -> 注意 -> -> 如果 HDFS 文件只能由特定用户访问，您仍然需要在 `broker.name` 中指定 HDFS 用户名，并在 `broker.password` 中指定用户密码。 - -- 查看资源 - -常规帐户只能查看他们具有 `USAGE-PRIV` 访问权限的资源。root 和 admin 帐户可以查看所有资源。 - -- 资源权限 - -资源权限通过 `GRANT REVOKE` 进行管理，目前仅支持 `USAGE-PRIV` 权限。您可以将 `USAGE-PRIV` 权限授予用户或角色。 - -~~~sql --- 授予 user0 访问 spark0 资源的权限 -GRANT USAGE_PRIV ON RESOURCE "spark0" TO "user0"@"%"; - --- 授予 role0 访问 spark0 资源的权限 -GRANT USAGE_PRIV ON RESOURCE "spark0" TO ROLE "role0"; - --- 授予 user0 访问所有资源的权限 -GRANT USAGE_PRIV ON RESOURCE* TO "user0"@"%"; - --- 授予 role0 访问所有资源的权限 -GRANT USAGE_PRIV ON RESOURCE* TO ROLE "role0"; - --- 撤销 user0 对 spark0 资源的使用权限 -REVOKE USAGE_PRIV ON RESOURCE "spark0" FROM "user0"@"%"; -~~~ - -### 配置 Spark Client - -为 FE 配置 Spark 客户端，以便后者可以通过执行 `spark-submit` 命令来提交 Spark 任务。建议使用官方版本的 Spark2 2.4.5 或更高版本 [spark download address](https://archive.apache.org/dist/spark/)。下载后，请按照以下步骤完成配置。 - -- 配置 `SPARK-HOME` - -将 Spark 客户端放置在与 FE 相同的机器上的目录中，并在 FE 配置文件中将 `spark_home_default_dir` 配置为此目录，默认情况下，该目录是 FE 根目录中的 `lib/spark2x` 路径，并且不能为空。 - -- **配置 SPARK 依赖包** - -要配置依赖包，请压缩并归档 Spark 客户端下 jars 文件夹中的所有 jar 文件，并将 FE 配置中的 `spark_resource_path` 项配置为此 zip 文件。如果此配置为空，FE 将尝试在 FE 根目录中查找 `lib/spark2x/jars/spark-2x.zip` 文件。如果 FE 无法找到它，它将报告错误。 - -提交 spark load 作业时，归档的依赖文件将上传到远程存储库。默认存储库路径位于 `working_dir/{cluster_id}` 目录下，并以 `--spark-repository--{resource-name}` 命名，这意味着集群中的一个资源对应于一个远程存储库。目录结构引用如下： - -~~~bash ----spark-repository--spark0/ - - |---archive-1.0.0/ - - | |\---lib-990325d2c0d1d5e45bf675e54e44fb16-spark-dpp-1.0.0\-jar-with-dependencies.jar - - | |\---lib-7670c29daf535efe3c9b923f778f61fc-spark-2x.zip - - |---archive-1.1.0/ - - | |\---lib-64d5696f99c379af2bee28c1c84271d5-spark-dpp-1.1.0\-jar-with-dependencies.jar - - | |\---lib-1bbb74bb6b264a270bc7fca3e964160f-spark-2x.zip - - |---archive-1.2.0/ - - | |-... - -~~~ - -除了 spark 依赖项（默认情况下命名为 `spark-2x.zip`）之外，FE 还会将 DPP 依赖项上传到远程存储库。如果 spark load 提交的所有依赖项已经存在于远程存储库中，则无需再次上传依赖项，从而节省了每次重复上传大量文件的时间。 - -### 配置 YARN Client - -为 FE 配置 yarn 客户端，以便 FE 可以执行 yarn 命令来获取正在运行的应用程序的状态或终止它。建议使用官方版本的 Hadoop2 2.5.2 或更高版本 ([hadoop download address](https://archive.apache.org/dist/hadoop/common/))。下载后，请按照以下步骤完成配置： - -- **配置 YARN 可执行路径** - -将下载的 yarn 客户端放置在与 FE 相同的机器上的目录中，并在 FE 配置文件中将 `yarn_client_path` 项配置为 yarn 的二进制可执行文件，默认情况下，该文件是 FE 根目录中的 `lib/yarn-client/hadoop/bin/yarn` 路径。 - -- **配置生成 YARN 所需的配置文件的路径（可选）** - -当 FE 通过 yarn 客户端获取应用程序的状态或终止应用程序时，默认情况下，StarRocks 会在 FE 根目录的 `lib/yarn-config` 路径中生成执行 yarn 命令所需的配置文件。可以通过配置 FE 配置文件中的 `yarn_config_dir` 条目来修改此路径，该条目当前包括 `core-site.xml` 和 `yarn-site.xml`。 - -### 创建导入作业 - -**语法：** - -~~~sql -LOAD LABEL load_label - (data_desc, ...) -WITH RESOURCE resource_name -[resource_properties] -[PROPERTIES (key1=value1, ... )] - -* load_label: - db_name.label_name - -* data_desc: - DATA INFILE ('file_path', ...) - [NEGATIVE] - INTO TABLE tbl_name - [PARTITION (p1, p2)] - [COLUMNS TERMINATED BY separator ] - [(col1, ...)] - [COLUMNS FROM PATH AS (col2, ...)] - [SET (k1=f1(xx), k2=f2(xx))] - [WHERE predicate] - - DATA FROM TABLE hive_external_tbl - [NEGATIVE] - INTO TABLE tbl_name - [PARTITION (p1, p2)] - [SET (k1=f1(xx), k2=f2(xx))] - [WHERE predicate] - -* resource_properties: - (key2=value2, ...) -~~~ - -**示例 1**：上游数据源为 HDFS 的情况 - -~~~sql -LOAD LABEL db1.label1 -( - DATA INFILE("hdfs://abc.com:8888/user/starrocks/test/ml/file1") - INTO TABLE tbl1 - COLUMNS TERMINATED BY "," - (tmp_c1,tmp_c2) - SET - ( - id=tmp_c2, - name=tmp_c1 - ), - DATA INFILE("hdfs://abc.com:8888/user/starrocks/test/ml/file2") - INTO TABLE tbl2 - COLUMNS TERMINATED BY "," - (col1, col2) - where col1 > 1 -) -WITH RESOURCE 'spark0' -( - "spark.executor.memory" = "2g", - "spark.shuffle.compress" = "true" -) -PROPERTIES -( - "timeout" = "3600" -); -~~~ - -**示例 2**：上游数据源为 Hive 的情况。 - -- 步骤 1：创建一个新的 Hive 资源 - -~~~sql -CREATE EXTERNAL RESOURCE hive0 -PROPERTIES -( - "type" = "hive", - "hive.metastore.uris" = "thrift://xx.xx.xx.xx:8080" -); - ~~~ - -- 步骤 2：创建一个新的 Hive 外部表 - -~~~sql -CREATE EXTERNAL TABLE hive_t1 -( - k1 INT, - K2 SMALLINT, - k3 varchar(50), - uuid varchar(100) -) -ENGINE=hive -PROPERTIES -( - "resource" = "hive0", - "database" = "tmp", - "table" = "t1" -); - ~~~ - -- 步骤 3：提交 load 命令，要求导入的 StarRocks 表中的列存在于 Hive 外部表中。 - -~~~sql -LOAD LABEL db1.label1 -( - DATA FROM TABLE hive_t1 - INTO TABLE tbl1 - SET - ( - uuid=bitmap_dict(uuid) - ) -) -WITH RESOURCE 'spark0' -( - "spark.executor.memory" = "2g", - "spark.shuffle.compress" = "true" -) -PROPERTIES -( - "timeout" = "3600" -); - ~~~ - -Spark load 中参数的介绍： - -- **Label** - -导入作业的 Label。每个导入作业都有一个 Label，该 Label 在数据库中是唯一的，遵循与 broker load 相同的规则。 - -- **数据描述类参数** - -目前，支持的数据源是 CSV 和 Hive 表。其他规则与 broker load 相同。 - -- **导入作业参数** - -导入作业参数是指属于导入语句的 `opt_properties` 部分的参数。这些参数适用于整个导入作业。规则与 broker load 相同。 - -- **Spark 资源参数** - -Spark 资源需要提前配置到 StarRocks 中，并且用户需要被授予 USAGE-PRIV 权限，然后才能将资源应用于 Spark load。 -当用户有临时需求时，可以设置 Spark 资源参数，例如为作业添加资源和修改 Spark 配置。该设置仅对该作业生效，不影响 StarRocks 集群中的现有配置。 - -~~~sql -WITH RESOURCE 'spark0' -( - "spark.driver.memory" = "1g", - "spark.executor.memory" = "3g" -) -~~~ - -- **当数据源为 Hive 时导入** - -目前，要在导入过程中使用 Hive 表，您需要创建 `Hive` 类型的外部表，然后在提交导入命令时指定其名称。 - -- **导入过程以构建全局字典** - -在 load 命令中，您可以按以下格式指定构建全局字典所需的字段：`StarRocks 字段名称=bitmap_dict(hive 表字段名称)` 请注意，目前**仅当上游数据源是 Hive 表时才支持全局字典**。 - -- **加载二进制类型数据** - -从 v2.5.17 开始，Spark Load 支持 bitmap_from_binary 函数，该函数可以将二进制数据转换为 bitmap 数据。如果 Hive 表或 HDFS 文件的列类型为二进制，并且 StarRocks 表中对应的列是 bitmap 类型的聚合列，则可以在 load 命令中按以下格式指定字段，`StarRocks 字段名称=bitmap_from_binary(Hive 表字段名称)`。这样就不需要构建全局字典。 - -## 查看导入作业 - -Spark load 导入是异步的，broker load 也是如此。用户必须记录导入作业的 label，并在 `SHOW LOAD` 命令中使用它来查看导入结果。查看导入的命令对于所有导入方法都是通用的。示例如下。 - -有关返回参数的详细说明，请参阅 Broker Load。不同之处如下。 - -~~~sql -mysql> show load order by createtime desc limit 1\G -*************************** 1. row *************************** - JobId: 76391 - Label: label1 - State: FINISHED - Progress: ETL:100%; LOAD:100% - Type: SPARK - EtlInfo: unselected.rows=4; dpp.abnorm.ALL=15; dpp.norm.ALL=28133376 - TaskInfo: cluster:cluster0; timeout(s):10800; max_filter_ratio:5.0E-5 - ErrorMsg: N/A - CreateTime: 2019-07-27 11:46:42 - EtlStartTime: 2019-07-27 11:46:44 - EtlFinishTime: 2019-07-27 11:49:44 - LoadStartTime: 2019-07-27 11:49:44 -LoadFinishTime: 2019-07-27 11:50:16 - URL: http://1.1.1.1:8089/proxy/application_1586619723848_0035/ - JobDetails: {"ScannedRows":28133395,"TaskNumber":1,"FileNumber":1,"FileSize":200000} -~~~ - -- **State** - -导入作业的当前阶段。 -PENDING：已提交作业。 -ETL：已提交 Spark ETL。 -LOADING：FE 调度 BE 执行 push 操作。 -FINISHED：push 已完成，版本已生效。 - -导入作业有两个最终阶段 – `CANCELLED` 和 `FINISHED`，都表示 load 作业已完成。`CANCELLED` 表示导入失败，`FINISHED` 表示导入成功。 - -- **Progress** - -导入作业进度的描述。有两种类型的进度 – ETL 和 LOAD，它们对应于导入过程的两个阶段，ETL 和 LOADING。 - -- LOAD 的进度范围为 0~100%。 - -`LOAD 进度 = 当前已完成的所有副本导入的 tablet 数量 / 此导入作业的 tablet 总数 * 100%`。 - -- 如果所有表都已导入，则 LOAD 进度为 99%，当导入进入最终验证阶段时，将更改为 100%。 - -- 导入进度不是线性的。如果在一段时间内进度没有变化，并不意味着导入没有执行。 - -- **Type** - - 导入作业的类型。SPARK 表示 spark load。 - -- **CreateTime/EtlStartTime/EtlFinishTime/LoadStartTime/LoadFinishTime** - -这些值表示创建导入的时间、ETL 阶段开始的时间、ETL 阶段完成的时间、LOADING 阶段开始的时间以及整个导入作业完成的时间。 - -- **JobDetails** - -显示作业的详细运行状态，包括导入的文件数、总大小（以字节为单位）、子任务数、正在处理的原始行数等。例如： - -~~~json - {"ScannedRows":139264,"TaskNumber":1,"FileNumber":1,"FileSize":940754064} -~~~ - -- **URL** - -您可以将输入复制到浏览器以访问相应应用程序的 Web 界面。 - -### 查看 Apache Spark™ Launcher 提交日志 - -有时，用户需要查看在 Apache Spark™ 作业提交期间生成的详细日志。默认情况下，日志保存在 FE 根目录中的 `log/spark_launcher_log` 路径中，命名为 `spark-launcher-{load-job-id}-{label}.log`。日志在此目录中保存一段时间，并在 FE 元数据中的导入信息被清除时删除。默认保留时间为 3 天。 - -### 取消导入 - -当 Spark load 作业状态不是 `CANCELLED` 或 `FINISHED` 时，用户可以通过指定导入作业的 Label 手动取消它。 - ---- - -## 相关系统配置 - -**FE 配置：** 以下配置是 Spark load 的系统级配置，适用于所有 Spark load 导入作业。可以通过修改 `fe.conf` 来调整配置值。 - -- enable-spark-load：启用 Spark load 和资源创建，默认值为 false。 -- spark-load-default-timeout-second：作业的默认超时时间为 259200 秒（3 天）。 -- spark-home-default-dir：Spark 客户端路径 (`fe/lib/spark2x`)。 -- spark-resource-path：打包的 S park 依赖项文件的路径（默认为空）。 -- spark-launcher-log-dir：Spark 客户端的提交日志存储的目录 (`fe/log/spark-launcher-log`)。 -- yarn-client-path：yarn 二进制可执行文件的路径 (`fe/lib/yarn-client/hadoop/bin/yarn`)。 -- yarn-config-dir：Yarn 的配置文件路径 (`fe/lib/yarn-config`)。 - ---- - -## 最佳实践 - -使用 Spark load 最合适的场景是原始数据位于文件系统 (HDFS) 中，并且数据量在数十 GB 到 TB 级别。对于较小的数据量，请使用 Stream Load 或 Broker Load。 - -有关完整的 spark load 导入示例，请参阅 github 上的演示：[https://github.com/StarRocks/demo/blob/master/docs/03_sparkLoad2StarRocks.md](https://github.com/StarRocks/demo/blob/master/docs/03_sparkLoad2StarRocks.md) - -## 常见问题解答 - -- `Error: When running with master 'yarn' either HADOOP-CONF-DIR or YARN-CONF-DIR must be set in the environment.` - - 使用 Spark Load 时，未在 Spark 客户端的 `spark-env.sh` 中配置 `HADOOP-CONF-DIR` 环境变量。 - -- `Error: Cannot run program "xxx/bin/spark-submit": error=2, No such file or directory` - - 使用 Spark Load 时，`spark_home_default_dir` 配置项未指定 Spark 客户端根目录。 - -- `Error: File xxx/jars/spark-2x.zip does not exist.` - - 使用 Spark load 时，`spark-resource-path` 配置项未指向打包的 zip 文件。 - -- `Error: yarn client does not exist in path: xxx/yarn-client/hadoop/bin/yarn` - - 使用 Spark load 时，yarn-client-path 配置项未指定 yarn 可执行文件。 - -- `ERROR: Cannot execute hadoop-yarn/bin/... /libexec/yarn-config.sh` - - 将 Hadoop 与 CDH 结合使用时，需要配置 `HADOOP_LIBEXEC_DIR` 环境变量。 - 由于 `hadoop-yarn` 和 hadoop 目录不同，因此默认的 `libexec` 目录将查找 `hadoop-yarn/bin/... /libexec`，而 `libexec` 位于 hadoop 目录中。 - ```yarn application status`` 命令获取 Spark 任务状态报告错误，导致导入作业失败。 \ No newline at end of file diff --git a/docs/zh/loading/StreamLoad.md b/docs/zh/loading/StreamLoad.md deleted file mode 100644 index 88047e4..0000000 --- a/docs/zh/loading/StreamLoad.md +++ /dev/null @@ -1,545 +0,0 @@ ---- -displayed_sidebar: docs -keywords: ['Stream Load'] ---- - -# 从本地文件系统加载数据 - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -StarRocks 提供了两种从本地文件系统加载数据的方法： - -- 使用 [Stream Load](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md) 进行同步导入 -- 使用 [Broker Load](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md) 进行异步导入 - -每种方式都有其优点： - -- Stream Load 支持 CSV 和 JSON 文件格式。如果您想从少量文件（每个文件大小不超过 10 GB）加载数据，建议使用此方法。 -- Broker Load 支持 Parquet、ORC、CSV 和 JSON 文件格式（从 v3.2.3 版本开始支持 JSON 文件格式）。如果您想从大量文件（每个文件大小超过 10 GB）加载数据，或者文件存储在网络附加存储 (NAS) 设备中，建议使用此方法。**从 v2.5 版本开始，支持使用 Broker Load 从本地文件系统加载数据。** - -对于 CSV 数据，请注意以下几点： - -- 您可以使用 UTF-8 字符串（例如逗号 (,)、制表符或管道符 (|)），其长度不超过 50 字节作为文本分隔符。 -- 空值用 `\N` 表示。例如，一个数据文件包含三列，该数据文件中的一条记录在第一列和第三列中包含数据，但在第二列中不包含数据。在这种情况下，您需要在第二列中使用 `\N` 来表示空值。这意味着该记录必须编译为 `a,\N,b` 而不是 `a,,b`。`a,,b` 表示该记录的第二列包含一个空字符串。 - -Stream Load 和 Broker Load 都支持在数据导入时进行数据转换，并支持在数据导入期间通过 UPSERT 和 DELETE 操作进行数据更改。更多信息，请参见 [在导入时转换数据](../loading/Etl_in_loading.md) 和 [通过导入更改数据](../loading/Load_to_Primary_Key_tables.md)。 - -## 前提条件 - -### 检查权限 - - - -#### 检查网络配置 - -确保您要加载的数据所在的机器可以通过 [`http_port`](../administration/management/FE_configuration.md#http_port) （默认值：`8030`）和 [`be_http_port`](../administration/management/BE_configuration.md#be_http_port) （默认值：`8040`）访问 StarRocks 集群的 FE 和 BE 节点。 - -## 通过 Stream Load 从本地文件系统加载 - -Stream Load 是一种基于 HTTP PUT 的同步导入方法。提交导入作业后，StarRocks 会同步运行该作业，并在作业完成后返回作业结果。您可以根据作业结果判断作业是否成功。 - -> **注意** -> -> 通过 Stream Load 将数据导入到 StarRocks 表后，也会更新基于该表创建的物化视图的数据。 - -### 原理 - -您可以在客户端上根据 HTTP 协议向 FE 提交导入请求，然后 FE 使用 HTTP 重定向将导入请求转发到特定的 BE 或 CN。您也可以直接在客户端上向您选择的 BE 或 CN 提交导入请求。 - -:::note - -如果您向 FE 提交导入请求，FE 会使用轮询机制来决定哪个 BE 或 CN 将作为协调器来接收和处理导入请求。轮询机制有助于在 StarRocks 集群中实现负载均衡。因此，我们建议您将导入请求发送到 FE。 - -::: - -接收导入请求的 BE 或 CN 作为协调器 BE 或 CN 运行，以根据使用的 schema 将数据拆分为多个部分，并将每个部分的数据分配给其他涉及的 BE 或 CN。导入完成后，协调器 BE 或 CN 将导入作业的结果返回给您的客户端。请注意，如果在导入期间停止协调器 BE 或 CN，则导入作业将失败。 - -下图显示了 Stream Load 作业的工作流程。 - -![Stream Load 工作流程](../_assets/4.2-1.png) - -### 限制 - -Stream Load 不支持加载包含 JSON 格式列的 CSV 文件的数据。 - -### 典型示例 - -本节以 curl 为例，介绍如何将 CSV 或 JSON 文件中的数据从本地文件系统加载到 StarRocks 中。有关详细的语法和参数说明，请参见 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -请注意，在 StarRocks 中，一些字面量被 SQL 语言用作保留关键字。不要在 SQL 语句中直接使用这些关键字。如果您想在 SQL 语句中使用这样的关键字，请将其用一对反引号 (`) 括起来。请参见 [关键字](../sql-reference/sql-statements/keywords.md)。 - -#### 加载 CSV 数据 - -##### 准备数据集 - -在您的本地文件系统中，创建一个名为 `example1.csv` 的 CSV 文件。该文件包含三列，依次表示用户 ID、用户名和用户分数。 - -```Plain -1,Lily,23 -2,Rose,23 -3,Alice,24 -4,Julia,25 -``` - -##### 创建数据库和表 - -创建一个数据库并切换到该数据库： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -创建一个名为 `table1` 的主键表。该表包含三列：`id`、`name` 和 `score`，其中 `id` 是主键。 - -```SQL -CREATE TABLE `table1` -( - `id` int(11) NOT NULL COMMENT "user ID", - `name` varchar(65533) NULL COMMENT "user name", - `score` int(11) NOT NULL COMMENT "user score" -) -ENGINE=OLAP -PRIMARY KEY(`id`) -DISTRIBUTED BY HASH(`id`); -``` - -:::note - -从 v2.5.7 开始，StarRocks 可以在您创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - -::: - -##### 启动 Stream Load - -运行以下命令将 `example1.csv` 的数据加载到 `table1` 中： - -```Bash -curl --location-trusted -u : -H "label:123" \ - -H "Expect:100-continue" \ - -H "column_separator:," \ - -H "columns: id, name, score" \ - -T example1.csv -XPUT \ - http://:/api/mydatabase/table1/_stream_load -``` - -:::note - -- 如果您使用的帐户未设置密码，则只需输入 `:`。 -- 您可以使用 [SHOW FRONTENDS](../sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_FRONTENDS.md) 查看 FE 节点的 IP 地址和 HTTP 端口。 - -::: - -`example1.csv` 包含三列，这些列由逗号 (,) 分隔，并且可以按顺序映射到 `table1` 的 `id`、`name` 和 `score` 列。因此，您需要使用 `column_separator` 参数将逗号 (,) 指定为列分隔符。您还需要使用 `columns` 参数将 `example1.csv` 的三列临时命名为 `id`、`name` 和 `score`，这些列按顺序映射到 `table1` 的三列。 - -导入完成后，您可以查询 `table1` 以验证导入是否成功： - -```SQL -SELECT * FROM table1; -+------+-------+-------+ -| id | name | score | -+------+-------+-------+ -| 1 | Lily | 23 | -| 2 | Rose | 23 | -| 3 | Alice | 24 | -| 4 | Julia | 25 | -+------+-------+-------+ -4 rows in set (0.00 sec) -``` - -#### 加载 JSON 数据 - -从 v3.2.7 开始，Stream Load 支持在传输过程中压缩 JSON 数据，从而减少网络带宽开销。用户可以使用参数 `compression` 和 `Content-Encoding` 指定不同的压缩算法。支持的压缩算法包括 GZIP、BZIP2、LZ4_FRAME 和 ZSTD。有关语法，请参见 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -##### 准备数据集 - -在您的本地文件系统中，创建一个名为 `example2.json` 的 JSON 文件。该文件包含两列，依次表示城市 ID 和城市名称。 - -```JSON -{"name": "Beijing", "code": 2} -``` - -##### 创建数据库和表 - -创建一个数据库并切换到该数据库： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -创建一个名为 `table2` 的主键表。该表包含两列：`id` 和 `city`，其中 `id` 是主键。 - -```SQL -CREATE TABLE `table2` -( - `id` int(11) NOT NULL COMMENT "city ID", - `city` varchar(65533) NULL COMMENT "city name" -) -ENGINE=OLAP -PRIMARY KEY(`id`) -DISTRIBUTED BY HASH(`id`); -``` - -:::note - -从 v2.5.7 开始，StarRocks 可以在您创建表或添加分区时自动设置 bucket 数量 (BUCKETS)。您不再需要手动设置 bucket 数量。有关详细信息，请参见 [设置 bucket 数量](../table_design/data_distribution/Data_distribution.md#set-the-number-of-buckets)。 - -::: - -##### 启动 Stream Load - -运行以下命令将 `example2.json` 的数据加载到 `table2` 中： - -```Bash -curl -v --location-trusted -u : -H "strict_mode: true" \ - -H "Expect:100-continue" \ - -H "format: json" -H "jsonpaths: [\"$.name\", \"$.code\"]" \ - -H "columns: city,tmp_id, id = tmp_id * 100" \ - -T example2.json -XPUT \ - http://:/api/mydatabase/table2/_stream_load -``` - -:::note - -- 如果您使用的帐户未设置密码，则只需输入 `:`。 -- 您可以使用 [SHOW FRONTENDS](../sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_FRONTENDS.md) 查看 FE 节点的 IP 地址和 HTTP 端口。 - -::: - -`example2.json` 包含两个键 `name` 和 `code`，它们映射到 `table2` 的 `id` 和 `city` 列，如下图所示。 - -![JSON - 列映射](../_assets/4.2-2.png) - -上图中显示的映射描述如下： - -- StarRocks 提取 `example2.json` 的 `name` 和 `code` 键，并将它们映射到 `jsonpaths` 参数中声明的 `name` 和 `code` 字段。 - -- StarRocks 提取 `jsonpaths` 参数中声明的 `name` 和 `code` 字段，并将它们**按顺序映射**到 `columns` 参数中声明的 `city` 和 `tmp_id` 字段。 - -- StarRocks 提取 `columns` 参数中声明的 `city` 和 `tmp_id` 字段，并将它们**按名称映射**到 `table2` 的 `city` 和 `id` 列。 - -:::note - -在前面的示例中，`example2.json` 中 `code` 的值在加载到 `table2` 的 `id` 列之前乘以 100。 - -::: - -有关 `jsonpaths`、`columns` 和 StarRocks 表的列之间的详细映射，请参见 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md) 中的“列映射”部分。 - -导入完成后，您可以查询 `table2` 以验证导入是否成功： - -```SQL -SELECT * FROM table2; -+------+--------+ -| id | city | -+------+--------+ -| 200 | Beijing| -+------+--------+ -4 rows in set (0.01 sec) -``` - -import Beta from '../_assets/commonMarkdown/_beta.mdx' - -#### 合并 Stream Load 请求 - - - -从 v3.4.0 开始，系统支持合并多个 Stream Load 请求。 - -:::warning - -请注意，Merge Commit 优化适用于在单个表上具有**并发** Stream Load 作业的场景。如果并发度为 1，则不建议使用此优化。同时，在将 `merge_commit_async` 设置为 `false` 并将 `merge_commit_interval_ms` 设置为较大的值之前，请三思，因为它们可能会导致导入性能下降。 - -::: - -Merge Commit 是一种针对 Stream Load 的优化，专为高并发、小批量（从 KB 到数十 MB）实时导入场景而设计。在早期版本中，每个 Stream Load 请求都会生成一个事务和一个数据版本，这导致在高并发导入场景中出现以下问题： - -- 过多的数据版本会影响查询性能，并且限制版本数量可能会导致 `too many versions` 错误。 -- 通过 Compaction 合并数据版本会增加资源消耗。 -- 它会生成小文件，从而增加 IOPS 和 I/O 延迟。在存算分离集群中，这也会增加云对象存储成本。 -- 作为事务管理器的 Leader FE 节点可能会成为单点瓶颈。 - -Merge Commit 通过将时间窗口内的多个并发 Stream Load 请求合并到单个事务中来缓解这些问题。这减少了高并发请求生成的事务和版本数量，从而提高了导入性能。 - -Merge Commit 支持同步和异步模式。每种模式都有其优点和缺点。您可以根据您的用例进行选择。 - -- **同步模式** - - 服务器仅在合并的事务提交后才返回，从而确保导入成功且可见。 - -- **异步模式** - - 服务器在收到数据后立即返回。此模式不保证导入成功。 - -| **模式** | **优点** | **缺点** | -| -------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| 同步 |
  • 确保请求返回时数据的持久性和可见性。
  • 保证来自同一客户端的多个顺序导入请求按顺序执行。
| 来自客户端的每个导入请求都会被阻塞，直到服务器关闭合并窗口。如果窗口过大，可能会降低单个客户端的数据处理能力。 | -| 异步 | 允许单个客户端发送后续导入请求，而无需等待服务器关闭合并窗口，从而提高导入吞吐量。 |
  • 不保证返回时数据的持久性或可见性。客户端必须稍后验证事务状态。
  • 不保证来自同一客户端的多个顺序导入请求按顺序执行。
| - -##### 启动 Stream Load - -- 运行以下命令以启动启用 Merge Commit 的 Stream Load 作业（同步模式），并将合并窗口设置为 `5000` 毫秒，并行度设置为 `2`： - - ```Bash - curl --location-trusted -u : \ - -H "Expect:100-continue" \ - -H "column_separator:," \ - -H "columns: id, name, score" \ - -H "enable_merge_commit:true" \ - -H "merge_commit_interval_ms:5000" \ - -H "merge_commit_parallel:2" \ - -T example1.csv -XPUT \ - http://:/api/mydatabase/table1/_stream_load - ``` - -- 运行以下命令以启动启用 Merge Commit 的 Stream Load 作业（异步模式），并将合并窗口设置为 `60000` 毫秒，并行度设置为 `2`： - - ```Bash - curl --location-trusted -u : \ - -H "Expect:100-continue" \ - -H "column_separator:," \ - -H "columns: id, name, score" \ - -H "enable_merge_commit:true" \ - -H "merge_commit_async:true" \ - -H "merge_commit_interval_ms:60000" \ - -H "merge_commit_parallel:2" \ - -T example1.csv -XPUT \ - http://:/api/mydatabase/table1/_stream_load - ``` - -:::note - -- Merge Commit 仅支持将**同构**导入请求合并到单个数据库和表中。“同构”表示 Stream Load 参数相同，包括：通用参数、JSON 格式参数、CSV 格式参数、`opt_properties` 和 Merge Commit 参数。 -- 对于加载 CSV 格式的数据，您必须确保每行都以行分隔符结尾。不支持 `skip_header`。 -- 服务器会自动为事务生成 label。如果指定了 label，则会被忽略。 -- Merge Commit 将多个导入请求合并到单个事务中。如果一个请求包含数据质量问题，则事务中的所有请求都将失败。 - -::: - -#### 检查 Stream Load 进度 - -导入作业完成后，StarRocks 以 JSON 格式返回作业结果。有关更多信息，请参见 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md) 中的“返回值”部分。 - -Stream Load 不允许您使用 SHOW LOAD 语句查询导入作业的结果。 - -#### 取消 Stream Load 作业 - -Stream Load 不允许您取消导入作业。如果导入作业超时或遇到错误，StarRocks 会自动取消该作业。 - -### 参数配置 - -本节介绍如果您选择导入方法 Stream Load，则需要配置的一些系统参数。这些参数配置对所有 Stream Load 作业生效。 - -- `streaming_load_max_mb`：您要加载的每个数据文件的最大大小。默认最大大小为 10 GB。有关更多信息，请参见 [配置 BE 或 CN 动态参数](../administration/management/BE_configuration.md)。 - - 我们建议您一次不要加载超过 10 GB 的数据。如果数据文件的大小超过 10 GB，我们建议您将数据文件拆分为每个小于 10 GB 的小文件，然后逐个加载这些文件。如果您无法拆分大于 10 GB 的数据文件，您可以根据文件大小增加此参数的值。 - - 增加此参数的值后，只有在您重新启动 StarRocks 集群的 BE 或 CN 后，新值才能生效。此外，系统性能可能会下降，并且在导入失败时重试的成本也会增加。 - - :::note - - 当您加载 JSON 文件的数据时，请注意以下几点： - - - 文件中每个 JSON 对象的大小不能超过 4 GB。如果文件中的任何 JSON 对象超过 4 GB，StarRocks 将抛出错误“This parser can't support a document that big.”。 - - - 默认情况下，HTTP 请求中的 JSON body 不能超过 100 MB。如果 JSON body 超过 100 MB，StarRocks 将抛出错误“The size of this batch exceed the max size [104857600] of json type data data [8617627793]. Set ignore_json_size to skip check, although it may lead huge memory consuming.”。要防止此错误，您可以在 HTTP 请求头中添加 `"ignore_json_size:true"` 以忽略对 JSON body 大小的检查。 - - ::: - -- `stream_load_default_timeout_second`：每个导入作业的超时时间。默认超时时间为 600 秒。有关更多信息，请参见 [配置 FE 动态参数](../administration/management/FE_configuration.md#configure-fe-dynamic-parameters)。 - - 如果您创建的许多导入作业超时，您可以根据从以下公式获得的计算结果来增加此参数的值： - - **每个导入作业的超时时间 > 要加载的数据量/平均加载速度** - - 例如，如果您要加载的数据文件的大小为 10 GB，并且 StarRocks 集群的平均加载速度为 100 MB/s，则将超时时间设置为超过 100 秒。 - - :::note - - 上述公式中的**平均加载速度**是 StarRocks 集群的平均加载速度。它因磁盘 I/O 和 StarRocks 集群中 BE 或 CN 的数量而异。 - - ::: - - Stream Load 还提供了 `timeout` 参数，允许您指定单个导入作业的超时时间。有关更多信息，请参见 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -### 使用注意事项 - -如果要在加载的数据文件中缺少某个记录的字段，并且 StarRocks 表中映射该字段的列定义为 `NOT NULL`，则 StarRocks 会在加载该记录期间自动在 StarRocks 表的映射列中填充 `NULL` 值。您还可以使用 `ifnull()` 函数来指定要填充的默认值。 - -例如，如果上述 `example2.json` 文件中缺少表示城市 ID 的字段，并且您想在 `table2` 的映射列中填充 `x` 值，则可以指定 `"columns: city, tmp_id, id = ifnull(tmp_id, 'x')"`. - -## 通过 Broker Load 从本地文件系统加载 - -除了 Stream Load 之外，您还可以使用 Broker Load 从本地文件系统加载数据。从 v2.5 版本开始支持此功能。 - -Broker Load 是一种异步导入方法。提交导入作业后，StarRocks 会异步运行该作业，并且不会立即返回作业结果。您需要手动查询作业结果。请参见 [检查 Broker Load 进度](#check-broker-load-progress)。 - -### 限制 - -- 目前，Broker Load 仅支持通过版本为 v2.5 或更高版本的单个 broker 从本地文件系统加载。 -- 针对单个 broker 的高并发查询可能会导致超时和 OOM 等问题。为了减轻影响，您可以使用 `pipeline_dop` 变量（请参见 [系统变量](../sql-reference/System_variable.md#pipeline_dop)）来设置 Broker Load 的查询并行度。对于针对单个 broker 的查询，我们建议您将 `pipeline_dop` 设置为小于 `16` 的值。 - -### 典型示例 - -Broker Load 支持从单个数据文件加载到单个表，从多个数据文件加载到单个表，以及从多个数据文件加载到多个表。本节以从多个数据文件加载到单个表为例。 - -请注意，在 StarRocks 中，一些字面量被 SQL 语言用作保留关键字。不要在 SQL 语句中直接使用这些关键字。如果您想在 SQL 语句中使用这样的关键字，请将其用一对反引号 (`) 括起来。请参见 [关键字](../sql-reference/sql-statements/keywords.md)。 - -#### 准备数据集 - -以 CSV 文件格式为例。登录到您的本地文件系统，并在特定存储位置（例如，`/home/disk1/business/`）中创建两个 CSV 文件 `file1.csv` 和 `file2.csv`。这两个文件都包含三列，依次表示用户 ID、用户名和用户分数。 - -- `file1.csv` - - ```Plain - 1,Lily,21 - 2,Rose,22 - 3,Alice,23 - 4,Julia,24 - ``` - -- `file2.csv` - - ```Plain - 5,Tony,25 - 6,Adam,26 - 7,Allen,27 - 8,Jacky,28 - ``` - -#### 创建数据库和表 - -创建一个数据库并切换到该数据库： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -创建一个名为 `mytable` 的主键表。该表包含三列：`id`、`name` 和 `score`，其中 `id` 是主键。 - -```SQL -CREATE TABLE `mytable` -( - `id` int(11) NOT NULL COMMENT "User ID", - `name` varchar(65533) NULL DEFAULT "" COMMENT "User name", - `score` int(11) NOT NULL DEFAULT "0" COMMENT "User score" -) -ENGINE=OLAP -PRIMARY KEY(`id`) -DISTRIBUTED BY HASH(`id`) -PROPERTIES("replication_num"="1"); -``` - -#### 启动 Broker Load - -运行以下命令以启动一个 Broker Load 作业，该作业将存储在本地文件系统的 `/home/disk1/business/` 路径中的所有数据文件（`file1.csv` 和 `file2.csv`）中的数据加载到 StarRocks 表 `mytable` 中： - -```SQL -LOAD LABEL mydatabase.label_local -( - DATA INFILE("file:///home/disk1/business/csv/*") - INTO TABLE mytable - COLUMNS TERMINATED BY "," - (id, name, score) -) -WITH BROKER "sole_broker" -PROPERTIES -( - "timeout" = "3600" -); -``` - -此作业有四个主要部分： - -- `LABEL`：一个字符串，用于查询导入作业的状态。 -- `LOAD` 声明：源 URI、源数据格式和目标表名称。 -- `PROPERTIES`：超时值和要应用于导入作业的任何其他属性。 - -有关详细的语法和参数说明，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -#### 检查 Broker Load 进度 - -在 v3.0 及更早版本中，使用 [SHOW LOAD](../sql-reference/sql-statements/loading_unloading/SHOW_LOAD.md) 语句或 curl 命令来查看 Broker Load 作业的进度。 - -在 v3.1 及更高版本中，您可以从 [`information_schema.loads`](../sql-reference/information_schema/loads.md) 视图中查看 Broker Load 作业的进度： - -```SQL -SELECT * FROM information_schema.loads; -``` - -如果您提交了多个导入作业，则可以按与该作业关联的 `LABEL` 进行过滤。示例： - -```SQL -SELECT * FROM information_schema.loads WHERE LABEL = 'label_local'; -``` - -确认导入作业已完成后，您可以查询表以查看数据是否已成功加载。示例： - -```SQL -SELECT * FROM mytable; -+------+-------+-------+ -| id | name | score | -+------+-------+-------+ -| 3 | Alice | 23 | -| 5 | Tony | 25 | -| 6 | Adam | 26 | -| 1 | Lily | 21 | -| 2 | Rose | 22 | -| 4 | Julia | 24 | -| 7 | Allen | 27 | -| 8 | Jacky | 28 | -+------+-------+-------+ -8 rows in set (0.07 sec) -``` - -#### 取消 Broker Load 作业 - -当导入作业未处于 **CANCELLED** 或 **FINISHED** 阶段时，您可以使用 [CANCEL LOAD](../sql-reference/sql-statements/loading_unloading/CANCEL_LOAD.md) 语句来取消该作业。 - -例如，您可以执行以下语句来取消数据库 `mydatabase` 中 label 为 `label_local` 的导入作业： - -```SQL -CANCEL LOAD -FROM mydatabase -WHERE LABEL = "label_local"; -``` - -## 通过 Broker Load 从 NAS 加载 - -有两种方法可以使用 Broker Load 从 NAS 加载数据： - -- 将 NAS 视为本地文件系统，并使用 broker 运行导入作业。请参见上一节“[通过 Broker Load 从本地系统加载](#loading-from-a-local-file-system-via-broker-load)”。 -- （推荐）将 NAS 视为云存储系统，并在没有 broker 的情况下运行导入作业。 - -本节介绍第二种方法。详细操作如下： - -1. 将 NAS 设备挂载到 StarRocks 集群的所有 BE 或 CN 节点和 FE 节点上的相同路径。这样，所有 BE 或 CN 都可以像访问自己本地存储的文件一样访问 NAS 设备。 - -2. 使用 Broker Load 将数据从 NAS 设备加载到目标 StarRocks 表。示例： - - ```SQL - LOAD LABEL test_db.label_nas - ( - DATA INFILE("file:///home/disk1/sr/*") - INTO TABLE mytable - COLUMNS TERMINATED BY "," - ) - WITH BROKER - PROPERTIES - ( - "timeout" = "3600" - ); - ``` - - 此作业有四个主要部分： - - - `LABEL`：一个字符串，用于查询导入作业的状态。 - - `LOAD` 声明：源 URI、源数据格式和目标表名称。请注意，声明中的 `DATA INFILE` 用于指定 NAS 设备的挂载点文件夹路径，如上例所示，其中 `file:///` 是前缀，`/home/disk1/sr` 是挂载点文件夹路径。 - - `BROKER`：您无需指定 broker 名称。 - - `PROPERTIES`：超时值和要应用于导入作业的任何其他属性。 - - 有关详细的语法和参数说明，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -提交作业后，您可以根据需要查看导入进度或取消作业。有关详细操作，请参见本主题中的“[检查 Broker Load 进度](#check-broker-load-progress)”和“[取消 Broker Load 作业](#cancel-a-broker-load-job)”。 \ No newline at end of file diff --git a/docs/zh/loading/Stream_Load_transaction_interface.md b/docs/zh/loading/Stream_Load_transaction_interface.md deleted file mode 100644 index f348822..0000000 --- a/docs/zh/loading/Stream_Load_transaction_interface.md +++ /dev/null @@ -1,546 +0,0 @@ ---- -displayed_sidebar: docs -keywords: ['Stream Load'] ---- - -# 使用 Stream Load 事务接口导入数据 - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -从 v2.4 版本开始，StarRocks 提供了一个 Stream Load 事务接口，用于为从外部系统（如 Apache Flink® 和 Apache Kafka®）加载数据的事务实现两阶段提交 (2PC)。Stream Load 事务接口有助于提高高并发流式导入的性能。 - -从 v4.0 版本开始，Stream Load 事务接口支持多表事务，即在同一数据库中将数据导入到多个表中。 - -本主题介绍 Stream Load 事务接口，以及如何使用此接口将数据导入到 StarRocks 中。 - -## 描述 - -Stream Load 事务接口支持使用与 HTTP 协议兼容的工具或语言来调用 API 操作。本主题以 curl 为例，说明如何使用此接口。此接口提供各种功能，例如事务管理、数据写入、事务预提交、事务去重和事务超时管理。 - -:::note -Stream Load 支持 CSV 和 JSON 文件格式。如果要从少量文件（单个文件大小不超过 10 GB）加载数据，建议使用此方法。Stream Load 不支持 Parquet 文件格式。如果需要从 Parquet 文件加载数据，请使用 [INSERT+files()](../loading/InsertInto.md#insert-data-directly-from-files-in-an-external-source-using-files) 。 -::: - -### 事务管理 - -Stream Load 事务接口提供以下 API 操作，用于管理事务： - -- `/api/transaction/begin`: 启动一个新事务。 - -- `/api/transaction/prepare`: 预提交当前事务，并使数据更改暂时持久化。预提交事务后，您可以继续提交或回滚事务。如果您的集群在事务预提交后崩溃，您仍然可以在集群恢复后继续提交事务。 - -- `/api/transaction/commit`: 提交当前事务以使数据更改持久化。 - -- `/api/transaction/rollback`: 回滚当前事务以中止数据更改。 - -> **NOTE** -> -> 事务预提交后，请勿继续使用该事务写入数据。如果继续使用该事务写入数据，您的写入请求将返回错误。 - -下图显示了事务状态和操作之间的关系： - -```mermaid -stateDiagram-v2 - direction LR - [*] --> PREPARE : begin - PREPARE --> PREPARED : prepare - PREPARE --> ABORTED : rollback - PREPARED --> COMMITTED : commit - PREPARED --> ABORTED : rollback -``` - -### 数据写入 - -Stream Load 事务接口提供 `/api/transaction/load` 操作，用于写入数据。您可以在一个事务中多次调用此操作。 - -从 v4.0 版本开始，您可以对不同的表调用 `/api/transaction/load` 操作，以将数据加载到同一数据库中的多个表中。 - -### 事务去重 - -Stream Load 事务接口沿用了 StarRocks 的标签机制。您可以将唯一标签绑定到每个事务，以实现事务的至多一次保证。 - -### 事务超时管理 - -启动事务时，可以使用 HTTP 请求头中的 `timeout` 字段指定事务从 `PREPARE` 到 `PREPARED` 状态的超时时间（以秒为单位）。如果事务在此时间段后仍未准备好，则会自动中止。如果未指定此字段，则默认值由 FE 配置 [`stream_load_default_timeout_second`](../administration/management/FE_configuration.md#stream_load_default_timeout_second) 确定（默认值：600 秒）。 - -启动事务时，您还可以使用 HTTP 请求头中的 `idle_transaction_timeout` 字段指定事务可以保持空闲的超时时间（以秒为单位）。如果在此期间未写入任何数据，则事务将自动回滚。 - -准备事务时，可以使用 HTTP 请求头中的 `prepared_timeout` 字段指定事务从 `PREPARED` 到 `COMMITTED` 状态的超时时间（以秒为单位）。如果事务在此时间段后仍未提交，则会自动中止。如果未指定此字段，则默认值由 FE 配置 [`prepared_transaction_default_timeout_second`](../administration/management/FE_configuration.md#prepared_transaction_default_timeout_second) 确定（默认值：86400 秒）。v3.5.4 及更高版本支持 `prepared_timeout`。 - -## 优势 - -Stream Load 事务接口具有以下优势： - -- **Exactly-once 语义** - - 事务分为两个阶段：预提交和提交，这使得跨系统加载数据变得容易。例如，此接口可以保证从 Flink 加载数据的 exactly-once 语义。 - -- **提高导入性能** - - 如果您使用程序运行导入作业，则 Stream Load 事务接口允许您根据需要合并多个小批量数据，然后通过调用 `/api/transaction/commit` 操作在一个事务中一次性发送所有数据。这样，需要加载的数据版本更少，并且导入性能得到提高。 - -## 限制 - -Stream Load 事务接口具有以下限制： - -- 从 v4.0 版本开始，支持**单数据库多表**事务。对**多数据库多表**事务的支持正在开发中。 - -- 仅支持**来自一个客户端的并发数据写入**。对**来自多个客户端的并发数据写入**的支持正在开发中。 - -- `/api/transaction/load` 操作可以在一个事务中多次调用。在这种情况下，为调用的所有 `/api/transaction/load` 操作指定的参数设置（`table` 除外）必须相同。 - -- 当您使用 Stream Load 事务接口加载 CSV 格式的数据时，请确保数据文件中的每个数据记录都以行分隔符结尾。 - -## 注意事项 - -- 如果您调用的 `/api/transaction/begin`、`/api/transaction/load` 或 `/api/transaction/prepare` 操作返回错误，则事务失败并自动回滚。 -- 调用 `/api/transaction/begin` 操作以启动新事务时，必须指定标签。请注意，后续的 `/api/transaction/load`、`/api/transaction/prepare` 和 `/api/transaction/commit` 操作必须使用与 `/api/transaction/begin` 操作相同的标签。 -- 如果您使用正在进行的事务的标签来调用 `/api/transaction/begin` 操作以启动新事务，则先前的事务将失败并回滚。 -- 如果您使用多表事务将数据加载到不同的表中，则必须为事务中涉及的所有操作指定参数 `-H "transaction_type:multi"`。 -- StarRocks 支持的 CSV 格式数据的默认列分隔符和行分隔符是 `\t` 和 `\n`。如果您的数据文件未使用默认列分隔符或行分隔符，则必须使用 `"column_separator: "` 或 `"row_delimiter: "` 在调用 `/api/transaction/load` 操作时指定数据文件中实际使用的列分隔符或行分隔符。 - -## 前提条件 - -### 检查权限 - - - -#### 检查网络配置 - -确保您要加载的数据所在的机器可以通过 [`http_port`](../administration/management/FE_configuration.md#http_port) （默认值：`8030`）和 [`be_http_port`](../administration/management/BE_configuration.md#be_http_port) （默认值：`8040`）访问 StarRocks 集群的 FE 和 BE 节点。 - -## 基本操作 - -### 准备示例数据 - -本主题以 CSV 格式的数据为例。 - -1. 在本地文件系统的 `/home/disk1/` 路径中，创建一个名为 `example1.csv` 的 CSV 文件。该文件由三列组成，依次表示用户 ID、用户名和用户分数。 - - ```Plain - 1,Lily,23 - 2,Rose,23 - 3,Alice,24 - 4,Julia,25 - ``` - -2. 在您的 StarRocks 数据库 `test_db` 中，创建一个名为 `table1` 的主键表。该表由三列组成：`id`、`name` 和 `score`，其中 `id` 是主键。 - - ```SQL - CREATE TABLE `table1` - ( - `id` int(11) NOT NULL COMMENT "user ID", - `name` varchar(65533) NULL COMMENT "user name", - `score` int(11) NOT NULL COMMENT "user score" - ) - ENGINE=OLAP - PRIMARY KEY(`id`) - DISTRIBUTED BY HASH(`id`) BUCKETS 10; - ``` - -### 启动事务 - -#### 语法 - -```Bash -curl --location-trusted -u : -H "label:" \ - -H "Expect:100-continue" \ - [-H "transaction_type:multi"]\ # 可选。启动多表事务。 - -H "db:" -H "table:" \ - -XPOST http://:/api/transaction/begin -``` - -> **NOTE** -> -> 如果要将数据加载到事务中的不同表中，请在命令中指定 `-H "transaction_type:multi"`。 - -#### 示例 - -```Bash -curl --location-trusted -u :<123456> -H "label:streamload_txn_example1_table1" \ - -H "Expect:100-continue" \ - -H "db:test_db" -H "table:table1" \ - -XPOST http://:/api/transaction/begin -``` - -> **NOTE** -> -> 在此示例中，`streamload_txn_example1_table1` 被指定为事务的标签。 - -#### 返回结果 - -- 如果事务成功启动，则返回以下结果： - - ```Bash - { - "Status": "OK", - "Message": "", - "Label": "streamload_txn_example1_table1", - "TxnId": 9032, - "BeginTxnTimeMs": 0 - } - ``` - -- 如果事务绑定到重复标签，则返回以下结果： - - ```Bash - { - "Status": "LABEL_ALREADY_EXISTS", - "ExistingJobStatus": "RUNNING", - "Message": "Label [streamload_txn_example1_table1] has already been used." - } - ``` - -- 如果发生除重复标签之外的错误，则返回以下结果： - - ```Bash - { - "Status": "FAILED", - "Message": "" - } - ``` - -### 写入数据 - -#### 语法 - -```Bash -curl --location-trusted -u : -H "label:" \ - -H "Expect:100-continue" \ - [-H "transaction_type:multi"]\ # 可选。通过多表事务加载数据。 - -H "db:" -H "table:" \ - -T \ - -XPUT http://:/api/transaction/load -``` - -> **NOTE** -> -> - 调用 `/api/transaction/load` 操作时，必须使用 `` 指定要加载的数据文件的保存路径。 -> - 您可以调用具有不同 `table` 参数值的 `/api/transaction/load` 操作，以将数据加载到同一数据库中的不同表中。在这种情况下，您必须在命令中指定 `-H "transaction_type:multi"`。 - -#### 示例 - -```Bash -curl --location-trusted -u :<123456> -H "label:streamload_txn_example1_table1" \ - -H "Expect:100-continue" \ - -H "db:test_db" -H "table:table1" \ - -T /home/disk1/example1.csv \ - -H "column_separator: ," \ - -XPUT http://:/api/transaction/load -``` - -> **NOTE** -> -> 在此示例中，数据文件 `example1.csv` 中使用的列分隔符是逗号 (`,`)，而不是 StarRocks 的默认列分隔符 (`\t`)。因此，在调用 `/api/transaction/load` 操作时，必须使用 `"column_separator: "` 指定逗号 (`,`) 作为列分隔符。 - -#### 返回结果 - -- 如果数据写入成功，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Seq": 0, - "Label": "streamload_txn_example1_table1", - "Status": "OK", - "Message": "", - "NumberTotalRows": 5265644, - "NumberLoadedRows": 5265644, - "NumberFilteredRows": 0, - "NumberUnselectedRows": 0, - "LoadBytes": 10737418067, - "LoadTimeMs": 418778, - "StreamLoadPutTimeMs": 68, - "ReceivedDataTimeMs": 38964, - } - ``` - -- 如果事务被认为是未知的，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "TXN_NOT_EXISTS" - } - ``` - -- 如果事务被认为处于无效状态，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "Transcation State Invalid" - } - ``` - -- 如果发生除未知事务和无效状态之外的错误，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "" - } - ``` - -### 预提交事务 - -#### 语法 - -```Bash -curl --location-trusted -u : -H "label:" \ - -H "Expect:100-continue" \ - [-H "transaction_type:multi"]\ # 可选。预提交多表事务。 - -H "db:" \ - [-H "prepared_timeout:"] \ - -XPOST http://:/api/transaction/prepare -``` - -> **NOTE** -> -> 如果要预提交的事务是多表事务，请在命令中指定 `-H "transaction_type:multi"`。 - -#### 示例 - -```Bash -curl --location-trusted -u :<123456> -H "label:streamload_txn_example1_table1" \ - -H "Expect:100-continue" \ - -H "db:test_db" \ - -H "prepared_timeout:300" \ - -XPOST http://:/api/transaction/prepare -``` - -> **NOTE** -> -> `prepared_timeout` 字段是可选的。如果未指定，则默认值由 FE 配置 [`prepared_transaction_default_timeout_second`](../administration/management/FE_configuration.md#prepared_transaction_default_timeout_second) 确定（默认值：86400 秒）。v3.5.4 及更高版本支持 `prepared_timeout`。 - -#### 返回结果 - -- 如果预提交成功，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "OK", - "Message": "", - "NumberTotalRows": 5265644, - "NumberLoadedRows": 5265644, - "NumberFilteredRows": 0, - "NumberUnselectedRows": 0, - "LoadBytes": 10737418067, - "LoadTimeMs": 418778, - "StreamLoadPutTimeMs": 68, - "ReceivedDataTimeMs": 38964, - "WriteDataTimeMs": 417851 - "CommitAndPublishTimeMs": 1393 - } - ``` - -- 如果事务被认为不存在，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "Transcation Not Exist" - } - ``` - -- 如果预提交超时，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "commit timeout", - } - ``` - -- 如果发生除不存在的事务和预提交超时之外的错误，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "publish timeout" - } - ``` - -### 提交事务 - -#### 语法 - -```Bash -curl --location-trusted -u : -H "label:" \ - -H "Expect:100-continue" \ - [-H "transaction_type:multi"]\ # 可选。提交多表事务。 - -H "db:" \ - -XPOST http://:/api/transaction/commit -``` - -> **NOTE** -> -> 如果要提交的事务是多表事务，请在命令中指定 `-H "transaction_type:multi"`。 - -#### 示例 - -```Bash -curl --location-trusted -u :<123456> -H "label:streamload_txn_example1_table1" \ - -H "Expect:100-continue" \ - -H "db:test_db" \ - -XPOST http://:/api/transaction/commit -``` - -#### 返回结果 - -- 如果提交成功，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "OK", - "Message": "", - "NumberTotalRows": 5265644, - "NumberLoadedRows": 5265644, - "NumberFilteredRows": 0, - "NumberUnselectedRows": 0, - "LoadBytes": 10737418067, - "LoadTimeMs": 418778, - "StreamLoadPutTimeMs": 68, - "ReceivedDataTimeMs": 38964, - "WriteDataTimeMs": 417851 - "CommitAndPublishTimeMs": 1393 - } - ``` - -- 如果事务已提交，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "OK", - "Message": "Transaction already commited", - } - ``` - -- 如果事务被认为不存在，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "Transcation Not Exist" - } - ``` - -- 如果提交超时，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "commit timeout", - } - ``` - -- 如果数据发布超时，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "publish timeout", - "CommitAndPublishTimeMs": 1393 - } - ``` - -- 如果发生除不存在的事务和超时之外的错误，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "" - } - ``` - -### 回滚事务 - -#### 语法 - -```Bash -curl --location-trusted -u : -H "label:" \ - -H "Expect:100-continue" \ - [-H "transaction_type:multi"]\ # 可选。回滚多表事务。 - -H "db:" \ - -XPOST http://:/api/transaction/rollback -``` - -> **NOTE** -> -> 如果要回滚的事务是多表事务，请在命令中指定 `-H "transaction_type:multi"`。 - -#### 示例 - -```Bash -curl --location-trusted -u :<123456> -H "label:streamload_txn_example1_table1" \ - -H "Expect:100-continue" \ - -H "db:test_db" \ - -XPOST http://:/api/transaction/rollback -``` - -#### 返回结果 - -- 如果回滚成功，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "OK", - "Message": "" - } - ``` - -- 如果事务被认为不存在，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "Transcation Not Exist" - } - ``` - -- 如果发生除不存在的事务之外的错误，则返回以下结果： - - ```Bash - { - "TxnId": 1, - "Label": "streamload_txn_example1_table1", - "Status": "FAILED", - "Message": "" - } - ``` - -## 相关参考 - -有关 Stream Load 的适用场景和支持的数据文件格式，以及 Stream Load 的工作原理的信息，请参见 [通过 Stream Load 从本地文件系统加载](../loading/StreamLoad.md#loading-from-a-local-file-system-via-stream-load)。 - -有关创建 Stream Load 作业的语法和参数的信息，请参见 [STREAM LOAD](../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 \ No newline at end of file diff --git a/docs/zh/loading/alibaba.md b/docs/zh/loading/alibaba.md deleted file mode 100644 index db92470..0000000 --- a/docs/zh/loading/alibaba.md +++ /dev/null @@ -1 +0,0 @@ -unlisted: true \ No newline at end of file diff --git a/docs/zh/loading/automq-routine-load.md b/docs/zh/loading/automq-routine-load.md deleted file mode 100644 index 4765159..0000000 --- a/docs/zh/loading/automq-routine-load.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -displayed_sidebar: docs -description: Cloud based Kafka from AutoMQ ---- - -# AutoMQ Kafka - -import Replicanum from '../_assets/commonMarkdown/replicanum.mdx' - -[AutoMQ for Kafka](https://www.automq.com/docs) 是一个为云环境重新设计的 Kafka 云原生版本。 -AutoMQ Kafka 是 [开源](https://github.com/AutoMQ/automq-for-kafka) 的，并且完全兼容 Kafka 协议，充分利用云的优势。 -与自管理的 Apache Kafka 相比，AutoMQ Kafka 凭借其云原生架构，提供了诸如容量自动伸缩、网络流量的自我平衡、秒级移动分区等功能。这些功能大大降低了用户的总拥有成本 (TCO)。 - -本文将指导您使用 StarRocks Routine Load 将数据导入到 AutoMQ Kafka 中。 -要了解 Routine Load 的基本原理，请参阅 Routine Load 原理部分。 - -## 准备环境 - -### 准备 StarRocks 和测试数据 - -确保您有一个正在运行的 StarRocks 集群。 - -创建一个数据库和一个 Primary Key 表用于测试： - -```sql -create database automq_db; -create table users ( - id bigint NOT NULL, - name string NOT NULL, - timestamp string NULL, - status string NULL -) PRIMARY KEY (id) -DISTRIBUTED BY HASH(id) -PROPERTIES ( - "enable_persistent_index" = "true" -); -``` - - - -## 准备 AutoMQ Kafka 和测试数据 - -要准备您的 AutoMQ Kafka 环境和测试数据，请按照 AutoMQ [Quick Start](https://www.automq.com/docs) 指南部署您的 AutoMQ Kafka 集群。确保 StarRocks 可以直接连接到您的 AutoMQ Kafka 服务器。 - -要在 AutoMQ Kafka 中快速创建一个名为 `example_topic` 的 topic 并写入测试 JSON 数据，请按照以下步骤操作： - -### 创建一个 topic - -使用 Kafka 的命令行工具创建一个 topic。确保您可以访问 Kafka 环境并且 Kafka 服务正在运行。 -以下是创建 topic 的命令： - -```shell -./kafka-topics.sh --create --topic example_topic --bootstrap-server 10.0.96.4:9092 --partitions 1 --replication-factor 1 -``` - -> Note: 将 `topic` 和 `bootstrap-server` 替换为您的 Kafka 服务器地址。 - -要检查 topic 创建的结果，请使用以下命令： - -```shell -./kafka-topics.sh --describe example_topic --bootstrap-server 10.0.96.4:9092 -``` - -### 生成测试数据 - -生成一个简单的 JSON 格式测试数据 - -```json -{ - "id": 1, - "name": "testuser", - "timestamp": "2023-11-10T12:00:00", - "status": "active" -} -``` - -### 写入测试数据 - -使用 Kafka 的命令行工具或编程方法将测试数据写入 example_topic。以下是使用命令行工具的示例： - -```shell -echo '{"id": 1, "name": "testuser", "timestamp": "2023-11-10T12:00:00", "status": "active"}' | sh kafka-console-producer.sh --broker-list 10.0.96.4:9092 --topic example_topic -``` - -> Note: 将 `topic` 和 `bootstrap-server` 替换为您的 Kafka 服务器地址。 - -要查看最近写入的 topic 数据，请使用以下命令： - -```shell -sh kafka-console-consumer.sh --bootstrap-server 10.0.96.4:9092 --topic example_topic --from-beginning -``` - -## 创建 Routine Load 任务 - -在 StarRocks 命令行中，创建一个 Routine Load 任务以持续从 AutoMQ Kafka topic 导入数据： - -```sql -CREATE ROUTINE LOAD automq_example_load ON users -COLUMNS(id, name, timestamp, status) -PROPERTIES -( - "desired_concurrent_number" = "5", - "format" = "json", - "jsonpaths" = "[\"$.id\",\"$.name\",\"$.timestamp\",\"$.status\"]" -) -FROM KAFKA -( - "kafka_broker_list" = "10.0.96.4:9092", - "kafka_topic" = "example_topic", - "kafka_partitions" = "0", - "property.kafka_default_offsets" = "OFFSET_BEGINNING" -); -``` - -> Note: 将 `kafka_broker_list` 替换为您的 Kafka 服务器地址。 - -### 参数说明 - -#### 数据格式 - -在 PROPERTIES 子句的 "format" = "json" 中将数据格式指定为 JSON。 - -#### 数据提取和转换 - -要指定源数据和目标表之间的映射和转换关系，请配置 COLUMNS 和 jsonpaths 参数。COLUMNS 中的列名对应于目标表的列名，它们的顺序对应于源数据中的列顺序。jsonpaths 参数用于从 JSON 数据中提取所需的字段数据，类似于新生成的 CSV 数据。然后，COLUMNS 参数临时命名 jsonpaths 中的字段，以便排序。有关数据转换的更多说明，请参见 [数据导入转换](./Etl_in_loading.md)。 -> Note: 如果每行 JSON 对象都具有与目标表的列相对应的键名和数量（不需要顺序），则无需配置 COLUMNS。 - -## 验证数据导入 - -首先，我们检查 Routine Load 导入作业，并确认 Routine Load 导入任务状态为 RUNNING 状态。 - -```sql -show routine load\G -``` - -然后，查询 StarRocks 数据库中的相应表，我们可以观察到数据已成功导入。 - -```sql -StarRocks > select * from users; -+------+--------------+---------------------+--------+ -| id | name | timestamp | status | -+------+--------------+---------------------+--------+ -| 1 | testuser | 2023-11-10T12:00:00 | active | -| 2 | testuser | 2023-11-10T12:00:00 | active | -+------+--------------+---------------------+--------+ -2 rows in set (0.01 sec) -``` \ No newline at end of file diff --git a/docs/zh/loading/azure.md b/docs/zh/loading/azure.md deleted file mode 100644 index 23b0d0b..0000000 --- a/docs/zh/loading/azure.md +++ /dev/null @@ -1,455 +0,0 @@ ---- -displayed_sidebar: docs -toc_max_heading_level: 4 -keywords: ['Broker Load'] ---- - -# 从 Microsoft Azure Storage 导入数据 - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -StarRocks 提供了以下从 Azure 导入数据的选项： - -- 使用 [INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md)+[`FILES()`](../sql-reference/sql-functions/table-functions/files.md) 进行同步导入 -- 使用 [Broker Load](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md) 进行异步导入 - -每个选项都有其自身的优势，以下各节将详细介绍。 - -在大多数情况下，我们建议您使用 INSERT+`FILES()` 方法，该方法更易于使用。 - -但是，INSERT+`FILES()` 方法目前仅支持 Parquet、ORC 和 CSV 文件格式。因此，如果您需要导入其他文件格式（如 JSON）的数据，或者[在数据导入期间执行数据更改（如 DELETE）](../loading/Load_to_Primary_Key_tables.md)，则可以求助于 Broker Load。 - -## 前提条件 - -### 准备源数据 - -确保要导入到 StarRocks 中的源数据已正确存储在 Azure 存储帐户中的容器中。 - -在本主题中，假设您要导入存储在 Azure Data Lake Storage Gen2 (ADLS Gen2) 存储帐户 (`starrocks`) 中的容器 (`starrocks-container`) 的根目录下的 Parquet 格式的示例数据集 (`user_behavior_ten_million_rows.parquet`) 的数据。 - -### 检查权限 - - - -### 收集身份验证详细信息 - -本主题中的示例使用共享密钥身份验证方法。为确保您有权从 ADLS Gen2 读取数据，我们建议您阅读 [Azure Data Lake Storage Gen2 > 共享密钥（存储帐户的访问密钥）](../integrations/authenticate_to_azure_storage.md#service-principal-1)，以了解您需要配置的身份验证参数。 - -简而言之，如果您使用共享密钥身份验证，则需要收集以下信息： - -- 您的 ADLS Gen2 存储帐户的用户名 -- 您的 ADLS Gen2 存储帐户的共享密钥 - -有关所有可用身份验证方法的信息，请参阅 [Azure 云存储身份验证](../integrations/authenticate_to_azure_storage.md)。 - -## 使用 INSERT+FILES() - -此方法从 v3.2 开始可用，目前仅支持 Parquet、ORC 和 CSV（从 v3.3.0 开始）文件格式。 - -### INSERT+FILES() 的优势 - -`FILES()` 可以读取存储在云存储中的文件，基于您指定的路径相关属性，推断文件中数据的表结构，然后将文件中的数据作为数据行返回。 - -使用 `FILES()`，您可以： - -- 使用 [SELECT](../sql-reference/sql-statements/table_bucket_part_index/SELECT.md) 直接从 Azure 查询数据。 -- 使用 [CREATE TABLE AS SELECT](../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_AS_SELECT.md) (CTAS) 创建和导入表。 -- 使用 [INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md) 将数据导入到现有表中。 - -### 典型示例 - -#### 使用 SELECT 直接从 Azure 查询 - -使用 SELECT+`FILES()` 直接从 Azure 查询可以在创建表之前很好地预览数据集的内容。例如： - -- 在不存储数据的情况下获取数据集的预览。 -- 查询最小值和最大值，并确定要使用的数据类型。 -- 检查 `NULL` 值。 - -以下示例查询存储在您的存储帐户 `starrocks` 中的容器 `starrocks-container` 中的示例数据集 `user_behavior_ten_million_rows.parquet`： - -```SQL -SELECT * FROM FILES -( - "path" = "abfss://starrocks-container@starrocks.dfs.core.windows.net/user_behavior_ten_million_rows.parquet", - "format" = "parquet", - "azure.adls2.storage_account" = "starrocks", - "azure.adls2.shared_key" = "xxxxxxxxxxxxxxxxxx" -) -LIMIT 3; -``` - -系统返回类似于以下的查询结果： - -```Plain -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 543711 | 829192 | 2355072 | pv | 2017-11-27 08:22:37 | -| 543711 | 2056618 | 3645362 | pv | 2017-11-27 10:16:46 | -| 543711 | 1165492 | 3645362 | pv | 2017-11-27 10:17:00 | -+--------+---------+------------+--------------+---------------------+ -``` - -> **NOTE** -> -> 请注意，上面返回的列名由 Parquet 文件提供。 - -#### 使用 CTAS 创建和导入表 - -这是前一个示例的延续。先前的查询包含在 CREATE TABLE AS SELECT (CTAS) 中，以使用模式推断自动执行表创建。这意味着 StarRocks 将推断表结构，创建您想要的表，然后将数据导入到表中。当使用 `FILES()` 表函数与 Parquet 文件时，不需要列名和类型来创建表，因为 Parquet 格式包含列名。 - -> **NOTE** -> -> 使用模式推断时，CREATE TABLE 的语法不允许设置副本数。如果您使用的是 StarRocks 存算一体集群，请在创建表之前设置副本数。以下示例适用于具有三个副本的系统： -> -> ```SQL -> ADMIN SET FRONTEND CONFIG ('default_replication_num' = "3"); -> ``` - -创建一个数据库并切换到该数据库： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -使用 CTAS 创建一个表，并将示例数据集 `user_behavior_ten_million_rows.parquet` 的数据导入到该表中，该数据集存储在您的存储帐户 `starrocks` 中的容器 `starrocks-container` 中： - -```SQL -CREATE TABLE user_behavior_inferred AS -SELECT * FROM FILES -( - "path" = "abfss://starrocks-container@starrocks.dfs.core.windows.net/user_behavior_ten_million_rows.parquet", - "format" = "parquet", - "azure.adls2.storage_account" = "starrocks", - "azure.adls2.shared_key" = "xxxxxxxxxxxxxxxxxx" -); -``` - -创建表后，您可以使用 [DESCRIBE](../sql-reference/sql-statements/table_bucket_part_index/DESCRIBE.md) 查看其结构： - -```SQL -DESCRIBE user_behavior_inferred; -``` - -系统返回以下查询结果： - -```Plain -+--------------+-----------+------+-------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+-----------+------+-------+---------+-------+ -| UserID | bigint | YES | true | NULL | | -| ItemID | bigint | YES | true | NULL | | -| CategoryID | bigint | YES | true | NULL | | -| BehaviorType | varbinary | YES | false | NULL | | -| Timestamp | varbinary | YES | false | NULL | | -+--------------+-----------+------+-------+---------+-------+ -``` - -查询表以验证数据是否已导入到其中。例如： - -```SQL -SELECT * from user_behavior_inferred LIMIT 3; -``` - -返回以下查询结果，表明数据已成功导入： - -```Plain -+--------+--------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+--------+------------+--------------+---------------------+ -| 84 | 162325 | 2939262 | pv | 2017-12-02 05:41:41 | -| 84 | 232622 | 4148053 | pv | 2017-11-27 04:36:10 | -| 84 | 595303 | 903809 | pv | 2017-11-26 08:03:59 | -+--------+--------+------------+--------------+---------------------+ -``` - -#### 使用 INSERT 导入到现有表中 - -您可能想要自定义要插入的表，例如： - -- 列数据类型、可空设置或默认值 -- 键类型和列 -- 数据分区和分桶 - -> **NOTE** -> -> 创建最有效的表结构需要了解数据的使用方式和列的内容。本主题不涵盖表设计。有关表设计的信息，请参阅 [表类型](../table_design/StarRocks_table_design.md)。 - -在此示例中，我们基于对表查询方式和 Parquet 文件中数据的了解来创建表。对 Parquet 文件中数据的了解可以通过直接在 Azure 中查询文件来获得。 - -- 由于对 Azure 中数据集的查询表明 `Timestamp` 列包含与 VARBINARY 数据类型匹配的数据，因此在以下 DDL 中指定了列类型。 -- 通过查询 Azure 中的数据，您可以发现数据集中没有 `NULL` 值，因此 DDL 不会将任何列设置为可空。 -- 基于对预期查询类型的了解，排序键和分桶列设置为 `UserID` 列。您的用例可能与此数据不同，因此您可能会决定将 `ItemID` 除了 `UserID` 之外或代替 `UserID` 用于排序键。 - -创建一个数据库并切换到该数据库： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表（我们建议该表具有与您要从 Azure 导入的 Parquet 文件相同的结构）： - -```SQL -CREATE TABLE user_behavior_declared -( - UserID int(11), - ItemID int(11), - CategoryID int(11), - BehaviorType varchar(65533), - Timestamp varbinary -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID); -``` - -显示结构，以便您可以将其与 `FILES()` 表函数生成的推断结构进行比较： - -```sql -DESCRIBE user_behavior_declared; -``` - -```plaintext -+--------------+----------------+------+-------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+----------------+------+-------+---------+-------+ -| UserID | int | NO | true | NULL | | -| ItemID | int | NO | false | NULL | | -| CategoryID | int | NO | false | NULL | | -| BehaviorType | varchar(65533) | NO | false | NULL | | -| Timestamp | varbinary | NO | false | NULL | | -+--------------+----------------+------+-------+---------+-------+ -5 rows in set (0.00 sec) -``` - -:::tip - -将您刚刚创建的结构与之前使用 `FILES()` 表函数推断的结构进行比较。查看： - -- 数据类型 -- 可空性 -- 键字段 - -为了更好地控制目标表的结构并获得更好的查询性能，我们建议您在生产环境中手动指定表结构。 - -::: - -创建表后，您可以使用 INSERT INTO SELECT FROM FILES() 导入它： - -```SQL -INSERT INTO user_behavior_declared -SELECT * FROM FILES -( - "path" = "abfss://starrocks-container@starrocks.dfs.core.windows.net/user_behavior_ten_million_rows.parquet", - "format" = "parquet", - "azure.adls2.storage_account" = "starrocks", - "azure.adls2.shared_key" = "xxxxxxxxxxxxxxxxxx" -); -``` - -导入完成后，您可以查询表以验证数据是否已导入到其中。例如： - -```SQL -SELECT * from user_behavior_declared LIMIT 3; -``` - -系统返回类似于以下的查询结果，表明数据已成功导入： - -```Plain - +--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 142 | 2869980 | 2939262 | pv | 2017-11-25 03:43:22 | -| 142 | 2522236 | 1669167 | pv | 2017-11-25 15:14:12 | -| 142 | 3031639 | 3607361 | pv | 2017-11-25 15:19:25 | -+--------+---------+------------+--------------+---------------------+ -``` - -#### 检查导入进度 - -您可以从 StarRocks Information Schema 中的 [`loads`](../sql-reference/information_schema/loads.md) 视图查询 INSERT 作业的进度。此功能从 v3.1 开始支持。例如： - -```SQL -SELECT * FROM information_schema.loads ORDER BY JOB_ID DESC; -``` - -有关 `loads` 视图中提供的字段的信息，请参阅 [`loads`](../sql-reference/information_schema/loads.md)。 - -如果您提交了多个导入作业，则可以按与作业关联的 `LABEL` 进行过滤。例如： - -```SQL -SELECT * FROM information_schema.loads WHERE LABEL = 'insert_f3fc2298-a553-11ee-92f4-00163e0842bd' \G -*************************** 1. row *************************** - JOB_ID: 10193 - LABEL: insert_f3fc2298-a553-11ee-92f4-00163e0842bd - DATABASE_NAME: mydatabase - STATE: FINISHED - PROGRESS: ETL:100%; LOAD:100% - TYPE: INSERT - PRIORITY: NORMAL - SCAN_ROWS: 10000000 - FILTERED_ROWS: 0 - UNSELECTED_ROWS: 0 - SINK_ROWS: 10000000 - ETL_INFO: - TASK_INFO: resource:N/A; timeout(s):300; max_filter_ratio:0.0 - CREATE_TIME: 2023-12-28 15:37:38 - ETL_START_TIME: 2023-12-28 15:37:38 - ETL_FINISH_TIME: 2023-12-28 15:37:38 - LOAD_START_TIME: 2023-12-28 15:37:38 - LOAD_FINISH_TIME: 2023-12-28 15:39:35 - JOB_DETAILS: {"All backends":{"f3fc2298-a553-11ee-92f4-00163e0842bd":[10120]},"FileNumber":0,"FileSize":0,"InternalTableLoadBytes":581730322,"InternalTableLoadRows":10000000,"ScanBytes":581574034,"ScanRows":10000000,"TaskNumber":1,"Unfinished backends":{"f3fc2298-a553-11ee-92f4-00163e0842bd":[]}} - ERROR_MSG: NULL - TRACKING_URL: NULL - TRACKING_SQL: NULL -REJECTED_RECORD_PATH: NULL -``` - -> **NOTE** -> -> INSERT 是一个同步命令。如果 INSERT 作业仍在运行，您需要打开另一个会话来检查其执行状态。 - -## 使用 Broker Load - -异步 Broker Load 进程处理与 Azure 的连接、提取数据以及将数据存储在 StarRocks 中。 - -此方法支持以下文件格式： - -- Parquet -- ORC -- CSV -- JSON（从 v3.2.3 开始支持） - -### Broker Load 的优势 - -- Broker Load 在后台运行，客户端无需保持连接即可继续作业。 -- Broker Load 是长时间运行作业的首选，默认超时时间为 4 小时。 -- 除了 Parquet 和 ORC 文件格式外，Broker Load 还支持 CSV 文件格式和 JSON 文件格式（从 v3.2.3 开始支持 JSON 文件格式）。 - -### 数据流 - -![Broker Load 的工作流程](../_assets/broker_load_how-to-work_en.png) - -1. 用户创建一个导入作业。 -2. 前端 (FE) 创建一个查询计划，并将该计划分发到后端节点 (BE) 或计算节点 (CN)。 -3. BE 或 CN 从源提取数据，并将数据导入到 StarRocks 中。 - -### 典型示例 - -创建一个表，启动一个从 Azure 提取示例数据集 `user_behavior_ten_million_rows.parquet` 的导入进程，并验证数据导入的进度和成功。 - -#### 创建数据库和表 - -连接到您的 StarRocks 集群。然后，创建一个数据库并切换到该数据库： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表（我们建议该表具有与您要从 Azure 导入的 Parquet 文件相同的结构）： - -```SQL -CREATE TABLE user_behavior -( - UserID int(11), - ItemID int(11), - CategoryID int(11), - BehaviorType varchar(65533), - Timestamp varbinary -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID); -``` - -#### 启动 Broker Load - -运行以下命令以启动一个 Broker Load 作业，该作业将数据从示例数据集 `user_behavior_ten_million_rows.parquet` 导入到 `user_behavior` 表： - -```SQL -LOAD LABEL user_behavior -( - DATA INFILE("abfss://starrocks-container@starrocks.dfs.core.windows.net/user_behavior_ten_million_rows.parquet") - INTO TABLE user_behavior - FORMAT AS "parquet" -) -WITH BROKER -( - "azure.adls2.storage_account" = "starrocks", - "azure.adls2.shared_key" = "xxxxxxxxxxxxxxxxxx" -) -PROPERTIES -( - "timeout" = "3600" -); -``` - -此作业有四个主要部分： - -- `LABEL`: 查询导入作业状态时使用的字符串。 -- `LOAD` 声明：源 URI、源数据格式和目标表名。 -- `BROKER`: 源的连接详细信息。 -- `PROPERTIES`: 超时值和要应用于导入作业的任何其他属性。 - -有关详细的语法和参数说明，请参阅 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -#### 检查导入进度 - -您可以从 StarRocks Information Schema 中的 [`loads`](../sql-reference/information_schema/loads.md) 视图查询 Broker Load 作业的进度。此功能从 v3.1 开始支持。 - -```SQL -SELECT * FROM information_schema.loads \G -``` - -有关 `loads` 视图中提供的字段的信息，请参阅 [`loads`](../sql-reference/information_schema/loads.md)。 - -如果您提交了多个导入作业，则可以按与作业关联的 `LABEL` 进行过滤： - -```SQL -SELECT * FROM information_schema.loads WHERE LABEL = 'user_behavior' \G -*************************** 1. row *************************** - JOB_ID: 10250 - LABEL: user_behavior - DATABASE_NAME: mydatabase - STATE: FINISHED - PROGRESS: ETL:100%; LOAD:100% - TYPE: BROKER - PRIORITY: NORMAL - SCAN_ROWS: 10000000 - FILTERED_ROWS: 0 - UNSELECTED_ROWS: 0 - SINK_ROWS: 10000000 - ETL_INFO: - TASK_INFO: resource:N/A; timeout(s):3600; max_filter_ratio:0.0 - CREATE_TIME: 2023-12-28 16:15:19 - ETL_START_TIME: 2023-12-28 16:15:25 - ETL_FINISH_TIME: 2023-12-28 16:15:25 - LOAD_START_TIME: 2023-12-28 16:15:25 - LOAD_FINISH_TIME: 2023-12-28 16:16:31 - JOB_DETAILS: {"All backends":{"6a8ef4c0-1009-48c9-8d18-c4061d2255bf":[10121]},"FileNumber":1,"FileSize":132251298,"InternalTableLoadBytes":311710786,"InternalTableLoadRows":10000000,"ScanBytes":132251298,"ScanRows":10000000,"TaskNumber":1,"Unfinished backends":{"6a8ef4c0-1009-48c9-8d18-c4061d2255bf":[]}} - ERROR_MSG: NULL - TRACKING_URL: NULL - TRACKING_SQL: NULL -REJECTED_RECORD_PATH: NULL -``` - -确认导入作业已完成后，您可以检查目标表的一个子集，以查看数据是否已成功导入。例如： - -```SQL -SELECT * from user_behavior LIMIT 3; -``` - -系统返回类似于以下的查询结果，表明数据已成功导入： - -```Plain -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 142 | 2869980 | 2939262 | pv | 2017-11-25 03:43:22 | -| 142 | 2522236 | 1669167 | pv | 2017-11-25 15:14:12 | -| 142 | 3031639 | 3607361 | pv | 2017-11-25 15:19:25 | -+--------+---------+------------+--------------+---------------------+ \ No newline at end of file diff --git a/docs/zh/loading/gcs.md b/docs/zh/loading/gcs.md deleted file mode 100644 index c6fd228..0000000 --- a/docs/zh/loading/gcs.md +++ /dev/null @@ -1,464 +0,0 @@ ---- -displayed_sidebar: docs -toc_max_heading_level: 4 -keywords: ['Broker Load'] ---- - -# 从 GCS 导入数据 - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -StarRocks 提供了以下从 GCS 导入数据的选项： - -- 使用 [INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md) + [`FILES()`](../sql-reference/sql-functions/table-functions/files.md) 进行同步导入 -- 使用 [Broker Load](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md) 进行异步导入 - -每个选项都有其自身的优势，以下各节将详细介绍。 - -在大多数情况下，我们建议您使用 INSERT+`FILES()` 方法，该方法更易于使用。 - -但是，INSERT+`FILES()` 方法目前仅支持 Parquet、ORC 和 CSV 文件格式。因此，如果您需要导入其他文件格式的数据（如 JSON），或者[在数据导入期间执行数据更改（如 DELETE）](../loading/Load_to_Primary_Key_tables.md)，则可以采用 Broker Load。 - -## 前提条件 - -### 准备源数据 - -确保要加载到 StarRocks 中的源数据已正确存储在 GCS bucket 中。您还可以考虑数据和数据库的位置，因为当您的 bucket 和 StarRocks 集群位于同一区域时，数据传输成本会低得多。 - -在本主题中，我们为您提供了一个 GCS bucket 中的示例数据集 `gs://starrocks-samples/user_behavior_ten_million_rows.parquet`。您可以使用任何有效的凭据访问该数据集，因为任何 GCP 用户都可以读取该对象。 - -### 检查权限 - - - -### 收集身份验证详细信息 - -本主题中的示例使用基于服务帐户的身份验证。要实践基于 IAM 用户的身份验证，您需要收集有关以下 GCS 资源的信息： - -- 存储数据的 GCS bucket。 -- GCS 对象键（对象名称），如果访问 bucket 中的特定对象。请注意，如果您的 GCS 对象存储在子文件夹中，则对象键可以包含前缀。 -- GCS bucket 所属的 GCS 区域。 -- 您的 Google Cloud 服务帐户的 `private_ key_id`、`private_key` 和 `client_email`。 - -有关所有可用身份验证方法的信息，请参阅 [验证到 Google Cloud Storage 的身份](../integrations/authenticate_to_gcs.md)。 - -## 使用 INSERT+FILES() - -此方法从 v3.2 开始可用，目前仅支持 Parquet、ORC 和 CSV（从 v3.3.0 开始）文件格式。 - -### INSERT+FILES() 的优势 - -`FILES()` 可以读取存储在云存储中的文件，基于您指定的路径相关属性，推断文件中数据的表结构，然后将文件中的数据作为数据行返回。 - -使用 `FILES()`，您可以： - -- 使用 [SELECT](../sql-reference/sql-statements/table_bucket_part_index/SELECT.md) 直接从 GCS 查询数据。 -- 使用 [CREATE TABLE AS SELECT](../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_AS_SELECT.md) (CTAS) 创建和加载表。 -- 使用 [INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md) 将数据加载到现有表中。 - -### 典型示例 - -#### 使用 SELECT 直接从 GCS 查询 - -使用 SELECT+`FILES()` 直接从 GCS 查询可以在创建表之前很好地预览数据集的内容。例如： - -- 在不存储数据的情况下获取数据集的预览。 -- 查询最小值和最大值，并确定要使用的数据类型。 -- 检查 `NULL` 值。 - -以下示例查询示例数据集 `gs://starrocks-samples/user_behavior_ten_million_rows.parquet`： - -```SQL -SELECT * FROM FILES -( - "path" = "gs://starrocks-samples/user_behavior_ten_million_rows.parquet", - "format" = "parquet", - "gcp.gcs.service_account_email" = "sampledatareader@xxxxx-xxxxxx-000000.iam.gserviceaccount.com", - "gcp.gcs.service_account_private_key_id" = "baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - "gcp.gcs.service_account_private_key" = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" -) -LIMIT 3; -``` - -> **NOTE** -> -> 将上述命令中的凭据替换为您自己的凭据。可以使用任何有效的服务帐户电子邮件、密钥和密码，因为任何经过 GCP 身份验证的用户都可以读取该对象。 - -系统返回类似于以下的查询结果： - -```Plain -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 543711 | 829192 | 2355072 | pv | 2017-11-27 08:22:37 | -| 543711 | 2056618 | 3645362 | pv | 2017-11-27 10:16:46 | -| 543711 | 1165492 | 3645362 | pv | 2017-11-27 10:17:00 | -+--------+---------+------------+--------------+---------------------+ -``` - -> **NOTE** -> -> 请注意，上面返回的列名由 Parquet 文件提供。 - -#### 使用 CTAS 创建和加载表 - -这是前一个示例的延续。先前的查询包装在 CREATE TABLE AS SELECT (CTAS) 中，以使用模式推断自动执行表创建。这意味着 StarRocks 将推断表模式，创建您想要的表，然后将数据加载到表中。当使用带有 Parquet 文件的 `FILES()` 表函数时，由于 Parquet 格式包含列名，因此不需要列名和类型来创建表。 - -> **NOTE** -> -> 使用模式推断时，CREATE TABLE 的语法不允许设置副本数。如果您使用的是 StarRocks 存算一体集群，请在创建表之前设置副本数。以下示例适用于具有三个副本的系统： -> -> ```SQL -> ADMIN SET FRONTEND CONFIG ('default_replication_num' = "3"); -> ``` - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -使用 CTAS 创建一个表，并将示例数据集 `gs://starrocks-samples/user_behavior_ten_million_rows.parquet` 的数据加载到该表中： - -```SQL -CREATE TABLE user_behavior_inferred AS -SELECT * FROM FILES -( - "path" = "gs://starrocks-samples/user_behavior_ten_million_rows.parquet", - "format" = "parquet", - "gcp.gcs.service_account_email" = "sampledatareader@xxxxx-xxxxxx-000000.iam.gserviceaccount.com", - "gcp.gcs.service_account_private_key_id" = "baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - "gcp.gcs.service_account_private_key" = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" -); -``` - -> **NOTE** -> -> 将上述命令中的凭据替换为您自己的凭据。可以使用任何有效的服务帐户电子邮件、密钥和密码，因为任何经过 GCP 身份验证的用户都可以读取该对象。 - -创建表后，您可以使用 [DESCRIBE](../sql-reference/sql-statements/table_bucket_part_index/DESCRIBE.md) 查看其模式： - -```SQL -DESCRIBE user_behavior_inferred; -``` - -系统返回类似于以下的查询结果： - -```Plain -+--------------+-----------+------+-------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+-----------+------+-------+---------+-------+ -| UserID | bigint | YES | true | NULL | | -| ItemID | bigint | YES | true | NULL | | -| CategoryID | bigint | YES | true | NULL | | -| BehaviorType | varbinary | YES | false | NULL | | -| Timestamp | varbinary | YES | false | NULL | | -+--------------+-----------+------+-------+---------+-------+ -``` - -查询表以验证数据是否已加载到其中。示例： - -```SQL -SELECT * from user_behavior_inferred LIMIT 3; -``` - -返回以下查询结果，表明数据已成功加载： - -```Plain -+--------+--------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+--------+------------+--------------+---------------------+ -| 84 | 162325 | 2939262 | pv | 2017-12-02 05:41:41 | -| 84 | 232622 | 4148053 | pv | 2017-11-27 04:36:10 | -| 84 | 595303 | 903809 | pv | 2017-11-26 08:03:59 | -+--------+--------+------------+--------------+---------------------+ -``` - -#### 使用 INSERT 加载到现有表中 - -您可能想要自定义要插入的表，例如： - -- 列数据类型、可为空设置或默认值 -- 键类型和列 -- 数据分区和分桶 - -> **NOTE** -> -> 创建最有效的表结构需要了解数据的使用方式和列的内容。本主题不涵盖表设计。有关表设计的信息，请参阅 [表类型](../table_design/StarRocks_table_design.md)。 - -在此示例中，我们基于对表的查询方式和 Parquet 文件中的数据的了解来创建表。对 Parquet 文件中的数据的了解可以通过直接在 GCS 中查询文件来获得。 - -- 由于 GCS 中数据集的查询表明 `Timestamp` 列包含与 VARBINARY 数据类型匹配的数据，因此在以下 DDL 中指定了列类型。 -- 通过查询 GCS 中的数据，您可以发现数据集中没有 `NULL` 值，因此 DDL 不会将任何列设置为可为空。 -- 根据对预期查询类型的了解，排序键和分桶列设置为列 `UserID`。您的用例可能与此数据不同，因此您可能会决定除了 `UserID` 之外或代替 `UserID` 使用 `ItemID` 作为排序键。 - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表（我们建议该表具有与要从 GCS 加载的 Parquet 文件相同的模式）： - -```SQL -CREATE TABLE user_behavior_declared -( - UserID int(11), - ItemID int(11), - CategoryID int(11), - BehaviorType varchar(65533), - Timestamp varbinary -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID); -``` - -显示模式，以便您可以将其与 `FILES()` 表函数生成的推断模式进行比较： - -```sql -DESCRIBE user_behavior_declared; -``` - -```plaintext -+--------------+----------------+------+-------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+----------------+------+-------+---------+-------+ -| UserID | int | NO | true | NULL | | -| ItemID | int | NO | false | NULL | | -| CategoryID | int | NO | false | NULL | | -| BehaviorType | varchar(65533) | NO | false | NULL | | -| Timestamp | varbinary | NO | false | NULL | | -+--------------+----------------+------+-------+---------+-------+ -5 rows in set (0.00 sec) -``` - -:::tip - -将您刚刚创建的模式与之前使用 `FILES()` 表函数推断的模式进行比较。查看： - -- 数据类型 -- 可为空性 -- 键字段 - -为了更好地控制目标表的模式并获得更好的查询性能，我们建议您在生产环境中手动指定表模式。 - -::: - -创建表后，您可以使用 INSERT INTO SELECT FROM FILES() 加载它： - -```SQL -INSERT INTO user_behavior_declared - SELECT * FROM FILES - ( - "path" = "gs://starrocks-samples/user_behavior_ten_million_rows.parquet", - "format" = "parquet", - "gcp.gcs.service_account_email" = "sampledatareader@xxxxx-xxxxxx-000000.iam.gserviceaccount.com", - "gcp.gcs.service_account_private_key_id" = "baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - "gcp.gcs.service_account_private_key" = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" -); -``` - -> **NOTE** -> -> 将上述命令中的凭据替换为您自己的凭据。可以使用任何有效的服务帐户电子邮件、密钥和密码，因为任何经过 GCP 身份验证的用户都可以读取该对象。 - -加载完成后，您可以查询表以验证数据是否已加载到其中。示例： - -```SQL -SELECT * from user_behavior_declared LIMIT 3; -``` - -系统返回类似于以下的查询结果，表明数据已成功加载： - -```Plain -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 142 | 2869980 | 2939262 | pv | 2017-11-25 03:43:22 | -| 142 | 2522236 | 1669167 | pv | 2017-11-25 15:14:12 | -| 142 | 3031639 | 3607361 | pv | 2017-11-25 15:19:25 | -+--------+---------+------------+--------------+---------------------+ -``` - -#### 检查导入进度 - -您可以从 StarRocks Information Schema 中的 [`loads`](../sql-reference/information_schema/loads.md) 视图查询 INSERT 作业的进度。此功能从 v3.1 开始受支持。示例： - -```SQL -SELECT * FROM information_schema.loads ORDER BY JOB_ID DESC; -``` - -有关 `loads` 视图中提供的字段的信息，请参阅 [`loads`](../sql-reference/information_schema/loads.md)。 - -如果您提交了多个导入作业，则可以按与该作业关联的 `LABEL` 进行筛选。示例： - -```SQL -SELECT * FROM information_schema.loads WHERE LABEL = 'insert_f3fc2298-a553-11ee-92f4-00163e0842bd' \G -*************************** 1. row *************************** - JOB_ID: 10193 - LABEL: insert_f3fc2298-a553-11ee-92f4-00163e0842bd - DATABASE_NAME: mydatabase - STATE: FINISHED - PROGRESS: ETL:100%; LOAD:100% - TYPE: INSERT - PRIORITY: NORMAL - SCAN_ROWS: 10000000 - FILTERED_ROWS: 0 - UNSELECTED_ROWS: 0 - SINK_ROWS: 10000000 - ETL_INFO: - TASK_INFO: resource:N/A; timeout(s):300; max_filter_ratio:0.0 - CREATE_TIME: 2023-12-28 15:37:38 - ETL_START_TIME: 2023-12-28 15:37:38 - ETL_FINISH_TIME: 2023-12-28 15:37:38 - LOAD_START_TIME: 2023-12-28 15:37:38 - LOAD_FINISH_TIME: 2023-12-28 15:39:35 - JOB_DETAILS: {"All backends":{"f3fc2298-a553-11ee-92f4-00163e0842bd":[10120]},"FileNumber":0,"FileSize":0,"InternalTableLoadBytes":581730322,"InternalTableLoadRows":10000000,"ScanBytes":581574034,"ScanRows":10000000,"TaskNumber":1,"Unfinished backends":{"f3fc2298-a553-11ee-92f4-00163e0842bd":[]}} - ERROR_MSG: NULL - TRACKING_URL: NULL - TRACKING_SQL: NULL -REJECTED_RECORD_PATH: NULL -``` - -> **NOTE** -> -> INSERT 是一个同步命令。如果 INSERT 作业仍在运行，您需要打开另一个会话来检查其执行状态。 - -## 使用 Broker Load - -异步 Broker Load 进程处理与 GCS 的连接、提取数据以及将数据存储在 StarRocks 中。 - -此方法支持以下文件格式： - -- Parquet -- ORC -- CSV -- JSON（从 v3.2.3 开始支持） - -### Broker Load 的优势 - -- Broker Load 在后台运行，客户端无需保持连接即可继续作业。 -- Broker Load 是长时间运行作业的首选，默认超时时间为 4 小时。 -- 除了 Parquet 和 ORC 文件格式外，Broker Load 还支持 CSV 文件格式和 JSON 文件格式（从 v3.2.3 开始支持 JSON 文件格式）。 - -### 数据流 - -![Broker Load 的工作流程](../_assets/broker_load_how-to-work_en.png) - -1. 用户创建一个导入作业。 -2. 前端 (FE) 创建一个查询计划，并将该计划分发到后端节点 (BEs) 或计算节点 (CNs)。 -3. BE 或 CN 从源中提取数据，并将数据加载到 StarRocks 中。 - -### 典型示例 - -创建一个表，启动一个从 GCS 提取示例数据集 `gs://starrocks-samples/user_behavior_ten_million_rows.parquet` 的导入进程，并验证数据加载的进度和成功。 - -#### 创建数据库和表 - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表（我们建议该表具有与要从 GCS 加载的 Parquet 文件相同的模式）： - -```SQL -CREATE TABLE user_behavior -( - UserID int(11), - ItemID int(11), - CategoryID int(11), - BehaviorType varchar(65533), - Timestamp varbinary -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID); -``` - -#### 启动 Broker Load - -运行以下命令以启动一个 Broker Load 作业，该作业将数据从示例数据集 `gs://starrocks-samples/user_behavior_ten_million_rows.parquet` 加载到 `user_behavior` 表： - -```SQL -LOAD LABEL user_behavior -( - DATA INFILE("gs://starrocks-samples/user_behavior_ten_million_rows.parquet") - INTO TABLE user_behavior - FORMAT AS "parquet" - ) - WITH BROKER - ( - - "gcp.gcs.service_account_email" = "sampledatareader@xxxxx-xxxxxx-000000.iam.gserviceaccount.com", - "gcp.gcs.service_account_private_key_id" = "baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - "gcp.gcs.service_account_private_key" = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" - ) -PROPERTIES -( - "timeout" = "72000" -); -``` - -> **NOTE** -> -> 将上述命令中的凭据替换为您自己的凭据。可以使用任何有效的服务帐户电子邮件、密钥和密码，因为任何经过 GCP 身份验证的用户都可以读取该对象。 - -此作业有四个主要部分： - -- `LABEL`: 查询导入作业状态时使用的字符串。 -- `LOAD` 声明：源 URI、源数据格式和目标表名称。 -- `BROKER`: 源的连接详细信息。 -- `PROPERTIES`: 超时值和要应用于导入作业的任何其他属性。 - -有关详细的语法和参数说明，请参阅 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -#### 检查导入进度 - -您可以从 StarRocks Information Schema 中的 [`loads`](../sql-reference/information_schema/loads.md) 视图查询 INSERT 作业的进度。此功能从 v3.1 开始受支持。 - -```SQL -SELECT * FROM information_schema.loads; -``` - -有关 `loads` 视图中提供的字段的信息，请参阅 [`loads`](../sql-reference/information_schema/loads.md)。 - -如果您提交了多个导入作业，则可以按与该作业关联的 `LABEL` 进行筛选。示例： - -```SQL -SELECT * FROM information_schema.loads WHERE LABEL = 'user_behavior'; -``` - -在下面的输出中，`user_behavior` 导入作业有两个条目： - -- 第一个记录显示 `CANCELLED` 状态。滚动到 `ERROR_MSG`，您可以看到该作业由于 `listPath failed` 而失败。 -- 第二个记录显示 `FINISHED` 状态，这意味着该作业已成功。 - -```Plain -JOB_ID|LABEL |DATABASE_NAME|STATE |PROGRESS |TYPE |PRIORITY|SCAN_ROWS|FILTERED_ROWS|UNSELECTED_ROWS|SINK_ROWS|ETL_INFO|TASK_INFO |CREATE_TIME |ETL_START_TIME |ETL_FINISH_TIME |LOAD_START_TIME |LOAD_FINISH_TIME |JOB_DETAILS |ERROR_MSG |TRACKING_URL|TRACKING_SQL|REJECTED_RECORD_PATH| -------+-------------------------------------------+-------------+---------+-------------------+------+--------+---------+-------------+---------------+---------+--------+----------------------------------------------------+-------------------+-------------------+-------------------+-------------------+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------+------------+------------+--------------------+ - 10121|user_behavior |mydatabase |CANCELLED|ETL:N/A; LOAD:N/A |BROKER|NORMAL | 0| 0| 0| 0| |resource:N/A; timeout(s):72000; max_filter_ratio:0.0|2023-08-10 14:59:30| | | |2023-08-10 14:59:34|{"All backends":{},"FileNumber":0,"FileSize":0,"InternalTableLoadBytes":0,"InternalTableLoadRows":0,"ScanBytes":0,"ScanRows":0,"TaskNumber":0,"Unfinished backends":{}} |type:ETL_RUN_FAIL; msg:listPath failed| | | | - 10106|user_behavior |mydatabase |FINISHED |ETL:100%; LOAD:100%|BROKER|NORMAL | 86953525| 0| 0| 86953525| |resource:N/A; timeout(s):72000; max_filter_ratio:0.0|2023-08-10 14:50:15|2023-08-10 14:50:19|2023-08-10 14:50:19|2023-08-10 14:50:19|2023-08-10 14:55:10|{"All backends":{"a5fe5e1d-d7d0-4826-ba99-c7348f9a5f2f":[10004]},"FileNumber":1,"FileSize":1225637388,"InternalTableLoadBytes":2710603082,"InternalTableLoadRows":86953525,"ScanBytes":1225637388,"ScanRows":86953525,"TaskNumber":1,"Unfinished backends":{"a5| | | | | -``` - -确认导入作业已完成后，您可以检查目标表的一个子集，以查看数据是否已成功加载。示例： - -```SQL -SELECT * from user_behavior LIMIT 3; -``` - -系统返回类似于以下的查询结果，表明数据已成功加载： - -```Plain -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 142 | 2869980 | 2939262 | pv | 2017-11-25 03:43:22 | -| 142 | 2522236 | 1669167 | pv | 2017-11-25 15:14:12 | -| 142 | 3031639 | 3607361 | pv | 2017-11-25 15:19:25 | -+--------+---------+------------+--------------+---------------------+ \ No newline at end of file diff --git a/docs/zh/loading/hdfs_load.md b/docs/zh/loading/hdfs_load.md deleted file mode 100644 index 4674d0b..0000000 --- a/docs/zh/loading/hdfs_load.md +++ /dev/null @@ -1,605 +0,0 @@ ---- -displayed_sidebar: docs -toc_max_heading_level: 4 -keywords: ['Broker Load'] ---- - -# 从 HDFS 导入数据 - -import LoadMethodIntro from '../_assets/commonMarkdown/loadMethodIntro.mdx' - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -import PipeAdvantages from '../_assets/commonMarkdown/pipeAdvantages.mdx' - -StarRocks 提供了以下从 HDFS 导入数据的选项： - - - -## 前提条件 - -### 准备源数据 - -确保要导入到 StarRocks 中的源数据已正确存储在 HDFS 集群中。本文档假设您要将 `/user/amber/user_behavior_ten_million_rows.parquet` 从 HDFS 导入到 StarRocks 中。 - -### 检查权限 - - - -### 收集认证信息 - -您可以使用简单的身份验证方法来建立与 HDFS 集群的连接。要使用简单的身份验证，您需要收集可用于访问 HDFS 集群的 NameNode 的帐户的用户名和密码。 - -## 使用 INSERT+FILES() - -此方法从 v3.1 开始可用，目前仅支持 Parquet、ORC 和 CSV (从 v3.3.0 开始支持) 文件格式。 - -### INSERT+FILES() 的优势 - -[`FILES()`](../sql-reference/sql-functions/table-functions/files.md) 可以读取存储在云存储中的文件，根据您指定的路径相关属性，推断文件中数据的表结构，然后将文件中的数据作为数据行返回。 - -使用 `FILES()`，您可以： - -- 使用 [SELECT](../sql-reference/sql-statements/table_bucket_part_index/SELECT.md) 直接从 HDFS 查询数据。 -- 使用 [CREATE TABLE AS SELECT](../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_AS_SELECT.md) (CTAS) 创建和导入表。 -- 使用 [INSERT](../sql-reference/sql-statements/table_bucket_part_index/SELECT.md) 将数据导入到现有表中。 - -### 典型示例 - -#### 使用 SELECT 直接从 HDFS 查询 - -使用 SELECT+`FILES()` 直接从 HDFS 查询可以在创建表之前很好地预览数据集的内容。例如： - -- 在不存储数据的情况下获取数据集的预览。 -- 查询最小值和最大值，并确定要使用的数据类型。 -- 检查 `NULL` 值。 - -以下示例查询存储在 HDFS 集群中的数据文件 `/user/amber/user_behavior_ten_million_rows.parquet`： - -```SQL -SELECT * FROM FILES -( - "path" = "hdfs://:/user/amber/user_behavior_ten_million_rows.parquet", - "format" = "parquet", - "hadoop.security.authentication" = "simple", - "username" = "", - "password" = "" -) -LIMIT 3; -``` - -系统返回以下查询结果： - -```Plaintext -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 543711 | 829192 | 2355072 | pv | 2017-11-27 08:22:37 | -| 543711 | 2056618 | 3645362 | pv | 2017-11-27 10:16:46 | -| 543711 | 1165492 | 3645362 | pv | 2017-11-27 10:17:00 | -+--------+---------+------------+--------------+---------------------+ -``` - -> **NOTE** -> -> 请注意，上面返回的列名由 Parquet 文件提供。 - -#### 使用 CTAS 创建和导入表 - -这是前一个示例的延续。前面的查询包含在 CREATE TABLE AS SELECT (CTAS) 中，以使用模式推断自动执行表创建。这意味着 StarRocks 将推断表结构，创建您想要的表，然后将数据导入到表中。使用 `FILES()` 表函数时，Parquet 格式包含列名，因此创建表时不需要列名和类型。 - -> **NOTE** -> -> 使用模式推断时，CREATE TABLE 的语法不允许设置副本数，因此请在创建表之前设置它。以下示例适用于具有三个副本的系统： -> -> ```SQL -> ADMIN SET FRONTEND CONFIG ('default_replication_num' = "3"); -> ``` - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -使用 CTAS 创建一个表，并将数据文件 `/user/amber/user_behavior_ten_million_rows.parquet` 的数据导入到该表中： - -```SQL -CREATE TABLE user_behavior_inferred AS -SELECT * FROM FILES -( - "path" = "hdfs://:/user/amber/user_behavior_ten_million_rows.parquet", - "format" = "parquet", - "hadoop.security.authentication" = "simple", - "username" = "", - "password" = "" -); -``` - -创建表后，您可以使用 [DESCRIBE](../sql-reference/sql-statements/table_bucket_part_index/DESCRIBE.md) 查看其结构： - -```SQL -DESCRIBE user_behavior_inferred; -``` - -系统返回以下查询结果： - -```Plain -+--------------+-----------+------+-------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+-----------+------+-------+---------+-------+ -| UserID | bigint | YES | true | NULL | | -| ItemID | bigint | YES | true | NULL | | -| CategoryID | bigint | YES | true | NULL | | -| BehaviorType | varbinary | YES | false | NULL | | -| Timestamp | varbinary | YES | false | NULL | | -+--------------+-----------+------+-------+---------+-------+ -``` - -查询表以验证数据是否已导入到其中。示例： - -```SQL -SELECT * from user_behavior_inferred LIMIT 3; -``` - -返回以下查询结果，表明数据已成功导入： - -```Plaintext -+--------+--------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+--------+------------+--------------+---------------------+ -| 84 | 56257 | 1879194 | pv | 2017-11-26 05:56:23 | -| 84 | 108021 | 2982027 | pv | 2017-12-02 05:43:00 | -| 84 | 390657 | 1879194 | pv | 2017-11-28 11:20:30 | -+--------+--------+------------+--------------+---------------------+ -``` - -#### 使用 INSERT 导入到现有表 - -您可能想要自定义要导入的表，例如： - -- 列数据类型、nullable 设置或默认值 -- 键类型和列 -- 数据分区和分桶 - -> **NOTE** -> -> 创建最有效的表结构需要了解数据的使用方式和列的内容。本主题不包括表设计。有关表设计的信息，请参见 [表类型](../table_design/StarRocks_table_design.md)。 - -在此示例中，我们基于对表查询方式和 Parquet 文件中数据的了解来创建表。对 Parquet 文件中数据的了解可以通过直接在 HDFS 中查询文件来获得。 - -- 由于 HDFS 中数据集的查询表明 `Timestamp` 列包含与 VARBINARY 数据类型匹配的数据，因此列类型在以下 DDL 中指定。 -- 通过查询 HDFS 中的数据，您可以发现数据集中没有 `NULL` 值，因此 DDL 不会将任何列设置为 nullable。 -- 根据对预期查询类型的了解，排序键和分桶列设置为列 `UserID`。您的用例可能与此数据不同，因此您可能会决定将 `ItemID` 除了 `UserID` 之外或代替 `UserID` 用于排序键。 - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表（我们建议该表具有与要从 HDFS 导入的 Parquet 文件相同的结构）： - -```SQL -CREATE TABLE user_behavior_declared -( - UserID int(11), - ItemID int(11), - CategoryID int(11), - BehaviorType varchar(65533), - Timestamp varbinary -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID); -``` - -显示结构，以便您可以将其与 `FILES()` 表函数生成的推断结构进行比较： - -```sql -DESCRIBE user_behavior_declared; -``` - -```plaintext -+--------------+----------------+------+-------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+----------------+------+-------+---------+-------+ -| UserID | int | NO | true | NULL | | -| ItemID | int | NO | false | NULL | | -| CategoryID | int | NO | false | NULL | | -| BehaviorType | varchar(65533) | NO | false | NULL | | -| Timestamp | varbinary | NO | false | NULL | | -+--------------+----------------+------+-------+---------+-------+ -5 rows in set (0.00 sec) -``` - -:::tip - -将您刚刚创建的结构与之前使用 `FILES()` 表函数推断的结构进行比较。查看： - -- 数据类型 -- nullable -- 键字段 - -为了更好地控制目标表的结构并获得更好的查询性能，我们建议您在生产环境中手动指定表结构。 - -::: - -创建表后，您可以使用 INSERT INTO SELECT FROM FILES() 导入它： - -```SQL -INSERT INTO user_behavior_declared -SELECT * FROM FILES -( - "path" = "hdfs://:/user/amber/user_behavior_ten_million_rows.parquet", - "format" = "parquet", - "hadoop.security.authentication" = "simple", - "username" = "", - "password" = "" -); -``` - -导入完成后，您可以查询表以验证数据是否已导入到其中。示例： - -```SQL -SELECT * from user_behavior_declared LIMIT 3; -``` - -返回以下查询结果，表明数据已成功导入： - -```Plaintext -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 107 | 1568743 | 4476428 | pv | 2017-11-25 14:29:53 | -| 107 | 470767 | 1020087 | pv | 2017-11-25 14:32:31 | -| 107 | 358238 | 1817004 | pv | 2017-11-25 14:43:23 | -+--------+---------+------------+--------------+---------------------+ -``` - -#### 检查导入进度 - -您可以从 StarRocks Information Schema 中的 [`loads`](../sql-reference/information_schema/loads.md) 视图查询 INSERT 作业的进度。此功能从 v3.1 开始支持。示例： - -```SQL -SELECT * FROM information_schema.loads ORDER BY JOB_ID DESC; -``` - -有关 `loads` 视图中提供的字段的信息，请参见 [`loads`](../sql-reference/information_schema/loads.md)。 - -如果您提交了多个导入作业，则可以按与该作业关联的 `LABEL` 进行过滤。示例： - -```SQL -SELECT * FROM information_schema.loads WHERE LABEL = 'insert_0d86c3f9-851f-11ee-9c3e-00163e044958' \G -*************************** 1. row *************************** - JOB_ID: 10214 - LABEL: insert_0d86c3f9-851f-11ee-9c3e-00163e044958 - DATABASE_NAME: mydatabase - STATE: FINISHED - PROGRESS: ETL:100%; LOAD:100% - TYPE: INSERT - PRIORITY: NORMAL - SCAN_ROWS: 10000000 - FILTERED_ROWS: 0 - UNSELECTED_ROWS: 0 - SINK_ROWS: 10000000 - ETL_INFO: - TASK_INFO: resource:N/A; timeout(s):300; max_filter_ratio:0.0 - CREATE_TIME: 2023-11-17 15:58:14 - ETL_START_TIME: 2023-11-17 15:58:14 - ETL_FINISH_TIME: 2023-11-17 15:58:14 - LOAD_START_TIME: 2023-11-17 15:58:14 - LOAD_FINISH_TIME: 2023-11-17 15:58:18 - JOB_DETAILS: {"All backends":{"0d86c3f9-851f-11ee-9c3e-00163e044958":[10120]},"FileNumber":0,"FileSize":0,"InternalTableLoadBytes":311710786,"InternalTableLoadRows":10000000,"ScanBytes":581574034,"ScanRows":10000000,"TaskNumber":1,"Unfinished backends":{"0d86c3f9-851f-11ee-9c3e-00163e044958":[]}} - ERROR_MSG: NULL - TRACKING_URL: NULL - TRACKING_SQL: NULL -REJECTED_RECORD_PATH: NULL -``` - -> **NOTE** -> -> INSERT 是一个同步命令。如果 INSERT 作业仍在运行，您需要打开另一个会话来检查其执行状态。 - -## 使用 Broker Load - -异步 Broker Load 进程处理与 HDFS 的连接、拉取数据以及将数据存储在 StarRocks 中。 - -此方法支持以下文件格式： - -- Parquet -- ORC -- CSV -- JSON (从 v3.2.3 开始支持) - -### Broker Load 的优势 - -- Broker Load 在后台运行，客户端无需保持连接即可继续作业。 -- 对于长时间运行的作业，Broker Load 是首选，默认超时时间为 4 小时。 -- 除了 Parquet 和 ORC 文件格式外，Broker Load 还支持 CSV 文件格式和 JSON 文件格式 (从 v3.2.3 开始支持 JSON 文件格式)。 - -### 数据流 - -![Broker Load 的工作流程](../_assets/broker_load_how-to-work_en.png) - -1. 用户创建一个导入作业。 -2. 前端 (FE) 创建一个查询计划，并将该计划分发到后端节点 (BEs) 或计算节点 (CNs)。 -3. BE 或 CN 从源拉取数据，并将数据导入到 StarRocks 中。 - -### 典型示例 - -创建一个表，启动一个从 HDFS 拉取数据文件 `/user/amber/user_behavior_ten_million_rows.parquet` 的导入进程，并验证数据导入的进度和成功。 - -#### 创建数据库和表 - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表（我们建议该表具有与要从 HDFS 导入的 Parquet 文件相同的结构）： - -```SQL -CREATE TABLE user_behavior -( - UserID int(11), - ItemID int(11), - CategoryID int(11), - BehaviorType varchar(65533), - Timestamp varbinary -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID); -``` - -#### 启动 Broker Load - -运行以下命令以启动一个 Broker Load 作业，该作业将数据从数据文件 `/user/amber/user_behavior_ten_million_rows.parquet` 导入到 `user_behavior` 表： - -```SQL -LOAD LABEL user_behavior -( - DATA INFILE("hdfs://:/user/amber/user_behavior_ten_million_rows.parquet") - INTO TABLE user_behavior - FORMAT AS "parquet" - ) - WITH BROKER -( - "hadoop.security.authentication" = "simple", - "username" = "", - "password" = "" -) -PROPERTIES -( - "timeout" = "72000" -); -``` - -此作业有四个主要部分： - -- `LABEL`: 查询导入作业状态时使用的字符串。 -- `LOAD` 声明：源 URI、源数据格式和目标表名称。 -- `BROKER`: 源的连接详细信息。 -- `PROPERTIES`: 超时值和要应用于导入作业的任何其他属性。 - -有关详细的语法和参数说明，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -#### 检查导入进度 - -您可以从 `information_schema.loads` 视图查询 Broker Load 作业的进度。此功能从 v3.1 开始支持。 - -```SQL -SELECT * FROM information_schema.loads; -``` - -有关 `loads` 视图中提供的字段的信息，请参见 [Information Schema](../sql-reference/information_schema/loads.md)。 - -如果您提交了多个导入作业，则可以按与该作业关联的 `LABEL` 进行过滤。示例： - -```SQL -SELECT * FROM information_schema.loads WHERE LABEL = 'user_behavior'; -``` - -在下面的输出中，`user_behavior` 导入作业有两个条目： - -- 第一个记录显示 `CANCELLED` 状态。滚动到 `ERROR_MSG`，您可以看到该作业由于 `listPath failed` 而失败。 -- 第二个记录显示 `FINISHED` 状态，这意味着该作业已成功。 - -```Plaintext -JOB_ID|LABEL |DATABASE_NAME|STATE |PROGRESS |TYPE |PRIORITY|SCAN_ROWS|FILTERED_ROWS|UNSELECTED_ROWS|SINK_ROWS|ETL_INFO|TASK_INFO |CREATE_TIME |ETL_START_TIME |ETL_FINISH_TIME |LOAD_START_TIME |LOAD_FINISH_TIME |JOB_DETAILS |ERROR_MSG |TRACKING_URL|TRACKING_SQL|REJECTED_RECORD_PATH| -------+-------------------------------------------+-------------+---------+-------------------+------+--------+---------+-------------+---------------+---------+--------+----------------------------------------------------+-------------------+-------------------+-------------------+-------------------+-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------+------------+------------+--------------------+ - 10121|user_behavior |mydatabase |CANCELLED|ETL:N/A; LOAD:N/A |BROKER|NORMAL | 0| 0| 0| 0| |resource:N/A; timeout(s):72000; max_filter_ratio:0.0|2023-08-10 14:59:30| | | |2023-08-10 14:59:34|{"All backends":{},"FileNumber":0,"FileSize":0,"InternalTableLoadBytes":0,"InternalTableLoadRows":0,"ScanBytes":0,"ScanRows":0,"TaskNumber":0,"Unfinished backends":{}} |type:ETL_RUN_FAIL; msg:listPath failed| | | | - 10106|user_behavior |mydatabase |FINISHED |ETL:100%; LOAD:100%|BROKER|NORMAL | 86953525| 0| 0| 86953525| |resource:N/A; timeout(s):72000; max_filter_ratio:0.0|2023-08-10 14:50:15|2023-08-10 14:50:19|2023-08-10 14:50:19|2023-08-10 14:50:19|2023-08-10 14:55:10|{"All backends":{"a5fe5e1d-d7d0-4826-ba99-c7348f9a5f2f":[10004]},"FileNumber":1,"FileSize":1225637388,"InternalTableLoadBytes":2710603082,"InternalTableLoadRows":86953525,"ScanBytes":1225637388,"ScanRows":86953525,"TaskNumber":1,"Unfinished backends":{"a5| | | | | -``` - -确认导入作业已完成后，您可以检查目标表的子集，以查看数据是否已成功导入。示例： - -```SQL -SELECT * from user_behavior LIMIT 3; -``` - -返回以下查询结果，表明数据已成功导入： - -```Plaintext -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 142 | 2869980 | 2939262 | pv | 2017-11-25 03:43:22 | -| 142 | 2522236 | 1669167 | pv | 2017-11-25 15:14:12 | -| 142 | 3031639 | 3607361 | pv | 2017-11-25 15:19:25 | -+--------+---------+------------+--------------+---------------------+ -``` - -## 使用 Pipe - -从 v3.2 开始，StarRocks 提供了 Pipe 导入方法，目前仅支持 Parquet 和 ORC 文件格式。 - -### Pipe 的优势 - - - -Pipe 非常适合连续数据导入和大规模数据导入： - -- **微批次中的大规模数据导入有助于降低由数据错误引起的重试成本。** - - 借助 Pipe，StarRocks 能够高效地导入大量数据文件，这些文件总共有很大的数据量。Pipe 根据文件的数量或大小自动拆分文件，将导入作业分解为较小的顺序任务。这种方法确保一个文件中的错误不会影响整个导入作业。每个文件的导入状态由 Pipe 记录，使您可以轻松识别和修复包含错误的文件。通过最大限度地减少由于数据错误而需要重试的次数，这种方法有助于降低成本。 - -- **连续数据导入有助于减少人力。** - - Pipe 帮助您将新的或更新的数据文件写入特定位置，并不断地将这些文件中的新数据导入到 StarRocks 中。在使用 `"AUTO_INGEST" = "TRUE"` 指定创建 Pipe 作业后，它将不断监视存储在指定路径中的数据文件的更改，并自动将数据文件中的新的或更新的数据导入到目标 StarRocks 表中。 - -此外，Pipe 执行文件唯一性检查，以帮助防止重复数据导入。在导入过程中，Pipe 根据文件名和摘要检查每个数据文件的唯一性。如果具有特定文件名和摘要的文件已经由 Pipe 作业处理，则 Pipe 作业将跳过所有后续具有相同文件名和摘要的文件。请注意，HDFS 使用 `LastModifiedTime` 作为文件摘要。 - -每个数据文件的导入状态都会被记录并保存到 `information_schema.pipe_files` 视图中。在删除与该视图关联的 Pipe 作业后，有关在该作业中导入的文件的记录也将被删除。 - -### 数据流 - -![Pipe 数据流](../_assets/pipe_data_flow.png) - -### Pipe 和 INSERT+FILES() 之间的区别 - -Pipe 作业根据每个数据文件的大小和行数拆分为一个或多个事务。用户可以在导入过程中查询中间结果。相比之下，INSERT+`FILES()` 作业作为一个事务处理，用户无法在导入过程中查看数据。 - -### 文件导入顺序 - -对于每个 Pipe 作业，StarRocks 维护一个文件队列，从中提取数据文件并将其作为微批次导入。Pipe 不保证数据文件以与上传顺序相同的顺序导入。因此，较新的数据可能在较旧的数据之前导入。 - -### 典型示例 - -#### 创建数据库和表 - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表（我们建议该表具有与要从 HDFS 导入的 Parquet 文件相同的结构）： - -```SQL -CREATE TABLE user_behavior_replica -( - UserID int(11), - ItemID int(11), - CategoryID int(11), - BehaviorType varchar(65533), - Timestamp varbinary -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID); -``` - -#### 启动 Pipe 作业 - -运行以下命令以启动一个 Pipe 作业，该作业将数据从数据文件 `/user/amber/user_behavior_ten_million_rows.parquet` 导入到 `user_behavior_replica` 表： - -```SQL -CREATE PIPE user_behavior_replica -PROPERTIES -( - "AUTO_INGEST" = "TRUE" -) -AS -INSERT INTO user_behavior_replica -SELECT * FROM FILES -( - "path" = "hdfs://:/user/amber/user_behavior_ten_million_rows.parquet", - "format" = "parquet", - "hadoop.security.authentication" = "simple", - "username" = "", - "password" = "" -); -``` - -此作业有四个主要部分： - -- `pipe_name`: Pipe 的名称。Pipe 名称在 Pipe 所属的数据库中必须是唯一的。 -- `INSERT_SQL`: 用于将数据从指定的源数据文件导入到目标表的 INSERT INTO SELECT FROM FILES 语句。 -- `PROPERTIES`: 一组可选参数，用于指定如何执行 Pipe。这些参数包括 `AUTO_INGEST`、`POLL_INTERVAL`、`BATCH_SIZE` 和 `BATCH_FILES`。以 `"key" = "value"` 格式指定这些属性。 - -有关详细的语法和参数说明，请参见 [CREATE PIPE](../sql-reference/sql-statements/loading_unloading/pipe/CREATE_PIPE.md)。 - -#### 检查导入进度 - -- 使用 [SHOW PIPES](../sql-reference/sql-statements/loading_unloading/pipe/SHOW_PIPES.md) 查询 Pipe 作业的进度。 - - ```SQL - SHOW PIPES; - ``` - - 如果您提交了多个导入作业，则可以按与该作业关联的 `NAME` 进行过滤。示例： - - ```SQL - SHOW PIPES WHERE NAME = 'user_behavior_replica' \G - *************************** 1. row *************************** - DATABASE_NAME: mydatabase - PIPE_ID: 10252 - PIPE_NAME: user_behavior_replica - STATE: RUNNING - TABLE_NAME: mydatabase.user_behavior_replica - LOAD_STATUS: {"loadedFiles":1,"loadedBytes":132251298,"loadingFiles":0,"lastLoadedTime":"2023-11-17 16:13:22"} - LAST_ERROR: NULL - CREATED_TIME: 2023-11-17 16:13:15 - 1 row in set (0.00 sec) - ``` - -- 从 StarRocks Information Schema 中的 [`pipes`](../sql-reference/information_schema/pipes.md) 视图查询 Pipe 作业的进度。 - - ```SQL - SELECT * FROM information_schema.pipes; - ``` - - 如果您提交了多个导入作业，则可以按与该作业关联的 `PIPE_NAME` 进行过滤。示例： - - ```SQL - SELECT * FROM information_schema.pipes WHERE pipe_name = 'user_behavior_replica' \G - *************************** 1. row *************************** - DATABASE_NAME: mydatabase - PIPE_ID: 10252 - PIPE_NAME: user_behavior_replica - STATE: RUNNING - TABLE_NAME: mydatabase.user_behavior_replica - LOAD_STATUS: {"loadedFiles":1,"loadedBytes":132251298,"loadingFiles":0,"lastLoadedTime":"2023-11-17 16:13:22"} - LAST_ERROR: - CREATED_TIME: 2023-11-17 16:13:15 - 1 row in set (0.00 sec) - ``` - -#### 检查文件状态 - -您可以从 StarRocks Information Schema 中的 [`pipe_files`](../sql-reference/information_schema/pipe_files.md) 视图查询从导入的文件的导入状态。 - -```SQL -SELECT * FROM information_schema.pipe_files; -``` - -如果您提交了多个导入作业，则可以按与该作业关联的 `PIPE_NAME` 进行过滤。示例： - -```SQL -SELECT * FROM information_schema.pipe_files WHERE pipe_name = 'user_behavior_replica' \G -*************************** 1. row *************************** - DATABASE_NAME: mydatabase - PIPE_ID: 10252 - PIPE_NAME: user_behavior_replica - FILE_NAME: hdfs://172.26.195.67:9000/user/amber/user_behavior_ten_million_rows.parquet - FILE_VERSION: 1700035418838 - FILE_SIZE: 132251298 - LAST_MODIFIED: 2023-11-15 08:03:38 - LOAD_STATE: FINISHED - STAGED_TIME: 2023-11-17 16:13:16 - START_LOAD_TIME: 2023-11-17 16:13:17 -FINISH_LOAD_TIME: 2023-11-17 16:13:22 - ERROR_MSG: -1 row in set (0.02 sec) -``` - -#### 管理 Pipes - -您可以更改、暂停或恢复、删除或查询您创建的 Pipes，并重试导入特定的数据文件。有关更多信息，请参见 [ALTER PIPE](../sql-reference/sql-statements/loading_unloading/pipe/ALTER_PIPE.md)、[SUSPEND or RESUME PIPE](../sql-reference/sql-statements/loading_unloading/pipe/SUSPEND_or_RESUME_PIPE.md)、[DROP PIPE](../sql-reference/sql-statements/loading_unloading/pipe/DROP_PIPE.md)、[SHOW PIPES](../sql-reference/sql-statements/loading_unloading/pipe/SHOW_PIPES.md) 和 [RETRY FILE](../sql-reference/sql-statements/loading_unloading/pipe/RETRY_FILE.md)。 \ No newline at end of file diff --git a/docs/zh/loading/huawei.md b/docs/zh/loading/huawei.md deleted file mode 100644 index db92470..0000000 --- a/docs/zh/loading/huawei.md +++ /dev/null @@ -1 +0,0 @@ -unlisted: true \ No newline at end of file diff --git a/docs/zh/loading/load_concept/strict_mode.md b/docs/zh/loading/load_concept/strict_mode.md deleted file mode 100644 index c6949b9..0000000 --- a/docs/zh/loading/load_concept/strict_mode.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# Strict mode - -Strict mode 是一个可选属性，您可以为数据导入配置它。它会影响导入行为和最终导入的数据。 - -本主题介绍 strict mode 是什么以及如何设置 strict mode。 - -## 了解 strict mode - -在数据导入期间，源列的数据类型可能与目标列的数据类型不完全一致。在这种情况下，StarRocks 会对数据类型不一致的源列值执行转换。由于各种问题，例如不匹配的字段数据类型和字段长度溢出，数据转换可能会失败。未能正确转换的源列值是不合格的列值，包含不合格列值的源行被称为“不合格行”。Strict mode 用于控制在数据导入期间是否过滤掉不合格的行。 - -Strict mode 的工作方式如下： - -- 如果启用了 strict mode，StarRocks 仅导入合格的行。它会过滤掉不合格的行，并返回有关不合格行的详细信息。 -- 如果禁用了 strict mode，StarRocks 会将不合格的列值转换为 `NULL`，并将包含这些 `NULL` 值的不合格行与合格行一起导入。 - -请注意以下几点： - -- 在实际业务场景中，合格行和不合格行都可能包含 `NULL` 值。如果目标列不允许 `NULL` 值，StarRocks 会报告错误并过滤掉包含 `NULL` 值的行。 - -- 可以为导入作业过滤掉的不合格行的最大百分比由可选作业属性 `max_filter_ratio` 控制。 - -:::note - -从 v3.4.0 开始支持 INSERT 的 `max_filter_ratio` 属性。 - -::: - -例如，您想要将 CSV 格式的数据文件中的四行数据（分别包含 `\N`（`\N` 表示 `NULL` 值）、`abc`、`2000` 和 `1` 值）导入到 StarRocks 表的某一列中，并且目标 StarRocks 表列的数据类型为 TINYINT [-128, 127]。 - -- 源列值 `\N` 在转换为 TINYINT 时会被处理为 `NULL`。 - - > **NOTE** - > - > 无论目标数据类型如何，`\N` 在转换时始终会被处理为 `NULL`。 - -- 源列值 `abc` 会被处理为 `NULL`，因为其数据类型不是 TINYINT 并且转换失败。 - -- 源列值 `2000` 会被处理为 `NULL`，因为它超出了 TINYINT 支持的范围并且转换失败。 - -- 源列值 `1` 可以被正确转换为 TINYINT 类型的值 `1`。 - -如果禁用了 strict mode，StarRocks 会导入所有这四行数据。 - -如果启用了 strict mode，StarRocks 仅导入包含 `\N` 或 `1` 的行，并过滤掉包含 `abc` 或 `2000` 的行。过滤掉的行会计入 `max_filter_ratio` 参数指定的最大行百分比，这些行由于数据质量不足而被过滤掉。 - -### 禁用 strict mode 后最终导入的数据 - -| 源列值 | 转换为 TINYINT 后的列值 | 目标列允许 NULL 值时的导入结果 | 目标列不允许 NULL 值时的导入结果 | -| ------------------- | --------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ | -| \N | NULL | 导入 `NULL` 值。 | 报告错误。 | -| abc | NULL | 导入 `NULL` 值。 | 报告错误。 | -| 2000 | NULL | 导入 `NULL` 值。 | 报告错误。 | -| 1 | 1 | 导入 `1` 值。 | 导入 `1` 值。 | - -### 启用 strict mode 后最终导入的数据 - -| 源列值 | 转换为 TINYINT 后的列值 | 目标列允许 NULL 值时的导入结果 | 目标列不允许 NULL 值时的导入结果 | -| ------------------- | --------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| \N | NULL | 导入 `NULL` 值。 | 报告错误。 | -| abc | NULL | 不允许 `NULL` 值，因此被过滤掉。 | 报告错误。 | -| 2000 | NULL | 不允许 `NULL` 值，因此被过滤掉。 | 报告错误。 | -| 1 | 1 | 导入 `1` 值。 | 导入 `1` 值。 | - -## 设置 strict mode - -您可以使用 `strict_mode` 参数为导入作业设置 strict mode。有效值为 `true` 和 `false`。默认值为 `false`。值 `true` 启用 strict mode，值 `false` 禁用 strict mode。请注意，从 v3.4.0 开始支持 INSERT 的 `strict_mode` 参数，默认值为 `true`。现在，除了 Stream Load 之外，对于所有其他导入方法，`strict_mode` 在 PROPERTIES 子句中以相同的方式设置。 - -您还可以使用 `enable_insert_strict` 会话变量来设置 strict mode。有效值为 `true` 和 `false`。默认值为 `true`。值 `true` 启用 strict mode，值 `false` 禁用 strict mode。 - -:::note - -从 v3.4.0 开始，当 `enable_insert_strict` 设置为 `true` 时，系统仅导入合格的行。它会过滤掉不合格的行，并返回有关不合格行的详细信息。相反，在早于 v3.4.0 的版本中，当 `enable_insert_strict` 设置为 `true` 时，如果存在不合格的行，则 INSERT 作业会失败。 - -::: - -示例如下： - -### Stream Load - -```Bash -curl --location-trusted -u : \ - -H "strict_mode: {true | false}" \ - -T -XPUT \ - http://:/api///_stream_load -``` - -有关 Stream Load 的详细语法和参数，请参见 [STREAM LOAD](../../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)。 - -### Broker Load - -```SQL -LOAD LABEL [.] -( - DATA INFILE (""[, "" ...]) - INTO TABLE -) -WITH BROKER -( - "username" = "", - "password" = "" -) -PROPERTIES -( - "strict_mode" = "{true | false}" -) -``` - -上面的代码片段使用 HDFS 作为示例。有关 Broker Load 的详细语法和参数，请参见 [BROKER LOAD](../../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -### Routine Load - -```SQL -CREATE ROUTINE LOAD [.] ON -PROPERTIES -( - "strict_mode" = "{true | false}" -) -FROM KAFKA -( - "kafka_broker_list" =":[,:...]", - "kafka_topic" = "" -) -``` - -上面的代码片段使用 Apache Kafka® 作为示例。有关 Routine Load 的详细语法和参数，请参见 [CREATE ROUTINE LOAD](../../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。 - -### Spark Load - -```SQL -LOAD LABEL [.] -( - DATA INFILE (""[, "" ...]) - INTO TABLE -) -WITH RESOURCE -( - "spark.executor.memory" = "3g", - "broker.username" = "", - "broker.password" = "" -) -PROPERTIES -( - "strict_mode" = "{true | false}" -) -``` - -上面的代码片段使用 HDFS 作为示例。有关 Spark Load 的详细语法和参数，请参见 [SPARK LOAD](../../sql-reference/sql-statements/loading_unloading/SPARK_LOAD.md)。 - -### INSERT - -```SQL -INSERT INTO [.] -PROPERTIES( - "strict_mode" = "{true | false}" -) - -``` - -有关 INSERT 的详细语法和参数，请参见 [INSERT](../../sql-reference/sql-statements/loading_unloading/INSERT.md)。 \ No newline at end of file diff --git a/docs/zh/loading/load_from_pulsar.md b/docs/zh/loading/load_from_pulsar.md deleted file mode 100644 index 009023b..0000000 --- a/docs/zh/loading/load_from_pulsar.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -displayed_sidebar: docs ---- -import Experimental from '../_assets/commonMarkdown/_experimental.mdx' - -# 从 Apache® Pulsar™ 持续导入数据 - - - -从 StarRocks 2.5 版本开始，Routine Load 支持从 Apache® Pulsar™ 持续导入数据。Pulsar 是一个分布式的开源发布-订阅消息和流平台，采用存储计算分离架构。通过 Routine Load 从 Pulsar 导入数据类似于从 Apache Kafka 导入数据。本文以 CSV 格式的数据为例，介绍如何通过 Routine Load 从 Apache Pulsar 导入数据。 - -## 支持的数据文件格式 - -Routine Load 支持从 Pulsar 集群消费 CSV 和 JSON 格式的数据。 - -> NOTE -> -> 对于 CSV 格式的数据，StarRocks 支持将 UTF-8 编码的、长度不超过 50 字节的字符串用作列分隔符。常用的列分隔符包括逗号 (,)、Tab 和竖线 (|)。 - -## Pulsar 相关概念 - -**[Topic](https://pulsar.apache.org/docs/2.10.x/concepts-messaging/#topics)** - -Topic 是 Pulsar 中用于将消息从生产者传输到消费者的命名通道。Pulsar 中的 Topic 分为分区 Topic 和非分区 Topic。 - -- **[Partitioned topics](https://pulsar.apache.org/docs/2.10.x/concepts-messaging/#partitioned-topics)** 是一种特殊类型的 Topic，由多个 Broker 处理，从而实现更高的吞吐量。分区 Topic 实际上是作为 N 个内部 Topic 实现的，其中 N 是分区的数量。 -- **Non-partitioned topics** 是一种普通类型的 Topic，仅由单个 Broker 提供服务，这限制了 Topic 的最大吞吐量。 - -**[Message ID](https://pulsar.apache.org/docs/2.10.x/concepts-messaging/#messages)** - -消息的 Message ID 由 [BookKeeper instances](https://pulsar.apache.org/docs/2.10.x/concepts-architecture-overview/#apache-bookkeeper) 在消息被持久化存储后立即分配。Message ID 指示消息在账本中的特定位置，并且在 Pulsar 集群中是唯一的。 - -Pulsar 支持消费者通过 consumer.*seek*(*messageId*) 指定初始位置。但与 Kafka 消费者 offset（一个长整型值）相比，Message ID 由四个部分组成：`ledgerId:entryID:partition-index:batch-index`。 - -因此，您无法直接从消息中获取 Message ID。因此，目前，**Routine Load 不支持在从 Pulsar 导入数据时指定初始位置，而仅支持从分区的开头或结尾消费数据。** - -**[Subscription](https://pulsar.apache.org/docs/2.10.x/concepts-messaging/#subscriptions)** - -Subscription 是一种命名配置规则，用于确定如何将消息传递给消费者。Pulsar 还支持消费者同时订阅多个 Topic。一个 Topic 可以有多个 Subscription。 - -Subscription 的类型在消费者连接到它时定义，并且可以通过使用不同的配置重新启动所有消费者来更改类型。Pulsar 中有四种 Subscription 类型可用： - -- `exclusive` (默认)*:* 只允许单个消费者连接到 Subscription。只允许一个客户消费消息。 -- `shared`: 多个消费者可以连接到同一个 Subscription。消息以轮询方式在消费者之间分发，并且任何给定的消息仅传递给一个消费者。 -- `failover`: 多个消费者可以连接到同一个 Subscription。为非分区 Topic 或分区 Topic 的每个分区选择一个主消费者并接收消息。当主消费者断开连接时，所有（未确认的和后续的）消息都会传递给队列中的下一个消费者。 -- `key_shared`: 多个消费者可以连接到同一个 Subscription。消息在消费者之间分发，并且具有相同 key 或相同排序 key 的消息仅传递给一个消费者。 - -> Note: -> -> 目前 Routine Load 使用 exclusive 类型。 - -## 创建 Routine Load 作业 - -以下示例描述了如何消费 Pulsar 中 CSV 格式的消息，并通过创建 Routine Load 作业将数据加载到 StarRocks 中。有关详细说明和参考，请参见 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。 - -```SQL -CREATE ROUTINE LOAD load_test.routine_wiki_edit_1 ON routine_wiki_edit -COLUMNS TERMINATED BY ",", -ROWS TERMINATED BY "\n", -COLUMNS (order_id, pay_dt, customer_name, nationality, temp_gender, price) -WHERE event_time > "2022-01-01 00:00:00", -PROPERTIES -( - "desired_concurrent_number" = "1", - "max_batch_interval" = "15000", - "max_error_number" = "1000" -) -FROM PULSAR -( - "pulsar_service_url" = "pulsar://localhost:6650", - "pulsar_topic" = "persistent://tenant/namespace/topic-name", - "pulsar_subscription" = "load-test", - "pulsar_partitions" = "load-partition-0,load-partition-1", - "pulsar_initial_positions" = "POSITION_EARLIEST,POSITION_LATEST", - "property.auth.token" = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUJzdWIiOiJqaXV0aWFuY2hlbiJ9.lulGngOC72vE70OW54zcbyw7XdKSOxET94WT_hIqD5Y" -); -``` - -当创建 Routine Load 以从 Pulsar 消费数据时，除了 `data_source_properties` 之外，大多数输入参数与从 Kafka 消费数据时相同。有关除了 `data_source_properties` 之外的参数的描述，请参见 [CREATE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)。 - -与 `data_source_properties` 相关的参数及其描述如下： - -| **Parameter** | **Required** | **Description** | -| ------------------------------------------- | ------------ | ------------------------------------------------------------ | -| pulsar_service_url | Yes | 用于连接到 Pulsar 集群的 URL。格式：`"pulsar://ip:port"` 或 `"pulsar://service:port"`。示例：`"pulsar_service_url" = "pulsar://``localhost:6650``"` | -| pulsar_topic | Yes | 订阅的 Topic。示例：`"pulsar_topic" = "persistent://tenant/namespace/topic-name"` | -| pulsar_subscription | Yes | 为 Topic 配置的 Subscription。示例：`"pulsar_subscription" = "my_subscription"` | -| pulsar_partitions, pulsar_initial_positions | No | `pulsar_partitions` : Topic 中订阅的分区。`pulsar_initial_positions`: 由 `pulsar_partitions` 指定的分区的初始位置。初始位置必须与 `pulsar_partitions` 中的分区相对应。有效值：`POSITION_EARLIEST`（默认值）：Subscription 从分区中最早可用的消息开始。`POSITION_LATEST`: Subscription 从分区中最新的可用消息开始。注意：如果未指定 `pulsar_partitions`，则订阅 Topic 的所有分区。如果同时指定了 `pulsar_partitions` 和 `property.pulsar_default_initial_position`，则 `pulsar_partitions` 值将覆盖 `property.pulsar_default_initial_position` 值。如果既未指定 `pulsar_partitions` 也未指定 `property.pulsar_default_initial_position`，则订阅从分区中最新的可用消息开始。示例：`"pulsar_partitions" = "my-partition-0,my-partition-1,my-partition-2,my-partition-3", "pulsar_initial_positions" = "POSITION_EARLIEST,POSITION_EARLIEST,POSITION_LATEST,POSITION_LATEST"` | - -Routine Load 支持以下 Pulsar 的自定义参数。 - -| Parameter | Required | Description | -| ---------------------------------------- | -------- | ------------------------------------------------------------ | -| property.pulsar_default_initial_position | No | 订阅 Topic 的分区时的默认初始位置。该参数在未指定 `pulsar_initial_positions` 时生效。其有效值与 `pulsar_initial_positions` 的有效值相同。示例：`"``property.pulsar_default_initial_position" = "POSITION_EARLIEST"` | -| property.auth.token | No | 如果 Pulsar 启用了使用安全令牌对客户端进行身份验证，则您需要令牌字符串来验证您的身份。示例：`"p``roperty.auth.token" = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUJzdWIiOiJqaXV0aWFuY2hlbiJ9.lulGngOC72vE70OW54zcbyw7XdKSOxET94WT_hIqD"` | - -## 检查导入作业和任务 - -### 检查导入作业 - -执行 [SHOW ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD.md) 语句以检查导入作业 `routine_wiki_edit_1` 的状态。StarRocks 返回执行状态 `State`、统计信息（包括已消费的总行数和已加载的总行数）`Statistics` 以及导入作业的进度 `progress`。 - -当您检查从 Pulsar 消费数据的 Routine Load 作业时，除了 `progress` 之外，大多数返回的参数与从 Kafka 消费数据时相同。`progress` 指的是积压，即分区中未确认的消息数。 - -```Plaintext -MySQL [load_test] > SHOW ROUTINE LOAD for routine_wiki_edit_1 \G -*************************** 1. row *************************** - Id: 10142 - Name: routine_wiki_edit_1 - CreateTime: 2022-06-29 14:52:55 - PauseTime: 2022-06-29 17:33:53 - EndTime: NULL - DbName: default_cluster:test_pulsar - TableName: test1 - State: PAUSED - DataSourceType: PULSAR - CurrentTaskNum: 0 - JobProperties: {"partitions":"*","rowDelimiter":"'\n'","partial_update":"false","columnToColumnExpr":"*","maxBatchIntervalS":"10","whereExpr":"*","timezone":"Asia/Shanghai","format":"csv","columnSeparator":"','","json_root":"","strict_mode":"false","jsonpaths":"","desireTaskConcurrentNum":"3","maxErrorNum":"10","strip_outer_array":"false","currentTaskConcurrentNum":"0","maxBatchRows":"200000"} -DataSourceProperties: {"serviceUrl":"pulsar://localhost:6650","currentPulsarPartitions":"my-partition-0,my-partition-1","topic":"persistent://tenant/namespace/topic-name","subscription":"load-test"} - CustomProperties: {"auth.token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUJzdWIiOiJqaXV0aWFuY2hlbiJ9.lulGngOC72vE70OW54zcbyw7XdKSOxET94WT_hIqD"} - Statistic: {"receivedBytes":5480943882,"errorRows":0,"committedTaskNum":696,"loadedRows":66243440,"loadRowsRate":29000,"abortedTaskNum":0,"totalRows":66243440,"unselectedRows":0,"receivedBytesRate":2400000,"taskExecuteTimeMs":2283166} - Progress: {"my-partition-0(backlog): 100","my-partition-1(backlog): 0"} -ReasonOfStateChanged: - ErrorLogUrls: - OtherMsg: -1 row in set (0.00 sec) -``` - -### 检查导入任务 - -执行 [SHOW ROUTINE LOAD TASK](../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD_TASK.md) 语句以检查导入作业 `routine_wiki_edit_1` 的导入任务，例如有多少任务正在运行、正在消费的 Kafka Topic 分区以及消费进度 `DataSourceProperties`，以及相应的 Coordinator BE 节点 `BeId`。 - -```SQL -MySQL [example_db]> SHOW ROUTINE LOAD TASK WHERE JobName = "routine_wiki_edit_1" \G -``` - -## 修改导入作业 - -在修改导入作业之前，必须使用 [PAUSE ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/PAUSE_ROUTINE_LOAD.md) 语句暂停它。然后，您可以执行 [ALTER ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/ALTER_ROUTINE_LOAD.md)。修改后，您可以执行 [RESUME ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/RESUME_ROUTINE_LOAD.md) 语句以恢复它，并使用 [SHOW ROUTINE LOAD](../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD.md) 语句检查其状态。 - -当 Routine Load 用于从 Pulsar 消费数据时，除了 `data_source_properties` 之外，大多数返回的参数与从 Kafka 消费数据时相同。 - -**请注意以下几点**： - -- 在与 `data_source_properties` 相关的参数中，目前仅支持修改 `pulsar_partitions`、`pulsar_initial_positions` 和自定义 Pulsar 参数 `property.pulsar_default_initial_position` 和 `property.auth.token`。参数 `pulsar_service_url`、`pulsar_topic` 和 `pulsar_subscription` 无法修改。 -- 如果您需要修改要消费的分区和匹配的初始位置，则需要确保在创建 Routine Load 作业时使用 `pulsar_partitions` 指定分区，并且只能修改指定分区的初始位置 `pulsar_initial_positions`。 -- 如果您在创建 Routine Load 作业时仅指定 Topic `pulsar_topic`，而不指定分区 `pulsar_partitions`，则可以通过 `pulsar_default_initial_position` 修改 Topic 下所有分区的起始位置。 \ No newline at end of file diff --git a/docs/zh/loading/loading.mdx b/docs/zh/loading/loading.mdx deleted file mode 100644 index 6a837cd..0000000 --- a/docs/zh/loading/loading.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 数据导入 - -import DocCardList from '@theme/DocCardList'; - - \ No newline at end of file diff --git a/docs/zh/loading/loading_introduction/feature-support-loading-and-unloading.md b/docs/zh/loading/loading_introduction/feature-support-loading-and-unloading.md deleted file mode 100644 index d8320e9..0000000 --- a/docs/zh/loading/loading_introduction/feature-support-loading-and-unloading.md +++ /dev/null @@ -1,632 +0,0 @@ ---- -displayed_sidebar: docs -sidebar_label: "Feature Support" ---- - -# 功能支持：数据导入和导出 - -本文档概述了 StarRocks 支持的各种数据导入和导出方法的功能。 - -## 文件格式 - -### 导入文件格式 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Data SourceFile Format
CSVJSON [3]ParquetORCAvroProtoBufThrift
Stream LoadLocal file systems, applications, connectorsYesYesTo be supportedTo be supportedTo be supported
INSERT from FILESHDFS, S3, OSS, Azure, GCS, NFS(NAS) [5]Yes (v3.3+)To be supportedYes (v3.1+)Yes (v3.1+)Yes (v3.4.4+)To be supported
Broker LoadYesYes (v3.2.3+)YesYesTo be supported
Routine LoadKafkaYesYesTo be supportedTo be supportedYes (v3.0+) [1]To be supportedTo be supported
Spark LoadYesTo be supportedYesYesTo be supported
ConnectorsFlink, SparkYesYesTo be supportedTo be supportedTo be supported
Kafka Connector [2]KafkaYes (v3.0+)To be supportedTo be supportedYes (v3.0+)To be supported
PIPE [4]Consistent with INSERT from FILES
- -:::note - -[1], [2]\: Schema Registry is required. - -[3]\: JSON 支持多种 CDC 格式。有关 StarRocks 支持的 JSON CDC 格式的详细信息，请参见 [JSON CDC format](#json-cdc-formats)。 - -[4]\: 目前，仅 INSERT from FILES 支持使用 PIPE 进行导入。 - -[5]\: 您需要将 NAS 设备作为 NFS 挂载在每个 BE 或 CN 节点的相同目录下，才能通过 `file://` 协议访问 NFS 中的文件。 - -::: - -#### JSON CDC formats - - - - - - - - - - - - - - - - - - - - - - - - - -
Stream LoadRoutine LoadBroker LoadINSERT from FILESKafka Connector [1]
DebeziumTo be supportedTo be supportedTo be supportedTo be supportedYes (v3.0+)
CanalTo be supported
Maxwell
- -:::note - -[1]\: 将 Debezium CDC 格式数据导入到 StarRocks 的主键表时，必须配置 `transforms` 参数。 - -::: - -### 导出文件格式 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TargetFile format
Table formatRemote storageCSVJSONParquetORC
INSERT INTO FILESN/AHDFS, S3, OSS, Azure, GCS, NFS(NAS) [3]Yes (v3.3+)To be supportedYes (v3.2+)Yes (v3.3+)
INSERT INTO CatalogHiveHDFS, S3, OSS, Azure, GCSYes (v3.3+)To be supportedYes (v3.2+)Yes (v3.3+)
IcebergHDFS, S3, OSS, Azure, GCSTo be supportedTo be supportedYes (v3.2+)To be supported
Hudi/DeltaTo be supported
EXPORTN/AHDFS, S3, OSS, Azure, GCSYes [1]To be supportedTo be supportedTo be supported
PIPETo be supported [2]
- -:::note - -[1]\: Configuring Broker process is supported. - -[2]\: Currently, unloading data using PIPE is not supported. - -[3]\: 您需要将 NAS 设备作为 NFS 挂载在每个 BE 或 CN 节点的相同目录下，才能通过 `file://` 协议访问 NFS 中的文件。 - -::: - -## 文件格式相关参数 - -### 导入文件格式相关参数 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
File formatParameterLoading method
Stream LoadINSERT from FILESBroker LoadRoutine LoadSpark Load
CSVcolumn_separatorYesYes (v3.3+)Yes [1]
row_delimiterYesYes [2] (v3.1+)Yes [3] (v2.2+)To be supported
encloseYes (v3.0+)Yes (v3.0+)Yes (v3.0+)To be supported
escape
skip_headerTo be supported
trim_spaceYes (v3.0+)
JSONjsonpathsYesTo be supportedYes (v3.2.3+)YesTo be supported
strip_outer_array
json_root
ignore_json_sizeTo be supported
- -:::note - -[1]\: 对应的参数是 `COLUMNS TERMINATED BY`。 - -[2]\: 对应的参数是 `ROWS TERMINATED BY`。 - -[3]\: 对应的参数是 `ROWS TERMINATED BY`。 - -::: - -### 导出文件格式相关参数 - - - - - - - - - - - - - - - - - - - - -
File formatParameterUnloading method
INSERT INTO FILESEXPORT
CSVcolumn_separatorYes (v3.3+)Yes
line_delimiter [1]
- -:::note - -[1]\: 数据导入中对应的参数是 `row_delimiter`。 - -::: - -## 压缩格式 - -### 导入压缩格式 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
File formatCompression formatLoading method
Stream LoadBroker LoadINSERT from FILESRoutine LoadSpark Load
CSV -
    -
  • deflate
    • -
  • bzip2
    • -
  • gzip
    • -
  • lz4_frame
    • -
  • zstd
    • -
- 		Yes [1]Yes [2]To be supportedTo be supportedTo be supported
JSONYes (v3.2.7+) [3]To be supportedN/ATo be supportedN/A
Parquet -
    -
  • gzip
    • -
  • lz4
    • -
  • snappy
    • -
  • zlib
    • -
  • zstd
    • -
- 		N/AYes [4]To be supportedYes [4]
ORC
- -:::note - -[1]\: 目前，仅当使用 Stream Load 导入 CSV 文件时，才能使用 `format=gzip` 指定压缩格式，表示 gzip 压缩的 CSV 文件。`deflate` 和 `bzip2` 格式也支持。 - -[2]\: Broker Load 不支持使用参数 `format` 指定 CSV 文件的压缩格式。Broker Load 通过文件的后缀名来识别压缩格式。gzip 压缩文件的后缀名为 `.gz`，zstd 压缩文件的后缀名为 `.zst`。此外，不支持其他与 `format` 相关的参数，例如 `trim_space` 和 `enclose`。 - -[3]\: 支持使用 `compression = gzip` 指定压缩格式。 - -[4]\: 由 Arrow Library 支持。您无需配置 `compression` 参数。 - -::: - -### 导出压缩格式 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
File formatCompression formatUnloading method
INSERT INTO FILESINSERT INTO CatalogEXPORT
HiveIcebergHudi/Delta
CSV -
    -
  • deflate
    • -
  • bzip2
    • -
  • gzip
    • -
  • lz4_frame
    • -
  • zstd
    • -
- 		To be supportedTo be supportedTo be supportedTo be supportedTo be supported
JSONN/AN/AN/AN/AN/AN/A
Parquet -
    -
  • gzip
    • -
  • lz4
    • -
  • snappy
    • -
  • zstd
    • -
- 		Yes (v3.2+)Yes (v3.2+)Yes (v3.2+)To be supportedN/A
ORC
- -## 凭据 - -### 导入 - 身份验证 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
AuthenticationLoading method
Stream LoadINSERT from FILESBroker LoadRoutine LoadExternal Catalog
Single KerberosN/AYes (v3.1+)Yes [1] (versions earlier than v2.5)Yes [2] (v3.1.4+)Yes
Kerberos Ticket Granting Ticket (TGT)N/ATo be supportedYes (v3.1.10+/v3.2.1+)
Single KDC Multiple KerberosN/A
Basic access authentications (Access Key pair, IAM Role)N/AYes (HDFS and S3-compatible object storage)Yes [3]Yes
- -:::note - -[1]\: 对于 HDFS，StarRocks 支持简单身份验证和 Kerberos 身份验证。 - -[2]\: 当安全协议设置为 `sasl_plaintext` 或 `sasl_ssl` 时，支持 SASL 和 GSSAPI (Kerberos) 身份验证。 - -[3]\: 当安全协议设置为 `sasl_plaintext` 或 `sasl_ssl` 时，支持 SASL 和 PLAIN 身份验证。 - -::: - -### 导出 - 身份验证 - -| | INSERT INTO FILES | EXPORT | -| :-------------- | :----------------: | :-------------: | -| Single Kerberos | To be supported | To be supported | - -## 导入 - 其他参数和功能 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Parameter and featureLoading method
Stream LoadINSERT from FILESINSERT from SELECT/VALUESBroker LoadPIPERoutine LoadSpark Load
partial_updateYes (v3.0+)Yes [1] (v3.3+)Yes (v3.0+)N/AYes (v3.0+)To be supported
partial_update_modeYes (v3.1+)To be supportedYes (v3.1+)N/ATo be supportedTo be supported
COLUMNS FROM PATHN/AYes (v3.2+)N/AYesN/AN/AYes
timezone or session variable time_zone [2]Yes [3]Yes [4]Yes [4]Yes [4]To be supportedYes [4]To be supported
Time accuracy - MicrosecondYesYesYesYes (v3.1.11+/v3.2.6+)To be supportedYesYes
- -:::note - -[1]\: 从 v3.3 开始，StarRocks 支持在行模式下通过指定列列表对 INSERT INTO 进行部分更新。 - -[2]\: 通过参数或会话变量设置时区会影响 strftime()、alignment_timestamp() 和 from_unixtime() 等函数返回的结果。 - -[3]\: 仅支持参数 `timezone`。 - -[4]\: 仅支持会话变量 `time_zone`。 - -::: - -## 导出 - 其他参数和功能 - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Parameter and featureINSERT INTO FILESEXPORT
target_max_file_sizeYes (v3.2+)To be supported
single
Partitioned_by
Session variable time_zoneTo be supported
Time accuracy - MicrosecondTo be supportedTo be supported
\ No newline at end of file diff --git a/docs/zh/loading/loading_introduction/loading_concepts.md b/docs/zh/loading/loading_introduction/loading_concepts.md deleted file mode 100644 index 0bbd53d..0000000 --- a/docs/zh/loading/loading_introduction/loading_concepts.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -displayed_sidebar: docs -toc_max_heading_level: 4 ---- - -# 数据导入概念 - -import InsertPrivNote from '../../_assets/commonMarkdown/insertPrivNote.mdx' - -本文介绍数据导入相关的常用概念和信息。 - -## 权限 - - - -## Label - -您可以通过运行数据导入作业将数据导入到 StarRocks 中。每个数据导入作业都有一个唯一的 label。该 label 由用户指定或由 StarRocks 自动生成，用于标识该作业。每个 label 只能用于一个数据导入作业。数据导入作业完成后，其 label 不能用于任何其他数据导入作业。只有失败的数据导入作业的 label 才能被重复使用。 - -## 原子性 - -StarRocks 提供的所有数据导入方法都保证原子性。原子性是指一个数据导入作业中，所有符合条件的数据必须全部成功导入，或者全部不成功导入。不会出现部分符合条件的数据被导入，而其他数据没有被导入的情况。请注意，符合条件的数据不包括由于数据质量问题（如数据类型转换错误）而被过滤掉的数据。 - -## 协议 - -StarRocks 支持两种可用于提交数据导入作业的通信协议：MySQL 和 HTTP。在 StarRocks 支持的所有数据导入方法中，只有 Stream Load 使用 HTTP，而所有其他方法都使用 MySQL。 - -## 数据类型 - -StarRocks 支持导入所有数据类型的数据。您只需要注意一些特定数据类型导入的限制。更多信息，请参见 [数据类型](../../sql-reference/data-types/README.md)。 - -## 严格模式 - -严格模式是您可以为数据导入配置的可选属性。它会影响数据导入的行为和最终导入的数据。详情请参见 [严格模式](../load_concept/strict_mode.md)。 - -## 导入模式 - -StarRocks 支持两种数据导入模式：同步导入模式和异步导入模式。 - -:::note - -如果您使用外部程序导入数据，您必须在选择数据导入方法之前，选择最适合您业务需求的导入模式。 - -::: - -### 同步导入 - -在同步导入模式下，提交数据导入作业后，StarRocks 会同步运行该作业以导入数据，并在作业完成后返回作业结果。您可以根据作业结果检查作业是否成功。 - -StarRocks 提供了两种支持同步导入的数据导入方法：[Stream Load](../StreamLoad.md) 和 [INSERT](../InsertInto.md)。 - -同步导入的流程如下： - -1. 创建一个数据导入作业。 - -2. 查看 StarRocks 返回的作业结果。 - -3. 根据作业结果检查作业是否成功。如果作业结果表明导入失败，您可以重试该作业。 - -### 异步导入 - -在异步导入模式下，提交数据导入作业后，StarRocks 会立即返回作业创建结果。 - -- 如果结果表明作业创建成功，StarRocks 会异步运行该作业。但这并不意味着数据已成功导入。您必须使用语句或命令来检查作业的状态。然后，您可以根据作业状态确定数据是否已成功导入。 - -- 如果结果表明作业创建失败，您可以根据失败信息确定是否需要重试该作业。 - -:::tip - -您可以为表设置不同的写入仲裁，即在 StarRocks 确定数据导入任务成功之前，需要有多少个副本返回数据导入成功。您可以通过在 [CREATE TABLE](../../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE.md) 时添加属性 `write_quorum` 来指定写入仲裁，或者使用 [ALTER TABLE](../../sql-reference/sql-statements/table_bucket_part_index/ALTER_TABLE.md) 将此属性添加到现有表中。 - -::: - -StarRocks 提供了四种支持异步导入的数据导入方法：[Broker Load](../../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)、[Pipe](../../sql-reference/sql-statements/loading_unloading/pipe/CREATE_PIPE.md)、[Routine Load](../../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md) 和 [Spark Load](../../sql-reference/sql-statements/loading_unloading/SPARK_LOAD.md)。 - -异步导入的流程如下： - -1. 创建一个数据导入作业。 - -2. 查看 StarRocks 返回的作业创建结果，并确定作业是否成功创建。 - - - 如果作业创建成功，请转到步骤 3。 - - - 如果作业创建失败，请返回到步骤 1。 - -3. 使用语句或命令检查作业的状态，直到作业状态显示为 **FINISHED** 或 **CANCELLED**。 - -#### Broker Load 或 Spark Load 的工作流程 - -Broker Load 或 Spark Load 作业的工作流程包括五个阶段，如下图所示。 - -![Broker Load or Spark Load overflow](../../_assets/4.1-1.png) - -工作流程描述如下： - -1. **PENDING** - - 作业在队列中等待 FE 调度。 - -2. **ETL** - - FE 预处理数据，包括数据清洗、分区、排序和聚合。 - - 只有 Spark Load 作业有 ETL 阶段。Broker Load 作业跳过此阶段。 - -3. **LOADING** - - FE 清洗和转换数据，然后将数据发送到 BE 或 CN。加载完所有数据后，数据在队列中等待生效。此时，作业的状态保持为 **LOADING**。 - -4. **FINISHED** - - 当数据导入完成并且所有涉及的数据生效时，作业的状态变为 **FINISHED**。此时，可以查询数据。**FINISHED** 是最终作业状态。 - -5. **CANCELLED** - - 在作业的状态变为 **FINISHED** 之前，您可以随时取消该作业。此外，如果发生数据导入错误，StarRocks 可以自动取消该作业。作业取消后，作业的状态变为 **CANCELLED**，并且在取消之前所做的所有数据更新都将被还原。**CANCELLED** 也是最终作业状态。 - -#### Pipe 的工作流程 - -Pipe 作业的工作流程描述如下： - -1. 从 MySQL 客户端将作业提交到 FE。 - -2. FE 根据指定路径中存储的数据文件的数量或大小拆分数据文件，将作业分解为更小的顺序任务。任务进入队列，等待调度，创建后。 - -3. FE 从队列中获取任务，并调用 INSERT INTO SELECT FROM FILES 语句来执行每个任务。 - -4. 数据导入完成： - - - 如果在作业创建时为作业指定了 `"AUTO_INGEST" = "FALSE"`，则在加载完指定路径中存储的所有数据文件的数据后，作业将完成。 - - - 如果在作业创建时为作业指定了 `"AUTO_INGEST" = "TRUE"`，则 FE 将继续监视数据文件的更改，并自动将数据文件中的新数据或更新数据加载到目标 StarRocks 表中。 - -#### Routine Load 的工作流程 - -Routine Load 作业的工作流程描述如下： - -1. 从 MySQL 客户端将作业提交到 FE。 - -2. FE 将作业拆分为多个任务。每个任务都设计为从多个分区加载数据。 - -3. FE 将任务分发到指定的 BE 或 CN。 - -4. BE 或 CN 执行任务，并在完成任务后向 FE 报告。 - -5. FE 生成后续任务，重试失败的任务（如果有），或根据 BE 的报告暂停任务调度。 \ No newline at end of file diff --git a/docs/zh/loading/loading_introduction/loading_considerations.md b/docs/zh/loading/loading_introduction/loading_considerations.md deleted file mode 100644 index 022aa34..0000000 --- a/docs/zh/loading/loading_introduction/loading_considerations.md +++ /dev/null @@ -1,73 +0,0 @@ -### 注意事项 - -本文档介绍在运行数据导入作业之前需要考虑的一些系统限制和配置。 - -## 内存限制 - -StarRocks 提供了参数来限制每个导入作业的内存使用量，从而减少内存消耗，尤其是在高并发场景下。但是，不要指定过低的内存使用量限制。如果内存使用量限制过低，则可能因为导入作业的内存使用量达到指定限制，导致数据频繁地从内存刷新到磁盘。建议您根据您的业务场景指定合适的内存使用量限制。 - -用于限制内存使用量的参数因每种导入方式而异。更多信息，请参见 [Stream Load](../../sql-reference/sql-statements/loading_unloading/STREAM_LOAD.md)、[Broker Load](../../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)、[Routine Load](../../sql-reference/sql-statements/loading_unloading/routine_load/CREATE_ROUTINE_LOAD.md)、[Spark Load](../../sql-reference/sql-statements/loading_unloading/SPARK_LOAD.md) 和 [INSERT](../../sql-reference/sql-statements/loading_unloading/INSERT.md)。请注意，一个导入作业通常在多个 BE 或 CN 上运行。因此，这些参数限制的是每个导入作业在每个涉及的 BE 或 CN 上的内存使用量，而不是导入作业在所有涉及的 BE 或 CN 上的总内存使用量。 - -StarRocks 还提供了参数来限制每个 BE 或 CN 上运行的所有导入作业的总内存使用量。更多信息，请参见下面的“[系统配置](#system-configurations)”部分。 - -## 系统配置 - -本节介绍一些适用于 StarRocks 提供的所有导入方法的参数配置。 - -### FE 配置 - -您可以在每个 FE 的配置文件 **fe.conf** 中配置以下参数： - -- `max_load_timeout_second` 和 `min_load_timeout_second` - - 这些参数指定每个导入作业的最大超时时间和最小超时时间。超时时间以秒为单位。默认的最大超时时间为 3 天，默认的最小超时时间为 1 秒。您指定的最大超时时间和最小超时时间必须在 1 秒到 3 天的范围内。这些参数对同步导入作业和异步导入作业都有效。 - -- `desired_max_waiting_jobs` - - 此参数指定队列中可以等待的最大导入作业数。默认值为 **1024**（v2.4 及更早版本中为 100，v2.5 及更高版本中为 1024）。当 FE 上处于 **PENDING** 状态的导入作业数达到您指定的最大数量时，FE 将拒绝新的导入请求。此参数仅对异步导入作业有效。 - -- `max_running_txn_num_per_db` - - 此参数指定您的 StarRocks 集群的每个数据库中允许的最大并发导入事务数。一个导入作业可以包含一个或多个事务。默认值为 **100**。当数据库中运行的导入事务数达到您指定的最大数量时，您提交的后续导入作业将不会被调度。在这种情况下，如果您提交的是同步导入作业，则该作业将被拒绝。如果您提交的是异步导入作业，则该作业将在队列中等待。 - - :::note - - StarRocks 将所有导入作业一起计数，不区分同步导入作业和异步导入作业。 - - ::: - -- `label_keep_max_second` - - 此参数指定已完成且处于 **FINISHED** 或 **CANCELLED** 状态的导入作业的历史记录的保留期限。默认保留期限为 3 天。此参数对同步导入作业和异步导入作业都有效。 - -### BE/CN 配置 - -您可以在每个 BE 的配置文件 **be.conf** 或每个 CN 的配置文件 **cn.conf** 中配置以下参数： - -- `write_buffer_size` - - 此参数指定最大内存块大小。默认大小为 100 MB。导入的数据首先写入 BE 或 CN 上的内存块。当导入的数据量达到您指定的最大内存块大小时，数据将刷新到磁盘。您必须根据您的业务场景指定合适的内存块大小。 - - - 如果最大内存块大小过小，则可能在 BE 或 CN 上生成大量小文件。在这种情况下，[查询性能] 会下降。您可以增加最大内存块大小以减少生成的文件数。 - - 如果最大内存块大小过大，则远程过程调用 (RPC) 可能会超时。在这种情况下，您可以根据您的业务需求调整此参数的值。 - -- `streaming_load_rpc_max_alive_time_sec` - - 每个 Writer 进程的等待超时时间。默认值为 1200 秒。在数据导入过程中，StarRocks 启动一个 Writer 进程来接收数据并将数据写入每个 tablet。如果在您指定的等待超时时间内，Writer 进程没有收到任何数据，StarRocks 将停止该 Writer 进程。当您的 StarRocks 集群以低速处理数据时，Writer 进程可能在很长一段时间内没有收到下一批数据，因此报告“TabletWriter add batch with unknown id”错误。在这种情况下，您可以增加此参数的值。 - -- `load_process_max_memory_limit_bytes` 和 `load_process_max_memory_limit_percent` - - 这些参数指定每个 BE 或 CN 上所有导入作业可以消耗的最大内存量。StarRocks 将这两个参数值中较小的内存消耗量确定为允许的最终内存消耗量。 - - - `load_process_max_memory_limit_bytes`: 指定最大内存大小。默认最大内存大小为 100 GB。 - - `load_process_max_memory_limit_percent`: 指定最大内存使用率。默认值为 30%。此参数与 `mem_limit` 参数不同。`mem_limit` 参数指定您的 StarRocks 集群的总最大内存使用量，默认值为 90% x 90%。 - - 如果 BE 或 CN 所在的机器的内存容量为 M，则可以为导入作业消耗的最大内存量计算如下：`M x 90% x 90% x 30%`。 - -### 系统变量配置 - -您可以配置以下 [系统变量](../../sql-reference/System_variable.md)： - -- `insert_timeout` - - INSERT 超时时间。单位：秒。取值范围：`1` 到 `259200`。默认值：`14400`。此变量将作用于当前连接中所有涉及 INSERT 作业的操作（例如，UPDATE、DELETE、CTAS、物化视图刷新、统计信息收集和 PIPE）。 \ No newline at end of file diff --git a/docs/zh/loading/loading_introduction/loading_overview.mdx b/docs/zh/loading/loading_introduction/loading_overview.mdx deleted file mode 100644 index 551ea6c..0000000 --- a/docs/zh/loading/loading_introduction/loading_overview.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 数据导入概览 - -import DocCardList from '@theme/DocCardList'; - - \ No newline at end of file diff --git a/docs/zh/loading/loading_introduction/troubleshooting_loading.md b/docs/zh/loading/loading_introduction/troubleshooting_loading.md deleted file mode 100644 index 93d173b..0000000 --- a/docs/zh/loading/loading_introduction/troubleshooting_loading.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -displayed_sidebar: docs -sidebar_label: "Troubleshooting" ---- - -# 数据导入问题排查 - -本文档旨在帮助DBA和运维工程师通过SQL界面监控数据导入作业的状态，而无需依赖外部监控系统。同时，本文档还提供了在导入操作期间识别性能瓶颈和排除异常情况的指导。 - -## 术语 - -**导入作业 (Load Job):** 连续的数据导入过程，例如 **Routine Load Job** 或 **Pipe Job**。 - -**导入任务 (Load Task):** 一次性的数据导入过程，通常对应于单个导入事务。例如 **Broker Load**、**Stream Load**、**Spark Load** 和 **INSERT INTO**。Routine Load 作业和 Pipe 作业会持续生成任务以执行数据摄取。 - -## 观察导入作业 - -有两种方法可以观察导入作业： - -- 使用 SQL 语句 **[SHOW ROUTINE LOAD](../../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD.md)** 和 **[SHOW PIPES](../../sql-reference/sql-statements/loading_unloading/pipe/SHOW_PIPES.md)**。 -- 使用系统视图 **[information_schema.routine_load_jobs](../../sql-reference/information_schema/routine_load_jobs.md)** 和 **[information_schema.pipes](../../sql-reference/information_schema/pipes.md)**。 - -## 观察导入任务 - -也可以通过两种方式监控导入任务： - -- 使用 SQL 语句 **[SHOW LOAD](../../sql-reference/sql-statements/loading_unloading/SHOW_LOAD.md)** 和 **[SHOW ROUTINE LOAD TASK](../../sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD_TASK.md)**。 -- 使用系统视图 **[information_schema.loads](../../sql-reference/information_schema/loads.md)** 和 statistics.loads_history。 - -### SQL 语句 - -**SHOW** 语句显示当前数据库正在进行和最近完成的导入任务，从而快速了解任务状态。检索到的信息是 **statistics.loads_history** 系统视图的子集。 - -SHOW LOAD 语句返回 Broker Load、Insert Into 和 Spark Load 任务的信息，SHOW ROUTINE LOAD TASK 语句返回 Routine Load 任务的信息。 - -### 系统视图 - -#### information_schema.loads - -**information_schema.loads** 系统视图存储最近的导入任务的信息，包括正在进行和最近完成的任务。StarRocks 定期将数据同步到 **statistics.loads_history** 系统表以进行持久存储。 - -**information_schema.loads** 提供以下字段： - -| 字段 (Field) | 描述 (Description) \ No newline at end of file diff --git a/docs/zh/loading/loading_tools.md b/docs/zh/loading/loading_tools.md deleted file mode 100644 index 8613965..0000000 --- a/docs/zh/loading/loading_tools.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -displayed_sidebar: docs ---- - -# 使用工具导入数据 - -StarRocks 及其生态系统合作伙伴提供以下工具，以帮助您将 StarRocks 与外部数据库无缝集成。 - -## [SMT](../integrations/loading_tools/SMT.md) - -SMT (StarRocks Migration Tool) 是 StarRocks 提供的数据迁移工具，旨在优化复杂的数据导入管道：源数据库（如 MySQL、Oracle、PostgreSQL）---> Flink ---> 目标 StarRocks 集群。其主要功能如下： - -- 简化 StarRocks 中的表创建：基于外部数据库和目标 StarRocks 集群的信息，生成在 StarRocks 中创建表的语句。 -- 简化数据管道中的全量或增量数据同步过程：生成可在 Flink 的 SQL 客户端中运行的 SQL 语句，以提交 Flink 作业来同步数据。 - -下图说明了通过 Flink 将数据从源数据库 MySQL 导入到 StarRocks 的过程。 - -![img](../_assets/load_tools.png) - -## [DataX](../integrations/loading_tools/DataX-starrocks-writer.md) - -DataX 是一款离线数据同步工具，由阿里巴巴开源。 DataX 可以同步各种异构数据源之间的数据，包括关系数据库（MySQL、Oracle 等）、HDFS 和 Hive。 DataX 提供了 StarRocks Writer 插件，用于将 DataX 支持的数据源中的数据同步到 StarRocks。 - -## [CloudCanal](../integrations/loading_tools/CloudCanal.md) - -CloudCanal 社区版是由 [ClouGence Co., Ltd](https://www.cloudcanalx.com/) 发布的免费数据迁移和同步平台，集成了 Schema Migration、全量数据迁移、验证、纠正和实时增量同步。 您可以直接在 CloudCanal 的可视化界面中添加 StarRocks 作为数据源，并创建任务以自动将数据从源数据库（例如，MySQL、Oracle、PostgreSQL）迁移或同步到 StarRocks。 - -## [Kettle connector](https://github.com/StarRocks/starrocks-connector-for-kettle) - -Kettle 是一款具有可视化图形界面的 ETL (Extract, Transform, Load) 工具，允许用户通过拖动组件和配置参数来构建数据处理工作流程。 这种直观的方法大大简化了数据处理和导入的过程，使用户能够更方便地处理数据。 此外，Kettle 提供了丰富的组件库，允许用户根据需要选择合适的组件并执行各种复杂的数据处理任务。 - -StarRocks 提供 Kettle Connector 以与 Kettle 集成。 通过将 Kettle 强大的数据处理和转换能力与 StarRocks 的高性能数据存储和分析能力相结合，可以实现更灵活、更高效的数据处理工作流程。 \ No newline at end of file diff --git a/docs/zh/loading/minio.md b/docs/zh/loading/minio.md deleted file mode 100644 index 94887e6..0000000 --- a/docs/zh/loading/minio.md +++ /dev/null @@ -1,717 +0,0 @@ ---- -displayed_sidebar: docs -toc_max_heading_level: 4 ---- - -# 从 MinIO 导入数据 - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -StarRocks 提供了以下从 MinIO 导入数据的选项： - -- 使用 [INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md) + [`FILES()`](../sql-reference/sql-functions/table-functions/files.md) 进行同步导入 -- 使用 [Broker Load](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md) 进行异步导入 - -这些选项各有优势，以下各节将详细介绍。 - -在大多数情况下，我们建议您使用 INSERT+`FILES()` 方法，因为它更易于使用。 - -但是，INSERT+`FILES()` 方法目前仅支持 Parquet、ORC 和 CSV 文件格式。因此，如果您需要导入其他文件格式（如 JSON）的数据，或者[在数据导入期间执行数据更改（如 DELETE）](../loading/Load_to_Primary_Key_tables.md)，您可以选择使用 Broker Load。 - -## 前提条件 - -### 准备源数据 - -确保要导入到 StarRocks 中的源数据已正确存储在 MinIO bucket 中。您还可以考虑数据和数据库的位置，因为当您的 bucket 和 StarRocks 集群位于同一区域时，数据传输成本会低得多。 - -在本主题中，我们为您提供了一个示例数据集。您可以使用 `curl` 下载它： - -```bash -curl -O https://starrocks-examples.s3.amazonaws.com/user_behavior_ten_million_rows.parquet -``` - -将 Parquet 文件导入到您的 MinIO 系统中，并记下 bucket 名称。本指南中的示例使用 `/starrocks` 作为 bucket 名称。 - -### 检查权限 - - - -### 收集连接详细信息 - -简而言之，要使用 MinIO Access Key 身份验证，您需要收集以下信息： - -- 存储数据的 bucket -- 对象 key（对象名称）（如果访问 bucket 中的特定对象） -- MinIO endpoint -- 用作访问凭据的 access key 和 secret key。 - -![MinIO access key](../_assets/quick-start/MinIO-create.png) - -## 使用 INSERT+FILES() - -此方法从 v3.1 版本开始可用，目前仅支持 Parquet、ORC 和 CSV（从 v3.3.0 版本开始）文件格式。 - -### INSERT+FILES() 的优势 - -[`FILES()`](../sql-reference/sql-functions/table-functions/files.md) 可以读取存储在云存储中的文件，基于您指定的路径相关属性，推断文件中数据的表结构，然后将文件中的数据作为数据行返回。 - -使用 `FILES()`，您可以： - -- 使用 [SELECT](../sql-reference/sql-statements/table_bucket_part_index/SELECT.md) 直接从 MinIO 查询数据。 -- 使用 [CREATE TABLE AS SELECT](../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_AS_SELECT.md) (CTAS) 创建和导入表。 -- 使用 [INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md) 将数据导入到现有表中。 - -### 典型示例 - -#### 使用 SELECT 直接从 MinIO 查询 - -使用 SELECT+`FILES()` 直接从 MinIO 查询可以在创建表之前很好地预览数据集的内容。例如： - -- 在不存储数据的情况下获取数据集的预览。 -- 查询最小值和最大值，并确定要使用的数据类型。 -- 检查 `NULL` 值。 - -以下示例查询先前添加到您的 MinIO 系统的示例数据集。 - -:::tip - -命令中突出显示的部分包含您可能需要更改的设置： - -- 设置 `endpoint` 和 `path` 以匹配您的 MinIO 系统。 -- 如果您的 MinIO 系统使用 SSL，请将 `enable_ssl` 设置为 `true`。 -- 将您的 MinIO access key 和 secret key 替换为 `AAA` 和 `BBB`。 - -::: - -```sql -SELECT * FROM FILES -( - -- highlight-start - "aws.s3.endpoint" = "http://minio:9000", - "path" = "s3://starrocks/user_behavior_ten_million_rows.parquet", - "aws.s3.enable_ssl" = "false", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", - -- highlight-end - "format" = "parquet", - "aws.s3.use_aws_sdk_default_behavior" = "false", - "aws.s3.use_instance_profile" = "false", - "aws.s3.enable_path_style_access" = "true" -) -LIMIT 3; -``` - -系统返回以下查询结果： - -```plaintext -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 543711 | 829192 | 2355072 | pv | 2017-11-27 08:22:37 | -| 543711 | 2056618 | 3645362 | pv | 2017-11-27 10:16:46 | -| 543711 | 1165492 | 3645362 | pv | 2017-11-27 10:17:00 | -+--------+---------+------------+--------------+---------------------+ -3 rows in set (0.41 sec) -``` - -:::info - -请注意，上面返回的列名由 Parquet 文件提供。 - -::: - -#### 使用 CTAS 创建和导入表 - -这是前一个示例的延续。先前的查询包装在 CREATE TABLE AS SELECT (CTAS) 中，以使用模式推断自动执行表创建。这意味着 StarRocks 将推断表结构，创建您想要的表，然后将数据加载到表中。使用 `FILES()` 表函数和 Parquet 文件时，不需要列名和类型来创建表，因为 Parquet 格式包含列名。 - -:::note - -使用模式推断时，CREATE TABLE 的语法不允许设置副本数，因此请在创建表之前设置它。以下示例适用于具有单个副本的系统： - -```SQL -ADMIN SET FRONTEND CONFIG ('default_replication_num' = '1'); -``` - -::: - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -使用 CTAS 创建一个表，并加载先前添加到您的 MinIO 系统的示例数据集的数据。 - -:::tip - -命令中突出显示的部分包含您可能需要更改的设置： - -- 设置 `endpoint` 和 `path` 以匹配您的 MinIO 系统。 -- 如果您的 MinIO 系统使用 SSL，请将 `enable_ssl` 设置为 `true`。 -- 将您的 MinIO access key 和 secret key 替换为 `AAA` 和 `BBB`。 - -::: - -```sql -CREATE TABLE user_behavior_inferred AS -SELECT * FROM FILES -( - -- highlight-start - "aws.s3.endpoint" = "http://minio:9000", - "path" = "s3://starrocks/user_behavior_ten_million_rows.parquet", - "aws.s3.enable_ssl" = "false", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", - -- highlight-end - "format" = "parquet", - "aws.s3.use_aws_sdk_default_behavior" = "false", - "aws.s3.use_instance_profile" = "false", - "aws.s3.enable_path_style_access" = "true" -); -``` - -```plaintext -Query OK, 10000000 rows affected (3.17 sec) -{'label':'insert_a5da3ff5-9ee4-11ee-90b0-02420a060004', 'status':'VISIBLE', 'txnId':'17'} -``` - -创建表后，您可以使用 [DESCRIBE](../sql-reference/sql-statements/table_bucket_part_index/DESCRIBE.md) 查看其结构： - -```SQL -DESCRIBE user_behavior_inferred; -``` - -系统返回以下查询结果： - -```Plaintext -+--------------+------------------+------+-------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+------------------+------+-------+---------+-------+ -| UserID | bigint | YES | true | NULL | | -| ItemID | bigint | YES | true | NULL | | -| CategoryID | bigint | YES | true | NULL | | -| BehaviorType | varchar(1048576) | YES | false | NULL | | -| Timestamp | varchar(1048576) | YES | false | NULL | | -+--------------+------------------+------+-------+---------+-------+ -``` - -查询表以验证数据是否已加载到其中。示例： - -```SQL -SELECT * from user_behavior_inferred LIMIT 3; -``` - -返回以下查询结果，表明数据已成功加载： - -```Plaintext -+--------+--------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+--------+------------+--------------+---------------------+ -| 58 | 158350 | 2355072 | pv | 2017-11-27 13:06:51 | -| 58 | 158590 | 3194735 | pv | 2017-11-27 02:21:04 | -| 58 | 215073 | 3002561 | pv | 2017-11-30 10:55:42 | -+--------+--------+------------+--------------+---------------------+ -``` - -#### 使用 INSERT 导入到现有表 - -您可能想要自定义要导入的表，例如： - -- 列数据类型、nullable 设置或默认值 -- key 类型和列 -- 数据分区和分桶 - -:::tip - -创建最有效的表结构需要了解如何使用数据以及列的内容。本主题不包括表设计。有关表设计的信息，请参见 [表类型](../table_design/StarRocks_table_design.md)。 - -::: - -在此示例中，我们基于对如何查询表以及 Parquet 文件中的数据的了解来创建表。对 Parquet 文件中数据的了解可以通过直接在 MinIO 中查询文件来获得。 - -- 由于在 MinIO 中查询数据集表明 `Timestamp` 列包含与 `datetime` 数据类型匹配的数据，因此在以下 DDL 中指定了列类型。 -- 通过查询 MinIO 中的数据，您可以发现数据集中没有 `NULL` 值，因此 DDL 不会将任何列设置为 nullable。 -- 根据对预期查询类型的了解，排序键和分桶列设置为列 `UserID`。您的用例可能与此数据不同，因此您可能会决定除了 `UserID` 之外或代替 `UserID` 使用 `ItemID` 作为排序键。 - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表（我们建议该表具有与要从 MinIO 导入的 Parquet 文件相同的结构）： - -```SQL -CREATE TABLE user_behavior_declared -( - UserID int(11) NOT NULL, - ItemID int(11) NOT NULL, - CategoryID int(11) NOT NULL, - BehaviorType varchar(65533) NOT NULL, - Timestamp datetime NOT NULL -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID) -PROPERTIES -( - 'replication_num' = '1' -); -``` - -显示结构，以便您可以将其与 `FILES()` 表函数生成的推断结构进行比较： - -```sql -DESCRIBE user_behavior_declared; -``` - -```plaintext -+--------------+----------------+------+-------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+----------------+------+-------+---------+-------+ -| UserID | int | NO | true | NULL | | -| ItemID | int | NO | false | NULL | | -| CategoryID | int | NO | false | NULL | | -| BehaviorType | varchar(65533) | NO | false | NULL | | -| Timestamp | datetime | NO | false | NULL | | -+--------------+----------------+------+-------+---------+-------+ -5 rows in set (0.00 sec) -``` - -:::tip - -将您刚刚创建的结构与之前使用 `FILES()` 表函数推断的结构进行比较。查看： - -- 数据类型 -- nullable -- key 字段 - -为了更好地控制目标表的结构并获得更好的查询性能，我们建议您在生产环境中手动指定表结构。对于时间戳字段，使用 `datetime` 数据类型比使用 `varchar` 更有效。 - -::: - -创建表后，您可以使用 INSERT INTO SELECT FROM FILES() 加载它： - -:::tip - -命令中突出显示的部分包含您可能需要更改的设置： - -- 设置 `endpoint` 和 `path` 以匹配您的 MinIO 系统。 -- 如果您的 MinIO 系统使用 SSL，请将 `enable_ssl` 设置为 `true`。 -- 将您的 MinIO access key 和 secret key 替换为 `AAA` 和 `BBB`。 - -::: - -```SQL -INSERT INTO user_behavior_declared -SELECT * FROM FILES -( - -- highlight-start - "aws.s3.endpoint" = "http://minio:9000", - "path" = "s3://starrocks/user_behavior_ten_million_rows.parquet", - "aws.s3.enable_ssl" = "false", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", - -- highlight-end - "format" = "parquet", - "aws.s3.use_aws_sdk_default_behavior" = "false", - "aws.s3.use_instance_profile" = "false", - "aws.s3.enable_path_style_access" = "true" -); -``` - -加载完成后，您可以查询表以验证数据是否已加载到其中。示例： - -```SQL -SELECT * from user_behavior_declared LIMIT 3; -``` - -返回以下查询结果，表明数据已成功加载： - -```Plaintext -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 58 | 4309692 | 1165503 | pv | 2017-11-25 14:06:52 | -| 58 | 181489 | 1165503 | pv | 2017-11-25 14:07:22 | -| 58 | 3722956 | 1165503 | pv | 2017-11-25 14:09:28 | -+--------+---------+------------+--------------+---------------------+ -``` - -#### 检查导入进度 - -您可以从 StarRocks Information Schema 中的 [`loads`](../sql-reference/information_schema/loads.md) 视图查询 INSERT 作业的进度。此功能从 v3.1 版本开始支持。示例： - -```SQL -SELECT * FROM information_schema.loads ORDER BY JOB_ID DESC; -``` - -有关 `loads` 视图中提供的字段的信息，请参见 [`loads`](../sql-reference/information_schema/loads.md)。 - -如果您提交了多个导入作业，则可以按与作业关联的 `LABEL` 进行过滤。示例： - -```SQL -SELECT * FROM information_schema.loads WHERE LABEL = 'insert_e3b882f5-7eb3-11ee-ae77-00163e267b60' \G -*************************** 1. row *************************** - JOB_ID: 10243 - LABEL: insert_e3b882f5-7eb3-11ee-ae77-00163e267b60 - DATABASE_NAME: mydatabase - STATE: FINISHED - PROGRESS: ETL:100%; LOAD:100% - TYPE: INSERT - PRIORITY: NORMAL - SCAN_ROWS: 10000000 - FILTERED_ROWS: 0 - UNSELECTED_ROWS: 0 - SINK_ROWS: 10000000 - ETL_INFO: - TASK_INFO: resource:N/A; timeout(s):300; max_filter_ratio:0.0 - CREATE_TIME: 2023-11-09 11:56:01 - ETL_START_TIME: 2023-11-09 11:56:01 - ETL_FINISH_TIME: 2023-11-09 11:56:01 - LOAD_START_TIME: 2023-11-09 11:56:01 - LOAD_FINISH_TIME: 2023-11-09 11:56:44 - JOB_DETAILS: {"All backends":{"e3b882f5-7eb3-11ee-ae77-00163e267b60":[10142]},"FileNumber":0,"FileSize":0,"InternalTableLoadBytes":311710786,"InternalTableLoadRows":10000000,"ScanBytes":581574034,"ScanRows":10000000,"TaskNumber":1,"Unfinished backends":{"e3b882f5-7eb3-11ee-ae77-00163e267b60":[]}} - ERROR_MSG: NULL - TRACKING_URL: NULL - TRACKING_SQL: NULL -REJECTED_RECORD_PATH: NULL -``` - -:::tip - -INSERT 是一个同步命令。如果 INSERT 作业仍在运行，您需要打开另一个会话来检查其执行状态。 - -::: - -### 比较磁盘上的表大小 - -此查询比较具有推断结构的表和声明了结构的表。由于推断的结构具有 nullable 列和时间戳的 varchar，因此数据长度更大： - -```sql -SELECT TABLE_NAME, - TABLE_ROWS, - AVG_ROW_LENGTH, - DATA_LENGTH -FROM information_schema.tables -WHERE TABLE_NAME like 'user_behavior%'\G -``` - -```plaintext -*************************** 1. row *************************** - TABLE_NAME: user_behavior_declared - TABLE_ROWS: 10000000 -AVG_ROW_LENGTH: 10 - DATA_LENGTH: 102562516 -*************************** 2. row *************************** - TABLE_NAME: user_behavior_inferred - TABLE_ROWS: 10000000 -AVG_ROW_LENGTH: 17 - DATA_LENGTH: 176803880 -2 rows in set (0.04 sec) -``` - -## 使用 Broker Load - -异步 Broker Load 进程处理与 MinIO 的连接、提取数据以及将数据存储在 StarRocks 中。 - -此方法支持以下文件格式： - -- Parquet -- ORC -- CSV -- JSON（从 v3.2.3 版本开始支持） - -### Broker Load 的优势 - -- Broker Load 在后台运行，客户端无需保持连接即可继续作业。 -- Broker Load 更适合长时间运行的作业，默认超时时间为 4 小时。 -- 除了 Parquet 和 ORC 文件格式外，Broker Load 还支持 CSV 文件格式和 JSON 文件格式（JSON 文件格式从 v3.2.3 版本开始支持）。 - -### 数据流 - -![Broker Load 的工作流程](../_assets/broker_load_how-to-work_en.png) - -1. 用户创建一个导入作业。 -2. 前端 (FE) 创建一个查询计划，并将该计划分发到后端节点 (BE) 或计算节点 (CN)。 -3. BE 或 CN 从源提取数据，并将数据加载到 StarRocks 中。 - -### 典型示例 - -创建一个表，启动一个导入进程，该进程提取先前加载到您的 MinIO 系统的示例数据集。 - -#### 创建数据库和表 - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表（我们建议该表具有与要从 MinIO 导入的 Parquet 文件相同的结构）： - -```SQL -CREATE TABLE user_behavior -( - UserID int(11) NOT NULL, - ItemID int(11) NOT NULL, - CategoryID int(11) NOT NULL, - BehaviorType varchar(65533) NOT NULL, - Timestamp datetime NOT NULL -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID) -PROPERTIES -( - 'replication_num' = '1' -); -``` - -#### 启动 Broker Load - -运行以下命令以启动一个 Broker Load 作业，该作业将数据从示例数据集 `user_behavior_ten_million_rows.parquet` 加载到 `user_behavior` 表： - -:::tip - -命令中突出显示的部分包含您可能需要更改的设置： - -- 设置 `endpoint` 和 `DATA INFILE` 以匹配您的 MinIO 系统。 -- 如果您的 MinIO 系统使用 SSL，请将 `enable_ssl` 设置为 `true`。 -- 将您的 MinIO access key 和 secret key 替换为 `AAA` 和 `BBB`。 - -::: - -```sql -LOAD LABEL UserBehavior -( - -- highlight-start - DATA INFILE("s3://starrocks/user_behavior_ten_million_rows.parquet") - -- highlight-end - INTO TABLE user_behavior - ) - WITH BROKER - ( - -- highlight-start - "aws.s3.endpoint" = "http://minio:9000", - "aws.s3.enable_ssl" = "false", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", - -- highlight-end - "aws.s3.use_aws_sdk_default_behavior" = "false", - "aws.s3.use_instance_profile" = "false", - "aws.s3.enable_path_style_access" = "true" - ) -PROPERTIES -( - "timeout" = "72000" -); -``` - -此作业有四个主要部分： - -- `LABEL`: 用于查询导入作业状态的字符串。 -- `LOAD` 声明：源 URI、源数据格式和目标表名称。 -- `BROKER`: 源的连接详细信息。 -- `PROPERTIES`: 超时值和要应用于导入作业的任何其他属性。 - -有关详细的语法和参数说明，请参见 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -#### 检查导入进度 - -您可以从 StarRocks Information Schema 中的 [`loads`](../sql-reference/information_schema/loads.md) 视图查询 Broker Load 作业的进度。此功能从 v3.1 版本开始支持。 - -```SQL -SELECT * FROM information_schema.loads; -``` - -有关 `loads` 视图中提供的字段的信息，请参见 [`loads`](../sql-reference/information_schema/loads.md)。 - -如果您提交了多个导入作业，则可以按与作业关联的 `LABEL` 进行过滤。示例： - -```sql -SELECT * FROM information_schema.loads -WHERE LABEL = 'UserBehavior'\G -``` - -```plaintext -*************************** 1. row *************************** - JOB_ID: 10176 - LABEL: userbehavior - DATABASE_NAME: mydatabase - STATE: FINISHED - PROGRESS: ETL:100%; LOAD:100% - TYPE: BROKER - PRIORITY: NORMAL - SCAN_ROWS: 10000000 - FILTERED_ROWS: 0 - UNSELECTED_ROWS: 0 - SINK_ROWS: 10000000 - ETL_INFO: - TASK_INFO: resource:N/A; timeout(s):72000; max_filter_ratio:0.0 - CREATE_TIME: 2023-12-19 23:02:41 - ETL_START_TIME: 2023-12-19 23:02:44 - ETL_FINISH_TIME: 2023-12-19 23:02:44 - LOAD_START_TIME: 2023-12-19 23:02:44 - LOAD_FINISH_TIME: 2023-12-19 23:02:46 - JOB_DETAILS: {"All backends":{"4aeec563-a91e-4c1e-b169-977b660950d1":[10004]},"FileNumber":1,"FileSize":132251298,"InternalTableLoadBytes":311710786,"InternalTableLoadRows":10000000,"ScanBytes":132251298,"ScanRows":10000000,"TaskNumber":1,"Unfinished backends":{"4aeec563-a91e-4c1e-b169-977b660950d1":[]}} - ERROR_MSG: NULL - TRACKING_URL: NULL - TRACKING_SQL: NULL -REJECTED_RECORD_PATH: NULL -1 row in set (0.02 sec) -``` - -确认导入作业已完成后，您可以检查目标表的一个子集，以查看数据是否已成功加载。示例： - -```SQL -SELECT * from user_behavior LIMIT 3; -``` - -返回以下查询结果，表明数据已成功加载： - -```Plaintext -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 142 | 2869980 | 2939262 | pv | 2017-11-25 03:43:22 | -| 142 | 2522236 | 1669167 | pv | 2017-11-25 15:14:12 | -| 142 | 3031639 | 3607361 | pv | 2017-11-25 15:19:25 | -+--------+---------+------------+--------------+---------------------+ -``` - - \ No newline at end of file diff --git a/docs/zh/loading/objectstorage.mdx b/docs/zh/loading/objectstorage.mdx deleted file mode 100644 index b33b7d9..0000000 --- a/docs/zh/loading/objectstorage.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -displayed_sidebar: docs -description: "从 S3、GCS、Azure 和 MinIO 导入数据" ---- - -# 从对象存储导入数据 - -import DocCardList from '@theme/DocCardList'; - - \ No newline at end of file diff --git a/docs/zh/loading/s3.md b/docs/zh/loading/s3.md deleted file mode 100644 index 1878479..0000000 --- a/docs/zh/loading/s3.md +++ /dev/null @@ -1,658 +0,0 @@ ---- -displayed_sidebar: docs -toc_max_heading_level: 4 -keywords: ['Broker Load'] ---- - -# 从 AWS S3 导入数据 - -import LoadMethodIntro from '../_assets/commonMarkdown/loadMethodIntro.mdx' - -import InsertPrivNote from '../_assets/commonMarkdown/insertPrivNote.mdx' - -import PipeAdvantages from '../_assets/commonMarkdown/pipeAdvantages.mdx' - -StarRocks 提供了以下从 AWS S3 导入数据的选项： - - - -## 前提条件 - -### 准备源数据 - -确保要导入到 StarRocks 中的源数据已正确存储在 S3 bucket 中。您还可以考虑数据和数据库的位置，因为当您的 bucket 和 StarRocks 集群位于同一区域时，数据传输成本会低得多。 - -在本主题中，我们为您提供了一个 S3 bucket 中的示例数据集 `s3://starrocks-examples/user-behavior-10-million-rows.parquet`。您可以使用任何有效的凭据访问该数据集，因为任何经过 AWS 身份验证的用户都可以读取该对象。 - -### 检查权限 - - - -### 收集身份验证详细信息 - -本主题中的示例使用基于 IAM 用户的身份验证。为确保您有权从 AWS S3 读取数据，我们建议您阅读 [IAM 用户身份验证准备](../integrations/authenticate_to_aws_resources.md) 并按照说明创建一个配置了正确 [IAM policies](../sql-reference/aws_iam_policies.md) 的 IAM 用户。 - -简而言之，如果您使用基于 IAM 用户的身份验证，则需要收集有关以下 AWS 资源的信息： - -- 存储数据的 S3 bucket。 -- S3 对象键（对象名称），如果访问 bucket 中的特定对象。请注意，如果您的 S3 对象存储在子文件夹中，则对象键可以包含前缀。 -- S3 bucket 所属的 AWS 区域。 -- 用作访问凭证的访问密钥和密钥。 - -有关所有可用的身份验证方法的信息，请参阅 [向 AWS 资源进行身份验证](../integrations/authenticate_to_aws_resources.md)。 - -## 使用 INSERT+FILES() - -此方法从 v3.1 开始可用，目前仅支持 Parquet、ORC 和 CSV（从 v3.3.0 开始）文件格式。 - -### INSERT+FILES() 的优势 - -[`FILES()`](../sql-reference/sql-functions/table_functions/files.md) 可以读取存储在云存储中的文件，基于您指定的路径相关属性，推断文件中数据的表结构，然后将文件中的数据作为数据行返回。 - -使用 `FILES()`，您可以： - -- 使用 [SELECT](../sql-reference/sql-statements/table_bucket_part_index/SELECT.md) 直接从 S3 查询数据。 -- 使用 [CREATE TABLE AS SELECT](../sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE_AS_SELECT.md) (CTAS) 创建和导入表。 -- 使用 [INSERT](../sql-reference/sql-statements/loading_unloading/INSERT.md) 将数据导入到现有表中。 - -### 典型示例 - -#### 使用 SELECT 直接从 S3 查询 - -使用 SELECT+`FILES()` 直接从 S3 查询可以在创建表之前很好地预览数据集的内容。例如： - -- 在不存储数据的情况下获取数据集的预览。 -- 查询最小值和最大值，并确定要使用的数据类型。 -- 检查 `NULL` 值。 - -以下示例查询示例数据集 `s3://starrocks-examples/user-behavior-10-million-rows.parquet`： - -```SQL -SELECT * FROM FILES -( - "path" = "s3://starrocks-examples/user-behavior-10-million-rows.parquet", - "format" = "parquet", - "aws.s3.region" = "us-east-1", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" -) -LIMIT 3; -``` - -> **NOTE** -> -> 在上面的命令中，将您的凭据替换为 `AAA` 和 `BBB`。可以使用任何有效的 `aws.s3.access_key` 和 `aws.s3.secret_key`，因为任何经过 AWS 身份验证的用户都可以读取该对象。 - -系统返回以下查询结果： - -```Plaintext -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 1 | 2576651 | 149192 | pv | 2017-11-25 01:21:25 | -| 1 | 3830808 | 4181361 | pv | 2017-11-25 07:04:53 | -| 1 | 4365585 | 2520377 | pv | 2017-11-25 07:49:06 | -+--------+---------+------------+--------------+---------------------+ -``` - -> **NOTE** -> -> 请注意，上面返回的列名由 Parquet 文件提供。 - -#### 使用 CTAS 创建和导入表 - -这是前一个示例的延续。先前的查询包装在 CREATE TABLE AS SELECT (CTAS) 中，以使用模式推断自动执行表创建。这意味着 StarRocks 将推断表结构，创建您想要的表，然后将数据加载到表中。使用 `FILES()` 表函数和 Parquet 文件时，不需要列名和类型来创建表，因为 Parquet 格式包含列名。 - -> **NOTE** -> -> 使用模式推断时，CREATE TABLE 的语法不允许设置副本数，因此请在创建表之前设置它。以下示例适用于具有一个副本的系统： -> -> ```SQL -> ADMIN SET FRONTEND CONFIG ('default_replication_num' = "1"); -> ``` - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -使用 CTAS 创建一个表，并将示例数据集 `s3://starrocks-examples/user-behavior-10-million-rows.parquet` 的数据加载到该表中： - -```SQL -CREATE TABLE user_behavior_inferred AS -SELECT * FROM FILES -( - "path" = "s3://starrocks-examples/user-behavior-10-million-rows.parquet", - "format" = "parquet", - "aws.s3.region" = "us-east-1", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" -); -``` - -> **NOTE** -> -> 在上面的命令中，将您的凭据替换为 `AAA` 和 `BBB`。可以使用任何有效的 `aws.s3.access_key` 和 `aws.s3.secret_key`，因为任何经过 AWS 身份验证的用户都可以读取该对象。 - -创建表后，您可以使用 [DESCRIBE](../sql-reference/sql-statements/table_bucket_part_index/DESCRIBE.md) 查看其结构： - -```SQL -DESCRIBE user_behavior_inferred; -``` - -系统返回以下查询结果： - -```Plain -+--------------+------------------+------+-------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+------------------+------+-------+---------+-------+ -| UserID | bigint | YES | true | NULL | | -| ItemID | bigint | YES | true | NULL | | -| CategoryID | bigint | YES | true | NULL | | -| BehaviorType | varchar(1048576) | YES | false | NULL | | -| Timestamp | varchar(1048576) | YES | false | NULL | | -+--------------+------------------+------+-------+---------+-------+ -``` - -查询表以验证数据是否已加载到其中。例如： - -```SQL -SELECT * from user_behavior_inferred LIMIT 3; -``` - -返回以下查询结果，表明数据已成功加载： - -```Plaintext -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 225586 | 3694958 | 1040727 | pv | 2017-12-01 00:58:40 | -| 225586 | 3726324 | 965809 | pv | 2017-12-01 02:16:02 | -| 225586 | 3732495 | 1488813 | pv | 2017-12-01 00:59:46 | -+--------+---------+------------+--------------+---------------------+ -``` - -#### 使用 INSERT 导入到现有表 - -您可能想要自定义要插入的表，例如： - -- 列数据类型、可空设置或默认值 -- 键类型和列 -- 数据分区和分桶 - -> **NOTE** -> -> 创建最有效的表结构需要了解数据的使用方式和列的内容。本主题不涵盖表设计。有关表设计的信息，请参阅 [表类型](../table_design/StarRocks_table_design.md)。 - -在此示例中，我们基于对表将被如何查询以及 Parquet 文件中的数据的了解来创建表。对 Parquet 文件中的数据的了解可以通过直接在 S3 中查询文件来获得。 - -- 由于对 S3 中数据集的查询表明 `Timestamp` 列包含与 VARCHAR 数据类型匹配的数据，并且 StarRocks 可以从 VARCHAR 转换为 DATETIME，因此在以下 DDL 中，数据类型更改为 DATETIME。 -- 通过查询 S3 中的数据，您可以发现数据集中没有 `NULL` 值，因此 DDL 也可以将所有列设置为不可为空。 -- 根据对预期查询类型的了解，排序键和分桶列设置为列 `UserID`。您的用例可能与此数据不同，因此您可能会决定除了 `UserID` 之外或代替 `UserID` 使用 `ItemID` 作为排序键。 - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表： - -```SQL -CREATE TABLE user_behavior_declared -( - UserID int(11), - ItemID int(11), - CategoryID int(11), - BehaviorType varchar(65533), - Timestamp datetime -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID); -``` - -显示结构，以便您可以将其与 `FILES()` 表函数生成的推断结构进行比较： - -```sql -DESCRIBE user_behavior_declared; -``` - -```plaintext -+--------------+----------------+------+-------+---------+-------+ -| Field | Type | Null | Key | Default | Extra | -+--------------+----------------+------+-------+---------+-------+ -| UserID | int | YES | true | NULL | | -| ItemID | int | YES | false | NULL | | -| CategoryID | int | YES | false | NULL | | -| BehaviorType | varchar(65533) | YES | false | NULL | | -| Timestamp | datetime | YES | false | NULL | | -+--------------+----------------+------+-------+---------+-------+ -``` - -:::tip - -将您刚刚创建的结构与之前使用 `FILES()` 表函数推断的结构进行比较。查看： - -- 数据类型 -- 可空性 -- 键字段 - -为了更好地控制目标表的结构并获得更好的查询性能，我们建议您在生产环境中手动指定表结构。 - -::: - -创建表后，您可以使用 INSERT INTO SELECT FROM FILES() 加载它： - -```SQL -INSERT INTO user_behavior_declared -SELECT * FROM FILES -( - "path" = "s3://starrocks-examples/user-behavior-10-million-rows.parquet", - "format" = "parquet", - "aws.s3.region" = "us-east-1", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" -); -``` - -> **NOTE** -> -> 在上面的命令中，将您的凭据替换为 `AAA` 和 `BBB`。可以使用任何有效的 `aws.s3.access_key` 和 `aws.s3.secret_key`，因为任何经过 AWS 身份验证的用户都可以读取该对象。 - -加载完成后，您可以查询表以验证数据是否已加载到其中。例如： - -```SQL -SELECT * from user_behavior_declared LIMIT 3; -``` - -返回以下查询结果，表明数据已成功加载： - -```Plaintext -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 393529 | 3715112 | 883960 | pv | 2017-12-02 02:45:44 | -| 393529 | 2650583 | 883960 | pv | 2017-12-02 02:45:59 | -| 393529 | 3715112 | 883960 | pv | 2017-12-02 03:00:56 | -+--------+---------+------------+--------------+---------------------+ -``` - -#### 检查导入进度 - -您可以从 StarRocks Information Schema 中的 [`loads`](../sql-reference/information_schema/loads.md) 视图查询 INSERT 作业的进度。此功能从 v3.1 开始支持。例如： - -```SQL -SELECT * FROM information_schema.loads ORDER BY JOB_ID DESC; -``` - -有关 `loads` 视图中提供的字段的信息，请参阅 [`loads`](../sql-reference/information_schema/loads.md)。 - -如果您提交了多个导入作业，则可以按与该作业关联的 `LABEL` 进行过滤。例如： - -```SQL -SELECT * FROM information_schema.loads WHERE LABEL = 'insert_e3b882f5-7eb3-11ee-ae77-00163e267b60' \G -*************************** 1. row *************************** - JOB_ID: 10243 - LABEL: insert_e3b882f5-7eb3-11ee-ae77-00163e267b60 - DATABASE_NAME: mydatabase - STATE: FINISHED - PROGRESS: ETL:100%; LOAD:100% - TYPE: INSERT - PRIORITY: NORMAL - SCAN_ROWS: 10000000 - FILTERED_ROWS: 0 - UNSELECTED_ROWS: 0 - SINK_ROWS: 10000000 - ETL_INFO: - TASK_INFO: resource:N/A; timeout(s):300; max_filter_ratio:0.0 - CREATE_TIME: 2023-11-09 11:56:01 - ETL_START_TIME: 2023-11-09 11:56:01 - ETL_FINISH_TIME: 2023-11-09 11:56:01 - LOAD_START_TIME: 2023-11-09 11:56:01 - LOAD_FINISH_TIME: 2023-11-09 11:56:44 - JOB_DETAILS: {"All backends":{"e3b882f5-7eb3-11ee-ae77-00163e267b60":[10142]},"FileNumber":0,"FileSize":0,"InternalTableLoadBytes":311710786,"InternalTableLoadRows":10000000,"ScanBytes":581574034,"ScanRows":10000000,"TaskNumber":1,"Unfinished backends":{"e3b882f5-7eb3-11ee-ae77-00163e267b60":[]}} - ERROR_MSG: NULL - TRACKING_URL: NULL - TRACKING_SQL: NULL -REJECTED_RECORD_PATH: NULL -``` - -> **NOTE** -> -> INSERT 是一个同步命令。如果 INSERT 作业仍在运行，您需要打开另一个会话来检查其执行状态。 - -## 使用 Broker Load - -异步 Broker Load 进程处理与 S3 的连接、提取数据以及将数据存储在 StarRocks 中。 - -此方法支持以下文件格式： - -- Parquet -- ORC -- CSV -- JSON（从 v3.2.3 开始支持） - -### Broker Load 的优势 - -- Broker Load 在后台运行，客户端无需保持连接即可继续作业。 -- Broker Load 是长时间运行的作业的首选，默认超时时间为 4 小时。 -- 除了 Parquet 和 ORC 文件格式外，Broker Load 还支持 CSV 文件格式和 JSON 文件格式（从 v3.2.3 开始支持 JSON 文件格式）。 - -### 数据流 - -![Broker Load 的工作流程](../_assets/broker_load_how-to-work_en.png) - -1. 用户创建一个导入作业。 -2. 前端 (FE) 创建一个查询计划，并将该计划分发到后端节点 (BE) 或计算节点 (CN)。 -3. BE 或 CN 从源提取数据，并将数据加载到 StarRocks 中。 - -### 典型示例 - -创建一个表，启动一个从 S3 提取示例数据集 `s3://starrocks-examples/user-behavior-10-million-rows.parquet` 的导入进程，并验证数据导入的进度和成功。 - -#### 创建数据库和表 - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表（我们建议该表具有与您要从 AWS S3 导入的 Parquet 文件相同的结构）： - -```SQL -CREATE TABLE user_behavior -( - UserID int(11), - ItemID int(11), - CategoryID int(11), - BehaviorType varchar(65533), - Timestamp datetime -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID); -``` - -#### 启动 Broker Load - -运行以下命令以启动一个 Broker Load 作业，该作业将数据从示例数据集 `s3://starrocks-examples/user-behavior-10-million-rows.parquet` 加载到 `user_behavior` 表： - -```SQL -LOAD LABEL user_behavior -( - DATA INFILE("s3://starrocks-examples/user-behavior-10-million-rows.parquet") - INTO TABLE user_behavior - FORMAT AS "parquet" - ) - WITH BROKER - ( - "aws.s3.enable_ssl" = "true", - "aws.s3.use_instance_profile" = "false", - "aws.s3.region" = "us-east-1", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" - ) -PROPERTIES -( - "timeout" = "72000" -); -``` - -> **NOTE** -> -> 在上面的命令中，将您的凭据替换为 `AAA` 和 `BBB`。可以使用任何有效的 `aws.s3.access_key` 和 `aws.s3.secret_key`，因为任何经过 AWS 身份验证的用户都可以读取该对象。 - -此作业有四个主要部分： - -- `LABEL`：一个字符串，用于查询导入作业的状态。 -- `LOAD` 声明：源 URI、源数据格式和目标表名称。 -- `BROKER`：源的连接详细信息。 -- `PROPERTIES`：超时值和要应用于导入作业的任何其他属性。 - -有关详细的语法和参数说明，请参阅 [BROKER LOAD](../sql-reference/sql-statements/loading_unloading/BROKER_LOAD.md)。 - -#### 检查导入进度 - -您可以从 StarRocks Information Schema 中的 [`loads`](../sql-reference/information_schema/loads.md) 视图查询 Broker Load 作业的进度。此功能从 v3.1 开始支持。 - -```SQL -SELECT * FROM information_schema.loads WHERE LABEL = 'user_behavior'; -``` - -有关 `loads` 视图中提供的字段的信息，请参阅 [`loads`](../sql-reference/information_schema/loads.md)。 - -此记录显示 `LOADING` 状态，进度为 39%。如果您看到类似的内容，请再次运行该命令，直到看到 `FINISHED` 状态。 - -```Plaintext - JOB_ID: 10466 - LABEL: user_behavior - DATABASE_NAME: mydatabase - # highlight-start - STATE: LOADING - PROGRESS: ETL:100%; LOAD:39% - # highlight-end - TYPE: BROKER - PRIORITY: NORMAL - SCAN_ROWS: 4620288 - FILTERED_ROWS: 0 - UNSELECTED_ROWS: 0 - SINK_ROWS: 4620288 - ETL_INFO: - TASK_INFO: resource:N/A; timeout(s):72000; max_filter_ratio:0.0 - CREATE_TIME: 2024-02-28 22:11:36 - ETL_START_TIME: 2024-02-28 22:11:41 - ETL_FINISH_TIME: 2024-02-28 22:11:41 - LOAD_START_TIME: 2024-02-28 22:11:41 - LOAD_FINISH_TIME: NULL - JOB_DETAILS: {"All backends":{"2fb97223-b14c-404b-9be1-83aa9b3a7715":[10004]},"FileNumber":1,"FileSize":136901706,"InternalTableLoadBytes":144032784,"InternalTableLoadRows":4620288,"ScanBytes":143969616,"ScanRows":4620288,"TaskNumber":1,"Unfinished backends":{"2fb97223-b14c-404b-9be1-83aa9b3a7715":[10004]}} - ERROR_MSG: NULL - TRACKING_URL: NULL - TRACKING_SQL: NULL -REJECTED_RECORD_PATH: NULL -``` - -在确认导入作业已完成后，您可以检查目标表的子集，以查看数据是否已成功加载。例如： - -```SQL -SELECT * from user_behavior LIMIT 3; -``` - -返回以下查询结果，表明数据已成功加载： - -```Plaintext -+--------+---------+------------+--------------+---------------------+ -| UserID | ItemID | CategoryID | BehaviorType | Timestamp | -+--------+---------+------------+--------------+---------------------+ -| 34 | 856384 | 1029459 | pv | 2017-11-27 14:43:27 | -| 34 | 5079705 | 1029459 | pv | 2017-11-27 14:44:13 | -| 34 | 4451615 | 1029459 | pv | 2017-11-27 14:45:52 | -+--------+---------+------------+--------------+---------------------+ -``` - -## 使用 Pipe - -从 v3.2 开始，StarRocks 提供了 Pipe 导入方法，该方法目前仅支持 Parquet 和 ORC 文件格式。 - -### Pipe 的优势 - - - -Pipe 非常适合连续数据导入和大规模数据导入： - -- **微批次中的大规模数据导入有助于降低由数据错误引起的重试成本。** - - 借助 Pipe，StarRocks 能够高效地导入大量数据文件，这些文件总数据量很大。Pipe 根据文件的数量或大小自动拆分文件，将导入作业分解为更小的顺序任务。这种方法确保一个文件中的错误不会影响整个导入作业。每个文件的导入状态都由 Pipe 记录，使您可以轻松识别和修复包含错误的文件。通过最大限度地减少因数据错误而需要重试的情况，这种方法有助于降低成本。 - -- **连续数据导入有助于减少人力。** - - Pipe 帮助您将新的或更新的数据文件写入特定位置，并不断地将这些文件中的新数据加载到 StarRocks 中。在使用 `"AUTO_INGEST" = "TRUE"` 指定创建 Pipe 作业后，它将不断监视存储在指定路径中的数据文件的更改，并自动将数据文件中的新数据或更新的数据加载到目标 StarRocks 表中。 - -此外，Pipe 执行文件唯一性检查，以帮助防止重复数据导入。在导入过程中，Pipe 根据文件名和摘要检查每个数据文件的唯一性。如果具有特定文件名和摘要的文件已由 Pipe 作业处理，则 Pipe 作业将跳过所有后续具有相同文件名和摘要的文件。请注意，对象存储（如 AWS S3）使用 `ETag` 作为文件摘要。 - -每个数据文件的导入状态都会被记录并保存到 `information_schema.pipe_files` 视图中。在删除与该视图关联的 Pipe 作业后，有关在该作业中加载的文件的记录也将被删除。 - -### Pipe 和 INSERT+FILES() 之间的区别 - -Pipe 作业根据每个数据文件的大小和行数拆分为一个或多个事务。用户可以在导入过程中查询中间结果。相比之下，INSERT+`FILES()` 作业作为单个事务处理，用户无法在导入过程中查看数据。 - -### 文件导入顺序 - -对于每个 Pipe 作业，StarRocks 维护一个文件队列，从中提取和加载数据文件作为微批次。Pipe 不保证数据文件以与上传顺序相同的顺序加载。因此，较新的数据可能在较旧的数据之前加载。 - -### 典型示例 - -#### 创建数据库和表 - -创建一个数据库并切换到它： - -```SQL -CREATE DATABASE IF NOT EXISTS mydatabase; -USE mydatabase; -``` - -手动创建一个表（我们建议该表具有与您要从 AWS S3 导入的 Parquet 文件相同的结构）： - -```SQL -CREATE TABLE user_behavior_from_pipe -( - UserID int(11), - ItemID int(11), - CategoryID int(11), - BehaviorType varchar(65533), - Timestamp datetime -) -ENGINE = OLAP -DUPLICATE KEY(UserID) -DISTRIBUTED BY HASH(UserID); -``` - -#### 启动 Pipe 作业 - -运行以下命令以启动一个 Pipe 作业，该作业将数据从示例数据集 `s3://starrocks-examples/user-behavior-10-million-rows/` 加载到 `user_behavior_from_pipe` 表。此 pipe 作业使用微批处理和连续加载（如上所述）pipe 特定的功能。 - -本指南中的其他示例加载包含 1000 万行的单个 Parquet 文件。对于 pipe 示例，相同的数据集被拆分为 57 个单独的文件，这些文件都存储在一个 S3 文件夹中。请注意，在下面的 `CREATE PIPE` 命令中，`path` 是 S3 文件夹的 URI，而不是提供文件名，URI 以 `/*` 结尾。通过设置 `AUTO_INGEST` 并指定文件夹而不是单个文件，pipe 作业将轮询 S3 文件夹中的新文件，并在将它们添加到文件夹时导入它们。 - -```SQL -CREATE PIPE user_behavior_pipe -PROPERTIES -( --- highlight-start - "AUTO_INGEST" = "TRUE" --- highlight-end -) -AS -INSERT INTO user_behavior_from_pipe -SELECT * FROM FILES -( --- highlight-start - "path" = "s3://starrocks-examples/user-behavior-10-million-rows/*", --- highlight-end - "format" = "parquet", - "aws.s3.region" = "us-east-1", - "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", - "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB" -); -``` - -> **NOTE** -> -> 在上面的命令中，将您的凭据替换为 `AAA` 和 `BBB`。可以使用任何有效的 `aws.s3.access_key` 和 `aws.s3.secret_key`，因为任何经过 AWS 身份验证的用户都可以读取该对象。 - -此作业有四个主要部分： - -- `pipe_name`：pipe 的名称。pipe 名称在 pipe 所属的数据库中必须是唯一的。 -- `INSERT_SQL`：INSERT INTO SELECT FROM FILES 语句，用于将数据从指定的源数据文件加载到目标表。 -- `PROPERTIES`：一组可选参数，用于指定如何执行 pipe。这些参数包括 `AUTO_INGEST`、`POLL_INTERVAL`、`BATCH_SIZE` 和 `BATCH_FILES`。以 `"key" = "value"` 格式指定这些属性。 - -有关详细的语法和参数说明，请参阅 [CREATE PIPE](../sql-reference/sql-statements/loading_unloading/pipe/CREATE_PIPE.md)。 - -#### 检查导入进度 - -- 通过在 Pipe 作业所属的当前数据库中使用 [SHOW PIPES](../sql-reference/sql-statements/loading_unloading/pipe/SHOW_PIPES.md) 来查询 Pipe 作业的进度。 - - ```SQL - SHOW PIPES WHERE NAME = 'user_behavior_pipe' \G - ``` - - 返回以下结果： - - :::tip - 在下面显示的输出中，pipe 处于 `RUNNING` 状态。pipe 将保持 `RUNNING` 状态，直到您手动停止它。输出还显示了加载的文件数 (57) 和上次加载文件的时间。 - ::: - - ```SQL - *************************** 1. row *************************** - DATABASE_NAME: mydatabase - PIPE_ID: 10476 - PIPE_NAME: user_behavior_pipe - -- highlight-start - STATE: RUNNING - TABLE_NAME: mydatabase.user_behavior_from_pipe - LOAD_STATUS: {"loadedFiles":57,"loadedBytes":295345637,"loadingFiles":0,"lastLoadedTime":"2024-02-28 22:14:19"} - -- highlight-end - LAST_ERROR: NULL - CREATED_TIME: 2024-02-28 22:13:41 - 1 row in set (0.02 sec) - ``` - -- 从 StarRocks Information Schema 中的 [`pipes`](../sql-reference/information_schema/pipes.md) 视图查询 Pipe 作业的进度。 - - ```SQL - SELECT * FROM information_schema.pipes WHERE pipe_name = 'user_behavior_replica' \G - ``` - - 返回以下结果： - - :::tip - 本指南中的某些查询以 `\G` 而不是分号 (`;`) 结尾。这会导致 MySQL 客户端以垂直格式输出结果。如果您使用的是 DBeaver 或其他客户端，则可能需要使用分号 (`;`) 而不是 `\G`。 - ::: - - ```SQL - *************************** 1. row *************************** - DATABASE_NAME: mydatabase - PIPE_ID: 10217 - PIPE_NAME: user_behavior_replica - STATE: RUNNING - TABLE_NAME: mydatabase.user_behavior_replica - LOAD_STATUS: {"loadedFiles":1,"loadedBytes":132251298,"loadingFiles":0,"lastLoadedTime":"2023-11-09 15:35:42"} - LAST_ERROR: - CREATED_TIME: 9891-01-15 07:51:45 - 1 row in set (0.01 sec) - ``` - -#### 检查文件状态 - -您可以从 StarRocks Information Schema 中的 [`pipe_files`](../sql-reference/information_schema/pipe_files.md) 视图查询加载的文件的加载状态。 - -```SQL -SELECT * FROM information_schema.pipe_files WHERE pipe_name = 'user_behavior_replica' \G -``` - -返回以下结果： - -```SQL -*************************** 1. row *************************** - DATABASE_NAME: mydatabase - PIPE_ID: 10217 - PIPE_NAME: user_behavior_replica - FILE_NAME: s3://starrocks-examples/user-behavior-10-million-rows.parquet - FILE_VERSION: e29daa86b1120fea58ad0d047e671787-8 - FILE_SIZE: 132251298 - LAST_MODIFIED: 2023-11-06 13:25:17 - LOAD_STATE: FINISHED - STAGED_TIME: 2023-11-09 15:35:02 - START_LOAD_TIME: 2023-11-09 15:35:03 -FINISH_LOAD_TIME: 2023-11-09 15:35:42 - ERROR_MSG: -1 row in set (0.03 sec) -``` - -#### 管理 Pipe 作业 - -您可以更改、暂停或恢复、删除或查询您已创建的 pipe，并重试加载特定的数据文件。有关更多信息，请参阅 [ALTER PIPE](../sql-reference/sql-statements/loading_unloading/pipe/ALTER_PIPE.md)、[SUSPEND or RESUME PIPE](../sql-reference/sql-statements/loading_unloading/pipe/SUSPEND_or_RESUME_PIPE.md)、[DROP PIPE](../sql-reference/sql-statements/loading_unloading/pipe/DROP_PIPE.md)、[SHOW PIPES](../sql-reference/sql-statements/loading_unloading/pipe/SHOW_PIPES.md) 和 [RETRY FILE](../sql-reference/sql-statements/loading_unloading/pipe/RETRY_FILE.md)。 \ No newline at end of file diff --git a/docs/zh/loading/s3_compatible.md b/docs/zh/loading/s3_compatible.md deleted file mode 100644 index db92470..0000000 --- a/docs/zh/loading/s3_compatible.md +++ /dev/null @@ -1 +0,0 @@ -unlisted: true \ No newline at end of file diff --git a/docs/zh/loading/tencent.md b/docs/zh/loading/tencent.md deleted file mode 100644 index db92470..0000000 --- a/docs/zh/loading/tencent.md +++ /dev/null @@ -1 +0,0 @@ -unlisted: true \ No newline at end of file diff --git a/docs/zh/quick_start/routine-load.md b/docs/zh/quick_start/routine-load.md new file mode 100644 index 0000000..e917e3b --- /dev/null +++ b/docs/zh/quick_start/routine-load.md @@ -0,0 +1,684 @@ +--- +displayed_sidebar: docs +sidebar_position: 2 +toc_max_heading_level: 2 +description: Kafka routine load with shared-data storage +--- + +# 在存算分离模式下使用 Kafka 的 Routine Load 功能导入数据至 StarRocks + +import Clients from '../_assets/quick-start/_clientsCompose.mdx' +import SQL from '../_assets/quick-start/_SQL.mdx' + +Routine Load 是一种使用 Apache Kafka（在本实验中为 Redpanda）将数据持续流式传输到 StarRocks 的方法。数据被流式传输到 Kafka topic 中，然后 Routine Load 作业将数据导入到 StarRocks 中。有关 Routine Load 的更多详细信息，请在本实验的末尾提供。 +## 关于存算分离 + +在存算分离的系统中，数据存储在低成本、高可靠的远端存储系统中，例如 Amazon S3、Google Cloud Storage、Azure Blob Storage 以及其他 S3 兼容的存储系统（如 MinIO）。热数据缓存在本地，当缓存命中时，查询性能与存算一体架构相当。计算节点（CN）可以根据需要在几秒钟内添加或删除。这种架构降低了存储成本，确保了更好的资源隔离，并提供了弹性和可扩展性。 + +本教程包括： + +- 使用 Docker Compose 运行 StarRocks、Redpanda 和 MinIO +- 使用 MinIO 作为 StarRocks 的存储层 +- 为存算分离配置 StarRocks +- 添加一个 Routine Load 作业来消费来自 Redpanda 的数据 + +所使用的数据是合成数据。 + +本文档包含大量信息，开头以循序渐进的内容呈现，结尾提供技术细节。这样做是为了按以下顺序实现这些目的： + +1. 配置 Routine Load。 +2. 允许读者在存算分离部署中加载数据并分析该数据。 +3. 提供存算分离部署的配置详情。 + +--- +## 前提条件 +### Docker + +- [Docker](https://docs.docker.com/engine/install/) +- 分配给 Docker 的 4 GB 内存 +- 分配给 Docker 的 10 GB 可用磁盘空间 +### SQL 客户端 + +您可以使用在 Docker 环境中提供的 SQL 客户端，或者使用您系统上的客户端。许多与 MySQL 兼容的客户端都可以工作，本指南介绍了 DBeaver 和 MySQL Workbench 的配置。 +### curl + +`curl` 用于下载 Compose 文件和用于生成数据的脚本。通过在您的操作系统提示符下运行 `curl` 或 `curl.exe` 来检查是否已安装。如果未安装 curl，请 [在此处获取 curl](https://curl.se/dlwiz/?type=bin) 。 +### Python + +需要 Python 3 和 Apache Kafka 的 Python 客户端 `kafka-python`。 + +- [Python](https://www.python.org/) +- [`kafka-python`](https://pypi.org/project/kafka-python/) + +--- +## 术语 +### FE + +FE 节点负责元数据管理、客户端连接管理、查询计划和查询调度。每个 FE 在其内存中存储并维护元数据的完整副本，这保证了 FE 之间的无差别服务。 +计算节点负责在存算分离部署中执行查询计划。 +### BE + +后端节点负责在存算一体部署中进行数据存储和执行查询计划。 + +:::note +本指南不使用 BE，此处包含此信息是为了让您了解 BE 和 CN 之间的区别。 +::: + +--- +## 启动 StarRocks + +要使用对象存储以存算分离模式运行 StarRocks，您需要： + +- 一个前端引擎 (FE) +- 一个计算节点 (CN) +- 对象存储 + +本指南使用 MinIO，它是一个与 S3 兼容的对象存储提供商。MinIO 是在 GNU Affero General Public License 许可下提供的。 +### 下载实验文件 +#### `docker-compose.yml` + +```bash +mkdir routineload +cd routineload +curl -O https://raw.githubusercontent.com/StarRocks/demo/master/documentation-samples/routine-load-shared-data/docker-compose.yml +``` +#### `gen.py` + +`gen.py` 是一个脚本，它使用 Apache Kafka 的 Python 客户端向 Kafka topic 发布（生产）数据。该脚本已使用 Redpanda 容器的地址和端口编写。 + +```bash +curl -O https://raw.githubusercontent.com/StarRocks/demo/master/documentation-samples/routine-load-shared-data/gen.py +``` +## 启动 StarRocks、MinIO 和 Redpanda + +```bash +docker compose up --detach --wait --wait-timeout 120 +``` + +检查服务的进度。容器变为健康状态需要 30 秒或更长时间。`routineload-minio_mc-1` 容器不会显示健康指标，并且在完成使用 StarRocks 将使用的访问密钥配置 MinIO 后，它将退出。等待 `routineload-minio_mc-1` 以代码 `0` 退出，其余服务处于 `Healthy` 状态。 + +运行 `docker compose ps` 直到服务健康： + +```bash +docker compose ps +``` + +```plaintext +WARN[0000] /Users/droscign/routineload/docker-compose.yml: `version` is obsolete +[+] Running 6/7 + ✔ Network routineload_default Crea... 0.0s + ✔ Container minio Healthy 5.6s + ✔ Container redpanda Healthy 3.6s + ✔ Container redpanda-console Healt... 1.1s + ⠧ Container routineload-minio_mc-1 Waiting 23.1s + ✔ Container starrocks-fe Healthy 11.1s + ✔ Container starrocks-cn Healthy 23.0s +container routineload-minio_mc-1 exited (0) +``` + +--- +## 检查 MinIO 凭据 + +为了将 MinIO 用于 StarRocks 的对象存储，StarRocks 需要一个 MinIO 访问密钥。该访问密钥是在启动 Docker 服务期间生成的。为了帮助您更好地了解 StarRocks 连接到 MinIO 的方式，您应该验证该密钥是否存在。 +### 打开 MinIO Web UI + +在浏览器中访问 http://localhost:9001/access-keys 。用户名和密码在 Docker Compose 文件中指定，分别为 `miniouser` 和 `miniopassword`。您应该看到有一个访问密钥。密钥是 `AAAAAAAAAAAAAAAAAAAA`，您无法在 MinIO 控制台中看到 secret，但它在 Docker Compose 文件中，是 `BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB`： + +![查看 MinIO 访问密钥](../_assets/quick-start/MinIO-view-key.png) + +--- +### 为您的数据创建一个存储桶 + +在 StarRocks 中创建存储卷时，您需要指定数据的 `LOCATION`： + +```sh + LOCATIONS = ("s3://my-starrocks-bucket/") +``` + +打开 [http://localhost:9001/buckets](http://localhost:9001/buckets) ，并为存储卷添加一个存储桶。将存储桶命名为 `my-starrocks-bucket`。接受三个已列出选项的默认设置。 + +--- +## SQL 客户端 + + + +--- +## 存算分离模式下的 StarRocks 配置 + +目前您已经成功运行了 StarRocks 和 MinIO。MinIO 访问密钥用于连接 StarRocks 和 MinIO。 + +以下是 `FE` 的配置，用于指定 StarRocks 部署将使用存算分离。此配置在 Docker Compose 创建部署时被添加到 `fe.conf` 文件中。 + +```sh +# 启用存算分离运行模式 +run_mode = shared_data +cloud_native_storage_type = S3 +``` + +:::info +您可以通过从 `quickstart` 目录运行以下命令并查看文件末尾来验证这些设置： +::: + +```sh +docker compose exec starrocks-fe \ + cat /opt/starrocks/fe/conf/fe.conf +``` +::: +### 使用 SQL 客户端连接到 StarRocks + +:::tip + +从包含 `docker-compose.yml` 文件的目录运行此命令。 + +如果您使用的客户端不是 mysql CLI，请立即打开它。 +::: + +```sql +docker compose exec starrocks-fe \ +mysql -P9030 -h127.0.0.1 -uroot --prompt="StarRocks > " +``` +#### 检查存储卷 + +```sql +SHOW STORAGE VOLUMES; +``` + +:::tip +应该没有任何存储卷，您接下来将创建一个。 +::: + +```sh +Empty set (0.04 sec) +``` +#### 创建一个存算分离存储卷 + +之前您在 MinIO 中创建了一个名为 `my-starrocks-volume` 的存储桶，并且您已验证 MinIO 是否具有名为 `AAAAAAAAAAAAAAAAAAAA` 的访问密钥。以下 SQL 将使用访问密钥和密钥在 MionIO 存储桶中创建一个存储卷。 + +```sql +CREATE STORAGE VOLUME s3_volume + TYPE = S3 + LOCATIONS = ("s3://my-starrocks-bucket/") + PROPERTIES + ( + "enabled" = "true", + "aws.s3.endpoint" = "minio:9000", + "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", + "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", + "aws.s3.use_instance_profile" = "false", + "aws.s3.use_aws_sdk_default_behavior" = "false" + ); +``` + +现在您应该看到一个存储卷已列出，之前它是一个空集： + +``` +SHOW STORAGE VOLUMES; +``` + +``` ++----------------+ +| Storage Volume | ++----------------+ +| s3_volume | ++----------------+ +1 row in set (0.02 sec) +``` + +查看存储卷的详细信息，并注意这还不是默认卷，并且它已配置为使用您的存储桶： + +``` +DESC STORAGE VOLUME s3_volume\G +``` + +:::tip +本文档以及 StarRocks 文档中的许多其他文档中的某些 SQL，都使用 `\G` 而不是分号。`\G` 会导致 mysql CLI 垂直呈现查询结果。 + +许多 SQL 客户端不解释垂直格式输出，因此您应该将 `\G` 替换为 `;`。 +::: + +```sh +*************************** 1. row *************************** + Name: s3_volume + Type: S3 +# highlight-start +IsDefault: false + Location: s3://my-starrocks-bucket/ +# highlight-end + Params: {"aws.s3.access_key":"******","aws.s3.secret_key":"******","aws.s3.endpoint":"minio:9000","aws.s3.region":"us-east-1","aws.s3.use_instance_profile":"false","aws.s3.use_web_identity_token_file":"false","aws.s3.use_aws_sdk_default_behavior":"false"} + Enabled: true + Comment: +1 row in set (0.02 sec) +``` +## 设置默认存储卷 + +``` +SET s3_volume AS DEFAULT STORAGE VOLUME; +``` + +``` +DESC STORAGE VOLUME s3_volume\G +``` + +```sh +*************************** 1. row *************************** + Name: s3_volume + Type: S3 +# highlight-next-line +IsDefault: true + Location: s3://my-starrocks-bucket/ + Params: {"aws.s3.access_key":"******","aws.s3.secret_key":"******","aws.s3.endpoint":"minio:9000","aws.s3.region":"us-east-1","aws.s3.use_instance_profile":"false","aws.s3.use_web_identity_token_file":"false","aws.s3.use_aws_sdk_default_behavior":"false"} + Enabled: true + Comment: +1 row in set (0.02 sec) +``` + +--- +## 创建表 + +以下 SQL 命令需要在您的 SQL 客户端中运行。 + +```SQL +CREATE DATABASE IF NOT EXISTS quickstart; +``` + +验证数据库 `quickstart` 是否正在使用存储卷 `s3_volume`： + +``` +SHOW CREATE DATABASE quickstart \G +``` + +```sh +*************************** 1. row *************************** + Database: quickstart +Create Database: CREATE DATABASE `quickstart` +# highlight-next-line +PROPERTIES ("storage_volume" = "s3_volume") +``` + +```SQL +USE quickstart; +``` + +```SQL +CREATE TABLE site_clicks ( + `uid` bigint NOT NULL COMMENT "uid", + `site` string NOT NULL COMMENT "site url", + `vtime` bigint NOT NULL COMMENT "vtime" +) +DISTRIBUTED BY HASH(`uid`) +PROPERTIES("replication_num"="1"); +``` +### 打开 Redpanda 控制台 + +现在还没有任何 topic，topic 将在下一步创建。 + +http://localhost:8080/overview +### 将数据发布到 Redpanda topic + +在 `routineload/` 文件夹的命令 shell 中，运行以下命令来生成数据： + +```python +python gen.py 5 +``` + +:::tip + +在您的系统中，您可能需要使用 `python3` 代替命令中的 `python`。 + +如果您缺少 `kafka-python`，请尝试： + +``` +pip install kafka-python +``` +或者 + +``` +pip3 install kafka-python +``` + +::: + +```plaintext +b'{ "uid": 6926, "site": "https://docs.starrocks.io/", "vtime": 1718034793 } ' +b'{ "uid": 3303, "site": "https://www.starrocks.io/product/community", "vtime": 1718034793 } ' +b'{ "uid": 227, "site": "https://docs.starrocks.io/", "vtime": 1718034243 } ' +b'{ "uid": 7273, "site": "https://docs.starrocks.io/", "vtime": 1718034794 } ' +b'{ "uid": 4666, "site": "https://www.starrocks.io/", "vtime": 1718034794 } ' +``` +### 在 Redpanda 控制台中验证 + +在 Redpanda 控制台中，导航到 http://localhost:8080/topics ，您将看到一个名为 `test2` 的主题。选择该主题，然后选择 **Messages** 选项卡，您将看到五个与 `gen.py` 输出匹配的消息。 +## 消费消息 + +在 StarRocks 中，您需要创建一个 Routine Load 作业来： + +1. 从 Redpanda topic `test2` 中消费消息。 +2. 将这些消息导入到表 `site_clicks` 中。 + +StarRocks 配置为使用 MinIO 进行存储，因此插入到 `site_clicks` 表中的数据将存储在 MinIO 中。 +### 创建一个 Routine Load 作业 + +在 SQL 客户端中运行以下命令来创建一个 Routine Load 作业。该命令的详细解释将在实验的最后给出。 + +```SQL +CREATE ROUTINE LOAD quickstart.clicks ON site_clicks +PROPERTIES +( + "format" = "JSON", + "jsonpaths" ="[\"$.uid\",\"$.site\",\"$.vtime\"]" +) +FROM KAFKA +( + "kafka_broker_list" = "redpanda:29092", + "kafka_topic" = "test2", + "kafka_partitions" = "0", + "kafka_offsets" = "OFFSET_BEGINNING" +); +``` +### 验证 `Routine Load` 作业 + +```SQL +SHOW ROUTINE LOAD\G +``` + +验证以下三个突出显示的行： + +1. 状态应为 `RUNNING` +2. `topic` 应为 `test2`，`broker` 应为 `redpanda:2092` +3. 统计信息应显示 0 或 5 个已加载的行，具体取决于您运行 `SHOW ROUTINE LOAD` 命令的时间。 如果有 0 个已加载的行，请再次运行。 + +```SQL +*************************** 1. row *************************** + Id: 10078 + Name: clicks + CreateTime: 2024-06-12 15:51:12 + PauseTime: NULL + EndTime: NULL + DbName: quickstart + TableName: site_clicks + -- highlight-next-line + State: RUNNING + DataSourceType: KAFKA + CurrentTaskNum: 1 + JobProperties: {"partitions":"*","partial_update":"false","columnToColumnExpr":"*","maxBatchIntervalS":"10","partial_update_mode":"null","whereExpr":"*","dataFormat":"json","timezone":"Etc/UTC","format":"json","log_rejected_record_num":"0","taskTimeoutSecond":"60","json_root":"","maxFilterRatio":"1.0","strict_mode":"false","jsonpaths":"[\"$.uid\",\"$.site\",\"$.vtime\"]","taskConsumeSecond":"15","desireTaskConcurrentNum":"5","maxErrorNum":"0","strip_outer_array":"false","currentTaskConcurrentNum":"1","maxBatchRows":"200000"} + -- highlight-next-line +DataSourceProperties: {"topic":"test2","currentKafkaPartitions":"0","brokerList":"redpanda:29092"} + CustomProperties: {"group.id":"clicks_ea38a713-5a0f-4abe-9b11-ff4a241ccbbd"} + -- highlight-next-line + Statistic: {"receivedBytes":0,"errorRows":0,"committedTaskNum":0,"loadedRows":0,"loadRowsRate":0,"abortedTaskNum":0,"totalRows":0,"unselectedRows":0,"receivedBytesRate":0,"taskExecuteTimeMs":1} + Progress: {"0":"OFFSET_ZERO"} + TimestampProgress: {} +ReasonOfStateChanged: + ErrorLogUrls: + TrackingSQL: + OtherMsg: +LatestSourcePosition: {} +1 row in set (0.00 sec) +``` + +```SQL +SHOW ROUTINE LOAD\G +``` + +```SQL +*************************** 1. row *************************** + Id: 10076 + Name: clicks + CreateTime: 2024-06-12 18:40:53 + PauseTime: NULL + EndTime: NULL + DbName: quickstart + TableName: site_clicks + State: RUNNING + DataSourceType: KAFKA + CurrentTaskNum: 1 + JobProperties: {"partitions":"*","partial_update":"false","columnToColumnExpr":"*","maxBatchIntervalS":"10","partial_update_mode":"null","whereExpr":"*","dataFormat":"json","timezone":"Etc/UTC","format":"json","log_rejected_record_num":"0","taskTimeoutSecond":"60","json_root":"","maxFilterRatio":"1.0","strict_mode":"false","jsonpaths":"[\"$.uid\",\"$.site\",\"$.vtime\"]","taskConsumeSecond":"15","desireTaskConcurrentNum":"5","maxErrorNum":"0","strip_outer_array":"false","currentTaskConcurrentNum":"1","maxBatchRows":"200000"} +DataSourceProperties: {"topic":"test2","currentKafkaPartitions":"0","brokerList":"redpanda:29092"} + CustomProperties: {"group.id":"clicks_a9426fee-45bb-403a-a1a3-b3bc6c7aa685"} + -- highlight-next-line + Statistic: {"receivedBytes":372,"errorRows":0,"committedTaskNum":1,"loadedRows":5,"loadRowsRate":0,"abortedTaskNum":0,"totalRows":5,"unselectedRows":0,"receivedBytesRate":0,"taskExecuteTimeMs":519} + Progress: {"0":"4"} + TimestampProgress: {"0":"1718217035111"} +ReasonOfStateChanged: + ErrorLogUrls: + TrackingSQL: + OtherMsg: + -- highlight-next-line +LatestSourcePosition: {"0":"5"} +1 row in set (0.00 sec) +``` +## 验证数据是否存储在 MinIO 中 + +打开 MinIO [http://localhost:9001/browser/](http://localhost:9001/browser/) ，并验证 `my-starrocks-bucket` 下是否存储了对象。 + +--- +## 从 StarRocks 查询数据 + +```SQL +USE quickstart; +SELECT * FROM site_clicks; +``` + +```SQL ++------+--------------------------------------------+------------+ +| uid | site | vtime | ++------+--------------------------------------------+------------+ +| 4607 | https://www.starrocks.io/blog | 1718031441 | +| 1575 | https://www.starrocks.io/ | 1718031523 | +| 2398 | https://docs.starrocks.io/ | 1718033630 | +| 3741 | https://www.starrocks.io/product/community | 1718030845 | +| 4792 | https://www.starrocks.io/ | 1718033413 | ++------+--------------------------------------------+------------+ +5 rows in set (0.07 sec) +``` +## 发布额外数据 + +再次运行 `gen.py` 会将另外五个记录发布到 Redpanda。 + +```bash +python gen.py 5 +``` +### 验证数据是否已添加 + +由于 Routine Load 作业按计划运行（默认情况下每 10 秒一次），因此数据将在几秒钟内完成导入。 + +```SQL +SELECT * FROM site_clicks; +```` + +``` ++------+--------------------------------------------+------------+ +| uid | site | vtime | ++------+--------------------------------------------+------------+ +| 6648 | https://www.starrocks.io/blog | 1718205970 | +| 7914 | https://www.starrocks.io/ | 1718206760 | +| 9854 | https://www.starrocks.io/blog | 1718205676 | +| 1186 | https://www.starrocks.io/ | 1718209083 | +| 3305 | https://docs.starrocks.io/ | 1718209083 | +| 2288 | https://www.starrocks.io/blog | 1718206759 | +| 7879 | https://www.starrocks.io/product/community | 1718204280 | +| 2666 | https://www.starrocks.io/ | 1718208842 | +| 5801 | https://www.starrocks.io/ | 1718208783 | +| 8409 | https://www.starrocks.io/ | 1718206889 | ++------+--------------------------------------------+------------+ +10 rows in set (0.02 sec) +``` + +--- +## 配置详情 + +既然您已经体验了在存算分离模式下使用 StarRocks ，那么了解配置就非常重要了。 +### CN 配置 + +这里使用的 CN 配置是默认配置，因为 CN 是为存算分离使用而设计的。默认配置如下所示。您无需进行任何更改。 + +```bash +sys_log_level = INFO + +# ports for admin, web, heartbeat service +be_port = 9060 +be_http_port = 8040 +heartbeat_service_port = 9050 +brpc_port = 8060 +starlet_port = 9070 +``` +### FE 配置 + +FE 的配置与默认配置略有不同，因为必须将 FE 配置为期望数据存储在对象存储中，而不是 BE 节点上的本地磁盘上。 + +`docker-compose.yml` 文件在 `command` 中生成 FE 配置。 + +```plaintext +# 启用存算分离，设置存储类型，设置 endpoint +run_mode = shared_data +cloud_native_storage_type = S3 +``` + +:::note +此配置文件不包含 FE 的默认条目，仅显示存算分离配置。 +::: + +非默认的 FE 配置设置： + +:::note +许多配置参数都带有 `s3_` 前缀。此前缀用于所有与 Amazon S3 兼容的存储类型（例如：S3、GCS 和 MinIO）。当使用 Azure Blob Storage 时，前缀为 `azure_`。 +::: +#### `run_mode=shared_data` + +该配置项用于启用存算分离模式。 +#### `cloud_native_storage_type=S3` + +该参数用于指定是否使用 S3 兼容的存储或 Azure Blob Storage。对于 MinIO，该参数值始终为 S3。 +### `CREATE storage volume` 详情 + +```sql +CREATE STORAGE VOLUME s3_volume + TYPE = S3 + LOCATIONS = ("s3://my-starrocks-bucket/") + PROPERTIES + ( + "enabled" = "true", + "aws.s3.endpoint" = "minio:9000", + "aws.s3.access_key" = "AAAAAAAAAAAAAAAAAAAA", + "aws.s3.secret_key" = "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", + "aws.s3.use_instance_profile" = "false", + "aws.s3.use_aws_sdk_default_behavior" = "false" + ); +``` +#### `aws_s3_endpoint=minio:9000` + +MinIO 端点，包括端口号。 +#### `aws_s3_path=starrocks` + +Bucket 的名称。 +#### `aws_s3_access_key=AAAAAAAAAAAAAAAAAAAA` + +MinIO 访问密钥。 +#### `aws_s3_secret_key=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB` + +MinIO 访问密钥。 +#### `aws_s3_use_instance_profile=false` + +当使用 MinIO 时，会使用访问密钥，因此实例配置文件不与 MinIO 一起使用。 +#### `aws_s3_use_aws_sdk_default_behavior=false` + +当使用 MinIO 时，此参数始终设置为 false。 + +--- +## 关于 Routine Load 命令的注意事项 + +StarRocks Routine Load 接受许多参数。这里只介绍本教程中使用的参数，其余参数将在更多信息部分链接。 + +```SQL +CREATE ROUTINE LOAD quickstart.clicks ON site_clicks +PROPERTIES +( + "format" = "JSON", + "jsonpaths" ="[\"$.uid\",\"$.site\",\"$.vtime\"]" +) +FROM KAFKA +( + "kafka_broker_list" = "redpanda:29092", + "kafka_topic" = "test2", + "kafka_partitions" = "0", + "kafka_offsets" = "OFFSET_BEGINNING" +); +``` +### 参数 + +``` +CREATE ROUTINE LOAD quickstart.clicks ON site_clicks +``` + +`CREATE ROUTINE LOAD ON` 的参数如下： + +- database_name.job_name +- table_name + +`database_name` 是可选的。在本实验中，它是 `quickstart` 并且已被指定。 + +`job_name` 是必需的，这里是 `clicks`。 + +`table_name` 是必需的，这里是 `site_clicks`。 +### Job properties + +### Job properties + +作业属性 +#### 属性 `format` + +``` +"format" = "JSON", +``` + +在这种情况下，数据为 JSON 格式，因此该属性设置为 `JSON`。其他有效的格式包括：`CSV`、`JSON` 和 `Avro`。`CSV` 是默认格式。 +#### 属性 `jsonpaths` + +``` +"jsonpaths" ="[\"$.uid\",\"$.site\",\"$.vtime\"]" +``` + +您想要从 JSON 格式的数据中加载的字段名称。此参数的值是有效的 JsonPath 表达式。更多信息请参见本页末尾。 +### 数据源属性 +#### `kafka_broker_list` + +``` +"kafka_broker_list" = "redpanda:29092", +``` + +Kafka 的 Broker 连接信息。格式为 `:`。多个 Broker 之间用逗号分隔。 +#### `kafka_topic` + +``` +"kafka_topic" = "test2", +``` + +要消费的 Kafka topic。 +#### `kafka_partitions` 和 `kafka_offsets` + +``` +"kafka_partitions" = "0", +"kafka_offsets" = "OFFSET_BEGINNING" +``` + +这些属性一起展示，因为每个 `kafka_partitions` 条目都需要一个 `kafka_offset`。 + +`kafka_partitions` 是要消费的一个或多个分区的列表。如果未设置此属性，则会消费所有分区。 + +`kafka_offsets` 是一个偏移量列表，`kafka_partitions` 中列出的每个分区对应一个偏移量。在本例中，该值为 `OFFSET_BEGINNING`，这将导致消费所有数据。默认情况下，仅消费新数据。 + +--- +## 概述 + +在本教程中，您将： + +- 在 Docker 中部署了 StarRocks、Reedpanda 和 MinIO +- 创建了一个 Routine Load 作业，用于从 Kafka topic 中消费数据 +- 学习了如何配置使用 MinIO 的 StarRocks 存储卷 +## 更多信息 + +[StarRocks 架构](../introduction/Architecture.md) + +本实验使用的示例非常简单。Routine Load 还有更多的选项和功能。 [了解更多](../loading/RoutineLoad.md) 。 + +[JSONPath](https://goessner.net/articles/JsonPath/) \ No newline at end of file diff --git a/docs/zh/sql-reference/sql-functions/dict-functions/dict_mapping.md b/docs/zh/sql-reference/sql-functions/dict-functions/dict_mapping.md index 105f7c2..8d40f58 100644 --- a/docs/zh/sql-reference/sql-functions/dict-functions/dict_mapping.md +++ b/docs/zh/sql-reference/sql-functions/dict-functions/dict_mapping.md @@ -6,10 +6,9 @@ displayed_sidebar: docs 返回字典表中与指定键映射的值。 -此函数主要用于简化全局字典表的应用。在将数据加载到目标表期间，StarRocks 会通过使用此函数中的输入参数，自动从字典表中获取与指定键映射的值，然后将该值加载到目标表中。 - -自 v3.2.5 起，StarRocks 支持此功能。另请注意，目前 StarRocks 的存算分离模式不支持此功能。 +`dict_mapping` 简化了全局字典表的应用。在将数据加载到目标表期间，StarRocks 通过使用此函数中的输入参数，自动从字典表中获取与指定键映射的值，然后将该值加载到目标表中。 +自 v3.2.5 起，StarRocks 支持此函数。另请注意，目前 StarRocks 的存算分离模式不支持此功能。 ## 语法 ```SQL @@ -19,30 +18,27 @@ key_column_expr_list ::= key_column_expr [, key_column_expr ... ] key_column_expr ::= | ``` - ## 参数 -- 必需参数： - - `[.]`：字典表的名称，需要是 Primary Key table。支持的数据类型为 VARCHAR。 - - `key_column_expr_list`：字典表中键列的表达式列表，包括一个或多个 `key_column_exprs`。`key_column_expr` 可以是字典表中键列的名称，也可以是特定的键或键表达式。 +- 必选参数： + - `[.]`：字典表的名称，必须是主键表。支持的数据类型为 VARCHAR。 + - `key_column_expr_list`：字典表中键列的表达式列表，包括一个或多个 `key_column_expr`。`key_column_expr` 可以是字典表中键列的名称，也可以是特定的键或键表达式。 - 此表达式列表需要包括字典表的所有 Primary Key 列，这意味着表达式的总数需要与字典表中 Primary Key 列的总数匹配。因此，当字典表使用组合主键时，此列表中的表达式需要按顺序与表结构中定义的 Primary Key 列相对应。此列表中的多个表达式用逗号 (`,`) 分隔。如果 `key_column_expr` 是特定的键或键表达式，则其类型必须与字典表中相应 Primary Key 列的类型匹配。 + 此表达式列表需要包含字典表的所有主键列，这意味着表达式的总数需要与字典表中的主键列总数相匹配。因此，当字典表使用组合主键时，此列表中的表达式需要按顺序与表结构中定义的主键列相对应。此列表中的多个表达式用逗号 (`,`) 分隔。并且如果 `key_column_expr` 是特定的键或键表达式，则其类型必须与字典表中相应主键列的类型相匹配。 - 可选参数： - - ``：值列的名称，也就是映射列。如果未指定值列，则默认值列是字典表的 AUTO_INCREMENT 列。值列也可以定义为字典表中的任何列，不包括自增列和主键。该列的数据类型没有限制。 - - ``（可选）：如果键在字典表中不存在，是否返回 Null。有效值： - - `true`：如果键不存在，则返回 Null。 + - ``：值列的名称，也就是映射列。如果未指定值列，则默认值列是字典表的自增列。值列也可以定义为字典表中的任何列，但自增列和主键除外。该列的数据类型没有限制。 + - ``（可选）：如果字典表中不存在键，是否返回 NULL。有效值： + - `true`：如果键不存在，则返回 NULL。 - `false`（默认）：如果键不存在，则抛出异常。 - ## 返回值 -返回的数据类型与值列的数据类型保持一致。如果值列是字典表的自增列，则返回的数据类型为 BIGINT。 - -但是，当未找到与指定键映射的值时，如果 `` 参数设置为 `true`，则返回 `NULL`。如果参数设置为 `false`（默认），则返回错误 `query failed if record not exist in dict table`。 +返回值的数据类型与值列的数据类型保持一致。如果值列是字典表的自增列，则返回值的数据类型为 BIGINT。 +但是，当找不到映射到指定键的值时，如果将 `` 参数设置为 `true`，则返回 `NULL`。如果该参数设置为 `false`（默认），则返回错误 `query failed if record not exist in dict table`。 ## 示例 -**示例 1：直接查询字典表中与键映射的值。** +**示例 1：直接从字典表中查询 key 映射的值。** 1. 创建一个字典表并加载模拟数据。 @@ -72,9 +68,9 @@ key_column_expr ::= | > **注意** > - > 目前，`INSERT INTO` 语句不支持部分更新。因此，请确保插入到 `dict` 的键列中的值不重复。否则，在字典表中多次插入相同的键列值会导致其在值列中映射的值发生更改。 + > 目前 `INSERT INTO` 语句不支持部分更新。因此，请确保插入到 `dict` 的 key 列中的值没有重复。否则，在字典表中多次插入相同的 key 列值会导致其在 value 列中的映射值发生变化。 -2. 查询字典表中与键 `a1` 映射的值。 +2. 查询字典表中 key `a1` 映射的值。 ```SQL MySQL [test]> SELECT dict_mapping('dict', 'a1'); @@ -86,7 +82,7 @@ key_column_expr ::= | 1 row in set (0.01 sec) ``` -**示例 2：表中的映射列配置为使用 `dict_mapping` 函数生成的列。因此，在将数据加载到此表时，StarRocks 可以自动获取与键映射的值。** +**示例 2：表中的映射列配置为使用 `dict_mapping` 函数的生成列。因此，在将数据加载到此表中时，StarRocks 可以自动获取 key 映射的值。** 1. 创建一个数据表，并通过使用 `dict_mapping('dict', order_uuid)` 将映射列配置为生成列。 @@ -95,9 +91,9 @@ key_column_expr ::= | id BIGINT, -- 此列记录 STRING 类型的订单号，对应于示例 1 中 dict 表中的 order_uuid 列。 order_uuid STRING, - batch int comment 'used to distinguish different batch loading', + batch int comment '用于区分不同的批量加载', -- 此列记录与 order_uuid 列映射的 BIGINT 类型的订单号。 - -- 因为此列是使用 dict_mapping 配置的生成列，所以此列中的值在数据加载期间会自动从示例 1 中的 dict 表中获取。 + -- 因为此列是使用 dict_mapping 配置的生成列，所以此列中的值在数据导入期间自动从示例 1 中的 dict 表中获取。 -- 随后，此列可以直接用于去重和 JOIN 查询。 order_id_int BIGINT AS dict_mapping('dict', order_uuid) ) @@ -105,7 +101,7 @@ key_column_expr ::= | DISTRIBUTED BY HASH(id); ``` -2. 当将模拟数据加载到此表中时，其中 `order_id_int` 列配置为 `dict_mapping('dict', 'order_uuid')`，StarRocks 会根据 `dict` 表中键和值之间的映射关系自动将值加载到 `order_id_int` 列中。 +2. 当将模拟数据加载到此表中时，其中 `order_id_int` 列配置为 `dict_mapping('dict', 'order_uuid')`，StarRocks 会根据 `dict` 表中 key 和 value 之间的映射关系自动将值加载到 `order_id_int` 列中。 ```SQL MySQL [test]> INSERT INTO dest_table1(id, order_uuid, batch) VALUES (1, 'a1', 1), (2, 'a1', 1), (3, 'a3', 1), (4, 'a3', 1); @@ -124,22 +120,22 @@ key_column_expr ::= | 4 rows in set (0.02 sec) ``` - 在此示例中使用 `dict_mapping` 可以加速 [去重计算和 JOIN 查询](../../../using_starrocks/query_acceleration_with_auto_increment.md)。与之前构建全局字典以加速精确去重的解决方案相比，使用 `dict_mapping` 的解决方案更加灵活和用户友好。因为映射值是在“将键和值之间的映射关系加载到表”的阶段直接从字典表中获取的。您无需编写语句来连接字典表以获取映射值。此外，此解决方案支持各种数据导入方法。 + 在此示例中，`dict_mapping` 的使用可以加速 [去重计算和 JOIN 查询](../../../using_starrocks/query_acceleration_with_auto_increment.md)。与之前构建全局字典以加速精准去重的解决方案相比，使用 `dict_mapping` 的解决方案更加灵活和用户友好。因为映射值是在“将 key 和 value 之间的映射关系加载到表”的阶段直接从字典表中获取的。您无需编写语句来连接字典表以获取映射值。此外，此解决方案支持各种数据导入方法。 -**示例 3：如果表中的映射列未配置为生成列，则在将数据加载到表时，您需要为映射列显式配置 `dict_mapping` 函数，以获取与键映射的值。** +**示例 3：如果表中的映射列未配置为生成列，则在将数据加载到表中时，您需要为映射列显式配置 `dict_mapping` 函数，以获取 key 映射的值。** > **注意** > -> 示例 3 和示例 2 之间的区别在于，在导入到数据表时，您需要修改导入命令，以便为映射列显式配置 `dict_mapping` 表达式。 +> 示例 3 和示例 2 之间的区别在于，导入到数据表时，您需要修改导入命令，以便为映射列显式配置 `dict_mapping` 表达式。 -1. 创建一个表。 +1. 创建表。 ```SQL CREATE TABLE dest_table2 ( id BIGINT, order_uuid STRING, order_id_int BIGINT NULL, - batch int comment 'used to distinguish different batch loading' + batch int comment '用于区分不同的批量加载' ) DUPLICATE KEY (id, order_uuid, order_id_int) DISTRIBUTED BY HASH(id); @@ -163,16 +159,16 @@ key_column_expr ::= | **示例 4：启用 null_if_not_exist 模式** -当 `` 模式被禁用，并且查询了字典表中不存在的键所映射的值时，将返回一个错误，而不是 `NULL`。它确保数据行的键首先被加载到字典表中，并且在将该数据行加载到目标表之前，会生成其映射的值（字典 ID）。 +当禁用 `` 模式并且查询在字典表中不存在的 key 映射的值时，将返回错误而不是 `NULL`。它确保数据行的 key 首先加载到字典表中，并且在将该数据行加载到目标表之前生成其映射的值（字典 ID）。 ```SQL MySQL [test]> SELECT dict_mapping('dict', 'b1', true); ERROR 1064 (HY000): Query failed if record not exist in dict table. ``` -**示例 5：如果字典表使用组合主键，则在查询时必须指定所有主键。** +**示例 5：如果字典表使用复合主键，则查询时必须指定所有主键。** -1. 创建一个具有组合主键的字典表，并将模拟数据加载到其中。 +1. 创建一个具有复合主键的字典表，并将模拟数据加载到其中。 ```SQL MySQL [test]> CREATE TABLE dict2 ( @@ -180,7 +176,7 @@ ERROR 1064 (HY000): Query failed if record not exist in dict table. order_date DATE, order_id_int BIGINT AUTO_INCREMENT ) - PRIMARY KEY (order_uuid,order_date) -- 组合主键 + PRIMARY KEY (order_uuid,order_date) -- 复合主键 DISTRIBUTED BY HASH (order_uuid,order_date) ; Query OK, 0 rows affected (0.02 sec) @@ -201,7 +197,7 @@ ERROR 1064 (HY000): Query failed if record not exist in dict table. 3 rows in set (0.01 sec) ``` -2. 查询字典表中与键映射的值。由于字典表具有组合主键，因此需要在 `dict_mapping` 中指定所有主键。 +2. 查询字典表中 key 映射的值。由于字典表具有复合主键，因此需要在 `dict_mapping` 中指定所有主键。 ```SQL SELECT dict_mapping('dict2', 'a1', cast('2023-11-22' as DATE));