MaxCompute:Projeto externo Paimon-DLF

Etapa 1: Conceder permissões

Etapa 2: Criar uma fonte de dados externa Paimon_DLF

1. Faça login no console do MaxCompute e selecione uma região no canto superior esquerdo.

2. No painel de navegação à esquerda, escolha Manage Configurations > External Data Source .

3. Na página External Data Source, clique em Create External Data Source.

4. Na caixa de diálogo Create External Data Source, configure os parâmetros. As tabelas a seguir descrevem os parâmetros.

   Parâmetro	Obrigatório	Descrição
   External Data Source Type	Sim	Selecione Paimon_DLF.
   External Data Source Name	Sim	Insira um nome personalizado. O nome deve atender aos seguintes requisitos: Deve começar com uma letra e conter apenas letras minúsculas, dígitos e sublinhados (_). Não pode exceder 128 caracteres. Por exemplo, você pode inserir paimon_dlf.
   Description	Não	Insira uma descrição conforme necessário.
   Region	Sim	A região atual é selecionada por padrão.
   Authentication and Authorization	Sim	O valor padrão é uma função RAM da Alibaba Cloud.
   Service-linked Role	Sim	A função é gerada por padrão.
   Endpoint	Sim	O endpoint é gerado automaticamente. Para a região China (Hangzhou), o endpoint é cn-hangzhou-intranet.dlf.aliyuncs.com.
   Foreign Server Supplemental Properties	Não	Essas propriedades definem como as tarefas que usam esta fonte de dados acessam o sistema de origem. Nota Para informações sobre parâmetros suportados, consulte futuras atualizações da documentação oficial. Os parâmetros disponíveis serão expandidos conforme o produto evoluir.

5. Clique em OK para criar a fonte de dados externa.

6. Na página External Data Source, localize a fonte de dados e clique em Details na coluna Actions para visualizar seus detalhes.

Etapa 3: Criar um projeto externo

1. Faça login no console do MaxCompute e selecione uma região no canto superior esquerdo.

2. No painel de navegação à esquerda, escolha Manage Configurations > Projects.

3. Na aba External Project, clique em Create Project.

4. Na caixa de diálogo Create Project, configure as definições e clique em OK.

   Parâmetro	Obrigatório	Descrição
   Project Type	Sim	O valor padrão é External Project.
   Region	Sim	A região atual é selecionada por padrão e não pode ser alterada.
   Project Name (Globally Unique)	Sim	O nome deve ter entre 3 e 28 caracteres, começar com uma letra e conter apenas letras, dígitos e sublinhados (_).
   MaxCompute Foreign Server Type	Não	O valor padrão é Paimon_DLF.
   MaxCompute Foreign Server	Não	Use Existing: Exibe uma lista de fontes de dados externas existentes. Create Foreign Server: Permite criar e usar uma nova fonte de dados externa.
   MaxCompute Foreign Server Name	Sim	Se você optou por usar uma fonte de dados existente, selecione seu nome na lista suspensa. Se você optou por criar uma nova fonte de dados, seu nome será usado automaticamente.
   Data Catalog	Sim	O catálogo de dados do DLF.
   Billing Method	Sim	Selecione Subscription ou Pay-as-you-go.
   Default Quota	Sim	Selecione uma cota existente.
   Description	Não	Insira uma descrição personalizada do projeto.

Etapa 4: Usar SQL para acessar a fonte de dados

1. Escolha uma ferramenta de conexão para fazer login no projeto externo.

   O exemplo a seguir usa um nó SQL para desenvolvimento de dados em um workspace do DataWorks (nova versão).

   1. Faça login no console do DataWorks e selecione uma região no canto superior esquerdo.

   2. No painel de navegação à esquerda, escolha Workspace.

   3. Na página Workspaces, clique em Create Workspace ou clique no nome de um workspace existente.

   4. Na página Workspace Details, clique em Computing Resource no painel de navegação à esquerda.

   5. Na página Computing Resource, clique em Associate Computing Resources e selecione MaxCompute.

   6. Configure as Basic Information para Associate MaxCompute Computing Resource.

      Para o projeto MaxCompute, selecione o projeto externo.

