Notez que vous consultez la documentation Looker. Pour accéder à la documentation sur Looker Studio, consultez la page https://support.google.com/looker-studio.

Nouveau code LookML : conversion d'un projet LookML en YAML

Looker 4.0 a introduit une nouvelle syntaxe LookML qui a amélioré le code LookML d'origine, de type YAML, avec une syntaxe familière, mais plus simple, ainsi qu'un IDE riche et d'assistance pour faciliter le développement LookML. À partir de Looker 4.4, tous les nouveaux projets LookML ont dû être créés dans le nouveau code LookML. Toutefois, certains projets créés avant la conversion peuvent encore être modélisés en code LookML (ancienne version).

Looker offre un moyen automatisé de convertir un projet LookML YAML en un nouveau code LookML. Cette page explique comment effectuer ce processus. Chaque projet LookML doit être converti individuellement, et les développeurs doivent préparer et coordonner les efforts. Veillez donc à lire l'intégralité de cette page avant de convertir un projet.

Se préparer à la conversion

La conversion d'un projet LookML YAML en un nouveau code LookML doit être effectuée par un seul développeur LookML. La conversion a lieu dans le mode Développement du développeur, puis les modifications sont validées et déployées comme toute modification LookML ordinaire.

Toutefois, ce processus nécessite la coopération de tous les développeurs LookML. Étant donné que la conversion modifie pratiquement toutes les lignes de LookML, il est important de s'assurer que les autres développeurs LookML ont validé et déployé toutes leurs modifications dans le projet avant le début du processus de conversion. Sinon, cela peut entraîner des conflits de fusion Git très désagréables.

Bien que le processus de conversion soit automatisé, la nouvelle version de LookML est beaucoup plus approfondie pour la vérification des erreurs que YAML pour le code LookML. Cela signifie qu'après la conversion, des erreurs qui n'ont pas été détectées précédemment peuvent apparaître. La résolution de ces erreurs améliorera la qualité du projet. Le nombre d'erreurs varie nécessairement d'un projet à l'autre, ce qui signifie que leur correction peut prendre de quelques minutes à quelques heures. Dans tous les cas, le développement sur le projet doit rester suspendu par tous les développeurs LookML jusqu'à ce que les erreurs soient corrigées.

Rechercher des projets YAML sur votre instance Looker

Pour afficher les projets YAML sur votre instance Looker:

Dans le menu Develop (Développer), sélectionnez l'option Manage LookML Projects (Gérer les projets LookML) ou Projects (Projets). L'option est légèrement différente selon l'endroit où vous accédez au menu Develop (Développer).
Sur la page Projets LookML, recherchez le libellé YAML LookML sur la ligne de la table d'un projet:

CONSEIL: Vous pouvez sélectionner le nom du projet dans la table pour accéder au code LookML du projet.

Coordonnez les développeurs avant d'effectuer la conversion

Pour préparer la conversion vers la nouvelle version de LookML:

Choisissez un développeur LookML pour exécuter le processus de conversion.
Assurez-vous que le projet est exempt d'erreur en exécutant l'outil de validation LookML. Corrigez toutes les erreurs, puis validez et déployez les modifications avant de passer à l'étape suivante.
Indiquez l'heure à laquelle effectuer la conversion.
Indiquer à tous les autres développeurs LookML qu'ils doivent apporter les modifications sur lesquelles ils travaillent engagés et déployées dans les délais prévus. Autrement dit, toutes les copies du projet en mode Développement doivent être à l'état Git à jour avec la production.
Indiquer à tous les autres développeurs LookML qu'ils ne doivent pas apporter, valider ni déployer de modifications tant que la conversion n'est pas terminée.

Convertir en code LookML nouvelle version

Pour effectuer la conversion dans la nouvelle version de LookML, exécutez le convertisseur:

Passez en mode Développement.
Ouvrez le projet à convertir.
Assurez-vous que l'état Git dans l'angle supérieur gauche indique À jour avec la production.
Exécutez le programme de validation LookML pour vous assurer que le projet ne comporte pas d'erreurs. Le résultat devrait être Aucun problème LookML. (Pour exécuter le programme de validation LookML, sélectionnez le bouton Valider le code LookML en haut à droite de l'IDE Looker ou cliquez sur l'icône État du projet en haut de l'IDE pour ouvrir le panneau État du projet, puis sélectionnez Valider le code LookML.)
Pour convertir le projet du code LookML YAML au nouveau code LookML:
1. Sélectionnez l'icône Git Actions (Actions Git) dans la barre latérale de navigation de l'IDE Looker.
  - Vous pouvez également sélectionner l'icône État du projet en haut de l'IDE:
2. Sélectionnez l'option Convert Project to New LookML (Convertir le projet en code LookML) dans le panneau Git Actions (Actions Git) ou en bas du panneau Project Health (État du projet).
3. Sélectionnez le bouton Convert to New LookML (Convertir en code LookML) dans la boîte de dialogue de confirmation.

Valider le nouveau code LookML

Une fois l'exécution du convertisseur terminée, l'IDE indique que vos fichiers ont été modifiés, à l'aide d'un point à côté de chacun d'eux:

Pour valider le nouveau code LookML:

Sélectionnez le bouton Validate LookML (Valider LookML) pour exécuter l'outil de validation LookML. En l'absence d'erreurs, vous pouvez passer directement à la section Valider et déployer le nouveau code LookML de cette page.
Il est possible que vous constatiez des erreurs là où il n'y en avait aucune auparavant. Comme indiqué précédemment, le nouveau code LookML est plus approfondi que le code LookML YAML pour détecter les erreurs. Examinez l'erreur et corrigez-la. Si vous ne parvenez pas à les résoudre, consultez la section Résoudre les erreurs au bas de cette page.

Valider et déployer le nouveau code LookML

À ce stade, validez et déployez comme vous le feriez pour n'importe quelle modification LookML ordinaire. Attention: ce commit déclenchera une recompilation de vos tables dérivées persistantes (PDT). Une fois le commit déployé, indiquez à tous les autres développeurs LookML que la conversion est terminée et que l'exécution des requêtes basées sur des PDT peut prendre un peu plus de temps que d'habitude, au moins jusqu'à ce que tout soit recréé. Les développeurs peuvent extraire des données de la production en mode Développement pour intégrer les modifications, puis poursuivent le développement. Ils bénéficient désormais d'une syntaxe LookML améliorée et plus intuitive, et d'un IDE beaucoup plus utile et puissant.

Résoudre les erreurs

En raison de la validation plus approfondie des modèles dans la nouvelle version de LookML, des erreurs qui n'ont pas été détectées auparavant peuvent s'afficher après la conversion. De plus, la vérification des erreurs ad hoc de la nouvelle version de LookML nécessite dans certains cas un peu plus d'informations. Le convertisseur tente de le savoir pour vous, mais dans certains cas, vous devrez ajouter une ligne include supplémentaire dans un ou deux fichiers de vue.

Références de champ non valides

Dans certains contextes, YAML ne garantit pas que les champs ou les ensembles que vous référencez sont réellement définis quelque part dans le modèle. Les emplacements les plus probables se trouvent dans les listes et les ensembles de champs d'exploration.

Par exemple, si votre ancien code LookML incluait drill_fields: [id, name, email], mais qu'à un moment donné au cours du développement de votre modèle, vous avez supprimé le champ name en faveur des champs first_name et last_name, le code LookML ne vous préviendra pas que vous référencez un champ (name) de cette liste de champs d'exploration qui n'existe pas. Cela peut également se produire si vous référencez un champ d'un groupe de dimensions et que votre code LookML YAML ne spécifie pas ce champ comme le fait la nouvelle version de LookML.

La nouvelle version de LookML, en revanche, affichera ces types d'erreurs. Ainsi, après avoir converti votre projet et exécuté l'outil de validation LookML, vous risquez de rencontrer des erreurs liées à des références de champ non valides que vous n'aviez jamais vues auparavant. En corrigeant ces erreurs, vous améliorerez la qualité globale de votre modèle.

Inclusions manquantes dans les fichiers de vue

Dans certains cas, la vérification des erreurs ad hoc du nouveau code LookML nécessite un peu plus de contexte que nécessaire dans le code LookML de YAML. Plus précisément, il peut être nécessaire de placer une ligne include dans certains fichiers de vue, le plus souvent lorsqu'une vue en étend une autre.

En l'absence d'ambiguïté sur le fichier à inclure dans une vue, le convertisseur ajoute automatiquement la déclaration include appropriée dans le nouveau fichier de vue LookML, et aucune erreur ne s'affiche.

Toutefois, dans certains cas (par exemple, pour les projets contenant plusieurs modèles), deux vues ou plus peuvent avoir le même nom et être déclarées dans des fichiers de vue distincts. Le convertisseur ne sera pas en mesure de déterminer laquelle est la bonne à inclure. Il ajoutera donc un commentaire en haut du nouveau fichier LookML pour indiquer qu'une seule de ces vues doit être incluse. Résolvez l'erreur résultante en accédant au fichier de vue et en annulant la mise en commentaire de la suggestion appropriée.

`extension_required` explorations bloquées

Comme pour le problème de références de champ non valides décrit précédemment, dans la nouvelle version de LookML, le validateur LookML vous alerte des explorations déclarées avec extension: required, mais qui ne sont pas en réalité étendues. Pour résoudre cette erreur, reconnectez ces explorations à leurs objets étendus ou, s'ils ne sont pas utilisés, supprimez-les.

Contrôle des versions

Étant donné que le processus de conversion LookML remplace vos fichiers de vue et de modèle .lookml par des versions .lkml, si un ou plusieurs développeurs s'engagent dans votre projet lors de la conversion, vous serez au cœur d'un conflit de fusion. C'est pourquoi il est extrêmement important qu'un seul développeur exécute le convertisseur. Il doit se coordonner pour s'assurer que les copies en mode Développement de tous les utilisateurs sont propres et à jour avant de commencer le processus de conversion.

Pour éviter les problèmes de contrôle des versions, un gel du code doit se produire lors de la conversion. Les autres développeurs ne doivent pas vérifier les modifications pendant la période pendant laquelle la conversion est bloquée.

Si le développeur qui exécute la conversion rencontre des problèmes pendant le processus de conversion, mais avant de valider les modifications et de passer en production, il peut être utile de revenir à l'environnement de production. Cette option de la liste déroulante (voir la section Exécuter le convertisseur de cette page) annule la conversion, ce qui permet au développeur de recommencer le processus.