Hologres:EXTERNAL_FILES

Configuração de permissões

O EXTERNAL_FILES acessa o OSS por meio de uma função RAM. Conclua as etapas a seguir antes de executar o EXTERNAL_FILES.

Etapa 1: Criar uma função RAM

1. Faça login no console RAM e acesse RAM Roles.

2. Clique em Create Role.

3. Na caixa de diálogo, defina Trusted Entity Type como Cloud Service e Trusted Entity como Real-time Data Warehouse Hologres.

4. Insira um nome para a função e conclua a criação.

Etapa 2: Conceder permissões do OSS à função

Anexe uma política do OSS à função RAM conforme as operações necessárias:

• Leitura de dados: Anexe AliyunOSSReadOnlyAccess.

• Gravação de dados: Anexe AliyunOSSFullAccess.

Etapa 3: Conceder a permissão GrantAssumeRole aos usuários RAM

Ignore esta etapa se o usuário que executa o SQL for uma conta Alibaba Cloud. Para usuários RAM, conceda a permissão GrantAssumeRole da seguinte forma:

1. No console RAM, acesse Policies e clique em Create Policy.

2. Mude para Script Editor e cole o JSON a seguir. Substitua <RoleARN> pelo ARN da função criada. Para localizar o ARN, consulte FAQ about RAM roles and STS tokens.

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

3. Anexe esta política ao usuário:

   • Para um usuário RAM: acesse Users > Permissions > Add Permissions.

   • Para uma função RAM: acesse Roles > Permissions > Add Permissions.

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://bucket/path',
    format = 'csv|parquet|orc',
    oss_endpoint = 'oss_endpoint',
    role_arn = 'acs:ram::xxx:role/xxx'
    [, other parameters...]
) [AS (col1 type1, col2 type2, ...)]

INSERT INTO target_table
SELECT * FROM EXTERNAL_FILES(
    path = 'oss://bucket/path',
    format = 'csv|parquet|orc',
    oss_endpoint = 'oss_endpoint',
    role_arn = 'acs:ram::xxx:role/xxx'
    [, other parameters...]
) [AS (col1 type1, col2 type2, ...)]

INSERT INTO EXTERNAL_FILES(
    path = 'oss://bucket/path',
    format = 'csv',
    oss_endpoint = 'oss_endpoint',
    role_arn = 'acs:ram::xxx:role/xxx'
    [, other parameters...]
) SELECT * FROM source_table;

Parâmetros comuns

Curingas com suporte em path

Parâmetros de leitura

Parâmetros de gravação

Consultar um arquivo CSV

Consulte um arquivo CSV com inferência automática de schema:

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'
);

Consulte um arquivo CSV com schema especificado manualmente:

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));

Consultar um arquivo 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'
);

Consultar um arquivo 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'
);

Importar dados para uma tabela do Hologres

-- Create the target table
CREATE TABLE orders (
    order_id int,
    customer_name text,
    amount decimal(10,2),
    PRIMARY KEY(order_id)
);

-- Import data from 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));

Exportar dados para o OSS

Exporte para múltiplos arquivos com limite de tamanho por arquivo:

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;

Exporte todos os dados para um único arquivo:

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;

Usar um grupo de recursos serverless

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'
);

Inferência automática

Se você omitir a cláusula AS, o Hologres infere o schema automaticamente:

• Parquet e ORC: O schema é inferido a partir dos metadados do arquivo.

• CSV com linha de cabeçalho: A inferência utiliza o cabeçalho e o conteúdo dos dados. Defina csv_skip_header = 'true' para evitar que a linha de cabeçalho seja lida como dado.

• CSV sem linha de cabeçalho: Todos os arquivos no caminho devem ter estruturas de colunas idênticas.

O Hologres verifica até schema_deduce_file_num arquivos (padrão: 5) e une todos os schemas encontrados.

Comportamento em caso de divergência de schema

Quando o schema inferido ou especificado não corresponde exatamente ao conteúdo do arquivo, o Hologres trata as divergências da seguinte maneira:

Exemplo: consulta de arquivos com colunas divergentes

Considere dois arquivos CSV no mesmo caminho:

orders_jan.csv — 3 colunas: order_id, customer_name, amount

orders_feb.csv — 4 colunas: order_id, customer_name, amount, region

Ao consultar o caminho sem especificar um schema, o Hologres une ambos os schemas. As linhas de orders_jan.csv retornam NULL na coluna region:

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'
);

Para evitar valores NULL inesperados, especifique o schema explicitamente usando a cláusula AS ou garanta que todos os arquivos compartilhem a mesma estrutura de colunas.

Mapeamento de tipos

Mapeamento de tipos ORC

Os tipos ORC UNION , STRUCT e MAP não têm suporte.

Mapeamento de tipos Parquet

Os tipos Parquet STRUCT e MAP não têm suporte.