Criar um JAR compatível com o Azure Databricks

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

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

• Alinhar versões: Use as mesmas versões de Java Development Kit (JDK), Scala e Spark que os seus recursos de computação.
• Forneça dependências: Inclua as bibliotecas necessárias no seu JAR ou instale-as no seu computador
• Usar a sessão Databricks Spark: Chamar SparkSession.builder().getOrCreate() para aceder à sessão
• Autorizar o seu JAR (apenas computação padrão): Adicionar o seu JAR à lista de autorização

Arquitetura de computação

A computação serverless e padrão utiliza a arquitetura Spark Connect para isolar o código do utilizador e impor a gestão do Unity Catalog. O Databricks Connect fornece acesso às APIs do Spark Connect. Serverless e computação padrão não suportam APIs Spark Context ou Spark RDD. Veja limitações sem servidor e limitações do modo de acesso padrão.

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

Encontre as suas versões para JDK, Scala e Spark

Compara as versões JDK, Scala e Spark a correr no teu computador

Quando constróis um JAR, as tuas versões JDK, Scala e Spark têm de coincidir com as versões a correr no teu computador. Estas três versões estão interligadas – 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 computação:

Serverless

1. Utilize o ambiente serverless, versão 4 ou superior
2. Encontre a versão Databricks Connect para o seu ambiente na tabela de versões do ambiente serverless . A versão Databricks Connect corresponde à sua versão do Spark.
3. Procura as versões correspondentes do JDK, Scala e Spark na matriz de suporte de versões

Standard

1. Clique Calcule na barra lateral e selecione o seu cálculo para visualizar a versão de Runtime do Databricks
2. Use uma versão Databricks Connect que corresponda às versões principais e menores do Databricks Runtime (por exemplo, Databricks Runtime 17.3 → databricks-connect 17.x)
3. Procura as versões correspondentes do JDK, Scala e Spark na matriz de suporte de versões. A versão Databricks Connect corresponde à sua versão do Spark.

Dedicado

1. Clique Calcule na barra lateral e selecione o seu cálculo para visualizar a versão de Runtime do Databricks
2. Encontre as versões JDK, Scala e Spark na secção do ambiente do Sistema das notas de lançamento da sua versão Databricks Runtime (por exemplo, Databricks Runtime 17.3 LTS)

Configuração do projeto

Depois de conheceres os requisitos de versão, configura os ficheiros de compilação e empacota o teu JAR.

Definir versões para JDK e Scala

Configura o teu ficheiro de build para usar as versões corretas do JDK e do Scala. Os exemplos seguintes 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")

Maven

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

Adiciona uma dependência do Spark para aceder às APIs do Spark sem o incluir no teu JAR.

Serverless

Use Databricks Connect

Adicionar uma dependência do Databricks Connect (recomendado). A versão do Databricks Connect deve corresponder à versão do Databricks Connect no seu ambiente serverless. Marque isso provided porque está incluído no tempo de execução. Não incluir dependências do Apache Spark, como spark-core, ou outros artefactos org.apache.spark no ficheiro de build. O Databricks Connect fornece todas as APIs 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

Podes compilar contra spark-sql-api em vez do Databricks Connect, mas o Databricks recomenda usar o Databricks Connect porque as APIs do Spark que executam em computação serverless podem diferir ligeiramente do Spark de código aberto. Estas bibliotecas estão incluídas no runtime, por isso 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

Use Databricks Connect

Adicionar uma dependência do Databricks Connect (recomendado). A versão do Databricks Connect deve corresponder à versão principal e menor do Databricks Runtime do seu cluster (por exemplo, Databricks Runtime 17.3 → databricks-connect 17.x). Marque isso provided porque está incluído no tempo de execução. Não incluir dependências do Apache Spark, como spark-core, ou outros artefactos org.apache.spark no ficheiro de build. O Databricks Connect fornece todas as APIs 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

Podes compilar contra spark-sql-api em vez do Databricks Connect, mas o Databricks recomenda usar o Databricks Connect porque as APIs do Spark que executam em computação serverless podem diferir ligeiramente do Spark de código aberto. Estas bibliotecas estão incluídas no runtime, por isso 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 dedicado

Use APIs Databricks Connect ou Spark

Adicionar uma dependência ao Databricks Connect (recomendado) ou compilar utilizando as bibliotecas Spark com âmbito provided.

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

Marque isso provided porque 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

Podes compilar contra spark-sql-api, mas isso não é recomendado porque a versão do Databricks pode diferir ligeiramente. Estas bibliotecas estão incluídas no runtime, por isso 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 Spark

Podes usar qualquer biblioteca Apache Spark (spark-core, spark-sql, etc.) com scope provided, desde que a versão coincida com a versão Spark a correr no teu cluster. Encontre a versão do Spark do seu cluster na secção de ambiente do Sistema das notas de lançamento do Databricks Runtime.

Dependências de aplicações

Adiciona as bibliotecas obrigatórias da tua aplicação ao ficheiro de build. A forma como geres estes depende do teu tipo de computação:

Serverless

A computação serverless fornece Databricks Connect e um conjunto limitado de dependências (ver notas de lançamento). Empacota todas as outras bibliotecas no teu JAR usando sbt-assembly ou Maven Shade Plugin, ou adiciona-as ao teu ambiente serverless.

Por exemplo, para empacotar uma biblioteca no 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 para além do Spark. Encontre a lista completa de bibliotecas e versões fornecidas na secção Ambiente de Sistema das notas de lançamento Databricks Runtime para a sua versão Databricks Runtime (por exemplo, Databricks Runtime 17.3 LTS).

Para bibliotecas fornecidas pelo Databricks Runtime, adicione-as como dependências com âmbito 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, ou empacote-as no seu JAR usando sbt-assembly ou Maven Shade Plugin, ou instale-as como bibliotecas com escopo de computação.

Modo de acesso dedicado

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

Para bibliotecas fornecidas pelo Databricks Runtime, adicione-as como dependências com âmbito 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, ou empacote-as no 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 seu código JAR, siga estes padrões para garantir compatibilidade com trabalhos Databricks.

Use a sessão do Databricks Spark

Ao executar um JAR num trabalho, deve usar a sessão Spark fornecida pelo Azure Databricks. O código a seguir mostra como acessar a sessão do seu código:

Java

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

Scala

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

Use try-finally blocos para a limpeza de tarefas

Se quiseres código que corra de forma fiável no final do teu trabalho, por exemplo, para limpar ficheiros temporários, usa um try-finally bloco. Não uses um gancho de desligamento, porque estes não funcionam de forma fiável nos trabalhos.

Considere um JAR que consiste em duas partes:

• jobBody() que contém a parte principal do trabalho.
• jobCleanup() que deve correr após jobBody(), quer essa função tenha sucesso ou devolva 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.

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 gere a vida útil dos contentores Spark de forma a impedir que os hooks de encerramento corram de forma fiável.

Leia os parâmetros do trabalho

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

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

Configuração adicional

Dependendo do tipo de computação, pode precisar de configurações adicionais:

• Modo de acesso padrão: Por razões de segurança, um administrador deve adicionar coordenadas e caminhos Maven para bibliotecas JAR a uma lista de permissões.
• Computação sem servidor: Se o seu trabalho aceder a recursos privados (bases de dados, APIs, armazenamento), configure a rede com uma Configuração de Conectividade de Rede (NCC). Consulte Segurança de rede sem servidor.

Próximos passos

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