Compartilhar via

Modelos de projetos do Pacote de Ativos do Databricks

Os Pacotes de Ativos do Databricks descrevem os recursos do Databricks, como trabalhos, pipelines e notebooks como arquivos de origem, permitem incluir metadados junto com esses arquivos de origem para provisionar a infraestrutura e outros recursos e fornecer uma definição de ponta a ponta de um projeto, tudo empacotado como um único projeto implantável. Consulte O que são os Pacotes de Ativos do Databricks?.

Os modelos de pacote permitem que os usuários criem pacotes de maneira consistente e repetível, estabelecendo estruturas de pastas, etapas de build e tarefas, testes e outros atributos de IaC (infraestrutura como código) de DevOps comuns em um pipeline de implantação.

Por exemplo, se você executa rotineiramente trabalhos que exigem pacotes personalizados com uma etapa de compilação demorada após a instalação, você pode acelerar seu loop de desenvolvimento criando um modelo de pacote que especifica um ambiente de contêiner personalizado.

O Databricks fornece um conjunto de modelos de pacote padrão, mas você também pode criar modelos de pacote personalizados. Os usuários podem inicializar pacotes usando o comando bundle init, especificando um modelo padrão ou seu modelo personalizado.

Criar um pacote usando um modelo

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

databricks bundle init default-python

Para usar um modelo de pacote personalizado, passe o caminho local ou a URL remota do modelo para o comando Databricks CLIbundle init.

Por exemplo, o seguinte comando usa o modelo dab-container-template criado no tutorial de modelo de pacote personalizado:

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

Se você não especificar um modelo, o bundle init comando solicitará o conjunto de modelos padrão disponíveis dos quais você pode escolher.

Modelos de pacote padrão

O Azure Databricks fornece os seguintes modelos de pacote padrão:

Modelo Descrição
default-python Um modelo para usar o Python com o Databricks. Esse modelo cria um pacote com um trabalho e um pipeline ETL e requer uv. Confira default-python.
default-sql Um modelo para usar o SQL com o Databricks. Esse modelo contém um arquivo de configuração que define um trabalho que executa consultas SQL em um SQL warehouse. Confira default-sql.
dbt-sql Um modelo que aproveita o dbt-core para desenvolvimento local e pacotes para implantação. Esse modelo 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 trabalhos de dbt implantados. Confira dbt-sql.
mlops-stacks Um modelo de pilha completa avançado para iniciar novos projetos do MLOps Stacks. Confira mlops-stacks e Pacotes de ativos do Databricks para o MLOps Stacks.

Modelos de pacote personalizados

Os modelos de pacote usam a sintaxe de modelagem de pacote Go, que fornece flexibilidade nos modelos de pacote personalizados que você pode criar. Consulte a documentação do modelo de pacote Go

Modelo de estrutura do projeto

No mínimo, um projeto de modelo de pacote precisa 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. Consulte o esquema de modelo.
  • Um arquivo databricks.yml.tmpl localizado em uma pasta template que define a configuração de todos os pacotes criados com o modelo. Se o arquivo databricks.yml.tmpl fizer referência a outros modelos de configuração de *.yml.tmpl, especifique o local deles no mapeamento de include. Consulte modelos de configuração.

Além disso, a estrutura de pastas e os arquivos incluídos do projeto de modelo de pacote template são refletidos em pacotes criados com esse modelo. Por exemplo, se você quiser que o modelo gere um pacote com um bloco de anotações simples na src pasta e uma definição de trabalho que executa o bloco de anotações na resources pasta, você organizará seu projeto de modelo assim:

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 de trabalho neste modelo de pacote usam uma variável de modelo. Para obter informações sobre auxiliares de modelo e variáveis, consulte auxiliares de modelo e variáveis.

Esquema de modelo

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

O arquivo básico databricks_template_schema.json a seguir define uma variável project_name de entrada para o projeto de pacote, que inclui a mensagem de prompt e um valor padrão. 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.

