Nuevo LookML: Cómo convertir un proyecto YAML de LookML

Looker 4.0 introdujo una nueva sintaxis de LookML que mejoró la original de estilo YAML con una sintaxis familiar, pero sencilla, y un IDE enriquecido y asistivo para facilitar el desarrollo de LookML. A partir de Looker 4.4, todos los proyectos nuevos de LookML tuvieron que crearse en el nuevo LookML. Sin embargo, es posible que algunos proyectos que se crearon antes de la conversión aún se modelen en LookML (antiguo) en YAML.

Looker proporciona una forma automatizada de convertir un proyecto YAML de LookML a LookML nuevo. En esta página, se explica cómo realizar ese proceso. Cada proyecto de LookML debe convertirse de forma individual, y los desarrolladores deben preparar y coordinar sus esfuerzos, así que asegúrate de leer toda esta página antes de convertir un proyecto.

Prepárate para realizar la conversión

Solo un desarrollador de LookML debe realizar la tarea de convertir un proyecto YAML de LookML al nuevo. La conversión se realiza en el Modo de desarrollo de ese desarrollador y, luego, los cambios se confirman y, luego, se implementan como cualquier cambio común de LookML.

Dicho esto, el proceso requiere la cooperación de todos los desarrolladores de LookML. Debido a que la conversión altera esencialmente cada línea de LookML, es importante asegurarse de que otros desarrolladores de LookML hayan confirmado y implementado todos sus cambios en el proyecto antes de que comience el proceso de conversión. De lo contrario, se pueden generar algunos conflictos de fusión de Git muy desagradables.

Aunque el proceso de conversión es automático, el nuevo LookML es mucho más exhaustivo sobre la verificación de errores que LookML en YAML. Esto significa que, después de la conversión, pueden aparecer errores que no se mostraron antes. Resolver estos errores mejorará la calidad del proyecto. La cantidad de errores variará necesariamente de un proyecto a otro, por lo que solucionarlos puede tardar entre unos minutos y unas horas. De cualquier manera, todos los desarrolladores de LookML deben pausar el desarrollo del proyecto hasta que se corrijan los errores.

Busca proyectos de YAML en tu instancia de Looker

Para ver los proyectos YAML en tu instancia de Looker, sigue estos pasos:

1. En el menú Desarrollar, selecciona la opción Administrar proyectos de LookML o Proyectos (la opción es ligeramente diferente según dónde accedas al menú Desarrollar).
2. En la página Proyectos de Looker, busca la etiqueta de LookML de YAML en la fila de la tabla de un proyecto:

   

   SUGERENCIA: Puedes seleccionar el nombre del proyecto en la tabla para navegar a LookML del proyecto.

Coordina con los desarrolladores antes de convertir

A fin de prepararte para la conversión al nuevo LookML, haz lo siguiente:

1. Elige un desarrollador de LookML para que ejecute el proceso de conversión.
2. Ejecuta el validador de LookML para asegurarte de que el proyecto no tenga errores. Corrige todos los errores y, luego, confirma y, luego, implementa los cambios antes de continuar con el siguiente paso.
3. Designa un horario para realizar la conversión.
4. Comunícate con todos los demás desarrolladores de LookML que necesitan que los cambios en los que estén trabajando se confirmen y se implementen antes del tiempo designado. Es decir, todas las copias del proyecto en Modo de desarrollo deben tener el estado de Git Actualizado con Producción.
5. Informa a todos los demás desarrolladores de LookML que no deben realizar, confirmar ni implementar ningún cambio hasta que se complete la conversión.

Convertir a nuevo LookML

Para convertir a LookML nuevo, ejecuta el conversor:

1. Ingresa en Modo de desarrollo.
2. Abre el proyecto que quieres convertir.
3. Asegúrate de que el estado de Git en la esquina superior izquierda muestre Up to Date con Production.
4. Ejecuta el validador de Looker para asegurarte de que no haya errores en el proyecto. El resultado debería ser No hay problemas con LookML. (para ejecutar el validador de LookML, selecciona el botón Validar LookML en la parte superior derecha del IDE de Looker o selecciona el ícono Estado del proyecto en la parte superior del IDE para abrir el panel Estado del proyecto y, luego, selecciona Validate LookML).
5. Para convertir el proyecto de LookML en YAML al nuevo LookML, sigue estos pasos:

   

   1. Selecciona el ícono de Git Actions en la barra lateral de navegación del IDE de Looker.
      • También puedes seleccionar el ícono de Project Health en la parte superior del IDE:

        

   2. Selecciona la opción Convert Project to New LookML en el panel Git Actions o en la parte inferior del panel Project Health.
   3. Selecciona el botón Convert to New LookML en el diálogo de confirmación.

Valida el nuevo LookML

Cuando haya terminado de ejecutarse el conversor, el IDE indicará que tus archivos cambiaron con un punto junto a cada nombre de archivo:

Para validar el nuevo LookML, haz lo siguiente:

