Pular para o conteúdo principal

Databricks projeto ativo Bundle padrão

Databricks Os ativo Bundles descrevem Databricks recurso como Job, pipeline e Notebook como arquivos de origem, permitem que o senhor inclua metadados junto com esses arquivos de origem para provisionamento de infraestrutura e outros recursos, e fornecem uma definição de ponta a ponta de um projeto, tudo isso como um único projeto implementável. Veja o que são Databricks ativo Bundles?

O padrão de pacotes permite que os usuários criem pacotes de forma consistente e repetível, estabelecendo estruturas de pastas, etapas e tarefas de construção, testes e outros atributos DevOps Infrastructure-as-Code (IaC) comuns em uma implantação pipeline.

Por exemplo, se você executa rotineiramente Databricks trabalhos que exigem pacotes personalizados com uma etapa de compilação demorada na instalação, poderá acelerar o ciclo de desenvolvimento criando um padrão de pacote que especifique um ambiente de contêiner personalizado.

Databricks fornece um conjunto de default bundle padrão, mas o senhor também pode criar bundle padrão personalizado. Os usuários podem então inicializar os pacotes usando o comando bundle init, especificando um padrão default ou seu padrão personalizado.

Criar um pacote usando um padrão​

Para usar um padrão de pacote Databricks para criar seu pacote, use o comando Databricks CLI bundle init comando, especificando o nome do padrão a ser usado. Por exemplo, o comando a seguir cria um pacote usando o endereço default Python bundle padrão:

sh
databricks bundle init default-python

Para usar um padrão de pacote personalizado, passe o caminho local ou o URL remoto do padrão para o comando Databricks CLI bundle init comando.

Por exemplo, o comando a seguir usa o dab-container-template padrão criado no tutorial Custom Bundle padrão:

sh
databricks bundle init /projects/my-custom-bundle-templates/dab-container-template

Se o senhor não especificar um padrão, o comando bundle init exibirá o conjunto de default padrões disponíveis entre os quais o senhor poderá escolher.

default bundle padrão​

Databricks fornece o seguinte default bundle padrão:

Template

Descrição

default-python

Um padrão para usar Python com Databricks. Esse padrão cria um pacote com um Job e um DLT pipeline. Consulte defaultPython-.

default-sql

Um padrão para usar SQL com Databricks. Esse padrão contém um arquivo de configuração que define um Job que executa SQL consultas em um SQL warehouse. Consulte default-sql.

dbt-sql

Um padrão que aproveita o dbt-core para desenvolvimento local e pacotes para implementação. Esse padrão contém a configuração que define um trabalho com uma tarefa dbt, bem como um arquivo de configuração que define perfis dbt para o trabalho dbt implantado. Veja dbt-sql.

mlops-stacks

Um padrão avançado de pilha completa para iniciar novos projetos MLOps Stacks. Consulte mlops-stacks e Databricks ativo Bundles para MLOps Stacks.

Padrão de pacote personalizado​

O padrão de pacote usa a sintaxe de modelo de pacote Go, que oferece flexibilidade no padrão de pacote personalizado que o senhor pode criar. Consulte a documentação do Go pacote padrão.

estrutura do projeto padrão​

No mínimo, um projeto de bundle padrão deve ter:

  • Um arquivo databricks_template_schema.json na raiz do projeto que define uma propriedade de solicitação do usuário para o nome do projeto do pacote. Veja o esquema de padrão.
  • Um arquivo databricks.yml.tmpl localizado em uma pasta template que define a configuração de todos os pacotes criados com o padrão. Se o arquivo databricks.yml.tmpl fizer referência a qualquer padrão de configuração *.yml.tmpl adicional, especifique o local desses padrões no mapeamento include. Ver Configuração padrão.

Além disso, a estrutura de pastas e os arquivos incluídos na pasta template do projeto padrão do pacote são espelhados pelos pacotes criados com o padrão. Por exemplo, se quiser que o padrão gere um pacote com um Notebook simples na pasta src e uma definição de trabalho que execute o Notebook na pasta resources, o senhor organizaria o projeto padrão da seguinte forma:

basic-bundle-template
  ├── databricks_template_schema.json
  └── template
      └── {{.project_name}}
          ├── databricks.yml.tmpl
          ├── resources
          │   └── {{.project_name}}_job.yml.tmpl
          └── src
              └── simple_notebook.ipynb
