MaxCompute:Primeiros passos com o cliente de exploração de dados com IA

Baixe e instale

Visão geral do console

O cliente utiliza um layout de três colunas:

• Barra lateral esquerda: Área de gerenciamento de recursos, que contém painéis como Gerenciamento de arquivos, Navegação no catálogo, Conexões de dados, Importação de dados, Pesquisa na base de conhecimento SQL, Histórico de consultas e Histórico de versões de arquivos. Use os ícones à esquerda para alternar entre esses painéis.

• Área central: Área de edição de SQL e exibição de dados, que oferece suporte a múltiplas abas.

• Barra lateral direita: Painel do Assistente de IA, que pode ser expandido ou recolhido.

O cliente oferece suporte aos temas escuro e claro, configuráveis em Settings.

Configurar conexão de dados

1. Na barra lateral esquerda, clique no ícone de conexão para abrir o painel de conexões de dados.

2. Clique em Add Connection.

3. Insira as informações da conexão:

   • Connection Name: Insira um nome descritivo para a conexão.

   • Region: Selecione a região onde seu projeto do MaxCompute está localizado na lista suspensa ou selecione "Custom Endpoint" para inseri-la manualmente.

   • Project Name: Insira o nome do seu projeto do MaxCompute.

   • AccessKey ID e AccessKey Secret: Insira o AccessKey ID e o AccessKey Secret para acesso ao projeto.

4. Clique em Test Connection para verificar a configuração.

5. Após a aprovação do teste, clique em Save.

Após a conexão, o painel Catalog na barra lateral esquerda carrega automaticamente a estrutura de tabelas do projeto.

Executar consulta

1. Pressione Option+N ou clique em New no painel de arquivos para criar um novo arquivo SQL.

2. No editor, insira uma consulta, por exemplo:

   SELECT * FROM your_table_name LIMIT 10;

3. Pressione Cmd+Enter (no macOS) para executar a consulta.

4. Os resultados da consulta aparecem no Result Panel abaixo do editor. Para analisar os resultados, alterne entre Table View, Chart View e Pivot Table View.

Configurar service de IA

1. Clique no ícone de engrenagem no canto superior direito para abrir Settings.

2. Acesse a aba AI Configuration.

3. Insira as seguintes informações:

   • API URL: O endpoint para o service de IA. O padrão é o endpoint do Alibaba Cloud Model Studio: https://dashscope.aliyuncs.com/compatible-mode/v1/.

   • API Key: Acesse o console do Alibaba Cloud Model Studio. No canto superior direito da página, selecione a região China (Beijing). Navegue até a página API Key e clique em Create API Key ou copie uma existente.

   • Model Name: O padrão é qwen3-max-2026-01-23. Você também pode inserir outros models compatíveis com a API OpenAI.

4. Clique em Save.

Após salvar, o painel do Assistente de IA à direita estará pronto para uso. Explore seus dados fazendo perguntas em linguagem natural.

Exploração de dados com IA

Após concluir a configuração, teste o seguinte no painel do Assistente de IA:

1. Insira "List the tables in the current project." O Assistente de IA listará as tabelas.

2. Selecione uma tabela e insira "Show the structure and first 10 rows of this table."

3. Após revisar os resultados, faça uma pergunta analítica, como "Analyze the data volume distribution across partitions in this table."

O Assistente de IA planeja as etapas, gera o SQL, executa a consulta e fornece uma análise. Você pode observar todo esse processo na interface.

Criar uma nova conexão

1. Na barra lateral esquerda, clique no ícone Connections para abrir o painel de conexões de dados.

2. Clique em Add Connection.

3. Configure os seguintes parâmetros:

   Parâmetro	Descrição
   Connection Name	Um nome personalizado para identificar a conexão.
   Region	Selecione a região onde seu projeto do MaxCompute está localizado. O cliente preenche automaticamente o endpoint correspondente.
   Project Name	O nome do seu projeto do MaxCompute.
   AccessKey ID	O AccessKey ID da sua conta Alibaba Cloud.
   AccessKey Secret	O AccessKey Secret da sua conta Alibaba Cloud.

4. Clique em Test Connection para verificar a conexão.

5. Clique em Save para criar a conexão.

Testar e solucionar problemas de conexões

