Importa metadatos de dbt Core

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

La integración de dbt captura los siguientes metadatos:

  • Metadatos técnicos: Incluyen recursos clave (fuentes, inicializaciones, modelos) y sus propiedades técnicas (nombres de columnas, tipos de datos, recuentos de filas).
  • Metadatos semánticos y empresariales: Con la tecnología de dbt MetricFlow, incluyen definiciones y lógica empresariales, como modelos semánticos, métricas y consultas guardadas.
  • Metadatos operativos y de calidad de los datos: Incluyen metadatos de ejecución, como la sincronización, el estado de éxito o error, la actualidad de los datos, las pruebas y los resultados de las pruebas.
  • Metadatos de linaje y relaciones: Incluyen gráficos de transformación (DAG) y dependencias entre recursos de dbt, linaje físico que hace un seguimiento de los bloques de transformación física y los vincula, claves de unión y uniones dinámicas, y relaciones entre elementos superiores y secundarios.
  • Metadatos de consumo: Incluyen los metadatos capturados en las 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 entrada 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 del 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 Storage (roles/storage.objectViewer) en el bucket de Cloud Storage de etapa de pruebas de salida (--storage-uri) para que el trabajo de importación pueda leer el archivo de metadatos en etapa de pruebas.

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 generes 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): Gráfico de ejecución y estructura principal del proyecto. También contiene los modelos semánticos, las métricas y las consultas guardadas de MetricFlow.
  • catalog.json: Nombres de las columnas y tipos de datos. Sin catalog.json, el aspecto del esquema se importa con columnas sin tipo.
  • run_results.json: Son los resultados de las pruebas y los metadatos de ejecución.
  • sources.json: Es la 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 cumplen diferentes propósitos y no deben confundirse:

  • Entrada (artefactos de origen de dbt): Es la ubicación de los archivos JSON de dbt que generaste. Puede ser una ruta de acceso a un directorio local en tu máquina o en el 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 de acceso con la marca --artifacts-path. El comando gcloud lee estos archivos de entrada durante la preparación del trabajo. La persona que llama y 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 etapa de pruebas 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 entidad 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 están accesibles, el proceso de importación realiza las siguientes acciones:

  1. Read input artifacts: 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 etapa de pruebas: Sube el archivo de importación de metadatos transformados a la ubicación de Cloud Storage de etapa de pruebas de salida especificada en --storage-uri.
  4. Trigger import job: Activa un trabajo de importación de metadatos de Knowledge Catalog que indica al agente de servicio de Knowledge Catalog que lea y transfiera los metadatos almacenados provisionalmente de --storage-uri a los recursos de Knowledge Catalog.

Console

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

    Ir a Conectores

  2. Haz clic en Agregar conexión.

  3. En la lista Connectors, selecciona la tarjeta dbt Core and MetricFlow.

  4. Para ver los recursos de dbt que importaste, ve a la página Búsqueda o a la página Grupos de entrada de destino.

