SDK do Databricks para Java

Nestes artigos, você aprende como automatizar operações na account do Databricks, workspace e no recurso relacionado com o SDK do Databricks para Java. Este artigo complementa o README do Databricks SDK para Java, referência de API e exemplos.

Observação

Este recurso está na versão beta e pode ser usado em produção.

Durante o período Beta, o Databricks recomenda que você pin uma dependência na versão secundária específica do SDK do Databricks para Java da qual seu código depende. Por exemplo, você pode pin dependências em arquivos como pom.xml para Maven. Para obter mais informações sobre fixação de dependências, consulte Introdução ao Mecanismo de Dependência.

Antes de começar

Antes de começar a usar o Databricks SDK para Java, sua máquina de desenvolvimento deve ter:

  • Autenticação do Databricks configurada.

  • Um Java Development Kit (JDK) compatível com Java 8 ou superior. O teste de CI (integração contínua) com o Databricks SDK para Java é compatível com as versões 8, 11, 17 e 20 do Java.

  • Um ambiente de desenvolvimento integrado (IDE) compatível com Java é recomendado. Databricks recomenda IntelliJ IDEA.

Comece a usar o Databricks SDK para Java

  1. No arquivo pom.xml do seu projeto, instrua seu sistema de compilação a tomar uma dependência do Databricks SDK para Java. Para fazer isso, adicione o seguinte <dependency> à seção <dependencies> existente do arquivo pom.xml . Se a seção <dependencies> ainda não existir no arquivo pom.xml , você também deverá adicionar o elemento pai <dependencies> ao arquivo pom.xml .

    Por exemplo, para abrir o arquivo pom.xml do seu projeto no IntelliJ IDEA, clique em view > Tool Windows > Project e clique duas vezes para abrir o nome do seu projeto > src > pom.xml.

    <dependencies>
  <dependency>
    <groupId>com.databricks</groupId>
    <artifactId>databricks-sdk-java</artifactId>
    <version>0.0.1</version>
  </dependency>
</dependencies>

    Observação

    Certifique-se de substituir 0.0.1 pela versão mais recente do SDK do Databricks para Java. Você pode encontrar a versão mais recente no repositório central do Maven.

  2. Instrua seu projeto a assumir a dependência declarada do Databricks SDK para Java. Por exemplo, no IntelliJ IDEA, na janela da ferramenta Projeto do seu projeto, clique com o botão direito do mouse no nó raiz do projeto e clique em Recarregar projeto.

  3. Adicione o código para importar o SDK do Databricks para Java e listar todos os clusters em seu workspace do Databricks. Por exemplo, no arquivo Main.java de um projeto, o código pode ser o seguinte:

    import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.compute.ClusterInfo;
import com.databricks.sdk.service.compute.ListClustersRequest;

public class Main {
  public static void main(String[] args) {
    WorkspaceClient w = new WorkspaceClient();

    for (ClusterInfo c : w.clusters().list(new ListClustersRequest())) {
      System.out.println(c.getClusterName());
    }
  }
}

    Observação

    Ao não definir nenhum argumento na chamada anterior para WorkspaceClient w = new WorkspaceClient(), o SDK do Databricks para Java usa seu processo default para tentar executar a autenticação do Databricks. Para substituir esse comportamento default , consulte a seção de autenticação a seguir.

  4. Construa seu projeto. Por exemplo, para fazer isso no IntelliJ IDEA, no menu principal, clique em Build > Build Project.

  5. execução do seu arquivo principal. Por exemplo, para fazer isso no IntelliJ IDEA para o arquivo Main.java de um projeto, no menu principal, clique em execução > execução 'Main'.

  6. A lista de clusters é exibida. Por exemplo, no IntelliJ IDEA, isso está na janela da ferramenta de execução . Para exibir esta janela de ferramentas, no menu principal, clique em view > Janelas de ferramentas > execução.

Autentique o SDK do Databricks para Java com sua conta ou espaço de trabalho do Databricks