{
  "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 de esquema de modelo

O arquivo databricks_template_schema.json dá suporte à definição de variáveis de entrada para coletar informações do usuário durante a inicialização do pacote dentro do campo properties, assim como campos adicionais para personalizar a inicialização.

As variáveis de entrada são definidas no properties campo do esquema de modelo. Cada variável de entrada define os metadados necessários para apresentar um prompt ao usuário durante a initalização do pacote. O valor da variável é então acessível usando a sintaxe de variável de modelo, 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 com suporte são listados na tabela a seguir.

Campo de esquema Descrição
properties As definições de variável de entrada do modelo de pacote. O Databricks recomenda definir pelo menos uma variável de entrada que seja o nome do projeto de pacote.
properties.<variable_name> O nome da variável de entrada.
properties.<variable_name>.default Um valor padrão a ser usado se um valor não for fornecido pelo usuário como --config-file parte do bundle init comando ou na linha de comando quando ele for solicitado.
properties.<variable_name>.description A mensagem de prompt 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 do 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 inteiro que define a ordem relativa das propriedades de entrada. Isso controla a ordem na qual os prompts dessas 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 uma sintaxe regexp com suporte, consulte https://github.com/google/re2/wiki/Syntax.
properties.<variable_name>.pattern_match_failure_message A mensagem 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 estiver satisfeito com a configuração já presente. Nesse caso, o valor padrão da propriedade é usado em vez disso. Para obter um exemplo, consulte o modelo de mlops-stacks. Somente const comparações são suportadas.
properties.<variable_name>.skip_prompt_if.properties.<previous_variable_name>.const Se o valor para <previous_variable_name> corresponder à constante configurada em skip_prompt_if, o prompt de <variable_name> será ignorado.
welcome_message A primeira mensagem a ser gerada antes de solicitar entrada ao usuário.
success_message A mensagem a ser impressa depois que o modelo é inicializado com êxito.
min_databricks_cli_version A versão semver mínima desta CLI do Databricks que o modelo exige. databricks bundle init falhará se a versão da CLI for menor que esta 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.

Modelos de configuração

Um modelo de pacote personalizado deve conter um arquivo databricks.yml.tmpl dentro de uma pasta template no projeto de modelo de pacote, que é usado para criar o arquivo de configuração databricks.yml do projeto de pacote. Modelos para arquivos de configuração para recursos podem ser criados na resources pasta. Preencha esses arquivos de modelo com o modelo de configuração YAML.

Os seguintes modelos simples de configuração para databricks.yml e o associativo *_job.yml estabelecem o nome do pacote e dois ambientes de destino, além de definir um trabalho que executa o notebook no pacote, para pacotes criados usando este modelo. Esses modelos de configuração aproveitam as substituições de pacote e os auxiliares de modelo de pacote.

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

# 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:

# {{.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

Auxiliares de modelo e variáveis

Os auxiliares de modelo são funções fornecidas pelo Databricks que você pode usar em seus arquivos de modelo para obter informações específicas do usuário em runtime ou interagir com o mecanismo de modelo. Você também pode definir suas próprias variáveis de modelo.

Os auxiliares de modelo a seguir estão disponíveis para projetos de modelo de pacote do Databricks. Para obter informações sobre como usar modelos e variáveis do Go, consulte os modelos do Go.

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 cadeia de caracteres, um UUID que é um Identificador Único Universal de 128 bits (16 bytes), conforme definido na RFC 4122. Este identificador é estável durante a execução do modelo e pode ser usado para preencher o campo bundle.uuid em databricks.yml por autores de modelos.
{{bundle_uuid}} Uma ID exclusiva para o pacote. Várias invocações dessa função retornarão a mesma UUID.
{{pair}} Um par de valores de chave. Isso é usado com o map auxiliar para gerar mapas a serem usados dentro de um modelo.
{{map}} Converte uma lista de pares em um objeto de mapa. Isso é útil para passar vários objetos para modelos definidos no diretório da biblioteca. Como a sintaxe do modelo de texto Go para invocar um modelo só permite especificar um único argumento, essa função pode ser usada para solucionar essa limitação.
Por exemplo, na linha a seguir, {{template "my_template" (map (pair "foo" $arg1) (pair "bar" $arg2))}}, $arg1 e $arg2 podem ser referenciados de dentro de my_template como .foo e .bar.
{{smallest_node_type}} Retorna o menor tipo de nó.
{{path_separator}} O caractere que separa caminhos no sistema operacional. Isso é / para sistemas baseados em Unix e \ para Windows.
{{workspace_host}} A URL do host do workspace à qual o usuário está autenticado no momento.
{{user_name}} O nome completo do usuário que inicializa o modelo.
{{short_name}} O nome curto do usuário inicializando o modelo.
{{default_catalog}} Retorna o catálogo de workspaces padrão. Se não houver nenhum padrão ou se o Catálogo do Unity não estiver habilitado, isso retornará uma cadeia de caracteres vazia.
{{is_service_principal}} Se o usuário atual é ou não um principal 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 correspondam ao padrão glob de entrada. Para obter um exemplo, consulte o modelo de mlops-stacks.

Auxiliares de modelo personalizado

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

{{ 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 de modelo mlops-stacks.

Testar o modelo de pacote

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

databricks bundle init basic-bundle-template

Na solicitação What is your bundle project name?, digite my_test_bundle.

Depois que o pacote de teste é criado, a mensagem de êxito do arquivo de esquema é a saída. 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

O arquivo databricks.yml e o trabalho agora estão personalizados:

# 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

# 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

Compartilhar o modelo

Se você quiser compartilhar esse modelo de pacote com outras pessoas, poderá armazená-lo no controle de versão com qualquer provedor que o Git ofereça suporte e ao qual seus usuários tenham acesso. Para executar o comando bundle init com uma URL do Git, verifique se o arquivo databricks_template_schema.json está no local raiz relativo a essa URL do Git.

Dica

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

Próximas etapas