E-MapReduce:Stream load

Sintaksis

curl --location-trusted -u <username>:<password> -XPUT <url>
(
    data_desc
)
[opt_properties]        

Parameter

• <username>:<password>: Username dan password untuk kluster StarRocks Anda. Parameter ini wajib diisi. Jika akun tidak memiliki password, gunakan <username>:.

• PUT: Metode permintaan HTTP yang wajib digunakan. Stream Load hanya mendukung metode PUT.

• <url>: URL tabel StarRocks tujuan. Parameter ini wajib diisi. Gunakan format berikut: http://<fe_host>:<fe_http_port>/api/<database_name>/<table_name>/_stream_load.

  Parameter	Wajib	Deskripsi
  <fe_host>	Ya	Alamat IP FE dalam kluster StarRocks.
  <fe_http_port>	Ya	Port HTTP FE. Default: 18030. Anda dapat menemukan nomor port dengan mencari parameter http_port pada tab Configure di halaman Services StarRocks. Selain itu, Anda juga dapat menjalankan perintah SHOW FRONTENDS untuk melihat alamat IP dan port HTTP node FE.
  <database_name>	Ya	Nama database yang berisi tabel tujuan.
  <table_name>	Ya	Nama tabel StarRocks tujuan.

• desc: Menjelaskan properti file data sumber, seperti nama file, format, pemisah kolom, pemisah baris, partisi tujuan, dan pemetaan kolom ke tabel StarRocks. Formatnya sebagai berikut.

  -T <file_path>
  -H "format: CSV | JSON"
  -H "column_separator: <column_separator>"
  -H "row_delimiter: <row_delimiter>"
  -H "columns: <column1_name>[, <column2_name>, ... ]"
  -H "partitions: <partition1_name>[, <partition2_name>, ...]"
  -H "temporary_partitions: <temporary_partition1_name>[, <temporary_partition2_name>, ...]"
  -H "jsonpaths: [ \"<json_path1>\"[, \"<json_path2>\", ...] ]"
  -H "strip_outer_array: true | false"
  -H "json_root: <json_path>"
  -H "ignore_json_size: true | false"
  -H "compression: <compression_algorithm> | Content-Encoding: <compression_algorithm>"

  Parameter dalam data_desc dapat dibagi menjadi tiga jenis: parameter umum, parameter khusus CSV, dan parameter khusus JSON.

  • Parameter umum

    Parameter	Wajib	Deskripsi
    <file_path>	Ya	Jalur ke file data sumber. Nama file boleh menyertakan ekstensi secara opsional.
    format	Tidak	Format data. Nilai yang valid: CSV dan JSON. Default: CSV.
    partitions	Tidak	Partisi tempat data dimuat. Jika parameter ini tidak ditentukan, data dimuat ke semua partisi tabel.
    temporary_partitions	Tidak	Partisi sementara tempat data dimuat.
    columns	Tidak	Menentukan pemetaan kolom antara file data sumber dan tabel StarRocks. Parameter ini tidak diperlukan jika kolom dalam file data sumber sesuai dengan urutan kolom dalam tabel tujuan. Jika kolom file sumber tidak sesuai dengan skema tabel, Anda harus menggunakan parameter ini untuk menentukan pemetaan. Anda dapat memetakan kolom dengan dua cara: Contoh 1: Tabel memiliki kolom c1, c2, c3, tetapi kolom file sumber berurutan c3, c2, c1. Anda harus menentukan -H "columns: c3, c2, c1". Contoh 2: Tabel memiliki tiga kolom c1, c2, c3, dan tiga kolom pertama file sumber dipetakan ke kolom tersebut, tetapi file memiliki kolom keempat yang tidak diperlukan. Dalam kasus ini, tentukan -H "columns: c1, c2, c3, temp", menggunakan placeholder untuk kolom tambahan. Contoh 3: Tabel memiliki tiga kolom year, month, day, tetapi file sumber hanya memiliki satu kolom timestamp dalam format 2018-06-01 01:02:03. Anda dapat menurunkan kolom tabel dengan menentukan -H "columns: col, year = year(col), month=month(col), day=day(col)".

  • Parameter khusus CSV

    Parameter	Wajib	Deskripsi
    column_separator	Tidak	Pemisah kolom dalam file data sumber. Default: \t. Untuk karakter non-printable, awali dengan \x dan gunakan nilai heksadesimal. Misalnya, untuk pemisah Hive \x01, tentukan -H "column_separator:\x01".
    row_delimiter	Tidak	Pemisah baris dalam file data sumber. Default: \n. Penting Saat menggunakan curl, shell mungkin menginterpretasikan \n sebagai string literal, bukan sebagai karakter baris baru. Dalam Bash, gunakan sintaksis $'string' untuk memastikan urutan escape seperti \n dan \t diinterpretasikan dengan benar. Contohnya: -H $'row_delimiter:\n'.
    skip_header	Tidak	Jumlah baris header yang dilewati di awal file CSV. Nilainya harus berupa bilangan bulat. Default: 0. Gunakan parameter ini untuk mengabaikan baris metadata, seperti nama atau tipe kolom, dalam file CSV. Misalnya, mengatur parameter ini ke 1 akan melewati baris pertama. Pemisah baris yang digunakan di sini harus sesuai dengan yang ditentukan dalam perintah pemuatan Anda.
    where	Tidak	Kondisi untuk memfilter baris mana yang akan dimuat. Sebagai contoh, untuk memuat hanya baris di mana kolom k1 bernilai 20180601, tentukan -H "where: k1 = 20180601".
    max_filter_ratio	Tidak	Rasio maksimum baris yang dapat dibuang karena kesalahan kualitas data. Default: 0 (toleransi nol). Catatan Ini tidak berlaku untuk baris yang difilter oleh kondisi where.
    partitions	Tidak	Partisi tujuan untuk pekerjaan pemuatan. Kami merekomendasikan untuk menentukan parameter ini jika Anda dapat menentukan partisi target. Data untuk partisi lain akan dibuang. Misalnya, untuk memuat data ke partisi p1 dan p2, tentukan -H "partitions: p1, p2".
    timeout	Tidak	Waktu tunggu untuk pekerjaan pemuatan, dalam detik. Default: 600. Nilainya harus antara 1 hingga 259200.
    strict_mode	Tidak	Mengaktifkan atau menonaktifkan mode ketat untuk pekerjaan pemuatan ini. Nilai yang valid: false (default): Mode ketat dinonaktifkan. true: Mode ketat diaktifkan. Saat diaktifkan, penyaringan ketat diterapkan pada konversi tipe kolom selama pemuatan.
    timezone	Tidak	Zona waktu untuk pekerjaan pemuatan. Default: Asia/Shanghai (UTC+08:00). Parameter ini memengaruhi semua fungsi terkait zona waktu yang digunakan dalam pemuatan.
    exec_mem_limit	Tidak	Batas memori untuk pekerjaan pemuatan. Default: 2 GB.

  • Parameter khusus JSON

    Parameter	Wajib	Deskripsi
    jsonpaths	Tidak	Menentukan field yang diekstraksi dari data JSON. Ini hanya diperlukan saat Anda perlu memetakan field sumber tertentu ke kolom tabel. Nilainya harus dalam format JSON.
    strip_outer_array	Tidak	Menentukan apakah struktur array terluar akan dihilangkan. Nilai yang valid: false (default): Mempertahankan struktur JSON asli. Seluruh array JSON diimpor sebagai satu nilai. Sebagai contoh, untuk data [{"k1" : 1, "k2" : 2},{"k1" : 3, "k2" : 4}], mengatur strip_outer_array ke false akan mengimpor data sebagai satu array. true: Jika data yang dimuat berupa array JSON, Anda perlu mengatur strip_outer_array ke true. Sebagai contoh, untuk data [{"k1" : 1, "k2" : 2},{"k1" : 3, "k2" : 4}], mengatur strip_outer_array ke true akan mengimpor data sebagai dua baris terpisah.
    json_root	Tidak	Menentukan elemen root data JSON yang akan diimpor. Parameter ini hanya diperlukan saat Anda memuat data JSON dengan mencocokkan field. Nilainya harus berupa string JsonPath yang valid. Default: kosong, yang berarti seluruh file JSON diimpor.
    ignore_json_size	Tidak	Menentukan apakah pemeriksaan ukuran badan JSON dalam permintaan HTTP akan dilewati. Catatan Secara default, ukuran badan JSON dalam permintaan HTTP tidak boleh melebihi 100 MB. Jika ukurannya melebihi batas ini, akan dikembalikan error: "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." Untuk memuat file yang lebih besar, tambahkan header "ignore_json_size:true" ke permintaan Anda untuk melewati pemeriksaan ini.
    compression, Content-Encoding	Tidak	Algoritma kompresi yang digunakan untuk badan permintaan. Algoritma yang didukung: GZIP, BZIP2, LZ4_FRAME, dan ZSTD. Contohnya: curl --location-trusted -u root: -v 'http://127.0.0.1:18030/api/db0/tbl_simple/_stream_load' \-X PUT -H "expect:100-continue" \-H 'format: json' -H 'compression: lz4_frame' -T ./b.json.lz4.