O SDK do Databricks para Java implementa o padrão de autenticação unificada do cliente Databricks , uma abordagem arquitetônica e programática consolidada e consistente para autenticação. Esta abordagem ajuda a tornar a configuração e a automação da autenticação com Databricks mais centralizada e previsível. Ele permite que você configure a autenticação do Databricks uma vez e, em seguida, use essa configuração em várias ferramentas e SDKs do Databricks sem mais alterações na configuração de autenticação. Para obter mais informações, incluindo exemplos de código mais completos em Java, consulte Autenticação unificada do cliente Databricks.

Alguns dos padrões de codificação disponíveis para inicializar a autenticação do Databricks com o SDK do Databricks para Java incluem:

  • Use a autenticação default do Databricks seguindo um destes procedimentos:

    • Crie ou identifique um perfil de configuração personalizado do Databricks com os campos obrigatórios para o tipo de autenticação do Databricks de destino. Em seguida, defina a variável de ambiente DATABRICKS_CONFIG_PROFILE com o nome do perfil de configuração personalizado.

    • Defina a variável de ambiente necessária para o tipo de autenticação Databricks de destino.

    Em seguida, instancie, por exemplo, um objeto WorkspaceClient com autenticação default do Databricks da seguinte maneira:

    import com.databricks.sdk.WorkspaceClient;
// ...
WorkspaceClient w = new WorkspaceClient();
// ...

  • A codificação dos campos obrigatórios tem suporte, mas não é recomendada, pois corre o risco de expor informações confidenciais em seu código, como access token pessoal do Databricks. O exemplo a seguir codifica os valores access tokens do Databricks para autenticação tokens do Databricks:

    import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
// ...
DatabricksConfig cfg = new DatabricksConfig()
  .setHost("https://...")
  .setToken("...");
WorkspaceClient w = new WorkspaceClient(cfg);
// ...

Consulte também Autenticação no SDK do Databricks para Java README.

Use Databricks russas e Java com o Databricks SDK para Java

Databricks russas fornece diversas funções auxiliares para facilitar o trabalho eficiente com armazenamento de objetos, encadear e parametrizar Notebook e trabalhar com segredos. Databricks fornece uma biblioteca Databricks russas para Scala , que você pode chamar com código Java, para permitir que você acesse programaticamente o Databricks russas.

Para usar o código Java para chamar o Databricks russos para Scala, faça o seguinte:

  1. No seu projeto Java, declare uma dependência do SDK do Databricks para Java, conforme descrito na seção anterior.

  2. Declare uma dependência da biblioteca Databricks russas para Scala. Para fazer isso, adicione o seguinte <dependency> à seção pom.xml existente do arquivo <dependencies> :

    <dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-dbutils-scala_2.12</artifactId>
  <version>0.1.4</version>
</dependency>

    Observação

    Certifique-se de substituir 0.1.4 pela versão mais recente da biblioteca Databricks russas para Scala. Você pode encontrar a versão mais recente no repositório central do Maven.

  3. Instrua seu projeto a assumir a dependência declarada do Databricks russos para Scala. Por exemplo, no IntelliJ IDEA, na janela de ferramentas Projeto do seu projeto, clique no nó raiz do seu projeto e clique em Maven > Recarregar Projeto.

  4. Adicione o código para importar e depois chame o Databricks russos para Scala. Por exemplo, o código a seguir automatiza um volume Unity Catalog . Este exemplo cria um arquivo chamado zzz_hello.txt no caminho do volume dentro do workspace, lê os dados do arquivo e, em seguida, exclui o arquivo:

    import com.databricks.sdk.core.DatabricksConfig;
import com.databricks.sdk.scala.dbutils.DBUtils;

public class Main {
  public static void main(String[] args) {
    String filePath = "/Volumes/main/default/my-volume/zzz_hello.txt";
    String fileData = "Hello, Databricks!";
    DBUtils dbutils = DBUtils.getDBUtils(new DatabricksConfig().setProfile("DEFAULT"));

    dbutils.fs().put(filePath, fileData, true);

    System.out.println(dbutils.fs().head(filePath, 18));

    dbutils.fs().rm(filePath, false);
  }
}

  5. Construa seu projeto e execute seu arquivo principal.

