orc external table - MaxCompute: Central de Documentação do Alibaba Cloud

Restrições

Tabelas externas do OSS não suportam a propriedade de cluster.
O tamanho de um único arquivo não pode exceder 2 GB. Divida arquivos maiores que 2 GB.
O MaxCompute e o OSS devem estar na mesma região.

Criar uma tabela externa

Sintaxe

Se o schema do arquivo ORC e o da tabela externa não coincidirem, o MaxCompute tratará as diferenças da seguinte forma:

Menos colunas no arquivo do que na tabela: O sistema preenche as colunas ausentes com NULL.
Mais colunas no arquivo do que na tabela: O sistema descarta as colunas excedentes.
Incompatibilidade de tipo: O tipo STRING lê dados INT de arquivos ORC, mas essa prática não é recomendada. O tipo INT, ao ler dados STRING, converte valores não numéricos para NULL e aceita valores numéricos.

Use a sintaxe simplificada ou a completa para criar uma tabela externa ORC.

Sintaxe simplificada (recomendada)

Use esta sintaxe para que o MaxCompute gerencie a autorização automaticamente com a função RAM padrão.

CREATE EXTERNAL TABLE [IF NOT EXISTS] <mc_oss_extable_name>
(
  <col_name> <data_type>,
  ...
)
[COMMENT <table_comment>]
[PARTITIONED BY (<col_name> <data_type>, ...)]
STORED AS orc
LOCATION '<oss_location>';

Sintaxe completa

CREATE EXTERNAL TABLE [IF NOT EXISTS] <mc_oss_extable_name>
(
  <col_name> <data_type>,
  ...
)
[COMMENT <table_comment>]
[PARTITIONED BY (<col_name> <data_type>, ...)]
ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.orc.OrcSerde'
WITH serdeproperties(
    'odps.properties.rolearn'='acs:ram::<uid>:role/aliyunodpsdefaultrole'
)
STORED AS orc
LOCATION '<oss_location>'
tblproperties (
    '<xxx>'='<yyy>'
);

Parâmetros comuns

Para mais informações sobre parâmetros comuns, consulte Parâmetros básicos de sintaxe.

Parâmetros específicos de formato

WITH serdeproperties

Propriedade	Quando usar	Valor	Padrão
`mcfed.orc.schema.resolution`	Os arquivos ORC na mesma tabela externa possuem schemas inconsistentes.	`name` — mapeia colunas por nome.	`position` — mapeia colunas por posição.

tblproperties

Propriedade	Quando usar	Descrição	Valor	Padrão
`mcfed.orc.compress`	Gravar dados ORC no OSS em formato compactado.	Algoritmo de compactação para arquivos de saída ORC.	`SNAPPY`, `ZLIB` ou `ZSTD`	Nenhum
`io.compression.codecs`	Os arquivos de dados no OSS estão no formato Raw-Snappy.	Permite ao MaxCompute ler dados compactados com Raw-Snappy.	`com.aliyun.odps.io.compress.SnappyRawCodec`	Nenhum
`odps.external.data.output.prefix` (ou `odps.external.data.prefix`)	Adicionar um prefixo personalizado aos arquivos de saída.	String de prefixo. Caracteres permitidos: letras, dígitos e sublinhados (a–z, A–Z, 0–9, _). Comprimento: 1–10 caracteres.	Exemplo: `mc_`	Nenhum
`odps.external.data.enable.extension`	Controlar se os arquivos de saída incluem extensão.	`True` exibe a extensão; `False` a oculta.	`True` ou `False`	`False`
`odps.external.data.output.suffix`	Adicionar um sufixo personalizado aos arquivos de saída.	String de sufixo. Caracteres permitidos: letras, dígitos e sublinhados.	Exemplo: `_hangzhou`	Nenhum
`odps.external.data.output.explicit.extension`	Adicionar uma extensão personalizada aos arquivos de saída. Tem prioridade sobre `odps.external.data.enable.extension`.	String de extensão. Caracteres permitidos: letras, dígitos e sublinhados. Comprimento: 1–10 caracteres.	Exemplo: `jsonl`	Nenhum
`mcfed.orc.batch.size`	Ajustar o uso de memória e o throughput de processamento.	Número de linhas processadas por lote (tamanho do lote ORC).	Inteiro não negativo	`1000`

Gravar dados

Para detalhes sobre a sintaxe de gravação no MaxCompute, consulte Sintaxe de gravação.

Consultar dados

Consulte Sintaxe de consulta para obter detalhes sobre a sintaxe SELECT.
Veja Otimização de consulta para saber como otimizar planos de consulta.
Ativar pushdown de predicado

O pushdown de predicado (PPD) melhora o desempenho de consultas em tabelas externas ORC ao enviar condições de filtro para a camada de varredura de dados. Esse recurso exige o modo nativo (odps.ext.oss.orc.native=true).

