Importa metadatos de dbt Core

En este documento, se describe cómo importar metadatos de dbt Core y MetricFlow a Knowledge Catalog (antes Dataplex Universal Catalog) con el comando gcloud.

La integración de dbt captura los siguientes metadatos:

  • Metadatos técnicos: Incluyen recursos clave (fuentes, semillas, modelos) y sus propiedades técnicas (nombres de columnas, tipos de datos, recuentos de filas).
  • Metadatos empresariales y semánticos: Con tecnología de dbt MetricFlow, esto incluye definiciones y lógica empresariales, como modelos semánticos, métricas y consultas guardadas.
  • Metadatos operacionales y de calidad de los datos: Incluyen metadatos de ejecución, como el tiempo, el estado de éxito o falla, la actualidad de los datos, las pruebas y los resultados de las pruebas.
  • Metadatos de linaje y relación: Incluyen gráficos de transformación (DAGs) y dependencias entre recursos de dbt, linaje físico que rastrea y vincula bloques de transformación física, claves de unión y uniones dinámicas, y relaciones superior-secundario.
  • Metadatos de consumo: Incluyen metadatos capturados en exposiciones que asignan cómo se usan los datos fuera de dbt.

Antes de importar metadatos de dbt Core y MetricFlow, completa las siguientes tareas:

  1. Otorga los roles y permisos necesarios.
  2. Habilita la API de Knowledge Catalog.
  3. Cumple con los requisitos previos de dbt .
  4. Crea el grupo de entradas de destino si aún no existe.
  5. Comprende los roles de Cloud Storage.

Permisos y funciones de IAM

Para crear y administrar un trabajo de conector de Knowledge Catalog, necesitas roles de Identity and Access Management (IAM) que otorguen permisos para Knowledge Catalog y Cloud Storage.

Para obtener los permisos que necesitas para configurar un conector de dbt, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Además, debes otorgar al agente de servicio de Knowledge Catalog (service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com) el rol de Visualizador de objetos de almacenamiento (roles/storage.objectViewer) en el bucket de Cloud Storage de preparación de salida (--storage-uri) para que el trabajo de importación pueda leer el archivo de metadatos preparado.

Si quieres obtener más información para otorgar roles, consulta Administra el acceso.

Habilita las APIs

Habilita la API de Knowledge Catalog.

Habilitar la API

Requisitos previos de dbt

Para importar el conjunto completo de metadatos de dbt, te recomendamos que produzcas los cuatro archivos de artefactos JSON de dbt. Solo se requiere manifest.json. Los demás enriquecen la importación y la transformación se degrada correctamente sin ellos:

  • manifest.json (obligatorio): Estructura del proyecto principal y gráfico de ejecución. También incluye los modelos semánticos, las métricas y las consultas guardadas de MetricFlow.
  • catalog.json: Nombres de columnas y tipos de datos. Sin catalog.json, el aspecto del esquema se importa con columnas sin tipo.
  • run_results.json: Resultados de las pruebas y metadatos de ejecución.
  • sources.json: Actualidad de la fuente.

Para generar el conjunto completo de archivos JSON de artefactos de metadatos de dbt, puedes ejecutar los siguientes comandos de dbt en este orden:

  1. dbt source freshness
  2. dbt build

  3. dbt docs generate --no-compile

Comprende los roles de Cloud Storage