gcloud

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 configurado un bucket de Cloud Storage de etapa intermedia de salida con los permisos adecuados para el llamador 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 obligatorias

    • --storage-uri=STORAGE_URI: (Resultado/etapa de pruebas) Prefijo del URI de Cloud Storage (gs://bucket/path/) en el que se sube el archivo JSONL transformado y desde el que el trabajo de importación lee durante la transferencia. La entidad llamadora 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 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 al directorio que contiene manifest.json. La configuración predeterminada es .. Si se proporciona un URI de Cloud Storage, el llamador debe tener acceso de lectura (roles/storage.objectViewer o roles/storage.objectAdmin) al bucket de entrada.
    • --async: Regresa de inmediato, sin esperar a que se complete la operación en curso.
    • --entry-group=ENTRY_GROUP: Es el 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 modificar. No se crea, borra ni reasigna ninguna entrada, y un aspecto cuyo artefacto de dbt no estaba presente en esta ejecución conserva el valor que le dio una ejecución anterior. Úsalo para la transferencia de datos rutinaria y repetida. Consulta Cómo volver a ejecutar la transferencia.
    • --validate-only: Compila y sube el JSON, y valida el trabajo de metadatos, pero no lo ingiere.

  4. Confirma que recibiste el estado Created.

REST

Para importar metadatos de dbt con la API de REST, haz lo siguiente:

  1. Genera los artefactos de dbt y transfórmalos en el archivo de importación JSON de Knowledge Catalog (dbt_metadata.jsonl).
  2. Sube el archivo transformado a tu bucket de Cloud Storage de etapa de pruebas (gs://BUCKET_NAME/PATH/).

  3. Llama al método projects.locations.metadataJobs.create de la siguiente forma:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs?metadataJobId=JOB_ID \
    -d '{
      "type": "IMPORT",
      "importSpec": {
        "sourceStorageUri": "gs://BUCKET_NAME/PATH/",
        "entrySyncMode": "FULL",
        "aspectSyncMode": "INCREMENTAL",
        "scope": {
          "entryGroups": [
            "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP"
          ],
          "entryTypes": [
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/entryTypes/dbt-test"
          ],
          "aspectTypes": [
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-node",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-project",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-source",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-seed",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-snapshot",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-group",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-exposure",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-metric",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-macro",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-semantic-model",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-saved-query",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-data-quality",
            "projects/dataplex-connector-types/locations/global/aspectTypes/dbt-model-contracts"
          ]
        }
      }
    }'

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto Google Cloud en el que se encuentra tu grupo de entradas.
    • LOCATION: Es la región de tu grupo de entradas (por ejemplo, us-central1).
    • JOB_ID: Es un identificador único para el trabajo de metadatos.
    • BUCKET_NAME/PATH: Es el prefijo del URI de Cloud Storage en el que se subió dbt_metadata.jsonl.
    • ENTRY_GROUP: Es el ID corto del grupo de entradas de destino.

  4. Para hacer un seguimiento del estado de tu trabajo de importación, usa el método projects.locations.metadataJobs.get:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/metadataJobs/JOB_ID

Después de crear el trabajo, Knowledge Catalog programa la primera ejecución según tu configuración, o bien 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. Solo actualiza lo que observó la ejecución de dbt y deja todo lo demás en el grupo de entrada, por lo que es seguro ejecutarlo repetidamente, en cualquier programa y desde más de un trabajo.

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

  • Es la primera vez que se realiza la transferencia a un grupo de entradas.
  • Se agregó, cambió el nombre o se borró un recurso de dbt.
  • Cambia el nombre visible, la descripción o las etiquetas de una entrada.
  • Cambia la jerarquía de entrada.

Una ejecución completa reescribe todos los aspectos requeridos de cada entrada a partir de 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 de --select.
  • Se agrega, quita, cambia el tipo 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 quitarlos.

Cómo buscar y ver metadatos de dbt

Console

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

    Ir a Búsqueda

  2. En el panel Filtros, filtra los recursos de dbt:

    • En la sección Sistema, selecciona Contexto importado.
    • En la subsección Managed Connectors que aparece, selecciona dbt.

  3. En el campo de búsqueda, ingresa tu consulta con palabras clave o lenguaje natural. Por ejemplo, para ver todos los recursos de dbt con la búsqueda de palabras clave, ingresa system=DBT o system=DBT AND type=dbt-model.

  4. En los resultados de la búsqueda, haz clic en cualquier activo de dbt para abrir su página de detalles de entrada y ver su esquema, linaje y aspectos técnicos.

gcloud

  1. Para buscar entradas de dbt en tu proyecto, usa el comando gcloud dataplex entries search:

    gcloud dataplex entries search 'system=DBT' \
    --project=PROJECT_ID

    Para filtrar por un tipo de entrada de dbt específico (como modelos o fuentes), haz lo siguiente:

    gcloud dataplex entries search 'system=DBT AND type=dbt-model' \
    --project=PROJECT_ID

  2. Para ver todos los detalles y aspectos de una entrada de dbt específica, usa el comando gcloud dataplex entries lookup:

    gcloud dataplex entries lookup ENTRY_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --entry-group=ENTRY_GROUP \
    --view=FULL

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • LOCATION: Es la ubicación del grupo de entradas (por ejemplo, us-central1).
    • ENTRY_GROUP: Es el ID corto de tu grupo de entradas de destino (por ejemplo, dbt-metadata-ingestion).
    • ENTRY_ID: Es el ID corto o el nombre del recurso relativo de la entrada de dbt.

REST

  1. Para buscar entradas de dbt, llama al método projects.locations:searchEntries:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT"
    }'

    Para filtrar por un tipo de recurso de dbt específico, haz lo siguiente:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global:searchEntries \
    -d '{
      "query": "system=DBT AND type=dbt-model"
    }'

  2. Para recuperar los detalles y aspectos completos de los metadatos de una entrada específica, llama al método projects.locations.entryGroups.entries.get:

    curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID?view=FULL

  3. Para recuperar el contexto del LLM para recursos específicos de dbt, usa la API de projects.locations:lookupContext:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext \
    -d '{
      "resources": [
        "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP/entries/ENTRY_ID"
      ]
    }'

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • LOCATION: Es la ubicación del grupo de entradas (por ejemplo, us-central1).
    • ENTRY_GROUP: Es el ID corto de tu grupo de entradas de destino (por ejemplo, dbt-metadata-ingestion).
    • ENTRY_ID: Es el ID corto o el nombre del recurso relativo de la entrada de dbt.

Para obtener más información sobre la búsqueda de recursos, consulta Cómo buscar recursos en Knowledge Catalog. Para obtener más información sobre las expresiones de búsqueda y los filtros, consulta Sintaxis de búsqueda de Knowledge Catalog.

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 podrían perder campos finales.
  • --aspects-only puede agregar y actualizar metadatos, pero no 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?