MaxCompute:Usage

Baixe o driver JDBC

Obtenha os pacotes JAR do MaxCompute para diferentes versões no OSS, no GitHub ou no repositório Maven. Recomendamos baixar o pacote JAR que inclui todas as dependências (jar-with-dependencies).

<dependency>
  <groupId>com.aliyun.odps</groupId>
  <artifactId>odps-jdbc</artifactId>
  <version>3.8.6</version>
  <classifier>jar-with-dependencies</classifier>
</dependency>

Parâmetros JDBC

Configure o JDBC usando parâmetros de URL e objetos Properties. Os objetos Properties têm prioridade maior e substituem os parâmetros da URL.

• Parâmetros básicos

  Chave da URL	Chave da propriedade	Obrigatório	Descrição
  project	project_name	Sim	Nome do projeto MaxCompute.
  accessId	access_id	Sim	AccessKey ID da sua conta Alibaba Cloud. Obtenha seu AccessKey ID na página AccessKey Management.
  accessKey	access_key	Sim	AccessKey secret da sua conta Alibaba Cloud. Obtenha seu AccessKey secret na página AccessKey Management.
  logview	logview_host	Não	URL do LogView do MaxCompute. O valor é fixo em http://logview.odps.aliyun.com.
  tunnelEndpoint	tunnel_endpoint	Não	Endpoint do service MaxCompute Tunnel. Para os endpoints do Tunnel de cada região e tipo de rede, consulte Endpoints.

• Parâmetros de configuração de log

  Chave da URL	Chave da propriedade	Obrigatório	Descrição
  enableOdpsLogger	enable_odps_logger	Não	Defina se o logger JDBC do MaxCompute deve ser ativado. Valores válidos: False (padrão): Desativa o logger. True: Ativado. Os logs são gravados no arquivo jdbc.log no diretório do pacote JAR.
  logConfFile	log_conf_file	Não	Especifique um arquivo de configuração SLF4J adicional para configurar flexivelmente a saída de log, como o arquivo de saída e o logLevel. Este método exige adicionar as seguintes dependências ao arquivo pom.xml do seu projeto: <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-core</artifactId> <version>1.2.3</version> </dependency> <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-classic</artifactId> <version>1.2.3</version> </dependency> Para um exemplo de configuração, consulte Exemplo de arquivo de configuração.
  logLevel	log_level	Não	Nível de log da saída. Valor padrão: INFO.

• Outros parâmetros

  Chave da URL	Chave da propriedade	Obrigatório	Descrição
  stsToken	sts_token	Não	Token STS da Alibaba Cloud.
  charset	charset	Não	Conjunto de caracteres para entrada e saída. Valor padrão: UTF-8.
  useProjectTimeZone	use_project_time_zone	Não	Defina se a propriedade odps.sql.timezone do projeto deve ser usada. Valores válidos: False (padrão): Não usa a propriedade. True: Usa a propriedade. Nota Também é possível especificar o fuso horário em uma instrução usando set odps.sql.timezone=xxx. Ordem de prioridade: Instrução > projeto > null.
  disableConnectionSetting	disable_connection_setting	Não	Defina se a configuração de parâmetros SQL para uma conexão é permitida. Valores válidos: False (padrão): Não permitido. True: Permitido. Quando este parâmetro é definido como true, o comando set xxx aplica-se tanto à instrução quanto à conexão. Caso contrário, aplica-se apenas à instrução.
  settings	settings	Não	String JSON para a sql setting padrão global. Exemplo: {"key":"value"}.
  tableList	table_list	Não	Nomes das tabelas do MaxCompute. Formato: projectname.tablename,projectname1.tablename1.
  connectTimeout	connect_timeout	Não	Tempo limite para estabelecer uma conexão de rede. Valor padrão: 10 segundos (s).
  readTimeout	read_timeout	Não	Tempo limite para leitura de dados de uma conexão de rede. Valor padrão: 120 segundos (s). Nota O tempo limite total para cada solicitação de API RESTful é a soma de connectTimeout e readTimeout, cujo padrão é 130 segundos. O driver tenta repetir cada solicitação até 3 vezes. Para ajustar o tempo limite de conexão para solicitações de API RESTful, modifique o parâmetro readTimeout.
  enableCommandApi	enable_command_api	Não	Defina se a API de comandos deve ser usada. Valores válidos: False (padrão): A API de comandos não é usada. True: A API de comandos é usada. Quando ativada, permite executar comandos no JDBC que normalmente são exclusivos do odpscmd.
  httpsCheck	https_check	Não	Defina se a verificação de certificado HTTPS deve ser realizada. Valores válidos: False (padrão): A verificação não é realizada. True: A verificação é realizada.
  tunnelConnectTimeout	tunnel_connect_timeout	Não	Período de tempo limite de conexão para o Tunnel durante o download de dados. Valor padrão: 180 segundos (s).
  tunnelReadTimeout	tunnel_read_timeout	Não	Período de tempo limite de leitura para o Tunnel durante o download de dados. Valor padrão: 300 segundos (s).
  skipCheckIfSelect	skipCheckIfSelect	Não	Defina se a análise sintática de SQL deve ser ignorada. Valores válidos: False (padrão): Não ignora a análise. True: Ignora a análise. Nota Ignorar a análise pode reduzir o consumo de CPU e memória no lado do cliente, mas pode aumentar a latência para instruções que não sejam SELECT.