La importación de metadatos de dbt implica dos ubicaciones distintas de Cloud Storage que tienen diferentes propósitos y no deben confundirse:

  • Entrada (artefactos de origen de dbt): Es donde residen los archivos JSON de dbt generados. Puede ser una ruta de acceso a un directorio local en tu máquina o ejecutor de CI (como ./target/ o .) o un prefijo de URI de bucket de Cloud Storage de entrada (como gs://my-dbt-artifacts-bucket/target/). Proporcionas esta ruta con la marca --artifacts-path. El comando gcloud lee estos archivos de entrada durante la preparación del trabajo. La persona que llama que ejecuta el comando gcloud necesita acceso de lectura (roles/storage.objectViewer o roles/storage.objectAdmin) si usa Cloud Storage. El agente de servicio de Knowledge Catalog no necesita acceso al bucket de artefactos de entrada.
  • Resultado (bucket de preparación de importación de Knowledge Catalog): Es un prefijo de URI de bucket de Cloud Storage (como gs://my-staging-bucket/dbt-imports/) en el que el comando gcloud sube el archivo de importación de metadatos transformados (dbt_metadata.jsonl), y desde el que el trabajo de importación de Knowledge Catalog lee durante la transferencia. Proporcionas este URI con la marca --storage-uri. La persona que llama que ejecuta el comando gcloud necesita acceso de escritura (roles/storage.objectCreator o roles/storage.objectAdmin) para subir el archivo, y el agente de servicio de Knowledge Catalog necesita acceso de lectura (roles/storage.objectViewer) para importarlo.

Configura la conectividad de dbt

Para establecer la conectividad de dbt, primero debes ejecutar los comandos de dbt adecuados para generar los artefactos de metadatos. Una vez que los archivos JSON se almacenan y son accesibles, puedes usar el comando gcloud alpha dataplex dbt metadata-jobs create para hacer lo siguiente:

  1. Leer artefactos de entrada: Lee los artefactos JSON generados por dbt Core y MetricFlow desde la ubicación de entrada (directorio local o URI de Cloud Storage especificado en --artifacts-path).
  2. Transformar metadatos: Transforma el contenido al formato de importación de metadatos de Knowledge Catalog (dbt_metadata.jsonl).
  3. Subir a la preparación: Sube el archivo de importación de metadatos transformados a la ubicación de Cloud Storage de preparación de salida especificada en --storage-uri.
  4. Activar el trabajo de importación: Activa un trabajo de importación de metadatos de Knowledge Catalog que le indica al agente de servicio de Knowledge Catalog que lea y transfiera los metadatos preparados de --storage-uri a los recursos de Knowledge Catalog.

Para crear un trabajo de metadatos de dbt, completa los siguientes pasos:

  1. Asegúrate de que los archivos de artefactos de metadatos de dbt se almacenen de forma local o en un bucket de Cloud Storage de entrada.
  2. Asegúrate de tener un bucket de Cloud Storage de preparación de salida configurado con los permisos adecuados para la persona que llama y el agente de servicio de Knowledge Catalog.

  3. Desde Cloud Shell, una terminal local o una herramienta de flujo de trabajo automatizada, ejecuta el comando gcloud:

    gcloud alpha dataplex dbt metadata-jobs create my-dbt-import \
    --project=my-project \
    --location=us-central1 \
    --artifacts-path=. \
    --entry-group=dbt-metadata-ingestion \
    --storage-uri=gs://my-bucket/dbt-imports/

    Marcas necesarias

    • --storage-uri=STORAGE_URI: (Resultado/Preparación) Prefijo de URI de Cloud Storage (gs://bucket/path/) en el que se sube el JSONL transformado y desde el que el trabajo de importación lee durante la transferencia. La persona que llama debe tener acceso de escritura (roles/storage.objectCreator o roles/storage.objectAdmin), y el agente de servicio de Knowledge Catalog debe tener acceso de lectura (roles/storage.objectViewer).

    Marcas opcionales

    • --artifacts-path=ARTIFACTS_PATH: (Entrada) Ruta de acceso a los artefactos de dbt de origen. Puede ser una ruta de acceso a un directorio local (como . o ./target) o un prefijo de URI de Cloud Storage (como gs://my-bucket/dbt-artifacts/). Puede apuntar a la raíz del proyecto de dbt (el subdirectorio target/ se detecta automáticamente) o directamente a el directorio que contiene manifest.json. El valor predeterminado es .. Si se proporciona un URI de Cloud Storage, la persona que llama debe tener acceso de lectura (roles/storage.objectViewer o roles/storage.objectAdmin) al bucket de entrada.
    • --async: Muestra el resultado de inmediato, sin esperar a que se complete la operación en curso.
    • --entry-group=ENTRY_GROUP: ID corto del grupo de entradas que recibe las entradas de dbt. Ya debe existir en el proyecto y la ubicación (el valor predeterminado es dbt-metadata-ingestion).
    • --aspects-only: Actualiza solo los metadatos que observó esta ejecución de dbt y deja el resto del grupo de entradas sin cambios. No se crea, borra ni vuelve a vincular ninguna entrada, y un aspecto cuyo artefacto de dbt no estuvo presente en esta ejecución conserva el valor que le dio una ejecución anterior. Usa esto para la transferencia de rutina y repetida. Consulta Volver a ejecutar la transferencia.
    • --validate-only: Compila y sube el JSON, y valida el trabajo de metadatos, pero no lo transfieras.

  4. Confirma que recibiste un estado Created.

  5. Después de crear el trabajo, Knowledge Catalog programa la primera ejecución según tu configuración, o puedes iniciarla de forma manual.

Volver a ejecutar la transferencia

Después de la primera importación, la mayoría de las ejecuciones solo necesitan actualizar los metadatos de los recursos que ya existen. Usa --aspects-only para esas ejecuciones. Actualiza solo lo que observó la ejecución de dbt y deja todo lo demás en el grupo de entradas, por lo que es seguro ejecutarlo de forma repetida, en cualquier programación y desde más de un trabajo.

Ejecuta una transferencia completa (omite --aspects-only) cuando cambia el conjunto de entradas:

  • La primera transferencia a un grupo de entradas.
  • Se agrega, cambia el nombre o se borra un recurso de dbt.
  • Cambia el nombre visible, la descripción o las etiquetas de una entrada.
  • Cambia la jerarquía de entradas.

Una ejecución completa vuelve a escribir los aspectos necesarios de cada entrada desde los artefactos en el disco, por lo que debes ejecutarla desde un conjunto de artefactos lo más completo posible que pueda producir tu canalización.

Ejecuta --aspects-only para las actualizaciones de rutina:

  • Después de cualquier comando de dbt que ejecute tu canalización: dbt build, dbt test, dbt source freshness o una recompilación reducida con --select.
  • Se agrega, quita, vuelve a escribir o se vuelve a describir una columna.
  • Se cambió el SQL del modelo y la ejecución también escribió catalog.json.
  • Nuevos resultados de pruebas o actualidad de la fuente.

--aspects-only puede agregar y actualizar metadatos, pero no puede quitarlos.

Busca y visualiza metadatos de dbt

  1. En la Google Cloud consola de, ve a la página Búsqueda de Knowledge Catalog.

    Ir a Búsqueda

  2. En el panel Filtros, puedes filtrar los recursos de dbt con las secciones Proyecto, Sistema y Alias de tipo. En la sección Sistema, selecciona Contexto importado. Si seleccionas este filtro, se abrirá una subsección Conectores administrados. Selecciona dbt para filtrar todos los metadatos de dbt.

  3. Puedes usar el campo de búsqueda para realizar consultas de búsqueda. Puedes realizar una búsqueda de palabras clave o de lenguaje natural. Por ejemplo, para ver todos los recursos de dbt a través de la búsqueda de palabras clave, ingresa system=DBT.

    Para obtener más información sobre la búsqueda de recursos, consulta Busca recursos en Knowledge Catalog. Para obtener más información sobre las expresiones que puedes usar en el campo de búsqueda, consulta Busca sintaxis para Knowledge Catalog.

  4. También puedes usar la LookupContext para recuperar el contexto de LLM para recursos de dbt específicos.

Limitaciones

  • Admite versiones recientes de dbt Core v1 (validadas en las versiones 1.11 y 1.12). No se admiten dbt Core v2 ni dbt Fusion.
  • No se admiten los modelos de dbt que usan el control de versiones del modelo.
  • No se admite dbt Cloud.
  • Los esquemas muy grandes o anidados de forma profunda se truncan: un solo aspecto no puede exceder el límite de tamaño por aspecto, por lo que los esquemas anidados de forma profunda pueden perder campos finales.
  • --aspects-only puede agregar y actualizar metadatos, pero no puede quitarlos. Para borrar un recurso de dbt, se requiere una ejecución completa.
  • No se admiten los vínculos de entrada.
  • Esta integración solo admite eventos de linaje de dbt en recursos de BigQuery en la API y el gráfico de Data Lineage. Las entradas de dbt (fuente, semillas, modelos) para fuentes externas de terceros no se capturan en el linaje de datos.

¿Qué sigue?