Criar um JAR compatível com o Azure Databricks

Um arquivo Java (JAR) empacota código Java ou Scala para implantação em Jobs do Lakeflow. Este artigo aborda os requisitos de compatibilidade do JAR e a configuração do projeto para diferentes tipos de computação.

Dica

Para implantação automatizada e fluxos de trabalho de integração contínua, use pacotes de ativos do Databricks para criar um projeto a partir de um modelo com configurações de build e implantação pré-configuradas. Consulte Como criar um JAR do Scala usando Pacotes de Ativos do Databricks e Como carregar um arquivo JAR no Catálogo do Unity. Este artigo descreve a abordagem manual para entender os requisitos jar e as configurações personalizadas.

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

Versões de correspondência: use as mesmas versões do JDK (Java Development Kit), Scala e Spark que sua computação
Fornecer dependências: incluir bibliotecas necessárias em seu JAR ou instalá-las em sua computação
Usar a sessão do Databricks Spark: Chamada SparkSession.builder().getOrCreate() para acessar a sessão
Adicionar seu JAR à lista de permissões (somente computação padrão): adicione seu JAR à lista de permissões

Importante

Os trabalhos Scala e Java sem servidor estão em Beta. Você pode usar tarefas JAR para implantar seu JAR. Consulte Gerenciar visualizações do Azure Databricks se ele ainda não estiver habilitado.

Arquitetura de computação

A computação padrão e sem servidor usa a arquitetura do Spark Connect para isolar o código do usuário e impor a governança do Catálogo do Unity. O Databricks Connect fornece acesso às APIs do Spark Connect. A computação padrão e sem servidor não dá suporte às APIs de contexto do Spark ou de RDD do Spark. Veja as limitações sem servidor e as limitações do modo de acesso padrão.

A computação dedicada usa a arquitetura clássica do Spark e fornece acesso a todas as APIs do Spark.

Localizar as versões do JDK, do Scala e do Spark

Corresponder as versões do JDK, scala e Spark em execução em sua computação

Quando você cria um JAR, as versões JDK, Scala e Spark devem corresponder às versões em execução em sua computação. Essas três versões são interconectadas – a versão do Spark determina a versão do Scala compatível e ambas dependem de uma versão específica do JDK.

Siga estas etapas para encontrar as versões corretas para o tipo de computação:

Serverless

Usar o ambiente sem servidor versão 4 ou superior
Localize a versão do Databricks Connect para seu ambiente na tabela de versões de ambiente sem servidor . A versão do Databricks Connect corresponde à sua versão do Spark.
Pesquisar as versões correspondentes do JDK, do Scala e do Spark na matriz de suporte à versão

Standard

Clique no Compute na barra lateral e selecione sua computação para exibir a versão do Databricks Runtime
Use uma versão do Databricks Connect que corresponda à versão principal e secundária do Databricks Runtime (por exemplo, Databricks Runtime 17.3 → databricks-connect 17.x)
Procure as versões correspondentes do JDK, do Scala e do Spark na matriz de suporte à versão. A versão do Databricks Connect corresponde à sua versão do Spark.

Dedicado

Clique no Compute na barra lateral e selecione sua computação para exibir a versão do Databricks Runtime
Localize as versões JDK, Scala e Spark na seção Ambiente do sistema das notas de versão para sua versão do Databricks Runtime (por exemplo, Databricks Runtime 17.3 LTS)

Observação

Usar versões incompatíveis do JDK, do Scala ou do Spark pode causar um comportamento inesperado ou impedir a execução do código.

Configuração do projeto

Depois de conhecer os requisitos de versão, configure seus arquivos de build e empacote seu JAR.

Definir versões do JDK e do Scala

Configure o arquivo de build 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 do ambiente sem servidor versão 4-scala-preview.

Sbt

Em build.sbt:

scalaVersion := "2.13.16"

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

Especialista

Em pom.xml:

<properties>
  <scala.version>2.13.16</scala.version>
  <scala.binary.version>2.13</scala.binary.version>
  <maven.compiler.source>17</maven.compiler.source>
  <maven.compiler.target>17</maven.compiler.target>
</properties>

Dependências do Spark

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

Serverless

Usar o Databricks Connect

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

Maven pom.xml:

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

sbt build.sbt:

libraryDependencies += "com.databricks" %% "databricks-connect" % "17.0.2" % "provided"

Alternativa: spark-sql-api

Você pode compilar contra spark-sql-api em vez do Databricks Connect, mas a Databricks recomenda usar o Databricks Connect, pois as APIs do Spark em execução na computação servidorless podem diferir ligeiramente do Spark de código aberto. Essas bibliotecas são incluídas no runtime, portanto, marque-as como provided.

Maven pom.xml:

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

sbt build.sbt:

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

Modo de acesso padrão

Usar o Databricks Connect

Adicione uma dependência no Databricks Connect (recomendado). A versão do Databricks Connect deve corresponder à versão principal e secundária do Databricks Runtime do cluster (por exemplo, Databricks Runtime 17.3 → databricks-connect 17.x). Marque-o como provided porque ele está incluído no tempo de execução. Não inclua dependências do Apache Spark como spark-core ou outros org.apache.spark artefatos em seu arquivo de build. O Databricks Connect fornece todas as APIs do Spark necessárias.

Maven pom.xml:

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

sbt build.sbt:

libraryDependencies += "com.databricks" %% "databricks-connect" % "17.0.2" % "provided"

Alternativa: spark-sql-api

Maven pom.xml:

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

sbt build.sbt:

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

Modo de acesso dedicado

Usar APIs do Databricks Connect ou do Spark