2. Liste os schemas no projeto externo.

   -- Enable schema syntax at the session level.
   SET odps.namespace.schema=true;
   SHOW schemas;
   -- Sample result. 
   ID = 20250919****am4qb
   default
   system
   OK

3. Liste as tabelas em um schema dentro do projeto externo.

   Se precisar acessar tabelas de um projeto externo de produção no ambiente atual, adicione use external_project_pro; antes de todas as instruções SQL.

   -- schema_name is the schema name returned by SHOW SCHEMAS in the external project.
   SET odps.namespace.schema=true;
   USE schema <schema_name>;
   SHOW tables;
   -- Result
   ID = 20250919****am4qb
   acs:ram::<uid>:root  emp
   OK

4. Crie um novo schema no projeto externo.

   -- In this example, schema_name is schema_demo_test.
   CREATE schema <schema_name>;

5. Use o novo schema.

   USE schema <schema_name>;

6. Crie uma tabela e insira dados no schema.

   Se estiver conectado como um usuário RAM, esta operação requer permissões no catálogo DLF. Para obter informações sobre como conceder permissões, consulte Gerenciamento de autorização de dados.

   • Formato do comando:

     -- Create a table.
     CREATE TABLE [IF NOT EXISTS] <table_name> 
     (
       <col_name> <data_type>,
       ...
     )
     [COMMENT <table_comment>]
     [PARTITIONED BY (<col_name> <data_type>, ...)] 
     ;
     -- Insert data.
     INSERT {INTO|OVERWRITE} TABLE <table_name> [PARTITION (<pt_spec>)] [(<col_name> [,<col_name> ...)]]
     <select_statement>
     FROM <from_statement>

   • Exemplo:

     Nota

     Para tipos TIMESTAMP de baixa precisão da tabela Paimon de origem, os dados são truncados durante operações de escrita da seguinte forma: precisão 0–3 é truncada para 3 casas decimais, 4–6 para 6 casas decimais e 7–9 para 9 casas decimais.

     CREATE TABLE schema_table(id int,name string);
     INSERT INTO schema_table VALUES (101,'Zhang San'),(102,'Li Si');
     -- Query the schema_table table.
     SELECT * FROM schema_table;
     -- Result
     +------------+------------+
     | id         | name       | 
     +------------+------------+
     | 101        | Zhang San  | 
     | 102        | Li Si      | 
     +------------+------------+

7. Alterne para o schema default existente.

   use schema default;
   SHOW tables;
   -- Sample result
   ID = 20250919*******yg5
   acs:ram::<uid>:root	emp
   acs:ram::<uid>:root	emp_detail
   acs:ram::<uid>:root	test_table
   OK
   -- Read data from the table.
   SELECT * FROM test_table;
   -- Result
   +------------+------------+
   | id         | name       | 
   +------------+------------+
   | 101        | Zhang San  | 
   | 102        | Li Si      | 
   +------------+------------+
   -- Write data to the table and query to verify the write operation.
   INSERT INTO test_table VALUES (103,'Wang Wu');
   SELECT * FROM test_table;
   -- Result
   +------------+------------+
   | id         | name       | 
   +------------+------------+
   | 101        | Zhang San  | 
   | 102        | Li Si      | 
   | 103        | Wang Wu    | 
   +------------+------------+

Exemplo

Criar uma tabela externa Paimon com buckets, chave primária e partições

1. Criar a tabela e configurar seus parâmetros externos

   -- Switch to your external project. You can skip this step if you are already in it.
   use <your external project>;
   -- Enable schema syntax at the session level.
   SET odps.namespace.schema=true;
   -- Select the schema to use.
   use schema <your schema>;
   CREATE TABLE oss_extable_bucket_pk_pt_bucket
   (
       id BIGINT,
       name STRING,
       dt STRING
   )tblproperties (
       'mcfed.bucket'='3', -- Number of buckets
       'mcfed.bucket-key'='id', -- Bucket key. Optional if a primary key is specified.
       "mcfed.primary-key"="dt,id", -- Primary key
       "mcfed.partition"="dt" -- Partition field
       );

