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

A função GET_DATA_FROM_OSS lê todo ou parte do conteúdo de um objeto do OSS e o retorna como um valor BINARY.

O recurso Object Table do MaxCompute permite que o mecanismo de computação acesse dados não estruturados e metadados armazenados no Object Storage Service (OSS). Uma Object Table armazena metadados de objetos do OSS em um caminho específico. Utilize GET_DATA_FROM_OSS para carregar dinamicamente o conteúdo binário de um objeto do OSS especificado. Para obter detalhes sobre Object Tables, consulte Definição de OBJECT TABLE.

Sintaxe

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

Parâmetros

Parâmetro	Obrigatório	Tipo de dado	Descrição	Padrão
`full_object_table_name`	Sim	STRING	Caminho completo para a OBJECT TABLE no modelo de três camadas, incluindo os nomes do Project e do Schema, por exemplo, `project.schema.object_table`. Caso você tenha utilizado autenticação RoleARN ao criar a tabela, este parâmetro aciona a geração automática de um token do Security Token Service (STS) para acessar o OSS.	Nenhum
`key`	Sim	STRING	Chave (nome) do objeto do OSS na Object Table. Para obter o valor exato, consulte o campo `key` em Visualizar propriedades da OBJECT TABLE.	Nenhum
`offset`	Não	BIGINT	Posição em bytes onde a leitura deve começar. Deve ser >= 0.	`0` (início do objeto)
`length`	Não	BIGINT	Quantidade de bytes a serem lidos.	`-1` (sem limite)
`object_not_found_policy`	Não	STRING	Comportamento adotado quando uma chave de objeto existe no cache de metadados, mas o objeto foi excluído do OSS. Consulte a tabela abaixo para valores válidos.	`OUTPUT_NULL`

Valores de object_not_found_policy

Este parâmetro se aplica quando o cache de metadados contém uma chave que não existe mais no OSS — por exemplo, porque o objeto foi excluído após a última execução de ALTER TABLE ... REFRESH METADATA.

Valor	Gera exceção	Retorna NULL	Registra aviso	Observações
`OUTPUT_NULL`	Não	Sim	Não	Padrão. Retorna null silenciosamente.
`THROW_EXCEPTION`	Sim	—	Não	Encerra a tarefa atual imediatamente.
`WARN_AND_NULL`	Não	Sim	Sim	Adiciona uma entrada de log para cada objeto ausente. Pode afetar o desempenho geral da tarefa se houver muitos objetos faltando.

Valor de retorno

Retorna um valor do tipo BINARY.

Exemplos

Nos exemplos a seguir, substitua <project_name> pelo nome real do seu projeto MaxCompute.

Pré-requisitos

Antes de executar os exemplos, conclua estas etapas de configuração.

Etapa 1: Carregar dados de teste no OSS

Faça login no console do OSS e carregue o arquivo de teste signedget.txt na pasta object-table-test/object_table_folder. Para instruções de upload, consulte Carregar arquivos.

Etapa 2: Criar uma Object Table

Utilizando o cliente local (odpscmd) ou um nó SQL do MaxCompute no DataWorks, execute o SQL a seguir. Este exemplo nomeia a Object Table como ot_demo_day. Para mais detalhes, consulte Criar uma OBJECT TABLE.

-- Enable the three-layer model (required for Object Table)
SET odps.namespace.schema=true;

-- Select the MaxCompute project
USE <project_name>;

-- Select the schema
USE SCHEMA <schema_name>;

-- Enable the 2.0 data type system (required for Object Table)
SET odps.sql.type.system.odps2=true;

-- Create the Object Table
CREATE OBJECT TABLE ot_demo_day
WITH serdeproperties (
  'odps.properties.rolearn'='acs:ram::xxxxxx:role/aliyunodpsdefaultrole')
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/object-table-test/object_table_folder';

Etapa 3: Atualizar o cache de metadados

ALTER TABLE ot_demo_day REFRESH METADATA;

Exemplo 1: Ler todo o conteúdo do objeto

As instruções a seguir leem o conteúdo completo da Object Table <project_name>.default.ot_demo_day. Todas as seis formas são equivalentes — cada uma define offset como 0, length como -1 e object_not_found_policy como OUTPUT_NULL por padrão.

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

-- The following statements are equivalent to the one above
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;

Resultado:

+------+
| _c0  |
+------+
| test=20maxcompute=20download=20files=20by=20url=20 |
+------+

Exemplo 2: Converter saída para STRING

Como GET_DATA_FROM_OSS retorna BINARY, envolva o resultado na função STRING() para trabalhar com o conteúdo como texto.

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

Resultado:

+-----+
| _c0 |
+-----+
| test maxcompute download files by url  |
+-----+

Funções relacionadas

A função GET_DATA_FROM_OSS faz parte das funções de processamento de dados não estruturados do MaxCompute. Para a lista completa, consulte Funções para processamento de dados não estruturados.