Ingerir relatórios do Workday incrementalmente

info

Beta

A ingestão incremental está em Beta.

Por padrão, o LakeFlow Connect ingere relatórios do Workday usando o modo Snapshot, que lê todas as linhas do relatório em cada atualização de pipeline. A ingestão incremental, em vez disso, lê apenas os dados que foram alterados desde a última atualização do pipeline. Isso reduz a carga na sua instância do Workday e diminui o custo e o tempo de cada execução de pipeline.

Como funciona a ingestão incremental

A ingestão incremental usa uma coluna de cursor (também chamada de coluna sequence_by) para rastrear o progresso. A coluna do cursor deve ser uma coluna de data no seu relatório do Workday. Em cada atualização de pipeline, o conector usa o cursor para determinar quais dados são novos e lê apenas essas linhas.

Para filtrar o relatório por data, o administrador do Workday define parâmetros na coluna do cursor. Parâmetros são parâmetros no URL do relatório do Workday que permitem passar um intervalo de datas para o relatório no momento da consulta. Os nomes dos parâmetros são escolhidos pelo administrador do Workday e devem corresponder aos nomes dos parâmetros que são especificados no URL do pipeline. Por exemplo, um administrador do Workday pode definir parâmetros chamados Date_Start e Date_End em uma coluna Date — mas os nomes reais dependem de como o relatório está configurado no Workday.

Atualização inicial do pipeline

Quando a execução do pipeline ocorre pela primeira vez, o conector ingere todos os dados do valor Date_Start especificado na definição do pipeline até a data atual. Por exemplo, se o seu relatório contém dados de 01-01-2025, mas se definir Date_Start para 06-02-2025, a atualização inicial ingere dados de 06-02-2025 em diante.

Após a conclusão da atualização inicial, o conector armazena o valor máximo do cursor encontrado nos dados ingeridos como o novo valor sequence_by. Este valor determina onde a próxima atualização do pipeline começa.

Atualizações subsequentes do pipeline

Em cada atualização subsequente, o conector ingere todas as novas linhas desde a última atualização, usando o valor sequence_by armazenado como o ponto de começar da nova janela de ingestão. O conector então atualiza o valor sequence_by armazenado para refletir o valor mais recente do cursor. Por exemplo, se a atualização inicial ingeriu dados até 12/02/2025, a próxima atualização lê linhas com um valor de cursor em ou após 12/02/2025.

Mantendo o pipeline um número fixo de dias atrasado

Se você quiser que o pipeline fique atrasado em relação à data atual por um intervalo fixo, defina o prompt Date_End para uma expressão como current date - INTERVAL 2 DAY. O pipeline então mantém esse atraso em cada atualização subsequente.

Limitações

As seguintes limitações se aplicam à ingestão incremental para relatórios do Workday. Para limitações adicionais do conector, consulte limitações do conector Workday Reports.

• É necessário um cursor que aumente monotonicamente. A coluna do cursor deve aumentar a cada linha nova ou atualizada. Linhas cujo valor do cursor é maior que o último valor do cursor ingerido são ingeridas — isso inclui tanto novas linhas quanto linhas atualizadas que avançam o cursor. Linhas que são excluídas do relatório de origem nunca são ingeridas. Se o seu relatório contém linhas que são excluídas após a ingestão inicial, use o modo Snapshot em vez disso.
• Somente cursor de data. A coluna de cursor deve ser uma coluna de data. Outros tipos de coluna não são suportados como cursor.
• Somente prompts inclusivos. Os prompts do relatório do Workday na coluna do cursor devem usar operadores inclusivos (maior ou igual a / menor ou igual a). Relatórios com prompts exclusivos (maior que / menor que) podem resultar em dados ausentes. O proprietário do relatório seleciona o tipo de prompt ao criar o relatório e seus prompts no Workday.

Configure a ingestão incremental

A ingestão incremental para relatórios do Workday é somente via API. Não é possível configurá-lo utilizando a interface do usuário do Databricks. Use os Pacotes de Automação Declarativa ou a CLI do Databricks.

Pré-requisitos

Antes de configurar o pipeline:

• Conclua a configuração da origem e confirme se existe uma conexão do Unity Catalog com o Workday.
• Peça ao administrador do Workday para definir prompts inclusivos na coluna de cursor no relatório do Workday. Por exemplo, prompts nomeados Date_Start e Date_End em uma coluna Date. O proprietário do relatório seleciona o operador **é em ou após** / **é em ou antes** ao criar os prompts no Workday.

Definição de pipeline

Para habilitar a ingestão incremental, adicione os seguintes campos à definição do seu pipeline:

• Em table_configuration, adicione um campo sequence_by definido como o nome da coluna do cursor no relatório.
• Em table_configuration, adicione um mapa workday_report_parameters.parameters que define os aliases XML de seus prompts do Workday para filtrar expressões. Use coalesce(current_offset(), date(...)) para o prompt de começar para retomar do último valor do cursor em execuções subsequentes, ou retornar para uma data de começar fixa na primeira execução.

O exemplo a seguir ingere o relatório Payroll_Journal incrementalmente, usando Journal_Date como coluna de cursor e Date_Start e Date_End como os aliás XML de prompt do Workday. O pipeline começa em 2025-01-01 na primeira execução e atrasa um dia em relação à data atual:

YAML

variables:
  dest_catalog:
    default: main
  dest_schema:
    default: ingest_destination_schema

resources:
  pipelines:
    pipeline_workday:
      name: workday_incremental_pipeline
      catalog: ${var.dest_catalog}
      schema: ${var.dest_schema}
      ingestion_definition:
        connection_name: <workday-connection>
        objects:
          - report:
              source_url: https://wd2-impl-services1.workday.com/ccx/service/customreport2/Payroll_Journal?format=json
              destination_catalog: ${var.dest_catalog}
              destination_schema: ${var.dest_schema}
              destination_table: Payroll_Journal
              table_configuration:
                primary_keys:
                  - Journal_ID
                sequence_by:
                  - Journal_Date
                workday_report_parameters:
                  parameters:
                    Date_Start: '{coalesce(current_offset(), date("2025-01-01"))}'
                    Date_End: '{current_date() - INTERVAL 1 DAY}'

Para mais exemplos de pipeline, incluindo um padrão de janela contínua, consulte Ingerir incrementalmente, a partir de uma data fixa.