2. Inserir dados na tabela externa

   INSERT INTO oss_extable_bucket_pk_pt_bucket PARTITION (dt='2025-06-18') 
     VALUES (1, 'Alice'),(2, 'Bob');
   INSERT INTO oss_extable_bucket_pk_pt_bucket PARTITION (dt='2025-06-19') 
     VALUES (3, 'Charlie'),(4, 'David'),(5, 'Eva');

3. Consultar a tabela externa

   SELECT * FROM oss_extable_bucket_pk_pt_bucket;
   -- Result:
   +------------+---------+------------+
   | id         | name    | dt         |
   +------------+---------+------------+
   | 1          | Alice   | 2025-06-18 |
   | 2          | Bob     | 2025-06-18 |
   | 4          | David   | 2025-06-19 |
   | 3          | Charlie | 2025-06-19 |
   | 5          | Eva     | 2025-06-19 |
   +------------+---------+------------+
   

4. Faça login no console do Data Lake Formation (DLF) e, no canto superior esquerdo, selecione uma região.

   Visualize os detalhes da tabela no catálogo.

Problema 1: Erro ao criar um projeto externo

Problema: Ao tentar criar um projeto externo, você recebe a mensagem de erro: "You are not authorized to perform this action."

Nos detalhes do erro, o código de erro é NoMCPermission.

Solução:

1. Se estiver usando um usuário RAM, certifique-se de que a política AliyunMaxComputeFullAccess esteja anexada ao usuário RAM. Para mais informações, consulte a Etapa 1.

2. Esta operação exige a seleção de um catálogo no Data Lake Formation (DLF). Certifique-se de ter as permissões necessárias para operações do DLF. Para mais informações, consulte a Etapa 1.

Problema 2: Erro ao executar SHOW TABLES no schema padrão

Problema: Ao executar o comando SHOW TABLES no schema padrão de um projeto externo, você recebe a seguinte mensagem de erro: "Forbidden:User acs: ram: :<uid>:user/** doesn't have privilege LIST on DATABASE default".

Solução:

1. Faça login no console do Data Lake Formation (DLF) e, no canto superior esquerdo, selecione uma região.

2. No painel de navegação à esquerda, escolha System & Security

3. Na aba Access Control > Users, atualize a página para verificar se o usuário RAM atual existe.

4. Se o usuário existir, vá para a aba Access Control > Role para conceder permissões ao usuário RAM.

Problema 3: Erro "invalid database operations on two-tier"

Problema: Ao executar o comando SHOW SCHEMAS em um projeto externo, você recebe a mensagem de erro: "invalid database operations on two-tier".

Solução:

1. Primeiro, certifique-se de que está usando um projeto externo.

   1. Se estiver usando um nó SQL do DataWorks, clique em Debug Configuration no painel à direita e verifique se o recurso de computação vinculado é um projeto externo.

   2. Se estiver usando a análise SQL do DataWorks, clique em Data Source no canto superior direito e verifique se a fonte de dados vinculada é um projeto externo.

   3. Se estiver usando a análise SQL do MaxCompute, clique em Run Configuration no painel à direita e verifique se o projeto selecionado na seção de recursos de computação é um projeto externo.

   4. Se estiver usando o odpscmd, verifique o valor do parâmetro project_name no arquivo odps_config.ini para garantir que esteja definido como o nome do projeto externo.

2. Após confirmar que está usando um projeto externo, selecione e execute as seguintes instruções SQL juntas.

   -- Enable schema syntax at the session level.
   SET odps.namespace.schema=true;
   SHOW schemas;

Problema 4: SHOW SCHEMAS retorna apenas o schema padrão