dica

O nome da pasta do projeto e o nome do arquivo de definição do trabalho nesse pacote padrão usam uma variável padrão. Para obter informações sobre auxiliares e variáveis de padrão, consulte auxiliares e variáveis de padrão.

esquema de padrão​

Um projeto padrão de pacote personalizado deve conter um databricks_template_schema.json JSON arquivo na raiz do projeto. Esse arquivo define os campos usados pelo site Databricks CLI quando o comando bundle init é executado, como o texto do prompt.

O arquivo básico databricks_template_schema.json a seguir define uma variável de entrada project_name para o projeto do pacote, que inclui a mensagem de prompt e um valor default. Em seguida, ele define uma mensagem de sucesso para a inicialização do projeto de pacote que usa o valor da variável de entrada dentro da mensagem.

JSON
{
  "properties": {
    "project_name": {
      "type": "string",
      "default": "basic_bundle",
      "description": "What is the name of the bundle you want to create?",
      "order": 1
    }
  },
  "success_message": "\nYour bundle '{{.project_name}}' has been created."
}

campos do esquema padrão​

O arquivo databricks_template_schema.json permite definir variáveis de entrada para coletar informações do usuário durante a inicialização do pacote no campo properties, bem como campos adicionais para personalizar a inicialização.

As variáveis de entrada são definidas no campo properties do esquema padrão. Cada variável de entrada define os metadados necessários para apresentar uma solicitação ao usuário durante a inicialização do pacote. O valor da variável pode ser acessado usando a sintaxe de variável padrão, como {{.project_name}}.

Você também pode definir os valores de alguns campos para personalizar o processo de inicialização do pacote.

Os campos de esquema compatíveis estão listados na tabela a seguir.

Campo do esquema

Descrição

properties

As definições da variável de entrada do padrão do pacote. A Databricks recomenda definir pelo menos uma variável de entrada que seja o nome do projeto do pacote.

properties.<variable_name>

O nome da variável de entrada.

properties.<variable_name>.default

Um valor default a ser usado se um valor não for fornecido pelo usuário com --config-file como parte do comando bundle init ou na linha de comando quando for solicitado.

properties.<variable_name>.description

A mensagem de aviso do usuário associada à variável de entrada.

properties.<variable_name>.enum

Uma lista de valores possíveis para a propriedade, como "enum": ["azure", "aws", "gcp"]. Se esse campo for definido, a CLI da Databricks apresentará os valores em uma lista na linha de comando para solicitar que o usuário selecione um valor.

properties.<variable_name>.order

Um número inteiro que define a ordem relativa das propriedades de entrada. Isso controla a ordem em que os prompts para essas variáveis de entrada são mostrados na linha de comando.

properties.<variable_name>.pattern

O padrão regexp a ser usado para validar a entrada do usuário, por exemplo, "pattern": "^[^ .\\\\/]{3,}$". Para obter a sintaxe regexp compatível, consulte https://github.com/google/re2/wiki/Syntax.

properties.<variable_name>.pattern_match_failure_message

A mensagem que é exibida ao usuário se o valor inserido pelo usuário não corresponder ao padrão especificado, por exemplo, Project name must be at least 3 characters long and cannot contain the following characters: \"\\\", \"/\", \" \" and \".\".".

properties.<variable_name>.skip_prompt_if

Ignore a solicitação da variável de entrada se esse esquema for satisfeito pela configuração já presente. Nesse caso, o valor default da propriedade é usado em seu lugar. Para obter um exemplo, consulte o padrão mlops-stacks. Somente as comparações const são suportadas.

properties.<variable_name>.skip_prompt_if.properties.<previous_variable_name>.const

Se o valor de <previous_variable_name> corresponder à constante configurada em skip_prompt_if, a solicitação de <variable_name> será ignorada.

welcome_message

A primeira mensagem a ser emitida antes de solicitar a entrada do usuário.

success_message

A mensagem a ser impressa após a inicialização bem-sucedida do padrão.

min_databricks_cli_version

A versão mínima do semver deste Databricks CLI que o padrão exige. databricks bundle init falhará se a versão da CLI for inferior a essa versão.

