Создание JAR-файла, совместимого с Azure Databricks

Архив Java (JAR) упаковывает код на Java или Scala для развертывания в заданиях Lakeflow. На этой странице рассматриваются требования к совместимости JAR и конфигурация проекта для различных типов вычислений.

На высоком уровне JAR-файл должен соответствовать следующим требованиям для обеспечения совместимости:

• Соответствующие версии: используйте те же версии Java Development Kit (JDK), Scala и Spark, что и ваши компьютерные ресурсы.
• Укажите зависимости: включите необходимые библиотеки в JAR-файл или установите их на вычислительные ресурсы.
• Использование сеанса Databricks Spark: вызов SparkSession.builder().getOrCreate() для доступа к сеансу
• Список разрешенных JAR-файлов (только для стандартных вычислений): добавьте JAR-файл в список разрешений

Архитектура вычислений

Бессерверные и стандартные вычислительные ресурсы используют архитектуру Spark Connect для изоляции пользовательского кода и обеспечения управления каталогом Unity. Databricks Connect включает API Spark Connect. Бессерверные и стандартные вычислительные ресурсы не поддерживают Spark Context и Spark RDD API напрямую. Ознакомьтесь с ограничениями бессерверного доступа и стандартным режимом доступа.

Выделенные вычисления используют классическую архитектуру Spark и включают все API Spark.

Поиск версий JDK, Scala и Spark

Сопоставление версий JDK, Scala и Spark, работающих в вычислительных средах

При сборке JAR-файла ваши версии JDK, Scala и Spark должны соответствовать версиям, установленным на ваших вычислительных ресурсах. Эти три версии связаны друг с другом— версия Spark определяет совместимую версию Scala, и обе версии зависят от конкретной версии JDK.

Выполните следующие действия, чтобы найти правильные версии для типа вычислений:

Serverless

1. Использование бессерверной среды версии 4 или более поздней

2. Найдите версию Databricks Connect, JDK и Scala для вашей среды в таблице версий бессерверных сред .

Стандарт

1. Нажмите Компьютер на боковой панели и выберите ваши вычислительные ресурсы для просмотра версии среды выполнения Databricks
2. Используйте версию Databricks Connect, которая соответствует основной и дополнительной версии Databricks Runtime (например, Databricks Runtime 17.3 → databricks-connect 17.x). Найдите соответствующие версии JDK и Scala в матрице поддержки версий.

Dedicated

1. Нажмите Компьютер на боковой панели и выберите ваши вычислительные ресурсы для просмотра версии среды выполнения Databricks
2. Найдите версии JDK, Scala и Spark в разделе "Системная среда " заметок о выпуске для версии среды выполнения Databricks (например, Databricks Runtime 17.3 LTS)

Настройка проекта

После получения сведений о требованиях к версии настройте файлы сборки и упаковайте JAR-файл.

Настройка версий JDK и Scala

Настройте файл сборки для использования правильных версий JDK и Scala. В следующих примерах показаны версии для Databricks Runtime 17.3 LTS и бессерверной среды версии 4.

Sbt

В build.sbt:

scalaVersion := "2.13.16"

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

Мейвен

В 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>

Зависимости Spark

Добавьте зависимость Spark для доступа к API Spark без упаковки Spark в JAR-файл.

Serverless

Использование Databricks Connect

Добавьте зависимость от Databricks Connect (рекомендуется). Версия Databricks Connect должна соответствовать версии Databricks Connect в бессерверной среде. Отметьте это как provided, потому что оно включено в среду выполнения. Не включайте зависимости Apache Spark, такие как spark-core, или прочие org.apache.spark компоненты в файл сборки. Databricks Connect имеет все необходимые API Spark.

Maven pom.xml:

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

sbt build.sbt:

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

Альтернатива: spark-sql-api

Вы можете скомпилироваться против spark-sql-api вместо Databricks Connect, но Databricks рекомендует использовать Databricks Connect, так как API Spark, работающие с использованием бессерверных вычислений, могут немного отличаться от Spark с открытым исходным кодом. Эти библиотеки включены в среду выполнения, поэтому помечайте их как 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"

Стандартный режим доступа

Использование Databricks Connect

Добавьте зависимость от Databricks Connect (рекомендуется). Версия Databricks Connect должна соответствовать основной и дополнительной версии среды выполнения Databricks в кластере (например, Databricks Runtime 17.3 → databricks-connect 17.x). Отметьте это как provided, потому что оно включено в среду выполнения. Не включайте зависимости Apache Spark, такие как spark-core, или прочие org.apache.spark компоненты в файл сборки. Databricks Connect имеет все необходимые API Spark.

Maven pom.xml:

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

sbt build.sbt:

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

Альтернатива: spark-sql-api

Вы можете компилировать против spark-sql-api вместо Databricks Connect, но Databricks рекомендует использовать Databricks Connect, так как Spark API, работающие в среде бессерверных вычислений, могут немного отличаться от открытого Spark. Эти библиотеки включены в среду выполнения, поэтому помечайте их как 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"

