Tipos de archivos en un proyecto de LookML

Un proyecto de LookML es una colección de archivos de LookML que le indican a Looker cómo conectarse a tu base de datos, cómo consultar tus datos y cómo controlar el comportamiento de la interfaz de usuario. Puedes acceder a los archivos de proyecto de LookML desde la sección Desarrollar en Looker o desde la IU, como se describe en la página de documentación Accede a los archivos de proyecto de LookML.

Los archivos de proyecto se organizan por tus desarrolladores de Looker con carpetas en el IDE.

Un proyecto de LookML consta de al menos un archivo de modelo y al menos un archivo de vista, y posiblemente algunos de los otros tipos de archivos que se describen en esta página. Todos los archivos de proyecto tienen extensiones, aunque las extensiones están ocultas en la lista del IDE si tu proyecto no está habilitado para carpetas en el IDE.

Selecciona los siguientes vínculos para obtener más información sobre cada uno de los tipos de archivos que se pueden usar en un proyecto de LookML:

Una vez que creaste un proyecto de LookML, puedes acceder a los archivos del proyecto y agregar archivos y carpetas nuevos al proyecto con el IDE de Looker.

Archivos de modelo

Un archivo de modelo especifica una conexión de base de datos y el conjunto de exploraciones que usan esa conexión. Un archivo de modelo también define las exploraciones en sí y sus relaciones con otras vistas. Una exploración es un punto de partida para consultar tus datos. En términos de SQL, una exploración es la cláusula FROM de una consulta. Tus usuarios ven las exploraciones que defines en el modelo cuando miran el menú Explorar de Looker.

En otras palabras, el archivo de modelo es donde defines qué tablas de datos se deben usar (como vistas incluidas) y cómo se deben unir, si es necesario.

Ten en cuenta lo siguiente sobre los archivos de modelo:

  • Las exploraciones suelen definirse dentro de un archivo de modelo. Sin embargo, a veces necesitas un archivo de exploración independiente para una tabla derivada, o para extender una exploración o para refinar una exploración en todos los modelos.
  • Un archivo de modelo debe tener un nombre único en todos los proyectos de tu instancia. Si tu instancia contiene dos archivos .model.lkml con el mismo nombre, es probable que encuentres errores, como errores de configuración del modelo en la página Proyectos de LookML y errores de renderización para errores del panel de LookML, ya que los paneles de LookML usan el nombre del modelo en su formato de URL (<hostname>/dashboard/model_name::<dashboard_name>). Puedes usar el validador de LookML para verificar si los nombres de los modelos están duplicados en tu instancia. Sin embargo, incluso si el validador de LookML detecta nombres de modelos duplicados en tu instancia, puedes enviar tu código a producción. Por lo tanto, asegúrate de corregir cualquier error de nombre de modelo duplicado antes de implementar tu proyecto de LookML en producción.

Consulta la página de documentación Administra archivos y carpetas de LookML para obtener instrucciones para crear archivos de proyecto de LookML, incluidos los archivos de modelo.

Estructura y sintaxis general

Dentro de las llaves de una exploración, { }, defines parámetros para la exploración. Puedes usar parámetros join para unir otras vistas a una exploración en un archivo de modelo.

En el siguiente ejemplo, el LookML en un archivo de modelo de muestra define una exploración llamada inventory_items, junto con sus vistas unidas:

connection: "thelook_events"

explore: inventory_items {
  join: products {
    type: left_outer
    sql_on: ${inventory_items.product_id} = ${products.id} ;;
    relationship: many_to_one
  }

  join: distribution_centers {
    type: left_outer
    sql_on: ${products.distribution_center_id} = ${distribution_center.id} ;;
    relationship: many_to_one
  }
}

Esta definición de LookML hace que Artículos del inventario aparezca en la sección Explorar de la navegación de Looker y une datos de las vistas products y distribution_centers a la vista inventory_items.

Se puede acceder a las vistas Centros de distribución, Artículos del inventario y Productos desde el selector de campos del Explorador de artículos del inventario.

Para obtener información más específica sobre las estructuras de LookML en un archivo de modelo, consulta la página de documentación Términos y conceptos de LookML.

Lee las páginas de documentación Parámetros del modelo, Parámetros de exploración y Parámetros de unión para obtener más información sobre los parámetros de LookML en el archivo de modelo.

Archivos de vista