• Parâmetros não MCQA (efetivos apenas no modo offline)

  Chave da URL	Chave da propriedade	Obrigatório	Descrição
  autoLimitFallback	auto_limit_fallback	Não	Fallback automático de limite. Valores válidos: False (padrão): Não realiza fallback. True: Realiza fallback. No modo offline, quando o Tunnel reporta uma exceção no download permission, o driver faz fallback automaticamente e limita o número de registros baixados a 10.000.

• Parâmetros MaxQA/MCQA 1.0 (efetivos apenas para MaxQA/MCQA 1.0)

  • Configuração básica

  Chave da URL	Chave da propriedade	Obrigatório	Descrição
  interactiveMode	interactive_mode	Não	Defina se o MaxQA/MCQA 1.0 deve ser ativado. Valores válidos: False (padrão): Desativado. True: Ativado.
  executeProject	execute_project_name	Não	Nome do projeto MaxCompute onde a tarefa SQL é realmente executada.
  tunnelRetryTime	tunnel_retry_time	Não	Número de tentativas do Tunnel para SQLExecutor. Valor padrão: 6.
  attachTimeout	attach_timeout	Não	Período de tempo limite para estabelecer uma conexão MCQA 1.0. Valor padrão: 60 segundos (s).
  fallbackQuota	fallback_quota	Não	Cota a ser usada quando um job MCQA 1.0 faz fallback. Se não configurada, a cota padrão do projeto é utilizada.
  quotaName	quota_name	Não	Cota de recursos de computação usada pelo job MaxQA.

  • Parâmetros relacionados a limites

    Chave da URL	Chave da propriedade	Obrigatório	Descrição
    instanceTunnelMaxRecord	instance_tunnel_max_record	Não	Número máximo de registros no conjunto de resultados. Nota Este parâmetro só entra em vigor quando o parâmetro enableLimit está definido como False.
    instanceTunnelMaxSize	instance_tunnel_max_size	Não	Tamanho máximo do conjunto de resultados. Unidade: byte.
    autoSelectLimit	auto_select_limit	Não	Limite automático de consulta. Por padrão, é possível consultar no máximo 1.000.000 linhas em ambientes de nuvem pública da Alibaba Cloud. Para consultar mais dados, configure este parâmetro. Nota Este parâmetro só entra em vigor quando o parâmetro enableLimit está definido como False. Para JDBC V3.2.29 e posterior, se você definir o parâmetro autoSelectLimit, o parâmetro enableLimit será automaticamente definido como False.
    enableLimit	enable_limit	Não	Defina se o limite deve ser ativado. Valores válidos: False: O limite não está ativado. True (padrão): O limite está ativado. Se ativado, a permissão de download não é verificada e os conjuntos de resultados são limitados a 10.000 registros por padrão.

  • Parâmetros relacionados a fallback

    Chave da URL	Chave da propriedade	Obrigatório	Descrição
    fallbackForUnknownError	fallback_for_unknownerror	Não	Defina se deve haver fallback para o modo offline quando ocorrer um erro desconhecido. Valores válidos: False: Não realiza fallback. True (padrão): Realiza fallback.
    fallbackForResourceNotEnough	fallback_for_resourcenotenough	Não	Defina se deve haver fallback para o modo offline quando os recursos forem insuficientes. Valores válidos: False: Não realiza fallback. True (padrão): Realiza fallback.
    fallbackForUpgrading	fallback_for_upgrading	Não	Defina se deve haver fallback para o modo offline durante uma atualização. Valores válidos: False: Não realiza fallback. True (padrão): Realiza fallback.
    fallbackForRunningTimeout	fallback_for_runningtimeout	Não	Defina se deve haver fallback para o modo offline quando um comando de operação atingir o tempo limite. Valores válidos: False: Não realiza fallback. True (padrão): Realiza fallback.
    fallbackForUnsupportedFeature	fallback_for_unsupported_feature	Não	Defina se deve haver fallback para o modo offline quando um recurso MCQA não suportado for usado. Valores válidos: False: Não realiza fallback. True (padrão): Realiza fallback.
    alwaysFallback	always_fallback	Não	Defina se deve haver fallback para o modo offline em todos os cenários anteriores. Valores válidos: False (padrão): Não realiza fallback. True: Realiza fallback. Nota Este parâmetro é suportado apenas no JDBC V3.2.3 e posterior.
    disableFallback	disable_fallback	Não	Defina se o fallback para o modo offline deve ser desativado em todos os cenários anteriores. Valores válidos: False (padrão): Realiza fallback. True: Não realiza fallback.
    fallbackQuota	fallback_quota	Não	Nome da cota para a qual um job MCQA faz fallback. Se não configurada, a cota padrão do projeto é utilizada.