Ao clicar em Test Connection, o cliente se conecta ao service do MaxCompute e recupera as informações do projeto. Se o teste falhar, verifique o seguinte:

• Certifique-se de que o endpoint corresponde à região do projeto.

• Verifique se o seu AccessKey está correto e não expirou.

• Confirme se o seu ambiente de rede atual pode acessar o service do MaxCompute na região especificada.

• Verifique se a conta Alibaba Cloud associada ao seu AccessKey tem acesso ao projeto.

Gerenciar múltiplas conexões

O painel de conexões de dados lista todas as suas conexões salvas. A partir dele, você pode:

• Alternar conexões:

  Clique em uma conexão para torná-la ativa. Operações como execução de SQL, navegação no Catalog e importação de dados utilizam a conexão ativa.

• Excluir uma conexão:

  Clique no ícone de exclusão em uma conexão para removê-la. Para modificar uma conexão, exclua a existente e crie uma nova.

Salve múltiplas conexões para diferentes regiões ou projetos para alternar rapidamente entre ambientes de produção, teste e outros.

Editor de SQL

O cliente inclui um editor de SQL integrado, baseado no Monaco, para uma experiência semelhante a uma IDE.

• Destaque de sintaxe e conclusão inteligente

  O editor destaca a sintaxe para MaxCompute SQL e fornece conclusão inteligente com base no contexto enquanto você digita. As sugestões incluem palavras-chave SQL, funções integradas do MaxCompute e nomes de tabelas e colunas da conexão atual. A lista de conclusão é filtrada automaticamente com base na posição do cursor. Digitar o nome de uma tabela seguido por um . sugere automaticamente os nomes das colunas dessa tabela.

• Edição de código

  O editor inclui dobramento de código, colorização de pares de colchetes, quebra de linha e um minimapa de código. Pressione Shift+Option+F para formatar automaticamente o script SQL atual.

Gerenciamento de scripts SQL

O File Panel na barra lateral esquerda exibe os arquivos SQL no seu sistema de arquivos local.

• Novo arquivo

  Pressione Option+N (macOS) para criar um novo arquivo SQL.

• Abrir arquivo

  No File Panel, clique em um arquivo SQL existente para abri-lo no editor.

• Salvar arquivo

  Pressione Option+S (macOS) para salvar suas alterações atuais.

• Operações com múltiplas abas

  Abra múltiplos arquivos SQL simultaneamente e alterne entre eles usando abas.

Gerenciamento de versões de arquivos SQL

O cliente mantém um histórico de versões para cada arquivo SQL. Clique no ícone Version History na barra lateral esquerda para visualizar uma lista de versões históricas do arquivo atual.

Cada registro de versão inclui um número de versão, horário de salvamento e tipo de versão. Os tipos de versão são salvamentos manuais (criados quando você salva um arquivo explicitamente) e snapshots de pré-execução (criados automaticamente antes da execução de uma consulta SQL).

Operações disponíveis em uma versão:

• Comparar diferenças: Clique duas vezes em uma versão para abrir uma visualização de diferenças que mostra as alterações entre essa versão e o conteúdo atual.

• Restaurar versão: Restaure o conteúdo do arquivo para uma versão específica.

• Excluir versão: Remova versões históricas que você não precisa mais.

Execução de SQL

Existem três maneiras de executar SQL:

• Executar tudo: Pressione Cmd+Enter para executar todas as instruções SQL no editor.

• Executar seleção: Selecione uma parte do texto SQL e pressione Shift+Enter para executar apenas a seleção.

• Execução de instrução única: O editor exibe um botão Run entre cada instrução SQL. Clique nele para executar essa instrução específica.

Se um arquivo SQL contiver instruções SET, como SET odps.sql.type.system.odps2=true;, o cliente mescla automaticamente essa configuração com as instruções SQL subsequentes e as executa juntas.

Durante a execução, o editor exibe uma barra de progresso e o status de execução abaixo. Ao concluir, os resultados da consulta aparecem em uma tabela, enquanto um status de execução aparece para instruções DDL/DML.

Análise de resultados de consultas

Após uma consulta retornar resultados, as seguintes visualizações estão disponíveis para análise.

Histórico de consultas

