Pular para o conteúdo principal

Crie um arquivo JAR compatível com o Databricks.

Esta página descreve como criar um JAR com código Scala ou Java que seja compatível com seu workspace Databricks .

Em linhas gerais, seu arquivo JAR deve atender aos seguintes requisitos de compatibilidade:

  • A versão do seu Java Development Kit (JDK) corresponde à versão do JDK no seu cluster Databricks ou compute serverless .
  • Para Scala, sua versão do Scala deve corresponder à versão Scala em seu cluster Databricks ou compute serverless .
  • Databricks Connect foi adicionado como uma dependência e corresponde à versão em execução no seu cluster Databricks ou compute serverless , ou suas dependências do Spark são compatíveis com seu ambiente Databricks .
  • O projeto local que você está compilando é empacotado como um único JAR e inclui todas as dependências não fornecidas. Alternativamente, você pode adicioná-los ao seu ambiente ou cluster.
  • O código no seu arquivo JAR interage corretamente com a sessão ou contexto do Spark.
  • Para compute padrão, todos os arquivos JAR utilizados são adicionados à lista de permissões.
dica

Para criar um projeto Java ou Scala totalmente configurado para implantar e executar um JAR em compute serverless , você pode usar Databricks Ativo Bundles. Para um exemplo de configuração de pacote que carrega um JAR, consulte Pacote que carrega um arquivo JAR para Unity Catalog. Para criar um projeto Scala usando pacotes ativos Databricks , consulte Construir um JAR Scala usando pacotes ativos Databricks.

info

Beta

O uso de compute serverless para tarefas JAR está em versão beta.

Controle de versão do Databricks Connect e do Databricks Runtime​

Ao criar um JAR para execução no Databricks, é útil entender como você chama APIs Spark e qual versão das APIs você está utilizando.

Databricks Connect​

O Databricks Connect implementa a arquitetura Spark Connect, que separa os componentes de cliente e servidor. Essa separação permite compartilhar clusters de forma eficiente, ao mesmo tempo que aplica integralmente a governança do Unity Catalog com medidas como filtros de linha e máscaras de coluna. No entanto, os clusters do Unity Catalog no modo de acesso padrão apresentam algumas limitações, como a falta de suporte para APIs como Spark Context e RDDs. As limitações estão listadas em Requisitos e limitações compute padrão.

Databricks Connect oferece acesso a todas as funcionalidades Spark , incluindo Spark Connect, e está incluído nos compute padrão e serverless . Para esses tipos compute , Databricks Connect é necessário, pois fornece todas APIs Spark necessárias.

Databricks Runtime​

A execução do Databricks Runtime no compute gerenciado pelo Databricks. É baseado no Spark, mas inclui melhorias de desempenho e outros aprimoramentos para facilitar o uso.

Em compute serverless ou computação padrão, Databricks Connect fornece APIs que chamam o Databricks Runtime em execução no compute. Em compute dedicada, você compila usando as APIs Spark , que são suportadas pelo Databricks Runtime na computação.

Encontre as versões corretas para o seu compute​

Para compilar um arquivo JAR compatível, você precisa saber a versão do Databricks Connect e Databricks Runtime que seu compute está executando.

Tipo de Compute

Como encontrar as versões corretas

Serverless

Utiliza o Databricks Connect. Você precisa de um ambiente serverless versão 4 ou superior. Para encontrar a versão atual Databricks Connect para um ambiente serverless , consulte Versões de ambiente sem servidor.

Encontre as versões do JDK e do Scala para a versão do Databricks Connect na matriz de suporte de versões.

calcular em modo padrão

Utiliza o Databricks Runtime e fornece o Databricks Connect para chamar APIs. Para encontrar a versão Databricks Runtime para seu compute:

  • Na workspace, clique em Ícone de nuvem. Na barra lateral, clique em " Calcular " e selecione o compute. A versão do Databricks Runtime é exibida nos detalhes da configuração.

Os valores de versão principal e secundária do Databricks Connect correspondem aos valores de versão principal e secundária do Databricks Runtime.