1. Selecciona el botón Validate LookML para ejecutar el validador de LookML. Si no hay errores, puedes pasar a la sección Confirma e implementa el nuevo LookML de esta página.
2. Es posible que, antes, no haya errores. Como se señaló antes, el nuevo LookML es más exhaustivo a la hora de buscar errores que LookML en YAML. Revísalos y corrige los errores. Si no puedes resolverlos, consulta la sección Resuelve errores al final de esta página.

Confirma e implementa el nuevo LookML

En este punto, confirma y, luego, implementa como lo harías con cualquier cambio común de LookML. Ten en cuenta que esta confirmación activará una nueva compilación de tus tablas derivadas persistentes (PDT). Una vez que se implemente la confirmación, informa a todos los demás desarrolladores de LookML que se completó la conversión y que las consultas que dependen de las PDT pueden tardar un poco más de lo habitual en ejecutarse, al menos hasta que se vuelva a compilar todo. Los desarrolladores pueden extraer datos de la producción en su Modo de desarrollo para aplicar los cambios y, luego, continuar el desarrollo, ahora con una sintaxis de LookML mejorada y más intuitiva, y un IDE mucho más útil y potente.

Cómo resolver errores

Como resultado de la validación más exhaustiva del modelo de LookML, es posible que, después de la conversión, veas errores que no se mostraron antes. Además, la verificación de errores ad hoc del nuevo LookML requiere un poco más de información en algunos casos. El conversor intenta resolverlo por ti, pero, en algunos casos, es posible que debas agregar una línea include adicional en uno o dos archivos de vista.

Referencias de campo no válidas

En algunos contextos, LookML con YAML (anterior) no garantiza que los campos o conjuntos de referencia estén definidos en algún lugar del modelo. El lugar más probable que aparezca es en las listas y conjuntos de campos de desglose.

Por ejemplo, si tu LookML anterior incluía drill_fields: [id, name, email], pero en algún momento del desarrollo de tu modelo quitaste el campo name en favor de los campos first_name y last_name, LookML en YAML no te advertirá que estabas haciendo referencia a un campo (name) en esta lista de campos de desglose que no existe. Esto también puede ocurrir si haces referencia a un campo en un grupo de dimensiones y tu LookML en YAML no especificó el campo como lo hace el nuevo LookML.

Por otro lado, el nuevo LookML muestra estos tipos de errores. Por lo tanto, después de convertir tu proyecto y ejecutar el validador de LookML, es posible que veas errores relacionados con referencias de campo no válidas que nunca antes viste. Corregir estos errores mejorará la calidad general de tu modelo.

Faltan inclusiones en los archivos de vista

En algunos casos, la verificación de errores ad hoc del nuevo LookML requiere un poco más de contexto del que se necesitaba en LookML en YAML. Específicamente, puede ser necesario colocar una línea include en algunos archivos de vista, por lo general, cuando una vista extiende otra.

Cuando no haya ambigüedad sobre qué archivo debe incluirse en una vista, el conversor agregará automáticamente la declaración include adecuada en el nuevo archivo de vista de LookML, y no verás ningún error.

Sin embargo, en algunos casos (como con los proyectos que contienen varios modelos), puede haber dos o más vistas con el mismo nombre declaradas en archivos de vista separados. El conversor no podrá determinar cuál es la correcta para incluir, por lo que agregará un comentario en la parte superior del archivo de LookML nuevo para indicar que solo se debe incluir una de esas vistas. Para resolver el error resultante, ve al archivo de vista y quita el comentario de la sugerencia correcta.

Exploraciones de extension_required trenzadas

Al igual que el problema de referencias de campos no válidos descrito anteriormente, en el nuevo LookML, el validador de LookML te alertará sobre las exploraciones que estén declaradas con extension: required, pero que en realidad no se están extendiendo. Para corregir este error, vuelve a conectar estas exploraciones a sus objetos extendidos o, si no se usan, quítalos.

Control de versión

Debido a que el proceso de conversión de LookML reemplaza tus archivos de vista y modelo .lookml por versiones de .lkml, si uno o más desarrolladores confirman tu proyecto durante la conversión, terminarás en medio de un conflicto de combinación. Por este motivo, es extremadamente importante que solo un desarrollador ejecute el conversor, y deben coordinarse para garantizar que las copias del Modo de desarrollo de todos los usuarios estén limpias y actualizadas antes de comenzar el proceso de conversión.

Para evitar problemas con el control de versiones, el código no se puede bloquear durante la conversión. Otros desarrolladores no deben registrar los cambios durante el período de bloqueo para la conversión.

Si el desarrollador que ejecuta la conversión tiene algún problema durante el proceso de conversión, pero antes de confirmar los cambios y enviarlos a producción, tal vez le resulte útil volver a la producción. Esta opción del menú desplegable (que se muestra en la sección Cómo ejecutar el conversor de esta página) revertirá la conversión, lo que le permitirá al desarrollador comenzar el proceso de nuevo.