Object Table - MaxCompute: Central de Documentação do Alibaba Cloud

Uma Object Table mapeia um diretório do OSS para uma tabela de metadados consultável no MaxCompute. Esse recurso permite que o mecanismo SQL leia, filtre e processe dados não estruturados — imagens, vídeos, PDFs, arquivos de log — na mesma escala dos dados estruturados, sem mover arquivos do OSS.

Com uma Object Table, é possível:

Query file metadata with SQL — listar todos os objetos em um diretório do OSS e filtrar por nome, tamanho, tipo ou hora da última modificação com instruções SELECT padrão.
Ler o conteúdo do objeto em escala — usar a função integrada GET_DATA_FROM_OSS em consultas SQL para transmitir o conteúdo do objeto aos workers de computação distribuída e permitir processamento em larga escala.
Manter os metadados sempre atualizados — armazenar metadados do OSS em cache no MaxCompute e configurar atualizações manuais, periódicas ou agendadas para garantir sincronização com alterações no OSS.
Processar dados não estruturados com lógica personalizada — carregar imagens personalizadas para criar UDFs (funções definidas pelo usuário) executadas junto ao mecanismo SQL, gravando resultados em tabelas internas ou externas. Em uma versão futura, as Object Tables também oferecerão suporte à gravação de resultados não estruturados de volta no OSS.
Usar o mecanismo Maxframe — as Object Tables oferecem suporte ao mecanismo Maxframe para o ecossistema Python.

Criar uma Object Table não copia nem modifica seus dados no OSS. O MaxCompute armazena em cache apenas os metadados do objeto. Os arquivos reais permanecem no OSS.

Pré-requisitos

Antes de começar, verifique se você tem:

Um projeto do MaxCompute com o recurso Schema ativado. Consulte Ativar o recurso Schema.
O sistema de tipos de dados do MaxCompute 2.0 ativado no projeto.
Concluído a autorização com um clique para a função AliyunODPSDefaultRole, que concede acesso do MaxCompute ao OSS por meio de um token do Security Token Service (STS). A autorização com um clique só está disponível quando o ProjectOwner do projeto MaxCompute é a mesma conta Alibaba Cloud proprietária do bucket do OSS.

Limitações

As Object Tables não oferecem suporte a partições.
Atualizações manuais e periódicas são sempre completas.

Faturamento

Armazenamento de metadados: O MaxCompute cobra taxas de armazenamento pelos metadados em cache em uma Object Table. Consulte Taxas de armazenamento. O OSS cobra separadamente pelos dados reais armazenados e acessados nos buckets. Consulte Taxas de armazenamento do OSS.

Tarefas de atualização: O valor de inputsize para cada arquivo verificado durante uma atualização baseia-se no tamanho dos metadados, não no tamanho real do arquivo. Os custos de atualização variam conforme o número de arquivos, independentemente do tamanho deles. Consulte Faturamento de SQL para tabelas externas.

Computação: Executar consultas em uma Object Table gera taxas de computação.

Pagamento conforme o uso: Consultas de metadados são faturadas como consultas de tabela interna. Consulte Faturamento padrão de SQL. Consultas que leem conteúdo de objetos do OSS via GET_DATA_FROM_OSS são faturadas como consultas de tabela externa. Consulte Faturamento de SQL para tabelas externas.
Assinatura: Consome recursos de computação por assinatura. Consulte Taxas de computação (Assinatura).

Crie uma Object Table

Sintaxe

CREATE OBJECT TABLE [IF NOT EXISTS] <objecttable_name>
WITH SERDEPROPERTIES ('<key>' = '<value>')
LOCATION '<location>'
[TBLPROPERTIES ('<key>' = '<value>')]
[COMMENT '<comment>'];

Não é necessário definir colunas. O MaxCompute fornece as colunas de metadados automaticamente.

Parâmetros

