Ingérer les rapports Workday incrémentiellement

info

Bêta

L'ingestion incrémentielle est en Bêta.

Par default, Lakeflow Connect ingère les rapports Workday en mode instantané, qui lit toutes les lignes du rapport à chaque mise à jour du pipeline. L'ingestion incrémentielle lit uniquement les données qui ont changé depuis la dernière mise à jour du pipeline. Cela réduit la charge sur votre instance Workday et diminue le coût et le temps de chaque exécution de pipeline.

Comment fonctionne l'ingestion incrémentielle

L'ingestion incrémentale utilise une colonne de curseur (également appelée colonne sequence_by) pour suivre la progression. La colonne de curseur doit être une colonne de date dans votre rapport Workday. À chaque mise à jour du pipeline, le connecteur utilise le curseur pour déterminer quelles données sont nouvelles et ne lit que ces lignes.

Pour filtrer le rapport par date, votre administrateur Workday définit des prompts sur la colonne du curseur. Les prompts sont des paramètres dans l'URL du rapport Workday qui vous permettent de transmettre une plage de dates au rapport au moment de la query. Les noms des prompts sont choisis par votre administrateur Workday et doivent correspondre aux noms des paramètres que vous spécifiez dans l'URL de votre pipeline. Par exemple, un administrateur Workday pourrait définir des prompts nommés Date_Start et Date_End sur une colonne Date — mais les noms réels dépendent de la configuration du rapport dans Workday.

Mise à jour initiale du pipeline

Lorsque vous exécutez le pipeline pour la première fois, le connecteur ingère toutes les données de la valeur Date_Start que vous spécifiez dans la définition du pipeline jusqu'à la date actuelle. Par exemple, si votre rapport contient des données du 2025-01-01 mais que vous avez défini Date_Start sur 2025-02-06, la mise à jour initiale ingère les données à partir du 2025-02-06.

Une fois la mise à jour initiale terminée, le connecteur stocke la valeur maximale du curseur trouvée dans les données ingérées comme nouvelle valeur sequence_by. Cette valeur détermine le point de départ de la prochaine mise à jour du pipeline.

Mises à jour ultérieures du pipeline

À chaque mise à jour ultérieure, le connecteur ingère toutes les nouvelles lignes depuis la dernière mise à jour, en utilisant la valeur stockée sequence_by comme start de la nouvelle fenêtre d'ingestion. Le connecteur met ensuite à jour la valeur sequence_by stockée pour refléter la dernière valeur du curseur. Par exemple, si la mise à jour initiale a ingéré des données jusqu'au 12-02-2025, la mise à jour suivante lit les lignes dont la valeur de curseur est égale ou postérieure au 12-02-2025.

Maintenir le pipeline avec un retard fixe de jours

Si vous souhaitez que le pipeline accuse un certain retard par rapport à la date actuelle, définissez l’invite Date_End sur une expression telle que current date - INTERVAL 2 DAY. Le pipeline maintient ensuite cet écart à chaque mise à jour ultérieure.

Limitations

Les limitations suivantes s'appliquent à l'ingestion incrémentielle des rapports Workday. Pour connaître les limitations supplémentaires des connecteurs, consultez les limitations des connecteurs Rapports Workday.

• Curseur à croissance monotone requis. La colonne de curseur doit augmenter à chaque ligne nouvelle ou mise à jour. Les lignes dont la valeur de curseur est supérieure à la dernière valeur de curseur ingérée sont ingérées — cela inclut à la fois les nouvelles lignes et les lignes mises à jour qui font avancer le curseur. Les lignes supprimées du rapport source ne sont jamais ingérées. Si votre rapport contient des lignes supprimées après l'ingestion initiale, utilisez plutôt le mode instantané.
• Curseur de date uniquement. La colonne du curseur doit être une colonne de date. Les autres types de colonnes ne sont pas pris en charge comme curseur.
• Prompts inclusifs uniquement. Les prompts du rapport Workday sur la colonne de curseur doivent utiliser des opérateurs inclusifs (supérieur ou égal à/inférieur ou égal à). Les rapports avec des prompts exclusifs (supérieur à/inférieur à) peuvent entraîner des données manquantes. Le propriétaire du rapport sélectionne le type de prompt lors de la création du rapport et de ses prompts dans Workday.

Configurer l'ingestion incrémentale

L'importation incrémentielle pour les rapports Workday est uniquement disponible via l'API. Vous ne pouvez pas le configurer à l'aide de l'interface utilisateur Databricks. Utilisez les Declarative Automation Bundles ou la CLI Databricks.

Prérequis

Avant de configurer le pipeline :

• Complétez la configuration de la source et confirmez qu'une connexion Unity Catalog vers Workday existe.
• Demandez à votre administrateur Workday de définir des invites inclusives sur la colonne du curseur dans le rapport Workday. Par exemple, les invites nommées Date_Start et Date_End sur une colonne Date. Le propriétaire du rapport sélectionne l'opérateur **est le ou après** / **est le ou avant** lors de la création des invites dans Workday.

Définition du pipeline

Pour activer l’ingestion incrémentielle, ajoutez les champs suivants à votre définition de pipeline :

• Dans table_configuration, ajoutez un champ sequence_by défini sur le nom de la colonne du curseur dans le rapport.
• Dans table_configuration, ajoutez une carte workday_report_parameters.parameters qui définit les alias XML de vos invites Workday pour filtrer les expressions. Utilisez coalesce(current_offset(), date(...)) pour le start prompt afin de reprendre à partir de la dernière valeur du curseur lors des exécutions ultérieures, ou revenez à une start date fixe lors de la première exécution.

L'exemple suivant ingère le rapport Payroll_Journal de manière incrémentielle, en utilisant Journal_Date comme colonne de curseur et Date_Start et Date_End comme alias XML d'invite Workday. Le pipeline start à partir de 2025-01-01 lors de la première exécution et accuse un jour de retard par rapport à la date actuelle :

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}'

Pour plus d'exemples de pipelines, y compris un modèle de fenêtre glissante, consultez Ingérer de manière incrémentielle, à partir d'une date fixe.