Configurer les adapters et les seeds

Les marts human_resources et educ_serv utilisent des adapters et des seeds pour configurer l'ETL. Comme expliqué dans la page "Architecture", ces deux mécanismes servent à fournir à l'ETL des règles d'affaires propres à un centre de services scolaire. Les seeds sont des fichiers csv utilisés pour créer des dimensions qui serviront ensuite à filtrer ou remapper les données. Les adapters sont des fichiers SQL contenant du SQL arbitraire pour créer des dimensions ou des faits. Nous privilégions généralement les seeds, car elles sont plus faciles à maintenir et à comprendre. Mais parfois, il faut simplement écrire du SQL.

Seeds

Implémenter une seed

Pour implémenter une seed, créez un fichier csv avec les colonnes définies par le contrat de la seed. Le fichier csv doit être placé au chemin correspondant sous cssXX.dashboards_store/seeds/**/*/ et doit utiliser le nom de seed défini dans le fichier YAML. Le fichier de définition indique les types de colonnes attendus et décrit chaque champ pour vous aider à l'alimenter.

Une fois la seed alimentée, vous pouvez la charger dans la base et la tester avec la commande:

dbt build --full-refresh --select <nom_de_la_seed>

Exemple:

Supposons que je veuille implémenter une seed nommée example_seed, définie dans core.dashboards_store/seeds/marts/example/schema.yml. Le contenu du fichier schema.yml est:

seeds:
  - name: example_seed
    description: >
      Ceci est la seed d exemple.
      Cette seed est volontairement inutile. Elle contient n importe quel ensemble d entiers.
    # Description des champs
    columns:
      - name: seq_value
        description: Entier aleatoire
        tests:
          - not_null  # Les valeurs nulles ne sont pas permises
          - unique  # L entier doit etre unique
    # Type de donnees de la seed
    config:
      column_types:
        value: int

Je crée d'abord un fichier csv vide et je l'enregistre sous cssXX.dashboards_store/seeds/marts/example/example_seed.csv. Notez que la seed est enregistrée dans le projet cssXX, pas dans le projet core. Le nom du fichier est celui indiqué à la deuxième ligne de la définition de la seed: example_seed. D'après la définition, je sais que mon implémentation ne doit avoir qu'une colonne nommée seq_value, remplie avec un ensemble d'entiers uniques et non nuls. Je peux maintenant alimenter le fichier csv avec le contenu suivant:

seq_value
1
2
3
4
6
7
9

Je charge ensuite ma seed dans la base de données et je la teste. Une table sera automatiquement créée et alimentée avec le contenu du fichier csv. La table s'appellera exemple_seed. Pour cela, j'exécute simplement la commande suivante:

dbt build --full-refresh --select example_seed

Adapters

Adapters obligatoires

Le tableau suivant indique les définitions d'adapters requises et les chemins où placer les fichiers sql.

Implémenter un adapter

Les adapters sont décrits dans des fichiers adapters.yml. Ces fichiers se trouvent sous core.dashboards_store/models/**/adapters.yml.

Pour implémenter un adapter, créez un fichier sql contenant du SQL arbitraire. Le fichier doit être enregistré sous cssXX.dashboards_store/models/**/*/<adapter_name>.sql. Le chemin exact doit correspondre au chemin de la définition YAML, suffixé par le nom de l'adapter.

Le fichier de définition indique les types de colonnes attendus et décrit chaque champ. Consultez-le pour connaître les spécifications et descriptions des colonnes.

Nous essayons d'ajouter une analysis dbt comme exemple d'implémentation d'un adapter. Lorsqu'elle existe, elle est enregistrée sous core.dashboards_store/analyses/**/*/<adapter_name>.sql, où **/*/<adapter_name>.sql correspond au chemin du fichier de définition de l'adapter.

Exemple:

Supposons que je doive implémenter l'adapter stg_ele_prescolaire. Il est défini dans core.dashboards_store/models/marts/educ_serv/adapters.yml. Sa définition est:

# core.dashboards_store/models/marts/educ_serv/adapters.yml
sources:
  - name: populations
    description: >
      Les populations identifient des groupes d'élèves aux profils cohérents, par exemple les élèves réguliers, les élèves en adaptation scolaire ou les élèves de la formation générale des adultes.
    schema: "{{ target.schema }}_educ_serv_staging"
    tables:
      - name: stg_ele_prescolaire
        description: >
          Identification de la population en maternelle 4 ans / Passe-Partout / maternelle 5 ans.
        columns:
          - name: code_perm
            description: Identifiant unique propre à un élève
          - name: id_eco
            description: Identifiant unique propre à une école par année
          - name: annee
            description: Années pendant lesquelles l'élève était actif

models:
  - name: stg_ele_prescolaire
    config:
      schema: "educ_serv_staging"
      <<: *x-common-tags
    description: >
      Identification de la population en maternelle 4 ans / Passe-Partout / maternelle 5 ans.
    tests:
      - resolution:
          combination_of_columns:
            - code_perm
            - id_eco
            - annee

1. Je crée d'abord un fichier sous cssXX.dashboards_store/models/marts/educ_serv/stg_ele_prescolaire.sql. Notez que le fichier est créé dans cssXX avec le même nom que celui du fichier de définition.
2. Je vérifie ensuite la définition:
   1. À partir de la clé source, je sais que l'adapter doit contenir les trois colonnes code_perm, id_eco et annee.
   2. À partir de la clé models, je sais que la table doit réussir un test de résolution sur ces trois colonnes, ce qui signifie qu'elle ne doit pas contenir de doublons sur cette combinaison.
3. Je vérifie ensuite core.dashboards_store/analyses/marts/educ_serv/stg_ele_prescolaire.sql pour voir si une analyse est disponible. Dans ce cas, il y en a une. Je la copie et l'adapte dans mon fichier sql pour amorcer l'implémentation de l'adapter.

-- cssXX.dashboards_store/models/marts/educ_serv/stg_ele_prescolaire.sql
select distinct ele.code_perm, eco.id_eco, eco.annee
from {{ ref("i_gpm_e_dan") }} as eledan
left join {{ ref("i_gpm_t_eco") }} as eco on eledan.id_eco = eco.id_eco
left join
    {{ ref("i_gpm_e_ele") }} as ele on eledan.fiche = ele.fiche
    /*WHERE 
    eledan.statut_don_an = 'A' AND (
        (
            eledan.ordre_ens = '1'
            AND eledan.grp_rep IN ('MA4','MA5','M41','M42')
        )

        OR (
            eledan.ordre_ens = '2'
            AND (eledan.grp_rep NOT LIKE '9%' OR eledan.grp_rep IS NULL)
            )
    )*/

4. J'ajuste ensuite le code copié, ou je le réécris complètement, pour qu'il corresponde à la réalité de mon centre de services scolaire.