Parâmetro	Obrigatório	Descrição
`objecttable_name`	Sim	Nome da tabela.
`SERDEPROPERTIES`	Sim	Especifica a função RAM para autenticação. A chave é `odps.properties.rolearn` e o valor é o ARN da função no formato `acs:ram::<uid>:role/aliyunodpsdefaultrole`. Se omitido, usa-se a função `AliyunODPSDefaultRole` da conta Alibaba Cloud atual. Para obter o UID da conta, consulte Visualize informações do usuário RAM. Para detalhes sobre autorização no modo STS, consulte Conceder permissões a uma função RAM comum no modo STS para o OSS.
`location`	Sim	Caminho do OSS a ser mapeado. Formato: `oss://<oss_endpoint>/<bucket_name>/<oss_directory_name>/`. A Object Table indexa todos os objetos nesse diretório. Use um endpoint de rede interna, não um público, pois endpoints públicos causam erros de conexão. Para obter o endpoint interno: faça logon no console do OSS, na página Buckets clique em Bucket Name desejado para abrir a página Objects. Em seguida, na seção Port da página Overview, obtenha o Endpoint para Access from ECS over the Classic Network (internal network).
`metadata.cache.mode`	Não	Modo de acionamento da atualização. Consulte Escolha um modo de atualização. Padrão: `manual`.
`metadata.staleness.seconds`	Não	Intervalo de atualização em segundos para o modo `periodic`. Faixa: 1–604800 (1 segundo a 1 semana). Não é uma garantia estrita; o agendador usa esse valor como meta. Obrigatório quando `metadata.cache.mode` é `periodic`.
`metadata.crontab.expression`	Não	Expressão Cron para o modo `crontab`. Por exemplo, `0 0 14 * * ?` executa uma atualização diariamente às 14h. Obrigatório quando `metadata.cache.mode` é `crontab`.
`comment`	Não	Comentário sobre a tabela.

Exemplo

SET odps.namespace.schema=true;

CREATE OBJECT TABLE ot_demo_day
WITH SERDEPROPERTIES (
  'odps.properties.rolearn'='acs:ram::xxxxxx:role/aliyunodpsdefaultrole'
)
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/odps-external-****/ottest/';

Visualize propriedades da Object Table

DESC <object_table_name>;

Exemplo:

DESC ot_demo_day;

A saída lista o proprietário da tabela, projeto, Schema, carimbos de data/hora e colunas de metadados nativas:

+------------------------------------------------------------------------------------+
| Owner:                    ALIYUN$****@test.aliyunid.com                            |
| Project:                  test_objecttable                                         |
| Schema:                   default                                                  |
| TableComment:                                                                      |
+------------------------------------------------------------------------------------+
| CreateTime:               2024-09-02 20:01:56                                      |
| LastDDLTime:              2024-09-02 20:01:56                                      |
| LastModifiedTime:         2024-09-02 20:01:56                                      |
+------------------------------------------------------------------------------------+
| InternalTable: YES      | Size: 0                                                  |
+------------------------------------------------------------------------------------+
| Native Columns:                                                                    |
+------------------------------------------------------------------------------------+
| Field              | Type          | Label | Comment                               |
+------------------------------------------------------------------------------------+
| key                | varchar(2048) |       | The name of the object.               |
| size               | bigint        |       | The size of the object in bytes.      |
| type               | varchar(32)   |       | Object type: Normal, Multipart, Appendable, or Symlink. |
| last_modified      | timestamp     |       | The last modified time of the object. |
| storage_class      | varchar(32)   |       | The storage class of the object.      |
| etag               | varchar(64)   |       | The ETag of the object.               |
| restore_info       | varchar(256)  |       | Restoration status from cold storage. |
| owner_id           | bigint        |       | The ID of the bucket owner.           |
| owner_display_name | varchar(256)  |       | The display name of the bucket owner. |
+------------------------------------------------------------------------------------+

As colunas nativas fornecem os seguintes metadados:

Coluna	Tipo	Anulável	Descrição
`key`	VARCHAR(2048) — limite de comprimento nativo: 1.023 caracteres	Não	Caminho relativo do objeto dentro da Object Table. Consulte Convenções de nomenclatura de objetos do OSS.
`size`	BIGINT	Não	Tamanho do objeto em bytes.
`type`	VARCHAR(32)	Não	Tipo de objeto do OSS: `Normal`, `Multipart`, `Appendable` ou `Symlink`.
`last_modified`	TIMESTAMP_NTZ	Não	Hora da última modificação do objeto no OSS.
`storage_class`	VARCHAR(32)	Não	Classe de armazenamento do OSS. Consulte Classe de armazenamento.
`etag`	VARCHAR(64)	Não	Tag de entidade gerada na criação do objeto. Identifica se o conteúdo do objeto mudou entre atualizações, mas não funciona como identificador exclusivo.
`restore_info`	VARCHAR(256)	Sim	Status de restauração para objetos arquivados. Preenchido apenas durante uma restauração em andamento.
`owner_id`	BIGINT	Sim	ID do proprietário do objeto.
`owner_display_name`	VARCHAR(256)	Sim	Nome de exibição do proprietário do objeto.