Conectar ao MaxCompute

1. Carregue o driver JDBC do MaxCompute.

   Class.forName("com.aliyun.odps.jdbc.OdpsDriver");

2. Crie uma conexão usando DriverManager.

   Connection cnct = DriverManager.getConnection(url, accessId, accessKey);

   • url: A URL deve estar no seguinte formato: jdbc:odps:<maxcompute_endpoint>?project=<maxcompute_project_name>[&useProjectTimeZone={true|false}]. Os parâmetros são descritos da seguinte forma:

     • <maxcompute_endpoint>: O endpoint do service MaxCompute para a região. Por exemplo, o endpoint público para a região China (Hangzhou) é http://service.cn-hangzhou.maxcompute.aliyun.com/api. Para mais informações, consulte Endpoints.

     • <maxcompute_project_name>: O nome do projeto MaxCompute.

     • useProjectTimeZone: Defina se o fuso horário do projeto MaxCompute deve ser usado.

     Exemplo:

     jdbc:odps:http://service.cn-hangzhou.maxcompute.aliyun.com/api?project=test_project&useProjectTimeZone=true;

   • accessId: O AccessKey ID da sua conta Alibaba Cloud.

   • accessKey: O AccessKey secret correspondente ao AccessKey ID.

     Nota

     Para criar e visualizar um AccessKey ID e um AccessKey secret, consulte Preparar uma conta Alibaba Cloud.

3. Execute uma consulta.

   try (
       Statement stmt = cnct.createStatement();
       ResultSet rset = stmt.executeQuery("SELECT foo FROM bar;")
   ) {
       while (rset.next()) {
         // process the results
       }
   } catch (SQLException e) {
     // handle the exception
   } finally {
       if (cnct != null) {
           try {
               cnct.close();
           } catch (SQLException e) {
               // Ignore or record a closed exception
           }
       }
   }

Código de exemplo