Exemplos de código

Os exemplos de código a seguir demonstram como usar o Databricks SDK para Java para criar e excluir clusters, criar Job e listar grupos de nível de account . Esses exemplos de código usam o SDK do Databricks para o processo de autenticação Databricks default do Java.

Para obter exemplos de código adicionais, consulte a pasta de exemplos no repositório Databricks SDK para Java no GitHub.

Criar um clusters

Este exemplo de código cria clusters com a versão especificada do Databricks Runtime e o tipo de nó clusters . Esses clusters têm um worker e os clusters serão encerrados automaticamente após 15 minutos de tempo de parada.

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.compute.CreateCluster;
import com.databricks.sdk.service.compute.CreateClusterResponse;

public class Main {
  public static void main(String[] args) {
    WorkspaceClient w = new WorkspaceClient();

    CreateClusterResponse c = w.clusters().create(
      new CreateCluster()
        .setClusterName("my-cluster")
        .setSparkVersion("12.2.x-scala2.12")
        .setNodeTypeId("i3.xlarge")
        .setAutoterminationMinutes(15L)
        .setNumWorkers(1L)
    ).getResponse();

    System.out.println("View the cluster at " +
      w.config().getHost() +
      "#setting/clusters/" +
      c.getClusterId() +
      "/configuration\n");
  }
}

Crie clusters que usem JDK 17

Observação

JDK 8 é totalmente compatível. O JDK 17 está em visualização pública para o Databricks Runtime versões 13.1 e acima.

Esta seção fornece um guia para criar clusters usando o Java Development Kit (JDK). Aprenda como criar clusters com JDK 17 para usar Java em seu Notebook e Job.

Ao criar clusters, especifique que os clusters usam JDK 17 para o driver e o executor adicionando a seguinte variável de ambiente em Advanced Options > Spark > Environment Variables:

JNAME=zulu17-ca-amd64

Se você estiver usando clusters baseados em ARM (por exemplo, instâncias do AWS Graviton), use a variável de ambiente a seguir.

JNAME=zulu17-ca-arm64

Excluir permanentemente um clusters

Este exemplo de código exclui permanentemente os clusters com o ID clusters especificado do workspace.

import com.databricks.sdk.WorkspaceClient;
import java.util.Scanner;

public class Main {
  public static void main(String[] args) {
    System.out.println("ID of cluster to delete (for example, 1234-567890-ab123cd4):");

    Scanner in = new Scanner(System.in);
    String c_id = in.nextLine();
    WorkspaceClient w = new WorkspaceClient();

    w.clusters().permanentDelete(c_id);
  }
}

Crie um Job

Este exemplo de código cria um Job do Databricks que pode ser usado para executar o Notebook especificado nos clusters especificados. Como esta execução de código, ele obtém o caminho do Notebookexistente, o ID clusters existentes e as configurações Job relacionadas do usuário no terminal.

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.jobs.JobTaskSettings;
import com.databricks.sdk.service.jobs.NotebookTask;
import com.databricks.sdk.service.jobs.NotebookTaskSource;
import com.databricks.sdk.service.jobs.CreateResponse;
import com.databricks.sdk.service.jobs.CreateJob;

import java.util.Scanner;
import java.util.Map;
import java.util.Collection;
import java.util.Arrays;