Visualize a instrução DDL de uma Object Table

SHOW CREATE TABLE <object_table_name>;

Exemplo:

SHOW CREATE TABLE ot_demo_day;

Saída de exemplo:

CREATE OBJECT TABLE IF NOT EXISTS yunqi_object_****.`default`.ot_demo_day
WITH SERDEPROPERTIES (
  'serialization.format'='1',
  'odps.properties.rolearn'='acs:ram::139699392458****:role/aliyunodpsdefaultrole')
LOCATION
  'oss://oss-cn-hangzhou-internal.aliyuncs.com/odps-external-****/ottest/'
TBLPROPERTIES (
  'last_modified_time'='1731478307',
  'transient_lastDdlTime'='1731478307',
  'metadata.cache.mode'='manual',
  'metadata.staleness.seconds'='3600');

Atualizar metadados da Object Table

O MaxCompute armazena em cache os metadados de objetos do OSS e executa consultas nesse cache. Atualize o cache antes de executar consultas para garantir que os metadados reflitam o estado atual do diretório no OSS.

Escolha um modo de atualização

Selecione um modo de atualização ao criar a tabela ou mantenha o padrão (manual).

Modo	Acionador	Indicado quando	Parâmetro obrigatório
`manual` (padrão)	`ALTER TABLE ... REFRESH METADATA`	As alterações são pouco frequentes ou você precisa de controle total sobre o momento da execução	—
`periodic`	Automático, em intervalo fixo	Os arquivos mudam frequentemente e você deseja manutenção com baixa intervenção	`metadata.staleness.seconds`
`crontab`	Automático, conforme cronograma cron	São necessárias atualizações em horários específicos do dia ou da semana	`metadata.crontab.expression`

Atualização manual

Execute o comando a seguir para acionar uma atualização completa de metadados:

ALTER TABLE <objecttable_name> REFRESH METADATA;

Exemplo:

ALTER TABLE ot_demo_day REFRESH METADATA;

Atualização periódica

Defina metadata.cache.mode como periodic e especifique metadata.staleness.seconds ao criar a tabela. O agendador aciona uma atualização completa aproximadamente no intervalo especificado.

SET odps.namespace.schema=true;
SET odps.sql.type.system.odps2 = true;

CREATE OBJECT TABLE ot_demo_day
WITH SERDEPROPERTIES (
  'odps.properties.rolearn'='acs:ram::xxxxxx:role/aliyunodpsdefaultrole'
)
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/odps-external-****/ottest/'
TBLPROPERTIES (
  'metadata.cache.mode' = 'periodic',
  'metadata.staleness.seconds' = '3600'
);

O parâmetro metadata.staleness.seconds aceita valores entre 1 e 604800 (1 segundo a 1 semana). Esse valor não é uma garantia estrita — o agendador o utiliza como meta.

Atualização agendada

Defina metadata.cache.mode como crontab e especifique metadata.crontab.expression ao criar a tabela. Use uma expressão cron padrão para definir o cronograma exato.

SET odps.namespace.schema=true;
SET odps.sql.type.system.odps2 = true;

CREATE OBJECT TABLE ot_demo_day
WITH SERDEPROPERTIES (
  'odps.properties.rolearn'='acs:ram::xxxxxx:role/aliyunodpsdefaultrole'
)
LOCATION 'oss://oss-cn-region-internal.aliyuncs.com/odps-external-****/ottest/'
TBLPROPERTIES (
  'metadata.cache.mode' = 'crontab',
  'metadata.crontab.expression' = '0 0 14 * * ?'
);

A expressão cron 0 0 14 * * ? executa uma atualização às 14h todos os dias: 0 (segundo), 0 (minuto), 14 (hora), * (qualquer dia do mês), * (qualquer mês), ? (dia da semana — mutuamente exclusivo com dia do mês).

