Hologres：Fungsi EXTERNAL_FILES

Persyaratan versi

Instans Hologres Anda harus menjalankan versi V4.1 atau yang lebih baru. Jika instans Anda menggunakan versi sebelumnya, lakukan upgrade. Untuk informasi selengkapnya, lihat Instance upgrades.

Konfigurasi izin

Hanya Pengguna RAM atau Akun Alibaba Cloud yang dapat menggunakan EXTERNAL_FILES. Akun kustom tidak didukung. Sebelum menggunakan EXTERNAL_FILES, selesaikan langkah-langkah berikut. EXTERNAL_FILES mengakses OSS melalui Peran RAM. Pertama, buat Peran RAM dan berikan kepada layanan Hologres. Kemudian, berikan izin OSS kepada peran tersebut.

Buat peran

• Masuk ke Konsol RAM di RAM Roles. Buka halaman Roles dan klik Create Role.

• Pada kotak dialog, atur Trusted Entity Type ke Cloud Service dan Trusted Entity ke Real-time Data Warehouse Hologres.

• Masukkan nama peran dan selesaikan pembuatan.

Konfigurasi izin akses OSS

Berikan izin OSS kepada Peran RAM:

• Baca data: Berikan izin AliyunOSSReadOnlyAccess.

• Tulis data: Berikan izin AliyunOSSFullAccess.

Berikan izin GrantAssumeRole kepada pengguna SQL

Jika pengguna yang menjalankan SQL bukan Akun Alibaba Cloud, berikan izin GrantAssumeRole terlebih dahulu:

• Di Konsol RAM, buat kebijakan izin. Buka Policies > Create Policy > Script Editor. Tempel JSON berikut. Ganti Role_ARN dengan role_arn yang sama yang digunakan di EXTERNAL_FILES. Untuk menemukan Role ARN, lihat FAQ about RAM roles and STS tokens.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "hologram:GrantAssumeRole",
      "Resource": "<RoleARN>"
    }
  ]
}

Kemudian, sambungkan kebijakan ini ke pengguna yang menjalankan kueri. Untuk Pengguna RAM, buka Users > Permissions > Add Permissions. Untuk Peran RAM, buka Roles > Permissions > Add Permissions.

Parameter umum

Parameter baca

Parameter tulis

Contoh 1: Kueri file CSV

Lakukan kueri terhadap file CSV di OSS dan inferensi skema secara otomatis:

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/data/',
    format = 'csv',
    csv_skip_header = 'true',
    csv_delimiter = ',',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

Lakukan kueri terhadap file CSV dan tentukan skema secara manual:

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/data/',
    format = 'csv',
    csv_skip_header = 'true',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
) AS (id int, name text, amount decimal(10,2));

Contoh 2: Kueri file Parquet

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/parquet_data/',
    format = 'parquet',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

Contoh 3: Kueri file ORC

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/orc_data/',
    format = 'orc',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

Contoh 4: Impor data ke tabel Hologres

-- Buat tabel target
CREATE TABLE orders (
    order_id int,
    customer_name text,
    amount decimal(10,2),
    PRIMARY KEY(order_id)
);

-- Impor data dari OSS
INSERT INTO orders 
SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/orders/',
    format = 'csv',
    csv_skip_header = 'true',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
) AS (order_id int, customer_name text, amount decimal(10,2));

Contoh 5: Ekspor data ke OSS

Ekspor data ke beberapa file:

INSERT INTO EXTERNAL_FILES(
    path = 'oss://mybucket/export/',
    format = 'csv',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role',
    target_file_size_mb = '100'
) SELECT * FROM orders;

Ekspor data ke satu file:

INSERT INTO EXTERNAL_FILES(
    path = 'oss://mybucket/export/',
    format = 'csv',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role',
    single_file = 'true'
) SELECT * FROM orders;

Contoh 6: Gunakan kelompok sumber daya arsitektur tanpa server

SET hg_computing_resource = 'serverless';

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/data/',
    format = 'csv',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

Inferensi skema otomatis

Jika Anda tidak menentukan skema menggunakan klausa AS, Hologres akan melakukan inferensi skema secara otomatis:

• Parquet/ORC: Inferensi dari metadata file.

• CSV dengan header: Inferensi dari baris pertama (header) dan konten data.

• CSV tanpa header: Semua file harus memiliki skema yang identik.

Hologres memindai jumlah file yang ditentukan oleh parameter schema_deduce_file_num dan menggabungkan semua skema yang ditemukan.

Perilaku inferensi skema

Pemetaan tipe

Saat EXTERNAL_FILES membaca file ORC atau Parquet, tipe data dalam file tersebut dipetakan ke tipe PostgreSQL. Pemetaan tersebut tercantum di bawah ini. Tipe yang tidak didukung dicantumkan setelah setiap tabel.

Pemetaan tipe ORC

Pemetaan tipe Parquet