Adicione as instruções abaixo antes da consulta SQL:
```
-- Enable the ORC native reader
SET odps.ext.oss.orc.native=true;

-- Enable ORC predicate pushdown
SET odps.storage.orc.use.predicate.pushdown=true;
```

Exemplo

Este exemplo cria uma tabela externa ORC com compactação SNAPPY, adiciona uma partição existente, lê dados e grava uma nova linha.

Pré-requisitos

Você já criou um projeto do MaxCompute.
Prepare um bucket e um diretório no OSS. Para mais informações, consulte Criar um bucket e Gerenciar diretórios.

Certifique-se de que o bucket esteja na mesma região do projeto do MaxCompute.
Conceda permissões.
1. Verifique se você tem permissão para acessar o OSS. Acesse a tabela externa do OSS usando uma conta Alibaba Cloud, um usuário RAM ou uma função RAM. Para mais informações sobre concessão de permissões, consulte Autorização no modo STS para OSS.
2. Garanta que você possui a permissão CreateTable no projeto do MaxCompute. Para mais informações sobre permissões relacionadas a tabelas, consulte Permissões do MaxCompute.

Etapa 1: Preparar o arquivo de dados

Com os dados de amostra fornecidos, crie o caminho orc_snappy/dt=20250526 no bucket oss-mc-test. Faça upload do arquivo snappy para a pasta da partição dt=20250526.

Etapa 2: Criar a tabela externa

CREATE EXTERNAL TABLE orc_data_type_snappy
(
    vehicleId INT,
    recordId INT,
    patientId INT,
    calls INT,
    locationLatitute DOUBLE,
    locationLongitude DOUBLE,
    recordTime STRING,
    direction STRING
)
PARTITIONED BY (dt STRING)
ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.orc.OrcSerde'
WITH serdeproperties (
    'odps.properties.rolearn'='acs:ram::<uid>:role/aliyunodpsdefaultrole'
)
STORED AS ORC
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/oss-mc-test/orc_snappy/'
tblproperties (
    'mcfed.orc.compress'='SNAPPY'
);

Etapa 3: Adicionar partições existentes

Em tabelas externas particionadas, execute MSCK REPAIR TABLE para registrar as partições existentes do OSS no MaxCompute. Para a sintaxe completa, consulte Adicionar partições a uma tabela externa do OSS.

MSCK REPAIR TABLE orc_data_type_snappy ADD PARTITIONS;

Etapa 4: Ler dados

SELECT * FROM orc_data_type_snappy WHERE dt = '20250526' LIMIT 10;

A consulta retorna:

+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+
| vehicleid  | recordid   | patientid  | calls      | locationlatitute | locationlongitude | recordtime     | direction  | dt         |
+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+
| 1          | 12         | 76         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:10 | SW         | 20250526   |
| 1          | 1          | 51         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:00 | S          | 20250526   |
| 1          | 2          | 13         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:01 | NE         | 20250526   |
| 1          | 3          | 48         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:02 | NE         | 20250526   |
| 1          | 4          | 30         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:03 | W          | 20250526   |
| 1          | 5          | 47         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:04 | S          | 20250526   |
| 1          | 6          | 9          | 1          | 46.81006         | -92.08174         | 9/14/2014 0:05 | S          | 20250526   |
| 1          | 7          | 53         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:06 | N          | 20250526   |
| 1          | 8          | 63         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:07 | SW         | 20250526   |
| 1          | 9          | 4          | 1          | 46.81006         | -92.08174         | 9/14/2014 0:08 | NE         | 20250526   |
| 1          | 10         | 31         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:09 | N          | 20250526   |
+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+

Etapa 5: Gravar dados

INSERT INTO orc_data_type_snappy PARTITION (dt = '20250526')
  VALUES (1, 16, 76, 1, 46.81006, -92.08174, '9/14/2014 0:10', 'SW');

-- Verify the inserted row
SELECT * FROM orc_data_type_snappy WHERE dt = '20250526' AND recordid = 16;

A consulta retorna:

+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+
| vehicleid  | recordid   | patientid  | calls      | locationlatitute | locationlongitude | recordtime     | direction  | dt         |
+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+
| 1          | 16         | 76         | 1          | 46.81006         | -92.08174         | 9/14/2014 0:10 | SW         | 20250526   |
+------------+------------+------------+------------+------------------+-------------------+----------------+------------+------------+

Tipos de dados suportados

Para obter a lista completa dos tipos de dados do MaxCompute, consulte Tipos de dados versão 1.0 e Tipos de dados versão 2.0.

O MaxCompute oferece dois modos para leitura de tabelas externas ORC:

Modo JNI (SET odps.ext.oss.orc.native=false;): Suporta operações de leitura e gravação.
Modo Nativo (SET odps.ext.oss.orc.native=true;): Suporta apenas operações de leitura.