Выделенный режим доступа

Использование API Databricks Connect или Spark

Добавьте зависимость от Databricks Connect (рекомендуется) или скомпилируйте библиотеки Spark с областью действия provided.

Вариант 1: databricks-connect (рекомендуется)

Отметьте это как provided, потому что оно включено в среду выполнения.

Maven pom.xml:

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

sbt build.sbt:

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

Вариант 2. Spark-sql-api

Вы можете компилировать с spark-sql-api, но это не рекомендуется, так как версия в Databricks может немного отличаться. Эти библиотеки включены в среду выполнения, поэтому помечайте их как 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"

Вариант 3. Другие библиотеки Spark

Вы можете использовать любую библиотеку Apache Spark (например, spark-core или spark-sql) с областью providedдействия, если версия соответствует версии Spark, работающей в кластере. Найдите версию Spark вашего кластера в разделе "Системная среда" в примечаниях к выпуску Databricks Runtime.

Зависимости приложений

Добавьте необходимые библиотеки приложения в файл сборки. Управление ими зависит от типа вычислительных ресурсов:

Serverless

Бессерверные вычисления предоставляют Databricks Connect и ограниченный набор зависимостей (см. заметки о выпуске). Упаковайте все остальные библиотеки в JAR с помощью sbt-assembly или подключаемого модуля шейдера Maven или добавьте их в бессерверную среду.

Например, чтобы упаковать библиотеку в 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"

Стандартный режим доступа

Среда выполнения Databricks включает множество распространенных библиотек за пределами Spark. Полный список предоставленных библиотек и версий см. в разделе Системная среда в заметках о выпуске Databricks Runtime для вашей версии Databricks Runtime (например, Databricks Runtime 17.3 LTS).

Для библиотек, предоставляемых Databricks Runtime, добавьте их в качестве зависимостей с областью provided. Например, в Databricks Runtime 17.3 LTS protobuf-java предоставляется:

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"

Для библиотек, не предоставляемых Databricks Runtime, либо упаковайте их в JAR-файл с помощью sbt-assembly или плагина Maven Shade, либо установите их как библиотеки, ограниченные областью вычислений.

Выделенный режим доступа

Среда выполнения Databricks включает множество распространенных библиотек за пределами Spark. Полный список предоставленных библиотек и версий см. в разделе Системная среда в заметках о выпуске Databricks Runtime для вашей версии Databricks Runtime (например, Databricks Runtime 17.3 LTS).

Для библиотек, предоставляемых Databricks Runtime, добавьте их в качестве зависимостей с областью provided. Например, в Databricks Runtime 17.3 LTS protobuf-java предоставляется:

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"

Для библиотек, не предоставляемых Databricks Runtime, либо упаковайте их в JAR-файл с помощью sbt-assembly или плагина Maven Shade, либо установите их как библиотеки, ограниченные областью вычислений.

Требования к коду

При написании JAR-кода следуйте этим шаблонам, чтобы обеспечить совместимость с заданиями Databricks.

Использование сеанса Databricks Spark

При запуске JAR-файла в задании необходимо использовать сеанс Spark, предоставляемый Azure Databricks. В следующем коде показано, как получить доступ к сеансу в вашем коде.

Ява

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

Scala

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

Использование try-finally блоков для очистки задания

Если вы хотите, чтобы код надежно выполнялся в конце вашего задания, например, для очистки временных файлов, используйте конструкцию try-finally. Не используйте перехватчик завершения работы, так как они не выполняются надежно в заданиях.

Возьмем для примера JAR, состоящий из двух частей:

• jobBody() — содержит основную часть задания;
• jobCleanup() должно выполняться после jobBody(), независимо от того, завершается ли функция успешно или выдает исключение.

Например, jobBody() создает таблицы и jobCleanup() удаляет эти таблицы.

Безопасный способ убедиться, что метод очистки вызывается, это поместить try-finally блок в код:

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

Не пытайтесь очистить с помощью sys.addShutdownHook(jobCleanup) или с использованием следующего кода:

// 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)

Azure Databricks управляет жизненным циклом контейнеров Spark таким образом, что хуки завершения не могут выполняться надежно.

Чтение параметров задания

Databricks передает параметры заданию JAR в виде массива строк JSON. Чтобы использовать эти параметры, проверьте массив, переданный String в функцию main .

Дополнительные сведения о параметрах см. в разделе "Параметризация заданий".

Дополнительная настройка

В зависимости от типа вычислений может потребоваться дополнительная конфигурация:

• Стандартный режим доступа: по соображениям безопасности администратор должен добавить координаты и пути Maven для библиотек JAR в список разрешений.
• Бессерверные вычисления: если задание обращается к частным ресурсам (базам данных, API, хранилищу), настройте сеть с конфигурацией сетевого подключения (NCC). См. раздел "Бессерверная сетевая безопасность".

Дальнейшие шаги

• Узнайте, как использовать jar в задании.
• Узнайте о Databricks Connect.
• Узнайте больше о Scala в Databricks.