public class Main {
  public static void main(String[] args) {
    System.out.println("Some short name for the job (for example, my-job):");
    Scanner in = new Scanner(System.in);
    String jobName = in.nextLine();

    System.out.println("Some short description for the job (for example, My job):");
    String description = in.nextLine();

    System.out.println("ID of the existing cluster in the workspace to run the job on (for example, 1234-567890-ab123cd4):");
    String existingClusterId = in.nextLine();

    System.out.println("Workspace path of the notebook to run (for example, /Users/someone@example.com/my-notebook):");
    String notebookPath = in.nextLine();

    System.out.println("Some key to apply to the job's tasks (for example, my-key): ");
    String taskKey = in.nextLine();

    System.out.println("Attempting to create the job. Please wait...");

    WorkspaceClient w = new WorkspaceClient();

    Map<String, String> map = Map.of("", "");

    Collection<JobTaskSettings> tasks = Arrays.asList(new JobTaskSettings()
      .setDescription(description)
      .setExistingClusterId(existingClusterId)
      .setNotebookTask(new NotebookTask()
        .setBaseParameters(map)
        .setNotebookPath(notebookPath)
        .setSource(NotebookTaskSource.WORKSPACE))
      .setTaskKey(taskKey)
    );

    CreateResponse j = w.jobs().create(new CreateJob()
      .setName(jobName)
      .setTasks(tasks)
    );

    System.out.println("View  the job at " +
      w.config().getHost() +
      "/#job/" +
      j.getJobId()
    );
  }
}

Listar grupos no nível da conta

Este exemplo de código lista os nomes de exibição de todos os grupos disponíveis na account do Databricks.

import com.databricks.sdk.AccountClient;
import com.databricks.sdk.core.DatabricksConfig;
import com.databricks.sdk.service.iam.Group;
import com.databricks.sdk.service.iam.ListAccountGroupsRequest;

public class Main {
  public static void main(String[] args) {
    AccountClient a = new AccountClient();

    for (Group g : a.groups().list((new ListAccountGroupsRequest()))) {
      System.out.println(g.getDisplayName());
    }
  }
}

Use Scala com o Databricks SDK para Java

Você pode usar projetos Scala com o Databricks SDK para Java. Antes de começar, sua máquina de desenvolvimento deve ter:

  • Autenticação do Databricks configurada.

  • Recomenda-se um ambiente de desenvolvimento integrado (IDE) compatível com Scala. A Databricks recomenda o IntelliJ IDEA com o plug-in Scala. Essas instruções foram testadas com o IntelliJ IDEA Community Edition 2023.3.6. Se o senhor usar uma versão ou edição diferente do IntelliJ IDEA, as instruções a seguir poderão variar.

  • Um Java Development Kit (JDK) compatível com Java 8 ouacima. Se você deseja executar seus aplicativos ou usar suas bibliotecas em clusters do Databricks, o Databricks recomenda que você use uma versão do JDK que corresponda à versão do JDK nos clusters. Para encontrar a versão do JDK incluída em um Databricks Runtime específico, consulte Databricks Runtime notas sobre a versão versões e compatibilidade. Se você usar o IntelliJ IDEA, poderá escolher uma instalação local existente do JDK ou instalar um novo JDK localmente durante a criação do projeto Scala.

  • Uma ferramenta de construção Scala. Databricks recomenda sbt. Se você usar o IntelliJ IDEA, poderá escolher a versão sbt para usar durante a criação do projeto Scala.

  • Scala. Se você deseja executar seus aplicativos ou usar suas bibliotecas em clusters do Databricks, o Databricks recomenda que você use uma versão do Scala que corresponda à versão do Scala nos clusters. Para encontrar a versão Scala incluída com um Databricks Runtime específico, consulte Databricks Runtime notas sobre a versão versões e compatibilidade. Se você usar o IntelliJ IDEA, poderá escolher a versão do Scala para usar durante a criação do projeto Scala.

Para configurar, construir e executar seu projeto Scala:

  1. No arquivo build.sbt do seu projeto, crie uma dependência na biblioteca Databricks SDK para Java adicionando a seguinte linha ao final do arquivo e, em seguida, salve o arquivo:

    libraryDependencies += "com.databricks" % "databricks-sdk-java" % "0.2.0"

    Observação

    Certifique-se de substituir 0.2.0 pela versão mais recente da biblioteca Databricks SDK para Java. Você pode encontrar a versão mais recente no repositório central do Maven.

  2. Instrua seu projeto a assumir a dependência declarada no Databricks SDK para Java. Por exemplo, no IntelliJ IDEA, clique no ícone Carregar notificação de alterações sbt .

  3. Adicione o código para importar o SDK do Databricks para Java e listar todos os clusters em seu workspace do Databricks. Por exemplo, no arquivo Main.scala de um projeto, o código pode ser o seguinte:

    import com.databricks.sdk.WorkspaceClient
