Pular para o conteúdo principal
Última atualização em

Crie um JAR compatível com Databricks

Um arquivo Java archive (JAR) empacota código Java ou Scala para implantação em LakeFlow Jobs. Atenda aos requisitos de compatibilidade JAR e configure seu projeto para o tipo de compute de destino.

dica

Para implantação automatizada e fluxos de trabalho de integração contínua, utilize Pacotes de Automação Declarativa para criar um projeto a partir de um padrão com configurações de compilação e implantação pré-configuradas. Consulte Crie um JAR Scala usando Pacotes de Automação Declarativa e Pacote que faz upload de um arquivo JAR para o Unity Catalog. Esta página descreve a abordagem manual para compreender os requisitos de JAR e as configurações personalizadas.

Em um nível alto, seu JAR deve atender aos seguintes requisitos de compatibilidade:

  • **Versões correspondentes**: Use as mesmas versões de Java Development Kit (JDK), Scala e Spark que seu compute
  • Forneça dependências : Inclua as bibliotecas necessárias em seu JAR ou instale-as em seu compute
  • Use a sessão Databricks Spark : Chame SparkSession.builder().getOrCreate() para acessar a sessão
  • Adicione seu JAR à lista de permissões (somente para compute padrão): Adicione seu JAR à lista de permissões
info

Visualização

Jobs serverless de Scala e Java estão em pré-visualização pública. Você pode usar tarefas JAR para implantar seu JAR. Consulte Gerenciar pré-visualizações do Databricks se ainda não estiver habilitado.

Arquitetura de compute​

Serverless e compute padrão usam a arquitetura Spark Connect para isolar o código do usuário e aplicar a governança do Unity Catalog. O Databricks Connect inclui as APIs Spark Connect. Serverless e compute padrão não suportam Spark Context ou APIs RDD do Spark diretamente. Veja limitações do serverless e limitações do modo de acesso padrão.

O compute dedicado usa a arquitetura Spark clássica e inclui todas as APIs do Spark.

Encontre suas versões do JDK, Scala e Spark​

Faça a correspondência entre as versões do JDK, Scala e Spark em execução em seu compute.

Ao construir um JAR, suas versões de JDK, Scala e Spark devem corresponder às versões executadas em seu compute. Estas três versões estão interconectadas — a versão do Spark determina a versão compatível do Scala, e ambas dependem de uma versão específica do JDK.

Siga estes passos para encontrar as versões corretas para o seu tipo de compute:

  1. Use a versão do ambiente serverless 4 ou superior

  2. Encontre as versões do Databricks Connect, JDK e Scala para seu ambiente na tabela de versões do ambiente serverless.

nota

O uso de versões incompatíveis de JDK, Scala ou Spark pode causar um comportamento inesperado ou impedir que seu código seja executado.

Configuração do projeto​

Depois de saber seus requisitos de versão, configure seus arquivos de compilação e empacote seu JAR.

Definir versões de JDK e Scala​

Configure seu arquivo de compilação para usar as versões corretas do JDK e do Scala. Os exemplos a seguir mostram as versões do Databricks Runtime 17,3 LTS e da versão 4 do ambiente serverless.

Em build.sbt:

Scala
scalaVersion := "2.13.16"

javacOptions ++= Seq("-source", "17", "-target", "17")

Dependências do Spark​

Adicione uma dependência do Spark para acessar as APIs do Spark sem empacotar o Spark em seu JAR.

Use o Databricks Connect

Adicione uma dependência no Databricks Connect (recomendado). A versão do Databricks Connect deve corresponder à versão do Databricks Connect no seu ambiente serverless. Marque-o como provided porque está incluído no runtime. Não inclua dependências do Apache Spark como spark-core ou outros artefatos org.apache.spark no seu arquivo de compilação. O Databricks Connect tem todas as APIs do Spark necessárias.

Maven pom.xml:

XML
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-connect_2.13</artifactId>
  <version>17.3.2</version>
  <scope>provided</scope>
</dependency>

sbt build.sbt:

Scala
libraryDependencies += "com.databricks" %% "databricks-connect" % "17.3.+" % "provided"

Alternativa: spark-sql-api

Você pode compilar com spark-sql-api em vez de Databricks Connect, mas a Databricks recomenda usar o Databricks Connect porque as APIs do Spark executadas em compute serverless podem diferir ligeiramente do Spark de código aberto. Estas bibliotecas estão incluídas no runtime, portanto, marque-as como provided.