• opt_properties: Menentukan parameter opsional untuk impor. Parameter yang ditentukan berlaku untuk seluruh tugas impor.

  Formatnya sebagai berikut:

  -H "label: <label_name>"
  -H "where: <kondisi1>[, <kondisi2>, ...]"
  -H "max_filter_ratio: <num>"
  -H "timeout: <num>"
  -H "strict_mode: true | false"
  -H "timezone: <string>"
  -H "load_mem_limit: <num>"
  -H "partial_update: true | false"
  -H "partial_update_mode: row | column"
  -H "merge_condition: <column_name>"

  Parameter	Wajib	Deskripsi
  label	Tidak	Label unik untuk pekerjaan pemuatan. StarRocks mencegah penggunaan label yang sama untuk lebih dari satu pekerjaan yang berhasil. Anda dapat menggunakan label untuk mencegah pemuatan duplikat. StarRocks menyimpan label dari pekerjaan yang berhasil selama 30 menit.
  where	Tidak	Menentukan kondisi filter. StarRocks menerapkan filter ini ke data setelah transformasi apa pun dari parameter columns. Hanya data yang memenuhi klausa where yang diimpor. Sebagai contoh, untuk mengimpor hanya baris di mana kolom k1 bernilai 20180601, tentukan -H "where: k1 = 20180601".
  max_filter_ratio	Tidak	Rasio maksimum baris yang dapat dibuang karena kesalahan kualitas data. Default: 0 (toleransi nol). Catatan Ini tidak berlaku untuk baris yang difilter oleh kondisi where.
  log_rejected_record_num	Tidak	Menentukan jumlah maksimum baris yang ditolak untuk dicatat karena masalah kualitas data. Didukung sejak v3.1. Nilai yang valid: 0, -1, atau bilangan bulat positif. Default: 0. 0: Tidak ada baris yang ditolak yang dicatat. -1: Semua baris yang ditolak dicatat. Bilangan bulat positif, seperti n: Maksimal n baris yang ditolak dicatat di setiap node BE (atau CN).
  timeout	Tidak	Waktu tunggu pekerjaan pemuatan dalam detik. Default: 600. Nilainya harus antara 1 hingga 259200.
  strict_mode	Tidak	Menentukan apakah mode ketat diaktifkan untuk pekerjaan pemuatan ini. false (default): Mode ketat dinonaktifkan. true: Mode ketat diaktifkan.
  timezone	Tidak	Zona waktu untuk pekerjaan pemuatan. Default: Asia/Shanghai (UTC+08:00). Parameter ini memengaruhi semua fungsi terkait zona waktu yang digunakan dalam pemuatan.
  load_mem_limit	Tidak	Batas memori untuk pekerjaan pemuatan. Default: 2 GB.
  partial_update	Tidak	Mengaktifkan pembaruan kolom parsial. Nilai yang valid: true dan false. Default: false.
  partial_update_mode	Tidak	Menentukan mode untuk pembaruan parsial. Nilai yang valid: row dan column. row (default): Mode baris. Paling cocok untuk pembaruan real-time dengan banyak kolom dalam batch kecil. column: Mode kolom. Paling cocok untuk pembaruan batch beberapa kolom di banyak baris. Mode ini dapat meningkatkan performa secara signifikan. Sebagai contoh, jika Anda memperbarui 10 dari 100 kolom (10%) untuk semua baris dalam tabel, mode kolom dapat meningkatkan performa hingga 10 kali lipat.
  merge_condition	Tidak	Menentukan nama kolom yang digunakan sebagai kondisi pembaruan. Pembaruan pada baris hanya terjadi jika nilai data baru untuk kolom ini lebih besar dari atau sama dengan nilai yang sudah ada. Catatan Kolom yang ditentukan tidak boleh merupakan bagian dari primary key. Fitur ini hanya tersedia untuk tabel primary key.