Clique no ícone History na barra lateral esquerda para navegar pelo seu histórico de consultas. Cada registro mostra o horário de execução, duração (em milissegundos), visualização do SQL, status (sucesso ou falha) e contagem de linhas. Clique em um registro para carregar essa instrução SQL de volta no editor.

O histórico de consultas oferece suporte à paginação para navegar por consultas anteriores.

Navegar no Catalog

Na barra lateral esquerda, clique no ícone Catalog para visualizar todas as tabelas no projeto atual, exibidas em uma estrutura de árvore. Expanda qualquer tabela para visualizar suas definições de colunas, incluindo o nome da coluna, tipo de dados e comentário.

Clique com o botão direito no nome de uma tabela para realizar as seguintes ações:

• Data Preview: Visualize as primeiras linhas de dados na tabela.

• View table schema: Exibe as informações completas das colunas, chave de partição e propriedades da tabela.

• View table information: Exibe metadados como o tamanho da tabela, contagem de registros, horário da última modificação e permissões.

Com múltiplas conexões salvas, o Catalog exibe os esquemas de tabelas para todos os projetos conectados.

Visualização de dados

Selecione uma tabela no Catalog para visualizar seus dados. O cliente executa uma consulta LIMIT e exibe os resultados no painel central.

Gerenciamento de partições

Visualize a lista de partições existentes no Catalog e adicione novas partições a uma tabela particionada.

Importação de dados

O cliente oferece suporte à importação de arquivos locais para tabelas do MaxCompute. Para abrir o painel de importação, clique no ícone Data Import na barra lateral esquerda.

Exportação de dados

Exporte os resultados da consulta nos seguintes formatos:

• CSV: Um arquivo de texto separado por vírgulas, compatível com ferramentas como o Excel.

• JSON: Dados no formato JSON.

• Parquet: Um formato de armazenamento colunar adequado para processamento posterior em cenários de big data.

No painel de resultados da consulta, clique no botão Export e selecione um formato.

Modo de chat e modo de agente

O assistente de IA fornece dois modos de trabalho:

O modo de chat é ideal para perguntas e respostas rápidas e operações leves, como explicar uma instrução SQL, otimizar código SQL ou sugerir insights com base nos resultados da consulta. A IA responde diretamente sem um processo de múltiplas etapas.

O modo de agente lida com tarefas de análise de dados de múltiplas etapas. A IA cria um plano de execução e, após sua aprovação, executa cada etapa em sequência. As etapas podem incluir consulta de metadados, geração de SQL, execução de consultas e análise de resultados.

Modo de chat

Insira uma pergunta na caixa de entrada do painel de IA para usar o modo de chat. Os casos de uso comuns incluem:

• Geração de SQL: Descreva seus requisitos de consulta e a IA gera o MaxCompute SQL correspondente.

• Otimização de SQL: Abra um script SQL no editor e peça à IA sugestões de otimização. Em seguida, insira o SQL otimizado no editor com um único clique.

• Explicação de SQL: Selecione uma instrução SQL complexa e peça à IA para explicar sua lógica seção por seção.

• Insights de resultados: Após executar uma consulta, peça à IA insights sobre os resultados, como análise de tendências ou detecção de anomalias.

Modo de agente

Ao fazer uma pergunta analítica que envolva múltiplas etapas, a IA entra automaticamente no modo de agente.

Espaço de trabalho de IA

O AI Workspace é um diretório local persistente que armazena a saída do modo de agente. Os resultados intermediários e finais de cada tarefa de análise são salvos automaticamente.

Casos de uso

Base de conhecimento de snippets SQL

A sql snippet knowledge base armazena modelos SQL reutilizáveis para recuperação periódica de dados. Manter o SQL de negócios padronizado na knowledge base permite que você use a reescrita de datas da IA para recuperar rapidamente dados de relatórios para diferentes períodos. Ao importar arquivos SQL frequentemente usados para a knowledge base, o sistema extrai automaticamente sql snippets individuais. Para cada snippet, ele extrai nomes de tabelas, palavras-chave, campos de partição e literais de data para criar um índice de texto completo.