Maven pom.xml:

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

sbt build.sbt:

Scala
libraryDependencies += "org.apache.spark" %% "spark-sql-api" % "4.0.1" % "provided"

Dependências do aplicativo​

Adicione as bibliotecas necessárias do seu aplicativo ao seu arquivo de compilação. A forma como você gerencia isso depende do seu tipo de compute:

O compute serverless fornece o Databricks Connect e um conjunto limitado de dependências (veja as notas sobre a versão). Empacote todas as outras bibliotecas em seu JAR usando sbt-assembly ou Maven Shade Plugin, ou adicione-as ao seu ambiente serverless.

Por exemplo, para empacotar uma biblioteca em seu JAR:

Maven pom.xml:

XML
<dependency>
  <groupId>io.circe</groupId>
  <artifactId>circe-core_2.13</artifactId>
  <version>0.14.10</version>
</dependency>

sbt build.sbt:

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

Requisitos de código​

Ao escrever seu código JAR, siga estes padrões para garantir a compatibilidade com Jobs do Databricks.

Use a sessão Spark do Databricks​

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

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

Use blocos try-finally para limpeza de jobs​

Se desejar um código que seja executado de forma confiável no final do seu Job, por exemplo, para limpar arquivos temporários, utilize um bloco try-finally. Não utilize um gancho de desligamento, porque estes não são executados de forma confiável em Jobs.

Considere um JAR que consiste em duas partes:

  • jobBody() que contém a parte principal do job.
  • jobCleanup() que deve executar após jobBody(), seja essa função bem-sucedida ou retorne uma exceção.

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

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

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

Não tente 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)

O Databricks gerencia os tempos de vida dos contêineres Spark de uma forma que impede que os ganchos de desligamento sejam executados de forma confiável.

Ler parâmetros de Job​

O Databricks passa parâmetros para seu Job JAR como uma matriz de strings do JSON. Para usar esses parâmetros, inspecione a matriz String passada para sua função main.

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

Configuração adicional​

Dependendo do seu tipo de compute, você pode precisar de configuração adicional:

  • Modo de acesso padrão : Por motivos de segurança, um administrador deve adicionar coordenadas Maven e caminhos para bibliotecas JAR a uma lista de permissões.
  • Compute serverless : Se seu Job acessar recursos privados (bancos de dados, APIs, armazenamento), configure a rede com uma Configuração de Conectividade de Rede (NCC). Consulte segurança de rede serverless.

Configurar registro para compute serverless​

No compute serverless, a API de log SLF4J usa um backend sem operações (NOP) por default. Isso significa que as mensagens de log de bibliotecas e do código do aplicativo que usam SLF4J são descartadas silenciosamente.

Para rotear a saída de log SLF4J para o backend do Log4j 2, você deve adicionar a ponte log4j-slf4j2-impl ao seu JAR fat ou como uma dependência JAR separada no seu job. O ambiente serverless inclui o backend Log4j 2 (log4j-api e log4j-core), mas a ponte que conecta SLF4J ao Log4j não está no classpath do usuário por default.

A versão da ponte deve corresponder à versão log4j-api fornecida no seu versão de ambiente serverless. Por exemplo, a versão 5 do ambiente usa log4j-api versão 2.20.0, portanto, é preciso adicionar log4j-slf4j2-impl versão 2.20.0.

Opção 1: Incluir a ponte em seu JAR monolítico​

Adicionar log4j-slf4j2-impl como uma dependência de compilação para que seja empacotado no seu JAR completo:

Em build.sbt:

Scala
libraryDependencies += "org.apache.logging.log4j" % "log4j-slf4j2-impl" % "2.20.0"

Opção 2: adicionar a bridge como uma dependência JAR separada no job​

Em vez de empacotar a ponte no seu JAR robusto, é possível adicioná-la como uma dependência de biblioteca separada ao configurar sua tarefa JAR. Na configuração da tarefa em **Ambiente e Bibliotecas**, adicione uma dependência JAR usando a coordenada Maven:

org.apache.logging.log4j:log4j-slf4j2-impl:2.20.0

Para obter detalhes sobre como adicionar dependências JAR a jobs serverless, consulte Configurar o ambiente serverless.

nota

Evite incluir log4j-api ou log4j-core no JAR monolítico. Estas bibliotecas já são fornecidas pelo runtime serverless, e empacotá-las pode causar conflitos de versão.

Outros recursos​

Nesta página