Adicione uma dependência de Databricks Connect (recomendado) ou compile contra bibliotecas do Spark com escopo provided.

Opção 1: databricks-connect (recomendado)

Marque-o como provided porque ele está incluído no tempo de execução.

Maven pom.xml:

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

sbt build.sbt:

libraryDependencies += "com.databricks" %% "databricks-connect" % "17.0.2" % "provided"

Opção 2: spark-sql-api

Você pode compilar com spark-sql-api, mas isso não é recomendado porque a versão no Databricks pode ser ligeiramente diferente. Essas bibliotecas são incluídas no runtime, portanto, marque-as como provided.

Maven pom.xml:

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

sbt build.sbt:

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

Opção 3: Outras bibliotecas do Spark

Você pode usar qualquer biblioteca do Apache Spark (spark-coreetc spark-sql.) com escopo provided, desde que a versão corresponda à versão do Spark em execução no cluster. Localize a versão do Spark do cluster na seção Ambiente do sistema das notas de versão do Databricks Runtime.

Dependências de aplicativo

Adicione as bibliotecas necessárias do aplicativo ao arquivo de build. A maneira como você gerencia isso depende do tipo de computação:

Serverless

A computação sem servidor fornece o Databricks Connect e um conjunto limitado de dependências (confira as notas de 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:

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

sbt build.sbt:

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

Modo de acesso padrão

O Databricks Runtime inclui muitas bibliotecas comuns além do Spark. Encontre a lista completa de bibliotecas e versões fornecidas na seção Ambiente do Sistema das notas de versão do Databricks Runtime para sua versão do Databricks Runtime (por exemplo, Databricks Runtime 17.3 LTS).

Para bibliotecas fornecidas pelo Databricks Runtime, adicione-as como dependências com escopo provided. Por exemplo, no Databricks Runtime 17.3 LTS, protobuf-java é fornecido:

Maven pom.xml:

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

sbt build.sbt:

libraryDependencies += "com.google.protobuf" % "protobuf-java" % "3.25.5" % "provided"

Para bibliotecas não fornecidas pelo Databricks Runtime, empacote-as em seu JAR usando sbt-assembly ou Maven Shade Plugin, ou instale-as como bibliotecas com escopo de computação.

Modo de acesso dedicado

Para bibliotecas fornecidas pelo Databricks Runtime, adicione-as como dependências com escopo provided. Por exemplo, no Databricks Runtime 17.3 LTS, protobuf-java é fornecido:

Maven pom.xml:

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

sbt build.sbt:

libraryDependencies += "com.google.protobuf" % "protobuf-java" % "3.25.5" % "provided"

Para bibliotecas não fornecidas pelo Databricks Runtime, empacote-as em seu JAR usando sbt-assembly ou Maven Shade Plugin, ou instale-as como bibliotecas com escopo de computação.

Requisitos de código

Ao escrever o código JAR, siga esses padrões para garantir a compatibilidade com trabalhos do Databricks.

Use a sessão do Databricks Spark

Ao executar um JAR em um trabalho, você deve usar a sessão spark fornecida pelo Azure Databricks. O código a seguir mostra como acessar a sessão de seu código:

Java

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

Scala

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

Usar `try-finally` blocos para limpeza de tarefas

Se você quiser um código que seja executado de forma confiável no final do trabalho, por exemplo, para limpar arquivos temporários, use um try-finally bloco. Não use um gancho de desligamento, pois eles não são executados de forma confiável em trabalhos.

Considere um JAR que consiste em duas partes:

jobBody(), que contém a parte principal do trabalho.
jobCleanup() que deve ser executada depois de jobBody(), independentemente de a função ser bem-sucedida ou retornar uma exceção.

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

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

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

Não tente limpar usando sys.addShutdownHook(jobCleanup) ou o seguinte código:

// 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 Azure Databricks gerencia o ciclo de vida dos contêineres do Spark de uma maneira que impede que os ganchos de desligamento sejam executados de maneira confiável.

Ler parâmetros de trabalho

O Databricks passa parâmetros para seu trabalho JAR como uma matriz de cadeia de caracteres JSON. Para acessar esses parâmetros, inspecione a matriz String transmitida na sua função main.

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

Configuração adicional

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

Modo de acesso padrão: por motivos de segurança, um administrador deve adicionar coordenadas e caminhos do Maven para bibliotecas JAR a uma lista de permissões.
Computação sem servidor: se o trabalho acessar recursos privados (bancos de dados, APIs, armazenamento), configure a rede com uma NCC (Configuração de Conectividade de Rede). Consulte a segurança de rede sem servidor.

Próximas etapas

Saiba como usar um jar em um trabalho.
Saiba mais sobre o Databricks Connect.
Saiba mais sobre o Scala no Databricks.

Comentários

Esta página foi útil?

Last updated on 2025-12-30

Compartilhar via

Criar um JAR compatível com o Azure Databricks

Arquitetura de computação

Localizar as versões do JDK, do Scala e do Spark

Serverless

Standard

Dedicado

Configuração do projeto

Definir versões do JDK e do Scala

Sbt

Especialista

Dependências do Spark

Serverless

Modo de acesso padrão

Modo de acesso dedicado

Dependências de aplicativo

Serverless

Modo de acesso padrão

Modo de acesso dedicado

Requisitos de código

Use a sessão do Databricks Spark

Java

Scala

Usar try-finally blocos para limpeza de tarefas

Ler parâmetros de trabalho

Configuração adicional

Próximas etapas

Comentários

Recursos adicionais

Usar `try-finally` blocos para limpeza de tarefas