import com.databricks.sdk.service.compute.ListClustersRequest

object Main {
  def main(args: Array[String]): Unit = {
    val w = new WorkspaceClient()

    w.clusters().list(new ListClustersRequest()).forEach{
      elem => println(elem.getClusterName)
    }
  }
}

    Observação

    Ao não definir nenhum argumento na chamada anterior para val w = new WorkspaceClient(), o SDK do Databricks para Java usa seu processo default para tentar executar a autenticação do Databricks. Para substituir esse comportamento default , consulte a seção de autenticação a seguir.

  4. Construa seu projeto. Por exemplo, para fazer isso no IntelliJ IDEA, no menu principal, clique em Build > Build Project.

  5. execução do seu arquivo principal. Por exemplo, para fazer isso no IntelliJ IDEA para o arquivo Main.scala de um projeto, no menu principal, clique em execução > execução 'Main.Scala'.

  6. A lista de clusters é exibida. Por exemplo, no IntelliJ IDEA, isso está na janela da ferramenta de execução . Para exibir esta janela de ferramentas, no menu principal, clique em view > Janelas de ferramentas > execução.

Use Databricks russas e Scala com o Databricks SDK para Java

Databricks russas fornece diversas funções auxiliares para facilitar o trabalho eficiente com armazenamento de objetos, encadear e parametrizar Notebook e trabalhar com segredos. Databricks fornece uma biblioteca Databricks russas para Scala para permitir que você acesse programaticamente Databricks russas com Scala.

Para chamar o Databricks russos para Scala, faça o seguinte:

  1. No seu projeto Scala, declare uma dependência do SDK do Databricks para Java, conforme descrito na seção anterior.

  2. Declare uma dependência da biblioteca Databricks russas para Scala. Por exemplo, no arquivo build.sbt do seu projeto, adicione a seguinte linha ao final do arquivo e salve-o:

    libraryDependencies += "com.databricks" % "databricks-dbutils-scala_2.12" % "0.1.4"

    Observação

    Certifique-se de substituir 0.1.4 pela versão mais recente da biblioteca Databricks russas para Scala. Você pode encontrar a versão mais recente no repositório central do Maven.

  3. Instrua seu projeto a assumir a dependência declarada do Databricks russos para Scala. Por exemplo, no IntelliJ IDEA, clique no ícone de notificação Carregar alterações do sbt .

  4. Adicione o código para importar e depois chame o Databricks russos para Scala. Por exemplo, o código a seguir automatiza um volume Unity Catalog . Este exemplo cria um arquivo chamado zzz_hello.txt no caminho do volume dentro do workspace, lê os dados do arquivo e, em seguida, exclui o arquivo:

    import com.databricks.sdk.scala.dbutils.DBUtils

object Main {
  def main(args: Array[String]): Unit = {
    val filePath = "/Volumes/main/default/my-volume/zzz_hello.txt"
    val fileData = "Hello, Databricks!"
    val dbutils = DBUtils.getDBUtils()

    dbutils.fs.put(
      file = filePath,
      contents = fileData,
      overwrite = true
    )

    println(dbutils.fs.head(filePath))

    dbutils.fs.rm(filePath)
  }
}

    Observação

    Ao não definir nenhum argumento na chamada anterior para val dbutils = DBUtils.getDBUtils(), o Databricks russos para Scala usa seu processo default para tentar realizar a autenticação do Databricks.

    Para substituir esse comportamento default , passe um objeto DatabricksCfg instanciado como argumento para getDBUtils. Para mais informações, consulte a secção de autenticação anterior.

    Observe, no entanto, que se o seu código estiver em execução dentro do Databricks Runtime, esse objeto DatabricksCfg será ignorado. Isso ocorre porque o Databricks utilidades para Scala delega ao Databricks utilidades integrado ao ser executado dentro do Databricks Runtime.

  5. Construa seu projeto e execute seu arquivo principal.