Un archivo de vista generalmente define una sola "vista" dentro de Looker. Una vista corresponde a una sola tabla en tu base de datos o a una sola tabla derivada. El archivo de vista especifica una tabla para consultar y los campos (dimensiones y mediciones) que se incluirán de esa tabla para que los usuarios puedan crear consultas con esos campos en la IU de Looker.

Consulta la página de documentación Administra archivos y carpetas de LookML para obtener instrucciones para crear archivos de proyecto de LookML, incluidos los archivos de vista.

Estructura y sintaxis general

Dentro de las llaves de cada vista, { }, se encuentran las definiciones de campo, que suelen corresponder a una columna de la tabla subyacente o a un cálculo en Looker. Looker categoriza la mayoría de estas definiciones como dimensiones o mediciones.

En el siguiente ejemplo de un archivo de vista, el archivo orders.view incluye definiciones para las dimensiones id, status y user_id, el grupo de dimensiones created y la medición count:

view: orders {
  sql_table_name: demo_db.orders ;;
  drill_fields: [id]

  dimension: id {
    primary_key: yes
    type: number
    sql: ${TABLE}.id ;;
  }

  dimension: status {
    type: string
    sql: ${TABLE}.status ;;
  }

  dimension: user_id {
    type: number
    # hidden: yes
    sql: ${TABLE}.user_id ;;
  }

    dimension_group: created {
    type: time
    timeframes: [
      raw,
      time,
      date,
      week,
      month,
      quarter,
      year
    ]
    sql: ${TABLE}.created_at ;;
  }

  measure: count {
    type: count
    drill_fields: [id, users.id, users.first_name, users.last_name, order_items.count]
  }
}

La definición de estos campos en la vista orders expone los campos Fecha de creación, ID, Estado, ID de usuario y Recuento en el selector de campos para la exploración Pedidos.

Los usuarios que tienen acceso a la exploración Pedidos pueden consultarla seleccionando y filtrando estos campos.

Además de las dimensiones y las mediciones, también puedes crear varias dimensiones basadas en el tiempo a la vez con grupos de dimensiones o especificar un filtro para tus usuarios con campos de filtro. Visita la página de documentación Parámetros de vista para obtener más información sobre los parámetros de LookML en los archivos de vista y visita la página de documentación Parámetros de campo para obtener información sobre los parámetros de LookML que se usan para definir dimensiones, mediciones, grupos de dimensiones y campos de filtro en LookML.

Archivos de panel

Looker admite dos tipos de paneles:

  • Paneles definidos por el usuario, que pueden crear usuarios que no son desarrolladores sin usar LookML. Para obtener más información, consulta la página de documentación Crea paneles definidos por el usuario.
  • Paneles de LookML, que se almacenan como archivos con control de versión asociados con el proyecto.

Si tu proyecto contiene paneles de LookML, se definirán en archivos de panel dedicados en el IDE, con la extensión .dashboard.lookml.

Para obtener más información sobre los paneles de LookML, consulta la página de documentación Crea paneles de LookML.

Archivos de documentos

Los archivos de documentos de Looker te permiten escribir documentación o cualquier otra nota sobre tu modelo de datos de Looker con Markdown compatible con GitHub. Esto puede ser útil para que tus usuarios se familiaricen con la forma en que tu organización usa Looker.

Consulta la página de documentación Administra archivos y carpetas de LookML para obtener instrucciones para crear archivos de proyecto de LookML, incluidos los archivos de documentos.

Cómo ver el documento fuera del IDE

Para ver un documento fuera del IDE, lo que deberás hacer para aprovechar las funciones de navegación que se describen en esta página, elige la opción Ver documento en el menú Ver acciones del archivo para el archivo de documento:

Puedes distribuir la URL de la página resultante a otros usuarios para que puedan acceder directamente al documento sin tener que navegar por el menú Desarrollar de Looker para llegar a él.

Cómo agregar una estructura de navegación a tu documento

Puedes agregar una barra lateral a tus archivos de documentos para que los usuarios puedan ver la estructura de la información y navegar entre documentos.

Para agregar navegación por la barra lateral a un documento, crea una sección de navegación que comience en la primera línea del documento. Marca el inicio y el final de la sección de navegación con tres guiones (---).

Puedes usar los siguientes parámetros en la sección de navegación:

Puedes usar navigation: true en un archivo de documento para agregar la barra lateral de navegación a ese documento. Por ejemplo, puedes agregar el siguiente código a la parte superior de un archivo Markdown:

---
navigation: true
---

Este código agrega al documento una barra lateral de navegación con vínculos a todos los documentos del proyecto. Si solo incluyes navigation: true en un documento, la barra lateral de ese documento muestra todos los documentos del proyecto en orden alfabético por nombre de archivo.

Además, es posible que la organización por nombre de archivo alfabético no sea ideal, o que tengas algunos documentos que no quieras que aparezcan en la navegación:

En la barra lateral, se enumeran los documentos Cuatro, Uno, Tres y Dos en orden alfabético, junto con un documento titulado No mostrar.

En este ejemplo, es posible que desees enumerar los documentos Documento uno, Documento dos, Documento tres y Documento cuatro en orden numérico en lugar de alfabético, así como ocultar el documento No mostrar en la barra lateral de navegación.

Para cambiar el orden de los documentos en la barra lateral de navegación o para mostrar solo un subconjunto de tus documentos en la barra lateral, puedes usar este formato:

---
navigation:
  - document_one
  - document_two
  - document_three
  - document_four
---

Ahora, la navegación mostrará solo los archivos de documentos que deseas que se muestren, y aparecerán en un orden más lógico:

En la barra lateral, se enumeran los documentos en orden numérico, y ya no se muestra el documento No mostrar.

title

De forma predeterminada, la barra lateral muestra el encabezado del documento (si el documento comienza con un encabezado) o el nombre de archivo del documento si no hay encabezado en el archivo. Puedes agregar un parámetro title en la parte superior de un documento para cambiar la forma en que se muestra el documento en las barras laterales de navegación:

---
title: New Title for Users
---

Este título se usará como texto del vínculo en las barras laterales de navegación de todos los documentos, a menos que especifiques un label diferente en la sección de navegación de un documento.

label

Si deseas cambiar la forma en que se muestra un documento en la barra lateral de navegación, puedes usar los parámetros document y label de la siguiente manera:

---
navigation:
  - document_one
  - document: document_two
    label: Customized Label for Document Two
  - document_three
  - document_four
---

El valor label define cómo se muestra un documento en la navegación de la barra lateral del documento, incluso si el documento al que hace referencia tiene su propio title parámetro.

El ejemplo anterior se ve de la siguiente manera en la barra lateral del documento:

El documento de la página dos aparece como etiqueta personalizada para el documento dos en la barra lateral.

section

Si deseas dividir la barra lateral de navegación en secciones, puedes usar el parámetro section de la siguiente manera:

---
navigation:
  - document_one
  - document_two
  - section: My Section Name
  - document_three
  - document_four
---

En este ejemplo, el parámetro section agrega un salto de sección y el encabezado de texto Nombre de mi sección a la barra lateral.

El encabezado de texto no es un vínculo en sí; no hace referencia a ninguno de tus archivos de documentos.

Archivos de datos

Los archivos de datos son archivos JSON con extensión .json, .topojson o .geojson.

El parámetro map_layer te permite usar un archivo JSON como un mapa personalizado que luego se puede usar para trazar tus datos en Looker.

Luego, usa el parámetro map_layer_name con una dimensión para poder asociar un valor de datos (como "París") con una región geográfica en tu mapa personalizado.

Puedes editar un archivo JSON en el IDE de LookML y, luego, seleccionar Guardar.

Para la depuración, puedes elegir Ver sin procesar seleccionando el menú Ver acciones del archivo junto al nombre del archivo para ver el archivo en formato sin procesar. Si tienes la extensión adecuada para ver JSON en tu navegador, también tendrás la opción de ver el archivo en formato Analizado.

Consulta la página de documentación Administra archivos y carpetas de LookML para obtener instrucciones sobre cómo subir un archivo JSON a un proyecto de LookML.

Archivos de manifiesto del proyecto

Tu proyecto puede contener un archivo de manifiesto del proyecto, que se usa para las siguientes tareas:

Consulta la página de documentación Parámetros del manifiesto del proyecto para ver un archivo de manifiesto de ejemplo y los parámetros posibles para los archivos de manifiesto. Consulta la página de documentación Administra archivos y carpetas de LookML para obtener instrucciones para crear archivos de proyecto de LookML, incluidos los archivos de manifiesto del proyecto.