computar em modo dedicado

Utiliza o Databricks Runtime e permite compilar diretamente com as APIs do Spark.

Para encontrar a versão Databricks Runtime para o seu cluster compute :

  • Na workspace, clique em Ícone de nuvem. Na barra lateral, clique em " Calcular " e selecione o compute. A versão do Databricks Runtime é exibida nos detalhes da configuração.

Versões do JDK e do Scala​

Ao criar um JAR, as versões do Java Development Kit (JDK) e Scala que você usa para compilar seu código devem corresponder às versões em execução no seu compute.

Para compute serverless ou computação padrão, use a versão Databricks Connect para encontrar as versões compatíveis do JDK e Scala . Consulte a matriz de suporte de versões.

Se você estiver usando compute dedicada, as versões do JDK e Scala do Databricks Runtime na compute devem ser compatíveis. A seção Ambiente do sistema das notas sobre a versão e compatibilidadeDatabricks Runtime Databricks Runtime para cada versão inclui as versões corretas Java e Scala . Por exemplo, para o Databricks Runtime 17.3 LTS, consulte Databricks Runtime 17.3 LTS.

nota

Usar uma versão do JDK ou Scala que não corresponda às versões do JDK ou Scala do seu compute pode causar comportamentos inesperados ou impedir a execução do seu código.

Dependências​

Você precisa configurar suas dependências corretamente no seu arquivo de compilação.

Databricks Connect ou Apache Spark​

Para compute padrão ou serverless , Databricks recomenda adicionar uma dependência do Databricks Connect em vez do Spark para criar arquivos JAR. O Databricks Runtime não é idêntico ao Spark e inclui melhorias de desempenho e estabilidade. O Databricks Connect fornece as APIs do Spark que estão disponíveis no Databricks. Para incluir o Databricks Connect, adicione uma dependência:

No arquivo Maven pom.xml :

<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-connect_2.13</artifactId>
  <version>17.0.2</version>
</dependency>
nota

A versão do Databricks Connect deve corresponder à versão incluída no Databricks Runtime do seu cluster.

A Databricks recomenda o uso do Databricks Connect. Se você não quiser usar o Databricks Connect, compile usando spark-sql-api. Adicione esta biblioteca Spark específica às suas dependências, mas não a inclua no seu JAR. No arquivo de compilação, configure o escopo da dependência como provided:

No arquivo Maven pom.xml :

<dependency>
  <groupId>org.apache.spark</groupId>
  <artifactId>spark-sql-api</artifactId>
  <version>4.0.1</version>
  <scope>provided</scope>
</dependency>

Dependências do Spark​

Para compute padrão e computação serverless, não inclua nenhuma outra dependência Spark em seu projeto. O uso do Databricks Connect fornece todas as APIs de sessão do Spark necessárias.

Biblioteca fornecida pelo Classic compute e Databricks Runtime​

Se você estiver executando em compute clássica (em modo dedicado ou padrão), o Databricks Runtime inclui muitas bibliotecas comuns. Encontre a biblioteca e as versões incluídas na seção Ambiente do Sistema das notas sobre a versãoDatabricks Runtime para a sua versão Databricks Runtime . Por exemplo, a seção Ambiente de Sistema do Databricks Runtime 17.3 LTS lista as versões de cada biblioteca disponíveis no Databricks Runtime.

Para compilar usando uma dessas bibliotecas, adicione-a como uma dependência com a opção provided . Por exemplo, no Databricks Runtime 17.3 LTS, a biblioteca protobuf-java é fornecida e você pode compilar com ela usando a seguinte configuração:

No Maven pom.xml:

<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java</artifactId>
  <version>3.25.5</version>
  <scope>provided</scope>
</dependency>

Sem servidor e biblioteca não fornecida​

O Serverless fornece, por default, um conjunto reduzido de dependências para minimizar problemas causados por conflitos entre bibliotecas.