Clique no ícone de pesquisa na barra lateral esquerda para pesquisar sql snippets por palavra-chave na knowledge base. Após encontrar um snippet, insira-o no editor para execução. Alternativamente, use o recurso "Execute SQL Snippet" do assistente de IA para corresponder automaticamente a um snippet, reescrever sua data e executá-lo.

Camada semântica

A semantic layer diferencia o client do MaxCompute de ferramentas de IA de uso geral, mapeando tabelas e colunas de banco de dados para termos, métricas e relacionamentos amigáveis ao negócio. Ao gerar SQL, a IA consulta a semantic layer para produzir consultas mais precisas.

A semantic layer consiste nos seguintes componentes:

• Termo de negócio: Define um termo especializado no seu domínio de negócios, como 'DAU' para 'Daily Active Users'.

• Definição de entidade: Descreve objetos de negócios principais e suas tabelas e campos-chave correspondentes.

• Definição de métrica: Define as fórmulas de cálculo e o escopo para métricas de negócios, como Conversion Rate = Number of users who placed an order / Number of visiting users.

• Relacionamento de tabela: Descreve os relacionamentos JOIN e as chaves de junção entre tabelas.

• Consulta validada: Um modelo de consulta padrão e validado que a IA pode reutilizar para perguntas semelhantes.

• Analysis playbook: Um modelo predefinido para cenários e etapas de análise que orienta a IA a concluir uma análise seguindo um fluxo de trabalho padrão.

Pacote semântico integrado

O client inclui um built-in semantic package para o Information Schema, cobrindo cenários comuns de análise de meta-warehouse no nível de tenant do MaxCompute: diagnóstico de pressão de armazenamento, diagnóstico de pressão de custos, análise de desempenho de jobs, análise de aumento de falhas de tarefas, auditorias de funções de usuário, auditorias de exposição de permissões, observação de tabelas quentes e monitoramento de cotas de recursos.

Após ativar este semantic package, faça perguntas de análise de meta-warehouse diretamente à IA, como "Analyze the top 10 tables by storage in the current project." A IA então usa as definições de métricas e consultas de referência do semantic package para gerar um SQL de análise preciso.

Pacote semântico personalizado

Crie um custom semantic package para seus cenários de negócios. No painel Semantic Layer Management, selecione um domínio de destino e edite business terms, entity definitions, metric definitions, table relationships, validated queries e analysis playbooks. Você também pode usar a assistência da IA para gerar um rascunho de semantic package a partir da estrutura de tabelas da conexão atual e, em seguida, refiná-lo manualmente.

Navegador de arquivos blob

O MaxCompute armazena dados de arquivos binários em colunas do tipo blob. O cliente fornece um navegador de arquivos blob que funciona como um gerenciador de arquivos para navegar em tabelas blob. Para usar este recurso, ative a opção Beta do navegador de arquivos.

O navegador de arquivos blob oferece suporte à alternância entre visualização em grade e visualização em lista, navegação por trilha, criação de pastas e upload/download de arquivos.

Importação de arquivos blob

No painel Data Import, alterne para o modo de importação de blob para fazer o upload de arquivos em massa para uma tabela blob do MaxCompute com arrastar e soltar. O cliente extrai metadados (caminho, nome e tipo do arquivo) e os grava nas colunas correspondentes da tabela.

Se a tabela de destino não existir, o cliente ajuda a gerar uma instrução de criação de tabela que inclui uma coluna do tipo blob.

Visualização de arquivos multimodais

O cliente fornece visualização integrada de arquivos multimodais para os seguintes formatos:

O cliente corresponde automaticamente o método de visualização com base no tipo MIME do arquivo, mas você também pode alterá-lo manualmente.

Montagem WebDAV

O cliente inclui um service WebDAV integrado para montar uma tabela blob do MaxCompute como uma pasta local. Após a montagem, visualize e baixe arquivos diretamente no Finder sem usar a interface do cliente.

Como montar no macOS:

No Finder, pressione Cmd+K e insira http://localhost:8899/dav/ para navegar pelos arquivos na tabela blob como uma pasta de rede.

Subagente OpenClaw

O cliente MaxCompute se integra como um subagente OpenClaw, lidando com tarefas de análise de dados delegadas pelo OpenClaw.

O OpenClaw controla e orquestra tarefas, enquanto o cliente MaxCompute lida com a análise de dados. Os benefícios incluem:

• Isolamento de segurança: As credenciais de conexão do MaxCompute são gerenciadas localmente no cliente. Você não precisa configurar um AccessKey no OpenClaw.

• Rastro de auditoria completo: O OpenClaw mantém uma experiência de conversação simples, enquanto o cliente armazena o processo de execução detalhado, incluindo o plano, SQL, resultados intermediários e informações de diagnóstico, para rastreamento e revisão.

• Análise estendida: Analise e exporte ainda mais os resultados do OpenClaw no modo Studio do cliente.

# Install the MaxCompute plugin
openclaw plugins install @maxcompute/openclaw-maxquery --pin

# Enable the plugin and configure the connection address
openclaw plugins enable maxquery
openclaw config set plugins.entries.maxquery.enabled true
openclaw config set plugins.entries.maxquery.config.baseUrl http://127.0.0.1:8899

Configurações do editor

Configurações de IA

Configurações avançadas de IA

Configurações de tema

Alterne entre os temas Dark e Light.

Atualização de versão

O aplicativo verifica automaticamente se há atualizações e solicita a instalação de novas versões quando disponíveis.

Erro de verificação de instalação no macOS

O recurso de segurança Gatekeeper do macOS causa esse erro. Para resolvê-lo, abra o Terminal, execute o seguinte comando e reinicie o aplicativo:

sudo xattr -rd com.apple.quarantine "/Applications/MaxCompute.app"

Problemas de conexão

• Falha no teste de conexão

  Verifique os seguintes itens em ordem:

  1. Certifique-se de que o endpoint corresponde à region do seu project do MaxCompute. Verifique a region correta na página de detalhes do project no console do MaxCompute.

  2. Verifique se o AccessKey ID e o AccessKey Secret estão corretos e não foram desativados ou expirados.

  3. Confirme se sua rede pode acessar o public endpoint do MaxCompute para a region especificada. Se você estiver atrás de uma VPN ou proxy, certifique-se de que sua política de rede permita conexões de saída.

  4. Certifique-se de que a conta associada ao AccessKey ID esteja autorizada a acessar o project de destino.

• Tempo limite de conexão

  Problemas de rede geralmente causam esse tempo limite. Alta latência, especialmente ao se conectar a uma region transfronteiriça, como acessar uma region no exterior a partir da China continental, pode levar a tempos limite. Verifique sua conectividade de rede ou entre em contato com o administrador da sua rede.

Problemas de execução de SQL

• A execução de SQL retorna um erro de sintaxe

  O MaxCompute SQL difere do SQL padrão. O cliente reescreve automaticamente algumas sintaxes antes da execução (por exemplo, convertendo NOW() para GETDATE()), mas nem todos os casos são cobertos. Consulte a documentação oficial do MaxCompute SQL para a sintaxe correta.

• A consulta retorna um grande volume de dados

  O cliente limita as linhas retornadas por padrão para garantir a capacidade de resposta. Para recuperar mais dados, adicione uma cláusula LIMIT à sua instrução SQL ou use o recurso de exportação de dados para o conjunto de resultados completo.

Problemas de configuração de IA

• O assistente de IA não está funcionando

  Certifique-se de que a API URL, a API key e o Model Name estejam configurados corretamente nas configurações. A configuração padrão usa o Model Studio (DashScope); para usá-lo, crie primeiro uma API key no console do Model Studio.

• As respostas da IA estão lentas

  A carga do service de models e as condições de rede afetam a velocidade de resposta. Para respostas mais rápidas, altere o inference service tier para fast nas configurações avançadas de IA ou escolha um model mais responsivo.

Problemas de importação e exportação

• Tipos de coluna incorretos após a importação de um arquivo Excel

  O cliente infere automaticamente os tipos de coluna ao analisar um arquivo Excel. Se os tipos inferidos estiverem incorretos, modifique manualmente as definições de tipo de coluna no DDL no modo Create New Table ou use o recurso AI Generate DDL para uma inferência de tipo mais precisa.

• Não é possível abrir um arquivo Parquet exportado

  Os Parquet file s exportados aderem ao formato Apache Parquet e podem ser lidos por ferramentas que suportam Parquet, como Python (pandas/pyarrow) e Spark.