Problema: Ao executar o comando SHOW SCHEMAS em um projeto externo, o comando retorna apenas 'default'.

Solução:

1. Primeiro, certifique-se de que está usando um projeto externo.

   1. Se estiver usando um nó SQL do DataWorks, clique em Debug Configuration no painel à direita e verifique se o recurso de computação vinculado é um projeto externo.

   2. Se estiver usando a análise SQL do DataWorks, clique em Data Source no canto superior direito e verifique se a fonte de dados vinculada é um projeto externo.

   3. Se estiver usando a análise SQL do MaxCompute, clique em Run Configuration no painel à direita e verifique se o projeto selecionado na seção de recursos de computação é um projeto externo.

   4. Se estiver usando o odpscmd, verifique o valor do parâmetro project_name no arquivo odps_config.ini para garantir que esteja definido como o nome do projeto externo.

2. Após confirmar que está usando um projeto externo, faça login no console do Data Lake Formation (DLF) e verifique se existem outros bancos de dados no catálogo vinculado ao projeto externo.

3. Se você concluiu as verificações nas Etapas 1 e 2, mas o comando SHOW SCHEMAS ainda não retorna os bancos de dados esperados, envie um ticket para relatar o problema.

Problema 5: Erro "Dynamic bucket"

Problema: Ao executar o comando SHOW TABLES em um projeto externo, você recebe a seguinte mensagem de erro:

ODPS-0110005: 
com.aliyun.odps.meta.exception.MetaException: 
com.aliyun.odps.common.table.na.NativeException: 
common/table/jni/utils/jni_helper.cpp(79): UnretryableException: Common table connector exception 
  - ExceptionType: java.lang.IllegalArgumentException 
  - Message: You should use dynamic bucket (bucket = -1) mode in cross partition update case (Primary key constraint [sending_time, symbol, sequence_number] not include all partition fields [pt]).[pt])

Solução:

Este erro ocorre porque o MaxCompute não suporta tabelas de chave primária entre partições com buckets fixos.

Solução temporária: Exclua as tabelas PK entre partições não suportadas no console do Data Lake Formation (DLF).

Problema 6: Erro "Can't set default schema..."

Problema: Ao executar SHOW TABLES ou SHOW SCHEMAS, você recebe a seguinte mensagem de erro: "FAILED: Can't set default schema if odps.namespace.schema is false."

Solução:

1. Primeiro, certifique-se de ter adicionado o sinalizador de sessão SET odps.namespace.schema=true; antes das suas instruções SQL para habilitar a sintaxe de schema.

2. Se o erro persistir após habilitar o sinalizador, verifique a ordem das suas instruções. Para ler uma tabela de outro projeto externo, use a seguinte sequência de comandos:

   USE external_project;
   SET odps.namespace.schema=true;
   USE schema schema_name;
   SHOW tables;

Problema 7: Erro "Failed to connect to...dlf.aliyuncs.com"

Problema: Ao tentar ler dados de uma tabela em um projeto externo Paimon_DLF, você recebe uma mensagem de erro semelhante a: "Caused by: java.net.ConnectException: Failed to connect to cn-***-intranet.dlf.aliyuncs.com/xx.xx.xx.xx:80"

Este erro indica que você precisa adicionar o endereço cn-***-intranet.dlf.aliyuncs.com à lista de permissões do projeto interno onde o job é executado.

Solução:

1. Junte-se ao grupo DingTalk da comunidade de desenvolvedores MaxCompute usando o link de inscrição ou pesquisando pelo ID do grupo 11782920 no DingTalk. Entre em contato com a equipe de suporte técnico do MaxCompute e solicite que adicionem o endereço da mensagem de erro à lista de permissões.

2. Depois que o endereço for adicionado à lista de permissões, inclua os seguintes parâmetros antes das suas operações de leitura.

   set odps.security.outbound.intranetlist=cn-***-intranet.dlf.aliyuncs.com:80;
   set odps.internet.access.list=cn-***-intranet.dlf.aliyuncs.com:80;