Visualize histórico de tarefas de atualização

Verifique o status das tarefas de atualização anteriores com:

SHOW refresh task history FOR object TABLE <object_table_name>;

Exemplo e saída:

-- View refresh task history for ot_demo_day04.
SHOW refresh task history FOR object TABLE ot_demo_day04;

ID = 20260105*******f
+---------------------------------------------------------------------------------------------------+
| Project:                  test_project                                                            |
| Schema:                   default                                                                 |
| Task:                     ***                                                                     |
+---------------------------------------------------------------------------------------------------+
| History:                                                                                          |
+---------------------------------------------------------------------------------------------------+
| InstanceId                       | CreateTime             | EndTime                | Status       |
+---------------------------------------------------------------------------------------------------+
| 20260105******************ks     | 2026-01-05 14:12:00    | 2026-01-05 14:12:04    | Terminated   |
| 20260105******************y3     | 2026-01-05 14:10:00    | 2026-01-05 14:10:03    | Terminated   |
+---------------------------------------------------------------------------------------------------+

OK

A saída contém uma linha por tarefa: InstanceId, CreateTime, EndTime e Status. Se uma tarefa exibir Failed, execute wait <InstanceId>; e verifique a saída do Logview para obter detalhes.

Consultar uma Object Table

Execute uma instrução SELECT padrão para consultar metadados de objetos:

SELECT * FROM <object_table_name>;

Exemplo — visualize os primeiros cinco registros:

SELECT * FROM ot_demo_day LIMIT 5;

É possível aplicar qualquer operação SQL aos metadados: agregações, junções, funções de janela, ORDER BY, LIMIT e filtros com pushdown de condições.

Ler o conteúdo do objeto

Consultar uma Object Table opera apenas nos metadados em cache — nenhum conteúdo de objeto é lido do OSS. Para processar o conteúdo real dos objetos, use a função integrada GET_DATA_FROM_OSS nas consultas SQL.

GET_DATA_FROM_OSS

A função GET_DATA_FROM_OSS lê parte ou todo o conteúdo de um objeto e o retorna como valor binário. Todos os exemplos abaixo usam o caminho de três níveis project.schema.object_table para identificar a Object Table.

BINARY GET_DATA_FROM_OSS (
  STRING <full_object_table_name>,
  STRING <key>
  [, BIGINT <offset>]
  [, BIGINT <length>]
  [, STRING <object_not_found_policy>]
)

Parâmetro	Obrigatório	Tipo	Padrão	Descrição
`full_object_table_name`	Sim	STRING	—	Caminho completo de três níveis para a Object Table: `project.schema.object_table`. Usado para gerar um token STS para acesso ao OSS quando a autenticação por função RAM (RoleARN) estiver configurada.
`key`	Sim	STRING	—	Valor da `key` da linha da Object Table — o caminho relativo do objeto a ser lido.
`offset`	Não	BIGINT	`0`	Deslocamento em bytes para iniciar a leitura. Deve ser >= 0.
`length`	Não	BIGINT	`-1` (sem limite)	Número de bytes a serem lidos.
`object_not_found_policy`	Não	STRING	`OUTPUT_NULL`	Ação a ser tomada quando uma chave em cache não existir mais no OSS. `OUTPUT_NULL`: retorna NULL sem erro. `THROW_EXCEPTION`: gera um erro e interrompe a tarefa. `WARN_AND_NULL`: retorna NULL e registra um aviso — se isso ocorrer para muitos objetos, o desempenho geral da tarefa poderá degradar.

A função GET_DATA_FROM_OSS retorna dados binários. Envolva-a em STRING() para obter um resultado em string.

Exemplos

Converter o resultado para STRING:

SELECT STRING(
  GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 0, -1, 'OUTPUT_NULL')
)
FROM ot_demo_day;

Chamadas equivalentes — todas as opções a seguir leem o conteúdo completo de cada objeto com as configurações padrão (offset=0, length=-1, policy=OUTPUT_NULL):

-- Full explicit form
SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 0, -1, 'OUTPUT_NULL') FROM ot_demo_day;

-- Equivalent shorthand forms
SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key) FROM ot_demo_day;

SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 0) FROM ot_demo_day;

SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 0, -1) FROM ot_demo_day;

SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 'OUTPUT_NULL') FROM ot_demo_day;

SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 0, 'OUTPUT_NULL') FROM ot_demo_day;

Considerações de desempenho

Quando uma consulta SQL baixa conteúdo de objetos do OSS via GET_DATA_FROM_OSS, a estratégia de fragmentação padrão do MaxCompute (baseada em contagem de linhas e bytes de registro) não é ideal. Os fragmentos são dimensionados pelo volume de metadados, não pelo tamanho real do objeto — um único arquivo grande pode acabar no mesmo fragmento que centenas de arquivos pequenos, causando desequilíbrio severo de dados e problemas de long tail.

Exemplo do problema:

Objeto	Tamanho
a0000.jpg – a1023.jpg (1.024 arquivos)	10 MB cada
b.avi	10 GB

Com dois workers e divisão baseada em linhas, o mecanismo pode criar split1 (a0000.jpg–a0511.jpg, baixe de 5 GB) e split2 (a0512.jpg–a1023.jpg + b.avi, baixe de 15 GB). O desequilíbrio de 3x causa um long tail.

Fragmentação da Object Table por tamanho: O MaxCompute fragmenta automaticamente as Object Tables pelo tamanho real do objeto. Com uma unidade de divisão de 10 GB, split1 recebe todos os 1.024 arquivos JPEG (10 GB no total) e split2 recebe b.avi (10 GB) — ambos os workers realizam quantidades iguais de trabalho.

A unidade de divisão padrão é 1 GB. Ajuste-a conforme sua carga de trabalho:

-- Split by GB (default: 1 GB)
SET odps.sql.object.table.split.unit.gb = 1;
SELECT GET_DATA_FROM_OSS('project.default.ot_demo_day', key) FROM ot_demo_day WHERE ...;

-- Split by MB (higher priority than GB)
SET odps.sql.object.table.split.unit.mb = 512;
SELECT GET_DATA_FROM_OSS('project.default.ot_demo_day', key) FROM ot_demo_day WHERE ...;

-- Split by KB (highest priority)
SET odps.sql.object.table.split.unit.kb = 512;
SELECT GET_DATA_FROM_OSS('project.default.ot_demo_day', key) FROM ot_demo_day WHERE ...;

Ordem de prioridade: KB > MB > GB.

Para desativar completamente a fragmentação baseada em tamanho, defina:

SET odps.sql.object.table.split.by.object.size.enabled = false;

Desativar a fragmentação baseada em tamanho faz com que a consulta seja executada como duas tarefas separadas. A primeira tarefa realiza o pré-processamento e fica visível no Logview.

Mais operações

Exclua uma Object Table

Excluir uma Object Table remove os metadados em cache e interrompe as cobranças de armazenamento. Os dados reais no OSS não são afetados. Recrie a tabela a qualquer momento para retomar o uso dos dados.

DROP TABLE [IF EXISTS] <object_table_name>;

Exemplo:

DROP TABLE IF EXISTS ot_demo_day;

Perguntas frequentes

Erro de conexão recusada ao atualizar metadados

Você vê um erro semelhante a:

ODPS-0010000:System internal error -
ActionHandler job failed with failinfo storage service worker error occured:
common/io/oss/oss_file_system_cppsdk.cpp(919):
OSSRequestException: Status: -50, RequestId: ,
ErrorCode: ClientError:-50, Message: E_HTTP_ERROR_CONN_REFUSED

O parâmetro location foi definido com um endpoint público do OSS. As Object Tables exigem um endpoint de rede interna. Atualize o parâmetro location para usar o endpoint interno — consulte a descrição do parâmetro location em Criar uma Object Table.

A atualização periódica não é acionada conforme o cronograma

Verifique se o parâmetro location usa um nome de domínio de rede interna do OSS, não um endpoint público. Consulte a descrição do parâmetro location em Criar uma Object Table.

Falha na tarefa de atualização periódica com erro interno

Você vê:

FAILED: ODPS-0010000:System internal error - ActionHandler job failed with failinfo
storage service worker error occured: common/io/oss/oss_file_system_cppsdk.cpp(877):
OSSRequestException: Status: -50, RequestId: , ErrorCode: ClientError:-50, Message:

Trata-se de um erro da plataforma. Abra um ticket para entrar em contato com o suporte técnico do MaxCompute.