• Excluir uma tabela, criar uma tabela e obter metadados

  Nota

  Se você adicionar a dependência JDBC ao seu projeto, não adicione a dependência sdk separadamente. A dependência JDBC inclui o sdk necessário, e adicioná-lo separadamente pode causar erros de incompatibilidade de versão.

  import java.sql.Connection;
  import java.sql.DatabaseMetaData;
  import java.sql.DriverManager;
  import java.sql.ResultSet;
  import java.sql.SQLException;
  import java.sql.Statement;
  
  public class Main {
  
      private static final String DRIVER_NAME = "com.aliyun.odps.jdbc.OdpsDriver";
      // An Alibaba Cloud account's AccessKey pair has permissions for all API operations, which is a security risk. We strongly recommend using a RAM user for API access or routine O&M. To create a RAM user, log on to the RAM console.
      // This example stores the AccessKey ID and AccessKey secret in environment variables. You can also store them in a configuration file based on your business requirements.
      // For security, do not hardcode the AccessKey ID and AccessKey secret in your code.
      private static String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
      private static String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
  
      public static void main(String[] args) {
          try {
              Class.forName(DRIVER_NAME);
          } catch (ClassNotFoundException e) {
              e.printStackTrace();
              System.exit(1);
          }
  
          try (
              Connection conn = DriverManager.getConnection(
                  "jdbc:odps:<maxcompute_endpoint>?project=<maxcompute_project>",
                  Main.accessId, Main.accessKey);
              Statement stmt = conn.createStatement()
          ) {
              // create a table
              final String tableName = "jdbc_test";
              stmt.execute("DROP TABLE IF EXISTS " + tableName);
              stmt.execute("CREATE TABLE " + tableName + " (key BIGINT, value STRING)");
  
              // get meta data
              DatabaseMetaData metaData = conn.getMetaData();
              System.out.println("product = " + metaData.getDatabaseProductName());
              System.out.println("jdbc version = "
                                 + metaData.getDriverMajorVersion() + ", "
                                 + metaData.getDriverMinorVersion());
  
              try (ResultSet tables = metaData.getTables(null, "default", tableName, null)) {
                  while (tables.next()) {
                      String name = tables.getString("TABLE_NAME");
                      System.out.println("inspecting table: " + name);
  
                      try (ResultSet columns = metaData.getColumns(null, null, name, null)) {
                          while (columns.next()) {
                              System.out.println(
                                  columns.getString("COLUMN_NAME") + "\t" +
                                  columns.getString("TYPE_NAME") + "(" +
                                  columns.getInt("DATA_TYPE") + ")");
                          }
                      }
                  }
              }
          } catch (SQLException e) {
              e.printStackTrace();
          }
      }
  }

  Saída de exemplo:

  product = MaxCompute/ODPS
  jdbc version = 3, 8
  inspecting table: jdbc_test
  key    BIGINT(-5)
  value    STRING(12)

• Atualize uma tabela

  import java.sql.Connection;
  import java.sql.DriverManager;
  import java.sql.SQLException;
  import java.sql.Statement;
  
  public class Main {
  
      private static final String DRIVER_NAME = "com.aliyun.odps.jdbc.OdpsDriver";
      // An Alibaba Cloud account's AccessKey pair has permissions for all API operations, which is a security risk. We strongly recommend using a RAM user for API access or routine O&M. To create a RAM user, log on to the RAM console.
      // This example stores the AccessKey ID and AccessKey secret in environment variables. You can also store them in a configuration file based on your business requirements.
      // For security, do not hardcode the AccessKey ID and AccessKey secret in your code.
      private static String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
      private static String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
  
      public static void main(String[] args) {
          try {
              Class.forName(DRIVER_NAME);
          } catch (ClassNotFoundException e) {
              e.printStackTrace();
              System.exit(1);
          }
  
          try (
              Connection conn = DriverManager.getConnection(
                  "jdbc:odps:<maxcompute_endpoint>?project=<maxcompute_project>",
                  Main.accessId, Main.accessKey);
              Statement stmt = conn.createStatement()
          ) {
              // The following DML also works
              // String dml = "INSERT INTO jdbc_test SELECT 1, \"foo\"";
              String dml = "INSERT INTO jdbc_test VALUES(1, \"foo\")";
              int ret = stmt.executeUpdate(dml);
  
              assert ret == 1;
          } catch (SQLException e) {
              e.printStackTrace();
          }
      }
  }