version

Reservado para uso futuro. A versão do esquema. Isso é usado para determinar se o esquema é compatível com a versão atual da CLI.

Configuração padrão​

Um pacote padrão personalizado deve conter um arquivo databricks.yml.tmpl em uma pasta template no projeto do pacote padrão que é usado para criar o arquivo de configuração databricks.yml do projeto do pacote. O padrão para arquivos de configuração de recurso pode ser criado na pasta resources. Preencha esses arquivos padrão com a configuração padrão YAML.

O seguinte exemplo simples de configuração padrão para databricks.yml e o *Job.yml associado estabelecem o nome do pacote e dois ambientes de destino, e definem um trabalho que executa o Notebook no pacote, para pacotes criados usando esse padrão. Esse padrão de configuração aproveita as substituições de pacotes e os auxiliares de padrão de pacotes.

template/{{.project_name}}/databricks.yml.tmpl:

YAML
# databricks.yml
# This is the configuration for the Databricks Asset Bundle {{.project_name}}.

bundle:
  name: {{.project_name}}

include:
  - resources/*.yml

targets:
  # The deployment targets. See https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html
  dev:
    mode: development
    default: true
    workspace:
      host: {{workspace_host}}

  prod:
    mode: production
    workspace:
      host: {{workspace_host}}
      root_path: /Shared/.bundle/prod/${bundle.name}
    
    {{- if not is_service_principal}}
    run_as:
      # This runs as {{user_name}} in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: {{user_name}}
    
    {{end -}}

template/{{.project_name}}/resources/{{.project_name}}_job.yml.tmpl:

YAML
# {{.project_name}}_job.yml
# The main job for {{.project_name}}

resources:
    jobs:
        
        {{.project_name}}_job:
        name: {{.project_name}}_job
        tasks:
            - task_key: notebook_task
            job_cluster_key: job_cluster
            notebook_task:
                notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
            new_cluster:
                node_type_id: i3.xlarge
                spark_version: 13.3.x-scala2.12

ajudantes e variáveis padrão​

Os padrão helpers são funções fornecidas pelo site Databricks que podem ser usadas nos arquivos padrão para obter informações específicas do usuário em tempo de execução ou interagir com o mecanismo padrão. O senhor também pode definir suas próprias variáveis padrão.

Os seguintes auxiliares de padrão estão disponíveis para Databricks bundle padrão projects. Para obter informações sobre o uso de Go padrão e variáveis, consulte Go padrão.

Ajudante

Descrição

{{url}}

Um alias para https://pkg.go.dev/net/url#Parse. Isso permite o uso de todos os métodos de url.URL.

{{regexp}}

Um alias para https://pkg.go.dev/regexp#Compile. Isso permite o uso de todos os métodos de regexp.Regexp.

{{random_int}}

Retorna, como um int, um número pseudo-aleatório não negativo no intervalo semiaberto (0, n).

{{uuid}}

Retorna, como uma string, um UUID que é um Universal Unique IDentifier de 128 bits (16 bytes), conforme definido na RFC 4122. Esse ID é estável durante a execução do padrão e pode ser usado para preencher o campo bundle.uuid no databricks.yml pelos autores do padrão.

{{bundle_uuid}}

Uma ID exclusiva para o pacote. Várias invocações dessa função retornarão o mesmo UUID.

{{pair}}

Um par key-value. Isso é usado com o auxiliar map para gerar mapas a serem usados dentro de um padrão.

{{map}}

Converte uma lista de pares em um objeto de mapa. Isso é útil para passar vários objetos para o padrão definido no diretório da biblioteca. Como a sintaxe do padrão de texto Go para invocar um padrão só permite a especificação de um único argumento, essa função pode ser usada para contornar essa limitação.

Por exemplo, na linha a seguir, {{template "my_template" (map (pair "foo" $arg1) (pair "bar" $arg2))}}, $arg1 e $arg2 podem ser chamados de dentro de my_template como .foo e .bar.

{{smallest_node_type}}

Retorna o menor tipo de nó.

{{path_separator}}

O caractere separador de caminho para o sistema operacional. Isso é / para sistemas baseados em Unix e \ para Windows.

{{workspace_host}}

O URL do host workspace no qual o usuário está autenticado no momento.

{{user_name}}

O nome completo do usuário que está inicializando o padrão.

{{short_name}}

O nome abreviado do usuário que está inicializando o padrão.

{{default_catalog}}

Retorna o catálogo default workspace . Se não houver default, ou se Unity Catalog não estiver habilitado, isso retorna uma cadeia de caracteres vazia.

{{is_service_principal}}

Se o usuário atual é ou não uma entidade de serviço.

{{ skip <glob-pattern-relative-to-current-directory> }}

Faz com que o mecanismo de modelo ignore a geração de todos os arquivos e diretórios que correspondem ao padrão glob de entrada. Para obter um exemplo, consulte o padrão mlops-stacks.

Ajudantes de padrão personalizados​

Para definir seus próprios auxiliares padrão, crie um arquivo padrão na pasta library do projeto padrão e use a sintaxe de modelo Go para definir os auxiliares. Por exemplo, o conteúdo a seguir de um arquivo library/variables.tmpl define as variáveis cli_version e model_name. Quando esse padrão é usado para inicializar um pacote, o valor da variável model_name é construído usando o campo input_project_name definido no arquivo de esquema do padrão. O valor desse valor de campo é a entrada do usuário após uma solicitação.

Go

{{ define `cli_version` -}}
    v0.240.0

{{- end }}


{{ define `model_name` -}}
    
    {{ .input_project_name }}-model

{{- end }}

Para ver um exemplo completo, consulte o arquivo de variáveis padrão mlops-stacks.

Teste o padrão do pacote​

Por fim, certifique-se de testar seu padrão. Por exemplo, use o endereço Databricks CLI para inicializar um novo pacote usando o padrão definido nas seções anteriores:

sh
databricks bundle init basic-bundle-template

Para o prompt, What is your bundle project name?, digite my_test_bundle.

Depois que o pacote de teste é criado, a mensagem de sucesso do arquivo de esquema é emitida. Se você examinar o conteúdo da pasta my_test_bundle, deverá ver o seguinte:

my_test_bundle
   ├── databricks.yml
   ├── resources
   │  └── my_test_bundle_job.yml
   └── src
      └── simple_notebook.ipynb

E o arquivo databricks.yml e o Job agora estão personalizados:

YAML
# databricks.yml
# This is the configuration for the Databricks Asset Bundle my-test-bundle.

bundle:
  name: my_test_bundle

include:
  - resources/*.yml

targets:
  # The 'dev' target, used for development purposes. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#development-mode)
  dev:
    mode: development
    default: true
    workspace:
      host: https://my-host.cloud.databricks.com

  # The 'prod' target, used for production deployment. See [_](https://docs.databricks.com/en/dev-tools/bundles/deployment-modes.html#production-mode)
  prod:
    mode: production
    workspace:
      host: https://my-host.cloud.databricks.com
      root_path: /Shared/.bundle/prod/${bundle.name}
    run_as:
      # This runs as someone@example.com in production. Alternatively,
      # a service principal could be used here using service_principal_name
      user_name: someone@example.com
YAML
# my_test_bundle_job.yml
# The main job for my_test_bundle

resources:
    jobs:
        my_test_bundle_job:
        name: my_test_bundle_job
        tasks:
            - task_key: notebook_task
                job_cluster_key: job_cluster
                notebook_task:
                    notebook_path: ../src/simple_notebook.ipynb
        job_clusters:
            - job_cluster_key: job_cluster
                new_cluster:
                    node_type_id: i3.xlarge
                    spark_version: 13.3.x-scala2.12

Compartilhe o padrão​

Se quiser compartilhar esse padrão de pacote com outras pessoas, poderá armazená-lo no controle de versão com qualquer provedor compatível com o Git e ao qual seus usuários tenham acesso. Para executar o comando bundle init com um URL Git, certifique-se de que o arquivo databricks_template_schema.json esteja no local da raiz relativo a esse URL Git.

dica

Você pode colocar o arquivo databricks_template_schema.json em uma pasta diferente, em relação à raiz do pacote. Em seguida, o senhor pode usar a opção --template-dir do comando bundle init para fazer referência a essa pasta, que contém o arquivo databricks_template_schema.json.

Próximas etapas​

Última atualização em