Para bibliotecas que não estão disponíveis em compute serverless ou no Databricks Runtime, você pode incluí-las você mesmo em seu JAR. Por exemplo, para incluir circe-core no seu arquivo build.sbt , adicione o seguinte comando:

libraryDependencies += "io.circe" %% "circe-core" % "0.14.10"

Para adicionar a biblioteca ao ambiente serverless , consulte Configurar ambiente para tarefas de trabalho que não sejam de notebook.

pacote como um único JAR​

A Databricks recomenda empacotar seu aplicativo e todas as dependências em um único arquivo JAR, também conhecido como über ou fat JAR . Para sbt, use sbt-assembly e para Maven, use maven-shade-plugin. Consulte a documentação oficial do Maven Shade Plugin e do sbt-assembly para obter detalhes.

Alternativamente, você pode instalar as dependências como uma biblioteca com escopo de cluster . Consulte a biblioteca com escopocompute para obter mais informações. Se você instalar a biblioteca em seu cluster, sua dependência no código deve incluir a palavra-chave provided para evitar empacotar a biblioteca em seu jar. Para serverless, adicione-os ao ambiente serverless que você utiliza. Consulte Configurar ambiente para tarefas de trabalho que não sejam em notebooks.

nota

Para JARs Scala instalados como biblioteca em clusters padrão Unity Catalog , as classes na biblioteca JAR devem estar em um pacote nomeado, como com.databricks.MyClass, ou ocorrerão erros ao importar a biblioteca.

Utilizando a sessão Spark em seu código​

Ao executar um JAR dentro de um Job, você deve usar a sessão Spark fornecida pelo Databricks para o Job. O código a seguir mostra como acessar a sessão a partir do seu código:

SparkSession spark = SparkSession.builder().getOrCreate();

Certifique-se de que seu JAR esteja na lista de permissões ( compute padrão).​

Por motivos de segurança, o modo de acesso padrão exige que um administrador adicione as coordenadas e os caminhos Maven para a biblioteca JAR a uma lista de permissões. Consulte a biblioteca Allowlist e o script de inicialização no compute com acesso padrão (anteriormente modo de acesso compartilhado).

Recomendação: Use blocos try-finally para limpeza de tarefas.​

Se você quiser ter um código que seja executado de forma confiável no final do seu Job, por exemplo, para limpar arquivos temporários que foram criados durante o Job, use um bloco try-finally . Não utilize um gancho de desligamento, pois estes não executam tarefas de forma confiável.

Considere um JAR que consiste em duas partes:

  • jobBody() que contém a parte principal do Trabalho.
  • jobCleanup() que deve ser executada após jobBody(), independentemente de a função ter sido bem-sucedida ou ter retornado uma exceção.

Por exemplo, jobBody() cria tabelas e jobCleanup() exclui essas tabelas.

A maneira segura de garantir que o método de limpeza seja chamado é inserir um bloco try-finally no código:

Scala
try {
  jobBody()
} finally {
  jobCleanup()
}

Você não deve tentar limpar usando sys.addShutdownHook(jobCleanup) ou o seguinte código:

Scala
// Do NOT clean up with a shutdown hook like this. This will fail.
val cleanupThread = new Thread { override def run = jobCleanup() }
Runtime.getRuntime.addShutdownHook(cleanupThread)

Devido à forma como o ciclo de vida dos contêineres Spark é gerenciado no Databricks, os hooks de desligamento não são executados de forma confiável.

Parâmetros de leitura do trabalho​

Os parâmetros são passados para o seu Job JAR através de um array de strings JSON . Para acessar esses parâmetros, inspecione a matriz String passada para sua função main .

Para obter mais detalhes sobre os parâmetros, consulte Parametrizar Tarefa.

Configure redes serverless​

Se o seu trabalho acessar recursos privados (bancos de dados, APIs, armazenamento), configure a rede com uma Configuração de Conectividade de Rede (NCC). Veja segurança de rede sem servidor.

Criar um arquivo JAR​

Os passos a seguir orientam você na criação e compilação de um arquivo JAR simples usando Scala ou Java para funcionar no Databricks.

Requisitos​

Seu ambiente de desenvolvimento local deve conter o seguinte:

  • Kit de Desenvolvimento Java (JDK) 17.
  • sbt (para JARs Scala).
  • Databricks CLI versão 0.218.0 ou acima. Para verificar a versão instalada do Databricks CLI, execute o comando databricks -v. Para instalar a CLI do Databricks, consulte Instalar ou atualizar a CLI do Databricks.
  • A autenticação da CLI do Databricks está configurada com um perfil DEFAULT . Para configurar a autenticação, consulte Configurar o acesso ao seu workspace.

Criar um JAR Scala​

  1. execute o seguinte comando para criar um novo projeto Scala :

    > sbt new scala/scala-seed.g8

    Quando solicitado, insira um nome de projeto, por exemplo, my-spark-app.

  2. Substitua o conteúdo do seu arquivo build.sbt pelo seguinte. Escolha as versões Scala e Databricks Connect necessárias para o seu compute. Consulte Dependências.

    Scala
    scalaVersion := "2.13.16"
    libraryDependencies += "com.databricks" %% "databricks-connect" % "17.0.1"
    // other dependencies go here...

    // to run with new jvm options, a fork is required otherwise it uses same options as sbt process
    fork := true
    javaOptions += "--add-opens=java.base/java.nio=ALL-UNNAMED"

  3. Edite ou crie um arquivo project/assembly.sbt e adicione esta linha:

    addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "2.3.1")

  4. Crie sua classe principal em src/main/scala/example/DatabricksExample.scala:

    Scala
    package com.examples

    import com.databricks.connect.DatabricksSession
    import org.apache.spark.sql.{SparkSession}

    object SparkJar {
      def main(args: Array[String]): Unit = {
        val spark: SparkSession = DatabricksSession.builder().getOrCreate()

        // Prints the arguments to the class, which
        // are job parameters when run as a job:
        println(args.mkString(", "))

        // Shows using spark:
        println(spark.version)
        println(spark.range(10).limit(3).collect().mkString(" "))
      }
    }

  5. Para construir seu arquivo JAR , execute o seguinte comando:

    Bash
    > sbt assembly

Criar um arquivo JAR Java​

  1. Crie uma pasta para o seu arquivo JAR.

  2. Na pasta, crie um arquivo chamado PrintArgs.java com o seguinte conteúdo:

    Java
    import java.util.Arrays;

    public class PrintArgs {
      public static void main(String[] args) {
        System.out.println(Arrays.toString(args));
      }
    }

  3. Compile o arquivo PrintArgs.java , que cria o arquivo PrintArgs.class:

    Bash
    javac PrintArgs.java

  4. (Opcional) execução do programa compilado:

    Bash
    java PrintArgs Hello World!

    # [Hello, World!]

  5. Na pasta, crie um arquivo pom.xml e adicione o seguinte código para habilitar o sombreamento do Maven.

    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-shade-plugin</artifactId>
          <version>3.6.0</version>
          <executions>
            <execution>
              <phase>package</phase>
              <goals><goal>shade</goal></goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>

  6. Na pasta JAR, crie uma pasta chamada META-INF.

  7. Na pasta META-INF , crie um arquivo chamado MANIFEST.MF com o seguinte conteúdo. Certifique-se de adicionar uma nova linha ao final deste arquivo:

    Main-Class: PrintArgs

  8. A partir da sua pasta JAR, crie um arquivo JAR chamado PrintArgs.jar:

    Bash
    jar cvfm PrintArgs.jar META-INF/MANIFEST.MF *.class

  9. (Opcional) Para testá-lo, execute o JAR:

    Bash
    java -jar PrintArgs.jar Hello World!

    # [Hello, World!]
nota

Se você receber o erro no main manifest attribute, in PrintArgs.jar, certifique-se de adicionar uma nova linha ao final do arquivo MANIFEST.MF e tente criar e executar o JAR novamente.

Próximos passos​

Última atualização em