Configure as versões de ambiente para o pipeline.

info

Pré-lançamento público

As versões de ambiente para LakeFlow Pipelines estão em pré-lançamento público.

Uma versão de ambiente define a versão da linguagem Python e o conjunto de bibliotecas Python pré-instaladas disponíveis para o código Python do seu pipeline. Quaisquer dependências externas que você adicionar ao pipeline serão sobrepostas a essa base.

As versões do ambiente desacoplam o runtime Python do seu pipeline da versão do Databricks Runtime em que seu pipeline é executado. Enquanto uma versão do ambiente está definida, as atualizações do Databricks Runtime não alteram sua versão da linguagem Python ou as versões de bibliotecas pré-instaladas. O runtime Python também é consistente com Jobs e Notebooks Serverless que usam a mesma versão do ambiente. Para encontrar a versão atual do Databricks Runtime para Lakeflow pipelines, consulte notas sobre a versão dos Lakeflow pipelines e o processo de atualização da versão.

O Databricks migra automaticamente pipelines qualificados para uma versão de ambiente. Consulte Migração automática.

importante

Pipelines com uma versão de ambiente executam código Python por meio do Spark Connect, o que pode alterar o comportamento de algum código de pipeline. Para a lista completa de limitações e alterações de comportamento, consulte Compatibilidade de versão de ambiente.

Requisitos

As versões de ambiente têm os seguintes requisitos:

• O pipeline deve usar o Unity Catalog. Pipelines Hive metastore não são suportados.

Versões de ambiente suportadas

Os LakeFlow Pipelines suportam as versões de ambiente **3** e **4** em Serverless e compute clássico. Para a versão da linguagem Python e a lista completa de bibliotecas Python pré-instaladas disponíveis em cada versão, consulte a referência de versão do ambiente.

Migração automática

O Databricks migra automaticamente pipelines qualificados para uma versão de ambiente. A migração ocorre na próxima atualização do pipeline, não requer etapas manuais e inclui estas salvaguardas:

• O comportamento é verificado antes da migração. O Databricks verifica seu pipeline em busca de padrões de código que se comportariam de forma diferente no Spark Connect e compara o plano de saída do pipeline antes e depois da migração. Consulte Compatibilidade de versão do ambiente.
• Uma migração com falha é revertida automaticamente. Se uma atualização migrada falhar por qualquer motivo, ela será interrompida antes que qualquer dado seja gravado , e o pipeline reverterá automaticamente para seu runtime anterior na próxima atualização. Nenhuma ação é necessária.
• Suas configurações explícitas são sempre respeitadas. Se você mesmo definir environment_version, o Databricks nunca o substituirá.

Assim que um pipeline é migrado com sucesso, ele é executado na versão do ambiente daqui para frente. Você pode ver a versão que foi selecionada nas configurações do pipeline, na resposta da API GetPipeline e no log de eventos runtime_details.

O que não é migrado automaticamente

Um pipeline não é migrado automaticamente se qualquer uma das seguintes condições se aplicar:

• Ele possui avisos de compatibilidade do Spark Connect não resolvidos desde sua atualização mais recente.
• Não é um pipeline do Unity Catalog.
• Ele usa um recurso que a migração automática ainda não cobre: coletoresforeach_batch, ganchos de eventos, AUTO CDC de uma fonte de função de snapshot ou uma imagem personalizada.

Os pipelines que não são migrados automaticamente continuam sendo executados em seu runtime do Python anterior sem alterações. Você pode ativar uma versão de ambiente por conta própria assim que o pipeline estiver qualificado.

Habilite você mesmo uma versão do ambiente

A migração automática cobre a maioria dos pipelines. Você também pode configurar uma versão de ambiente explicitamente, por exemplo, para migrar mais cedo ou para fixar (pin) uma versão específica, por meio da interface do editor de pipeline, da API REST de Pipelines ou de Pacotes de Automação Declarativa.

Antes de ativar uma versão de ambiente explicitamente, verifique se o seu pipeline é compatível com o Spark Connect. Se o Databricks detectar que a ativação da versão alteraria o comportamento do seu pipeline, a atualização falhará antes que qualquer dado seja gravado, com um erro identificando a diferença a ser resolvida.

Habilitar através da interface do usuário

1. No editor de pipeline, clique em Configurações .
2. Em Ambiente de pipeline , selecione Editar ambiente .
3. Selecione uma versão de ambiente na lista dropdown .
4. Salve as configurações do pipeline.

As dependências externas adicionadas na seção Ambiente do pipeline são sobrepostas à biblioteca incluída na versão do ambiente selecionada. Consulte a documentação sobre gerenciamento de dependências Python para o pipeline.

Habilitar através da API

A API REST do pipeline aceita um bloco environment na criação e atualização pipeline . A autenticação por token de acesso pessoal deve estar habilitada para o workspace.

Para criar um pipeline com uma versão de ambiente:

Shell

curl --request POST \
  --url 'https://<workspace-host>/api/2.0/pipelines' \
  --header 'Authorization: Bearer <personal-access-token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<pipeline-name>",
    "catalog": "<catalog>",
    "schema": "<schema>",
    "channel": "CURRENT",
    "environment": {
      "environment_version": "4",
      "dependencies": [
        "simplejson==3.19.*"
      ]
    }
  }'

Para definir a versão do ambiente em um pipeline existente, envie o mesmo bloco environment com PUT /api/2.0/pipelines/<pipeline-id>.

Habilite através de pacotes de automação declarativa.

Ao criar um pipeline usando Pacotes de Automação Declarativa, é possível definir uma versão de ambiente na definição YAML do pipeline.

1. Certifique-se de que sua CLI do Databricks esteja na versão v0.294.0 ou posterior. Caso contrário, atualize seguindo o guia de instalação.
2. Configure um pacote seguindo o tutorialde pacote de pipeline.
3. Localize o YAML do pipeline no seu pacote, normalmente <bundle-folder>/resources/<pipeline_name>_pipeline.yml.
4. Defina os campos environment_version e dependencies no YAML do pipeline:

YAML

resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      catalog: ${var.catalog}
      schema: ${var.schema}
      root_path: '../src/my_pipeline'
      libraries:
        - glob:
            include: ../src/my_pipeline/transformations/**
      environment:
        environment_version: 4
        dependencies:
          - --editable ${workspace.file_path}

Verifique a versão do ambiente em um pipeline.

Para verificar qual versão de ambiente um pipeline está executando, seja você a tendo definido explicitamente ou o Databricks a tendo selecionado durante a migração automática:

• IU : Abra as configurações do pipeline e verifique a seção Ambiente do pipeline ou inspecione o painel JSON para o campo environment.environment_version.
• API : chame GET /api/2.0/pipelines/<pipeline-id> e procure por environment.environment_version na resposta. Isto mostra uma versão que você definiu explicitamente; para ver uma versão selecionada por migração automática, use o log de eventos abaixo.
• Log de eventos : inspecione o evento runtime_details, que relata a versão do ambiente usada para a atualização. Consulte Detalhes do evento runtime_details.

Desative ou reverta uma versão do ambiente

Você não precisa reverter uma migração automática manualmente. Uma migração que falha é revertida automaticamente na próxima atualização. Quando a versão do ambiente é removida, o pipeline retorna à sua configuração anterior de runtime do Python. Se algo inesperado acontecer, entre em contato com o suporte da Databricks.

Recursos adicionais

• Compatibilidade de versão de ambiente — limitações, mudanças de comportamento, o compatibility scan e migração automática.
• Gerenciar dependências Python para pipeline — sobrepondo dependências Python externas a uma versão de ambiente.