Testes

Para testar seu código, use estruturas de teste Java, como o JUnit. Para testar seu código em condições simuladas sem chamar o endpoint Databricks REST API ou alterar o estado de sua conta ou espaço de trabalho Databricks, use a biblioteca de simulação Java, como o Mockito.

Por exemplo, dado o seguinte arquivo chamado Helpers.java contendo uma função createCluster que retorna informações sobre o novo cluster:

// Helpers.java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.compute.CreateCluster;
import com.databricks.sdk.service.compute.CreateClusterResponse;

public class Helpers {
  static CreateClusterResponse createCluster(
    WorkspaceClient w,
    CreateCluster   createCluster,
    String          clusterName,
    String          sparkVersion,
    String          nodeTypeId,
    Long            autoTerminationMinutes,
    Long            numWorkers
  ) {
    return w.clusters().create(
      createCluster
        .setClusterName(clusterName)
        .setSparkVersion(sparkVersion)
        .setNodeTypeId(nodeTypeId)
        .setAutoterminationMinutes(autoTerminationMinutes)
        .setNumWorkers(numWorkers)
    ).getResponse();
  }
}

E dado o seguinte arquivo chamado Main.java que chama a função createCluster:

// Main.java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.compute.CreateCluster;
import com.databricks.sdk.service.compute.CreateClusterResponse;

public class Main {
  public static void main(String[] args) {
    WorkspaceClient w = new WorkspaceClient();
    // Replace <spark-version> with the target Spark version string.
    // Replace <node-type-id> with the target node type string.
    CreateClusterResponse c = Helpers.createCluster(
      w,
      new CreateCluster(),
      "My Test Cluster",
      "<spark-version>",
      "<node-type-id>",
      15L,
      1L
    );
    System.out.println(c.getClusterId());
  }
}

O arquivo a seguir, denominado HelpersTest.java, testa se a função createCluster retorna a resposta esperada. Em vez de criar um cluster no destino workspace, esse teste simula um objeto WorkspaceClient, define as configurações do objeto simulado e, em seguida, passa o objeto simulado para a função createCluster. Em seguida, o teste verifica se a função retorna a ID esperada do novo cluster simulado.

// HelpersTest.java

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.mixin.ClustersExt;
import com.databricks.sdk.service.compute.ClusterDetails;
import com.databricks.sdk.service.compute.CreateCluster;
import com.databricks.sdk.support.Wait;
import com.databricks.sdk.service.compute.CreateClusterResponse;
import org.junit.jupiter.api.Test;
import org.mockito.Mockito;
import static org.junit.jupiter.api.Assertions.assertEquals;

public class HelpersTest {
  @Test
  public void testCreateCluster() {
    WorkspaceClient mockWorkspaceClient = Mockito.mock(WorkspaceClient.class);
    ClustersExt mockClustersExt = Mockito.mock(ClustersExt.class);
    CreateCluster mockCreateCluster = new CreateCluster();
    Wait<ClusterDetails, CreateClusterResponse> mockWait = Mockito.mock(Wait.class);
    CreateClusterResponse mockResponse = Mockito.mock(CreateClusterResponse.class);

    Mockito.when(mockWorkspaceClient.clusters()).thenReturn(mockClustersExt);
    Mockito.when(mockClustersExt.create(Mockito.any(CreateCluster.class))).thenReturn(mockWait);
    Mockito.when(mockWait.getResponse()).thenReturn(mockResponse);

    // Replace <spark-version> with the target Spark version string.
    // Replace <node-type-id> with the target node type string.
    CreateClusterResponse response = Helpers.createCluster(
      mockWorkspaceClient,
      mockCreateCluster,
      "My Test Cluster",
      "<spark-version>",
      "<node-type-id>",
      15L,
      1L
    );
    assertEquals(mockResponse, response);
  }
}

Recursos adicionais

Para mais informações, consulte: