StarRocks支持從本地直接導入數據，支持CSV文件格式，數據量在10 GB以下。本文為您介紹Stream Load導入的基本原理、使用示例和最佳實踐。
背景信息
Stream Load是一種同步的導入方式，通過發送HTTP請求將本地文件或數據流導入到StarRocks中。Stream Load同步執行導入并返回導入結果。您可以直接通過請求的返回值判斷導入是否成功。
基本概念
Coordinator：協調節點。負責接收數據并分發數據到其他數據節點，導入完成后返回結果。
基本原理
Stream Load通過HTTP協議提交導入命令。如果提交到FE節點，則FE節點會通過HTTP Redirect指令將請求轉發給某一個BE節點，您也可以直接提交導入命令給某一指定BE節點。該BE節點作為Coordinator節點，將數據按表Schema劃分并分發數據到相關的BE節點。導入的最終結果由Coordinator節點返回給用戶。
Stream Load的主要流程如下圖所示。
導入示例
創建導入任務
Stream Load通過HTTP協議提交和傳輸數據。本示例通過curl命令展示如何提交導入任務。您也可以通過其他HTTP Client進行操作。
語法
curl --location-trusted -u user:passwd [-H ""...] -T data.file -XPUT \
http://fe_host:http_port/api/{db}/{table}/_stream_load當前支持HTTP chunked與非chunked兩種上傳方式，對于非chunked方式，必須要有Content-Length來標示上傳的內容長度，保證數據的完整性。
建議設置Expect Header字段內容為100-continue，可以在某些出錯場景下避免不必要的數據傳輸。
Header中支持的屬性見下表的導入任務參數描述，格式為-H "key1:value1"。如果同時有多個任務參數，需要用多個-H來指示，類似于-H "key1:value1" -H "key2:value2"……。Stream Load中所有與導入任務相關的參數均設置在Header中。相關參數描述如下表所示。
參數 | 描述 | |
簽名參數 | user:passwd | Stream Load創建導入任務使用的是HTTP協議，已通過Basic access authentication進行簽名。StarRocks系統會根據簽名來驗證用戶身份和導入權限。 |
導入任務參數 | label | 導入任務的標簽，相同標簽的數據無法多次導入。 您可以通過指定Label的方式來避免一份數據重復導入的問題。當前StarRocks系統會保留最近30分鐘內成功完成的任務的Label。 |
column_separator | 用于指定導入文件中的列分隔符，默認為\t。 如果是不可見字符，則需要加\x作為前綴，使用十六進制來表示分隔符。例如，Hive文件的分隔符\x01，需要指定為 | |
row_delimiter | 指定導入文件中的行分隔符，默認為\n。 重要 curl命令無法傳遞\n，換行符手動指定為\n時，Shell會先傳遞反斜線（\），然后傳遞n而不是直接傳遞換行符\n。 Bash支持另一種轉義字符串語法，傳遞\n和\t時，使用美元符號和全角單引號（$'）啟動字符串并以半角單引號（'）結束字符串。例如， | |
columns | 用于指定導入文件中的列和Table中列的對應關系。 如果源文件中的列正好對應表中的內容，則無需指定該參數。如果源文件與表Schema不對應，則需要該參數來配置數據轉換規則。列有兩種形式，一種是直接對應于導入文件中的字段，可以直接使用字段名表示，一種需要通過計算得出。
| |
where | 用于抽取部分數據。如需過濾掉不需要的數據，則可以通過設置該參數來實現。 例如，只導入k1列等于20180601的數據，則可以在導入時指定 | |
max_filter_ratio | 最大容忍可過濾（例如，因為數據不規范等原因而過濾）的數據比例。默認為0，取值范圍是0~1。 說明 此處數據不規范的數據不包括通過WHERE條件過濾的數據。 | |
partitions | 用于指定該導入所涉及的Partition。 如果您能夠確定數據對應的Partition，則推薦指定該項。不滿足指定分區的數據將被過濾掉。例如，指定導入到p1和p2分區，可以指定 | |
timeout | 指定導入的超時時間。默認是600，單位為秒。 設置范圍為1~259200。 | |
strict_mode | 指定此次導入是否開啟嚴格模式，默認為開啟。 關閉方式為 | |
timezone | 指定本次導入所使用的時區。默認為東八區。 該參數會影響所有導入涉及和時區有關的函數結果。 | |
exec_mem_limit | 導入內存限制。默認值為2 GB。 | |
示例
curl --location-trusted -u root -T date -H "label:123" \
http://abc.com:8030/api/test/date/_stream_load導入任務完成后，Stream Load會以JSON格式返回導入任務的相關內容，返回結果示例如下。
{
"TxnId": 11672,
"Label": "f6b62abf-4e16-4564-9009-b77823f3c024",
"Status": "Success",
"Message": "OK",
"NumberTotalRows": 199563535,
"NumberLoadedRows": 199563535,
"NumberFilteredRows": 0,
"NumberUnselectedRows": 0,
"LoadBytes": 50706674331,
"LoadTimeMs": 801327,
"BeginTxnTimeMs": 103,
"StreamLoadPlanTimeMs": 0,
"ReadDataTimeMs": 760189,
"WriteDataTimeMs": 801023,
"CommitAndPublishTimeMs": 199"
}參數 | 描述 |
TxnId | 導入的事務ID。用戶可不感知。 |
Label | 導入的Label。由用戶指定或系統自動生成。 |
Status | 導入完成狀態。
|
ExistingJobStatus | 已存在Label對應的導入作業的狀態。該字段只有當Status為Label Already Exists時才會顯示。您可以通過該狀態，知曉已存在Label對應的導入作業的狀態。
|
Message | 導入狀態的詳細說明。導入失敗時會返回具體的失敗原因。 |
NumberTotalRows | 從數據流中讀取到的總行數。 |
NumberLoadedRows | 導入任務的數據行數，僅在導入狀態為Success時有效。 |
NumberFilteredRows | 導入任務過濾掉的行數，即數據質量不合格的行。 |
NumberUnselectedRows | 通過Where條件被過濾掉的行數。 |
LoadBytes | 導入任務的源文件數據量大小。 |
LoadTimeMs | 導入任務所用的時間，單位為ms。 |
ErrorURL | 被過濾數據的具體內容，僅保留前1000條數據。如果導入任務失敗，可以直接用以下方式獲取被過濾的數據并進行分析，以調整導入任務。 |
取消導入任務
Stream Load可以通過停止進程來取消任務，Stream Load在超時或者導入錯誤后會被系統自動取消。
ps -ef | grep stream_load最佳實踐
應用場景
Stream Load的最佳使用場景是原始文件在內存中或者存儲在本地磁盤中。由于Stream Load是一種同步的導入方式，所以當您希望用同步方式獲取導入結果時，也可以使用該導入方式。
數據量
由于Stream Load是由BE發起的導入并分發數據，建議的導入數據量在1 GB到10 GB之間。系統默認的最大Stream Load導入數據量為10 GB，所以導入超過10 GB的文件需要修改BE的配置項streaming_load_max_mb。例如，待導入文件大小約為15 GB（15360 MB），則可以修改BE的配置項streaming_load_max_mb大于15 GB即可。
curl --location-trusted -u 'admin:****' -XPOST http://be-c-****-internal.starrocks.aliyuncs.com:8040/api/update_config?streaming_load_max_mb=15360Stream Load的默認超時為600秒，您可以登錄EMR Serverless控制臺，通過設置FE的參數來修改該參數值。
完整示例
數據情況：數據在客戶端本地磁盤路徑/mnt/disk1/customer.tbl中，希望導入到數據庫stream_load的表customer中。
標準數據下載：customer.tbl
集群情況：Stream Load的并發數不受集群大小影響。
示例如下：
當導入文件大小超過默認的最大導入大小時，需要修改BE的配置文件BE.conf。例如，修改參數streaming_load_max_mb，調整最大導入為15360 MB。
curl --location-trusted -u 'admin:*****' -XPOST http://be-c-****-internal.starrocks.aliyuncs.com:8040/api/update_config?streaming_load_max_mb=15360在EMR Serverless StarRocks實例配置頁面，修改參數stream_load_default_timeout_second，本示例調整超時時間為3600。
創建目標表customer。
CREATE TABLE `customer` ( `c_custkey` bigint(20) NULL COMMENT "", `c_name` varchar(65533) NULL COMMENT "", `c_address` varchar(65533) NULL COMMENT "", `c_nationkey` bigint(20) NULL COMMENT "", `c_phone` varchar(65533) NULL COMMENT "", `c_acctbal` double NULL COMMENT "", `c_mktsegment` varchar(65533) NULL COMMENT "", `c_comment` varchar(65533) NULL COMMENT "" ) ENGINE=OLAP DUPLICATE KEY(`c_custkey`) COMMENT "OLAP" DISTRIBUTED BY HASH(`c_custkey`) BUCKETS 24 PROPERTIES ( "replication_num" = "1", "in_memory" = "false", "storage_format" = "DEFAULT", "enable_persistent_index" = "false", "compression" = "LZ4" );創建導入任務。由于數據集較大，可以在后臺執行。
curl --location-trusted -u 'admin:*****' -T /mnt/disk1/customer.tbl -H "label:labelname" -H "column_separator:|" http://fe-c-****-internal.starrocks.aliyuncs.com:8030/api/load_test/customer/_stream_load返回信息如下。
{ "TxnId": 575, "Label": "labelname", "Status": "Success", "Message": "OK", "NumberTotalRows": 150000, "NumberLoadedRows": 150000, "NumberFilteredRows": 0, "NumberUnselectedRows": 0, "LoadBytes": 24196144, "LoadTimeMs": 1081, "BeginTxnTimeMs": 104, "StreamLoadPlanTimeMs": 106, "ReadDataTimeMs": 85, "WriteDataTimeMs": 850, "CommitAndPublishTimeMs": 20 }說明如果報錯
"ErrorURL": "http://***:8040/api/_load_error_log?file=error_log_***"，使用curl命令查看詳細信息即可。
代碼集成示例
Java開發Stream Load，詳情請參見stream_load。
Spark集成Stream Load，詳情請參見01_sparkStreaming2StarRocks。