Ten en cuenta lo siguiente sobre los archivos de manifiesto del proyecto:

  • Cada proyecto solo puede tener un archivo de manifiesto, que debe llamarse manifest.lkml y estar ubicado en el nivel raíz de la estructura de directorios de tu proyecto y en tu repositorio de Git.
  • Looker no admite un archivo de manifiesto del proyecto vacío. Si tu archivo de manifiesto está vacío, borra el archivo.
  • Cada proyecto solo puede tener un archivo de manifiesto.
  • El archivo de manifiesto del proyecto debe llamarse manifest.lkml y estar ubicado en el nivel raíz de la estructura de directorios de tu proyecto.

Archivos de bloqueo de manifiesto

Los archivos de bloqueo de manifiesto se crean automáticamente cuando se agrega una dependencia remota al archivo de manifiesto del proyecto. Looker usa el archivo de bloqueo de manifiesto para hacer un seguimiento de la versión de los proyectos remotos que se especifican en el archivo de manifiesto. El archivo de bloqueo de manifiesto aparece en el panel del navegador de archivos del IDE de Looker y tiene el nombre de archivo manifest_lock.lkml.

Los desarrolladores de Looker no necesitan crear ni editar un archivo de bloqueo de manifiesto, ya que Looker administra los archivos de bloqueo automáticamente.

Para obtener más información, consulta la página de documentación Importa archivos de otros proyectos.

Archivos de cadenas de configuración regional

Si localizas tu modelo de datos, deberás crear archivos de cadenas de configuración regional para cada configuración regional a la que deseas localizar, incluida tu configuración regional predeterminada (por ejemplo, a menudo inglés en EE.UU.).

Los archivos de cadenas de configuración regional enumeran pares clave-valor para cada etiqueta y descripción que localizas en tu modelo. El archivo de cadenas para cada configuración regional debe proporcionar la traducción de esa configuración regional para cada etiqueta o descripción. En la página de documentación Localiza tu modelo de LookML, aparece más información sobre la creación de archivos de cadenas de configuración regional.

Consulta la página de documentación Administra archivos y carpetas de LookML para obtener instrucciones para crear archivos de proyecto de LookML, incluidos los archivos de cadenas de configuración regional.

Explorar archivos

Una exploración es una vista que los usuarios pueden consultar. Una exploración es el punto de partida de una consulta o, en términos de SQL, la cláusula FROM en una instrucción de SQL. Consulta la página de documentación Visualiza las exploraciones e interactúa con ellas en Looker para obtener información sobre cómo los usuarios interactúan con las exploraciones para consultar tus datos.

Las exploraciones suelen definirse dentro de un archivo de modelo. Sin embargo, a veces necesitas un archivo de exploración independiente para una tabla derivada, o para extender o refinar una exploración en todos los modelos.

Consulta la página de documentación Administra archivos y carpetas de LookML para obtener instrucciones para crear archivos de proyecto de LookML, incluidos los archivos de exploración.

Archivos de prueba de datos

Tu proyecto puede tener archivos de prueba de datos que se usan para verificar la lógica de tu modelo de LookML. Las pruebas de datos se pueden incluir en archivos de modelo o en archivos de vista, pero si tus desarrolladores desean usar las mismas pruebas de datos en varios modelos diferentes, puede ser útil mantener las pruebas de datos en su propio archivo dedicado.

Consulta la página de documentación Administra archivos y carpetas de LookML para obtener instrucciones para crear archivos de proyecto de LookML, incluidos los archivos de prueba de datos.

Archivos de refinamientos

Tu proyecto puede tener archivos que se usan para refinamientos de LookML. Con los refinamientos de LookML, puedes adaptar una vista o una exploración existentes sin editar el archivo de LookML que las contiene. Los refinamientos de LookML se pueden incluir en archivos de modelo, vista o exploración, o en su propio archivo dedicado.

Consulta la página de documentación Administra archivos y carpetas de LookML para obtener instrucciones para crear archivos de proyecto de LookML, incluidos los archivos de refinamientos.

Otros archivos

Muchos elementos de LookML se pueden alojar en diferentes archivos de tu proyecto o en sus propios archivos dedicados. Por ejemplo, las pruebas de datos se pueden alojar en archivos de modelo, archivos de vista o sus propios archivos .lkml dedicados.