Contoh

Contoh ini memuat data.csv ke tabel example_table dalam database load_test di kluster StarRocks. Untuk contoh lengkap, lihat Contoh pemuatan data lengkap.

curl --location-trusted -u "root:" \
     -H "Expect:100-continue" \
     -H "label:label2" \
     -H "column_separator: ," \
     -T data.csv -XPUT \
     http://172.17.**.**:18030/api/load_test/example_table/_stream_load

Nilai kembali

Saat tugas pemuatan selesai, hasilnya dikembalikan dalam format JSON. Berikut adalah contohnya.

{
    "TxnId": 9,
    "Label": "label2",
    "Status": "Success",
    "Message": "OK",
    "NumberTotalRows": 4,
    "NumberLoadedRows": 4,
    "NumberFilteredRows": 0,
    "NumberUnselectedRows": 0,
    "LoadBytes": 45,
    "LoadTimeMs": 235,
    "BeginTxnTimeMs": 101,
    "StreamLoadPlanTimeMs": 102,
    "ReadDataTimeMs": 0,
    "WriteDataTimeMs": 11,
    "CommitAndPublishTimeMs": 19
}

Nilai kembali mencakup parameter berikut:

wget "http://172.17.**.**:18040/api/_load_error_log?file=error_log_b74dccdcf0ceb4de_e82b2709c6c013ad"