Tipo de dado	Modo JNI (leitura e gravação)	Modo Nativo (somente leitura)
TINYINT	Suportado	Suportado
SMALLINT	Suportado	Suportado
INT	Suportado	Suportado
BIGINT	Suportado	Suportado
BINARY	Suportado	Suportado
FLOAT	Suportado	Suportado
DOUBLE	Suportado	Suportado
DECIMAL(precision,scale)	Suportado	Suportado
VARCHAR(n)	Suportado	Suportado
CHAR(n)	Suportado	Suportado
STRING	Suportado	Suportado
DATE	Suportado	Suportado
DATETIME	Não suportado	Suportado
TIMESTAMP	Não suportado	Não suportado
TIMESTAMP_NTZ	Suportado	Não suportado
BOOLEAN	Suportado	Suportado
ARRAY	Suportado	Suportado
MAP	Suportado	Suportado
STRUCT	Suportado	Suportado
JSON	Não suportado	Não suportado

Formatos de compactação suportados

Para ler ou gravar arquivos ORC compactados, adicione a propriedade mcfed.orc.compress à seção with serdeproperties durante a criação da tabela. Consulte WITH serdeproperties.
Formatos suportados: ORC compactado com SNAPPY, ZLIB ou ZSTD.

Evolução de schema

Tabelas externas ORC aceitam dois métodos para mapear colunas da tabela para campos de arquivo ORC: mapeamento por posição e mapeamento por nome.

Mapeamento por posição (padrão): Defina 'mcfed.orc.schema.resolution'='position' ou omita a propriedade. As colunas são correspondidas pela ordem; portanto, a ordem das colunas da tabela deve coincidir exatamente com a ordem dos campos no arquivo ORC.
Mapeamento por nome: Defina 'mcfed.orc.schema.resolution'='name'. As colunas são correspondidas pelo nome, independentemente da ordem.

Nota

A tabela a seguir mostra quais operações de alteração de schema são compatíveis com cada método de mapeamento. "Compatível" significa que tanto os dados recém-gravados quanto os históricos podem ser lidos corretamente após a operação.

Alteração de schema	Modo de mapeamento	Suportado	Descrição	Compatibilidade de dados
Adicionar coluna	Por posição	Suportado	Novas colunas são anexadas ao final. Não é possível especificar a posição. Os valores padrão para colunas adicionadas aplicam-se apenas aos dados gravados pelo MaxCompute após a alteração.	Novos dados correspondentes ao schema atualizado são lidos normalmente. Dados históricos gravados antes da alteração são lidos com o novo schema. Por exemplo, após adicionar uma coluna, linhas históricas sem essa nova coluna retornam NULL para ela.
Adicionar coluna	Por nome	Suportado
Excluir coluna	Por posição	Não suportado	Não recomendado. O mapeamento por posição exige que a ordem das colunas no DDL corresponda à do arquivo. Após excluir uma coluna, os schemas do DDL e do arquivo divergem, causando erros de leitura.	Novos dados correspondentes ao schema atualizado são lidos normalmente. Dados históricos gravados antes da alteração são lidos com o novo schema. Por exemplo, após excluir uma coluna, dados históricos que ainda a contêm causam erros de leitura.
Excluir coluna	Por nome	Suportado	O mapeamento por nome associa colunas pelo nome, independentemente da ordem.	Compatível
Modificar ordem das colunas	Por posição	Não suportado	Não recomendado. O mapeamento por posição exige que a ordem das colunas no DDL corresponda à do arquivo. Após reordenar as colunas, os schemas do DDL e do arquivo divergem, causando erros de leitura.	Novos dados correspondentes ao schema atualizado são lidos normalmente. Dados históricos gravados antes da alteração são lidos com o novo schema. Por exemplo, após reordenar as colunas, os dados históricos mantêm a ordem original, causando desalinhamento entre schema e dados.
Modificar ordem das colunas	Por nome	Suportado	O mapeamento por nome associa colunas pelo nome, independentemente da ordem.	Compatível
Alterar tipo de dado da coluna	Por posição	Suportado	Para conversões de tipo permitidas, consulte Alterar tipo de dado da coluna.	Compatível
Alterar tipo de dado da coluna	Por nome	Suportado		Compatível
Renomear coluna	Por posição	Suportado		Compatível
Renomear coluna	Por nome	Não suportado	Não recomendado. O mapeamento por nome associa colunas pelo nome. Após renomear uma coluna, arquivos existentes com o nome original deixam de ter correspondência.	Novos dados correspondentes ao schema atualizado são lidos normalmente. Dados históricos gravados antes da alteração são lidos com o novo schema. Por exemplo, após renomear uma coluna, se o schema do arquivo ORC ainda usar o nome original, a coluna retornará NULL na leitura.
Modificar comentário da coluna	Por posição	Suportado	O comentário deve ser uma string válida com no máximo 1.024 bytes.	Compatível
Modificar comentário da coluna	Por nome	Suportado		Compatível
Modificar nulabilidade da coluna	Por posição	Não suportado	As colunas aceitam valores nulos por padrão.	Não aplicável
Modificar nulabilidade da coluna	Por nome	Não suportado	As colunas aceitam valores nulos por padrão.	Não aplicável