• Atualize uma tabela em lote

  import java.sql.Connection;
  import java.sql.DriverManager;
  import java.sql.PreparedStatement;
  import java.sql.SQLException;
  
  public class Main {
  
      private static final String DRIVER_NAME = "com.aliyun.odps.jdbc.OdpsDriver";
      // An Alibaba Cloud account's AccessKey pair has permissions for all API operations, which is a security risk. We strongly recommend using a RAM user for API access or routine O&M.
      // This example stores the AccessKey ID and AccessKey secret in environment variables. You can also store them in a configuration file based on your business requirements.
      // For security, do not hardcode the AccessKey ID and AccessKey secret in your code.
      private static String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
      private static String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
  
      public static void main(String[] args) {
          try {
              Class.forName(DRIVER_NAME);
          } catch (ClassNotFoundException e) {
              e.printStackTrace();
              System.exit(1);
          }
  
          try (
              Connection conn = DriverManager.getConnection(
                  "jdbc:odps:<maxcompute_endpoint>?project=<maxcompute_project>",
                  Main.accessId, Main.accessKey);
              PreparedStatement pstmt = conn.prepareStatement("INSERT INTO jdbc_test VALUES(?, ?)")
          ) {
              // First batch
              pstmt.setLong(1, 1L);
              pstmt.setString(2, "foo");
              pstmt.addBatch();
  
              // Second batch
              pstmt.setLong(1, 2L);
              pstmt.setString(2, "bar");
              pstmt.addBatch();
  
              int[] ret = pstmt.executeBatch();
  
              assert ret[0] == 1;
              assert ret[1] == 1;
  
          } catch (SQLException e) {
              e.printStackTrace();
          }
      }
  }

  Nota

  • O método executeBatch não suporta gravações em lote em tabelas clusterizadas, como tabelas Transaction Table 2.0.

  • Para gravar dados em uma tabela particionada padrão em lotes, especifique a partição de destino na instrução INSERT INTO. Exemplo:

    -- The table creation statement for the partitioned table sale_detail is as follows.
    create table if not exists sale_detail
    (
    shop_name string,
    customer_id string,
    total_price double
    )
    partitioned by (sale_date string, region string);
    
    -- Assume that the partition sale_date='20240219', region='hangzhou' already exists. The INSERT INTO statement for batch writes to the partitioned table is as follows.
    INSERT INTO sale_detail PARTITION(sale_date='20240219', region='hangzhou') VALUES(?, ?, ?)

• Visualize uma tabela

  import java.sql.Connection;
  import java.sql.DriverManager;
  import java.sql.ResultSet;
  import java.sql.SQLException;
  import java.sql.Statement;
  
  public class Main {
  
      private static final String DRIVER_NAME = "com.aliyun.odps.jdbc.OdpsDriver";
      // An Alibaba Cloud account's AccessKey pair has permissions for all API operations, which is a security risk. We strongly recommend using a RAM user for API access or routine O&M.
      // This example stores the AccessKey ID and AccessKey secret in environment variables. You can also store them in a configuration file based on your business requirements.
      // For security, do not hardcode the AccessKey ID and AccessKey secret in your code.
      private static String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
      private static String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");
  
      public static void main(String[] args) {
          try {
              Class.forName(DRIVER_NAME);
          } catch (ClassNotFoundException e) {
              e.printStackTrace();
              System.exit(1);
          }
  
          try (
              Connection conn = DriverManager.getConnection(
                  "jdbc:odps:<maxcompute_endpoint>?project=<maxcompute_project>",
                  accessId, accessKey);
              Statement stmt = conn.createStatement();
              ResultSet rset = stmt.executeQuery("SELECT * FROM JDBC_TEST")
          ) {
              while (rset.next()) {
                  System.out.println(rset.getInt(1) + "\t" + rset.getString(2));
              }
          } catch (SQLException e) {
              e.printStackTrace();
          }
      }
  }

  Nota

  OdpsStatement suporta três métodos: execute(sql), executeQuery(sql) e executeUpdate(sql). Os métodos execute(sql) e executeQuery(sql) também suportam três comandos comuns: desc table, show tables e show partitions.