Importa metadatos de dbt Core

Para los ingenieros de datos, los ingenieros de análisis y los administradores de datos, la centralización de los metadatos es fundamental para el descubrimiento y la administración de datos empresariales. Cuando los equipos usan dbt para la transformación de datos, se generan valiosos metadatos operativos, semánticos y de linaje, pero a menudo permanecen aislados dentro del ecosistema de dbt.

Para integrar esta información en tu catálogo centralizado, puedes importar metadatos de dbt Core, dbt Cloud y MetricFlow a Knowledge Catalog (anteriormente, Dataplex Universal Catalog).

Dado que dbt Core funciona como un motor de transformación en lugar de un sistema de almacenamiento como Oracle o PostgreSQL, la importación de sus metadatos habilita diferentes casos de uso. Importas metadatos de Oracle o PostgreSQL para responder a la pregunta "¿Qué datos sin procesar tenemos?" y metadatos de dbt Core para responder a la pregunta "¿Cómo se transforman nuestros datos, son confiables y qué significan para la empresa?".

En este documento, se describe cómo importar metadatos con el comando de Google Cloud CLI y tus archivos de artefactos de dbt.

Cuando ejecutas la integración de dbt, capturas los siguientes metadatos:

  • Metadatos técnicos: Descubre datos empresariales explorando recursos clave (fuentes, semillas, modelos) y sus propiedades técnicas (nombres de columnas, tipos de datos, recuentos de filas).
  • Metadatos semánticos y empresariales: Proporcionan contexto para las herramientas de IE y los agentes de IA explorando las definiciones y la lógica empresariales potenciadas por dbt MetricFlow, como modelos semánticos, métricas y consultas guardadas.
  • Metadatos operativos y de calidad de los datos: Supervisa el estado de la canalización y soluciona problemas relacionados con los datos explorando metadatos de ejecución, como la sincronización, el estado de éxito o error, la actualización de los datos y los resultados de las pruebas.
  • Metadatos de linaje y relaciones: Permiten el análisis del impacto en los procesos posteriores y el seguimiento de la causa raíz explorando gráficos de transformación (DAG) y dependencias entre los recursos de dbt, el linaje físico que rastrea y vincula los bloques de transformación física, las claves de unión y las uniones dinámicas, y las relaciones entre elementos principales y secundarios.
  • Metadatos de consumo: Soluciona problemas relacionados con la forma en que las aplicaciones posteriores consumen los datos transformados explorando los metadatos capturados en las exposiciones que asignan cómo se usan los datos fuera de dbt.

Limitaciones

  • Es compatible con dbt Core v1 (validado en las versiones 1.11 y 1.12), dbt Core v2 y dbt Fusion.
  • La versión 586.0.0 y posteriores de gcloud CLI admiten la integración de dbt y BigQuery. Para instalar o actualizar la CLI, consulta Instala la CLI de Google Cloud CLI.
  • No hay conexión directa a dbt Cloud. Para importar metadatos de un trabajo de dbt Cloud, primero obtén los artefactos del trabajo. Consulta Importa metadatos de las ejecuciones de dbt Cloud.
  • Los esquemas muy grandes o anidados profundamente se truncan: ningún aspecto puede superar el límite de tamaño por aspecto, por lo que los esquemas anidados profundamente pueden 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.
  • 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 (fuentes, semillas, modelos) para fuentes externas de terceros no se capturan en el linaje de datos.

Antes de comenzar

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:

Si tienes los permisos necesarios para administrar el acceso a IAM en tu proyecto, puedes otorgar estos roles a tu propia cuenta de usuario ejecutando los siguientes comandos de gcloud:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="user:USER_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="user:USER_EMAIL" \
    --role="roles/storage.objectCreator"

Si ejecutas la importación con una cuenta de servicio, como en una canalización de CI/CD automatizada, puedes otorgar estos roles a la cuenta de servicio ejecutando los siguientes comandos de gcloud:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.metadataJobOwner"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/dataplex.entryGroupOwner"

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectCreator"

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 etapa de pruebas de salida (--storage-uri) para que el trabajo de importación pueda leer el archivo de metadatos en etapa de pruebas:

gcloud storage buckets add-iam-policy-binding gs://STAGING_BUCKET \
    --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • USER_EMAIL: La dirección de correo electrónico de tu cuenta de usuario
  • SERVICE_ACCOUNT_EMAIL: La dirección de correo electrónico de tu cuenta de servicio
  • STAGING_BUCKET: Es el nombre de tu bucket de Cloud Storage de etapa de pruebas de salida (--storage-uri).
  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .

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.

En tu terminal local, Cloud Shell o entorno de CI/CD automatizado en el que está instalado dbt, ve al directorio raíz del proyecto de dbt y ejecuta los siguientes comandos de dbt en orden contra un solo perfil y destino para generar el conjunto completo de archivos JSON de artefactos de metadatos de dbt:

  • Para dbt Core 2.x y dbt Fusion:

    1. dbt source freshness
    2. dbt build

    3. dbt parse --write-catalog

  • Para dbt Core 1.x (en el que dbt parse no escribe un catálogo):

    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.

Importa metadatos de las ejecuciones de dbt Cloud

Knowledge Catalog no se conecta directamente a dbt Cloud. Dado que un trabajo de dbt Cloud genera los mismos archivos de artefactos que dbt Core, puedes importar metadatos desde dbt Cloud recuperando esos archivos de artefactos en un directorio local o en un bucket de Cloud Storage de entrada y ejecutando el comando gcloud.

Antes de recuperar los artefactos, configura el trabajo de dbt Cloud para generar el conjunto completo de artefactos. Luego, puedes recuperar los archivos de artefactos de una ejecución de trabajo de dbt Cloud con uno de los siguientes métodos:

Configura el trabajo de dbt Cloud

En la consola de dbt Google Cloud , configura los parámetros de tu trabajo para generar el conjunto completo de artefactos de metadatos:

  1. En la sección Configuración de ejecución, selecciona Ejecutar la actualización de la fuente. dbt Cloud ejecuta dbt source freshness antes de los comandos del trabajo para generar sources.json.
  2. En la sección Comandos, agrega dbt build.
  3. Agrega un comando para generar catalog.json según tu segmento de versión:
    • Para los segmentos de versiones de dbt Core 2.x y dbt Fusion: Agrega dbt parse --write-catalog como un comando de trabajo.
    • Para los segmentos de versiones de dbt Core 1.x: Agrega dbt docs generate --no-compile como un comando de trabajo en lugar de seleccionar la opción Generate docs on run. La casilla de verificación Generate docs on run ejecuta dbt docs generate sin --no-compile, lo que reemplaza los resultados de la prueba de dbt build, como se describe en los requisitos previos de dbt. Ten en cuenta que, si falla un paso de comando, también falla el trabajo, mientras que el paso de casilla de verificación no hace que falle el trabajo.

Si falla dbt build, por ejemplo, porque falla una prueba, dbt Cloud omite los comandos posteriores y la ejecución no tiene catalog.json. Para generar siempre uno, agrega el comando del catálogo antes de dbt build. Luego, el catálogo describe las tablas tal como estaban antes de la compilación.

Para obtener más información, consulta Comandos de trabajos y Segmentos de versiones en la documentación de dbt.

Descarga artefactos desde la consola de dbt Google Cloud

Para descargar manualmente artefactos de una ejecución completada en la consola de dbtGoogle Cloud , haz lo siguiente:

  1. En la consola de dbt Google Cloud , abre la ejecución del trabajo completada.
  2. Ve a la pestaña Artifacts para ver los archivos de artefactos generados.
  3. Descarga manifest.json, catalog.json, run_results.json y sources.json en un directorio local.
  4. En tu terminal local o en Cloud Shell, ejecuta el comando de importación gcloud que se describe en Configura la conectividad de dbt y establece --artifacts-path en el directorio que contiene los archivos descargados.

Para obtener más información, consulta Run visibility en la documentación de dbt.

Descarga artefactos con la CLI de la plataforma de dbt

La CLI de la plataforma de dbt (anteriormente, la CLI de dbt Cloud) ejecuta comandos de dbt en la plataforma de dbt Cloud desde tu terminal local y descarga automáticamente los artefactos generados en el directorio target/ de tu proyecto de dbt local.

  1. En tu terminal local, ve al directorio raíz de tu proyecto de dbt y ejecuta los tres comandos que se indican en requisitos previos de dbt.
  2. Ejecuta el comando de importación gcloud que se describe en Configura la conectividad de dbt y establece --artifacts-path en la raíz del proyecto o en el directorio target/.

La CLI se ejecuta en tu entorno de desarrollo con tus credenciales personales del almacén de datos, por lo que los metadatos generados reflejan tu esquema de desarrollo en lugar de las tablas de producción creadas por un trabajo programado. Usa la CLI para los flujos de trabajo de prueba o desarrollo, y usa un trabajo de implementación para las importaciones de producción programadas.

Para obtener más información, consulta Instala la CLI de la plataforma de dbt en la documentación de dbt.

Descarga artefactos con la API administrativa de dbt

Puedes usar la API administrativa de dbt para recuperar artefactos de forma programática desde cualquier ejecución de trabajo completada. El extremo List Run Artifacts devuelve las rutas de acceso a los archivos generados por una ejecución, y el extremo Retrieve Run Artifact descarga un archivo de artefacto específico desde la siguiente URL:

https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/RUN_ID/artifacts/FILE

ACCESS_URL depende de la región que aloja tu cuenta de dbt Cloud. Autentica solicitudes con un token de servicio de dbt Cloud. Para obtener más información, consulta las siguientes páginas de la documentación de dbt:

Desde tu terminal local, Cloud Shell o entorno de flujo de trabajo automatizado, descarga manifest.json, catalog.json, run_results.json y sources.json en un directorio local o un bucket de Cloud Storage y, luego, ejecuta el comando gcloud que se describe en Configura la conectividad de dbt en esa ruta de acceso.

De forma predeterminada, el extremo de artefactos devuelve artefactos del paso final de la ejecución, a menos que especifiques el parámetro de consulta step. Cuando configuras el trabajo como se describe en Configura el trabajo de dbt Cloud, el paso final es dbt parse --write-catalog o dbt docs generate --no-compile, que solo escribe catalog.json y deja los otros tres artefactos intactos en el paso predeterminado.

Recupera el ID de ejecución

Para descargar los artefactos de una ejecución específica, necesitas su ID. Puedes copiar el ID de ejecución de la URL de ejecución en la consola de dbt Google Cloud o consultar la API desde tu terminal o secuencia de comandos de flujo de trabajo para obtener la ejecución exitosa más reciente de un trabajo:

GET https://ACCESS_URL/api/v2/accounts/ACCOUNT_ID/runs/?job_definition_id=JOB_ID&status=10&order_by=-finished_at&limit=1

En los parámetros de consulta, status=10 filtra las ejecuciones completadas con un estado Success. Puedes sondear este extremo según un programa para identificar la ejecución exitosa más reciente, descargar sus artefactos y ejecutar el comando de importación gcloud.

Activa la importación con un webhook

En lugar de sondear la API, puedes configurar un webhook de dbt Cloud para activar una importación de metadatos automatizada cada vez que finalice una ejecución de trabajo. El webhook envía una carga útil a un extremo HTTP que proporcionas:

  1. En la consola de dbt Google Cloud , ve a Configuración de la cuenta > Webhooks y haz clic en Crear webhook (o Crear webhook nuevo). Configura la suscripción al webhook:
    • Eventos: Selecciona Ejecución completada (job.run.completed), que se activa solo después de que finaliza la ejecución y sus artefactos están disponibles para su descarga.
    • Trabajos: Selecciona los trabajos de implementación de dbt Cloud que deseas supervisar.
    • Endpoint: Ingresa la URL HTTPS de un servicio que ejecutes (por ejemplo, un servicio o una función de Cloud Run).
  2. Guarda el token secreto del webhook que muestra dbt Cloud. Tu servicio usa este secreto para verificar el encabezado Authorization, que contiene una firma HMAC-SHA256 del cuerpo de la solicitud.
  3. En tu servicio, lee data.runId desde la carga útil de JSON, descarga los artefactos de la ejecución con la API administrativa, como se describió anteriormente, y ejecuta el comando gcloud alpha dataplex dbt metadata-jobs create.

Cuando implementes tu controlador de webhook, ten en cuenta lo siguiente:

  • dbt Cloud espera una respuesta durante un máximo de 10 segundos. Dado que la importación de metadatos tarda varios minutos, primero devuelve una respuesta HTTP y ejecuta la importación en segundo plano (por ejemplo, como un trabajo de Cloud Run o con la marca --async).
  • job.run.completed también se activa para las ejecuciones fallidas, por lo que las ejecuciones con pruebas fallidas se siguen importando. No te suscribas a job.run.errored, ya que se puede activar antes de que estén disponibles los artefactos de la ejecución.

Para obtener más información sobre las cargas útiles de webhook y la verificación de firmas, consulta Webhooks for your jobs en la documentación de dbt.

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, no se emite ningún vínculo de entrada y un aspecto cuyo artefacto de dbt estuvo ausente 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.
    • --include-entry-links: Emite vínculos de entrada para las relaciones de dbt. Esta opción está habilitada de forma predeterminada. Para inhabilitarlo, usa --no-include-entry-links. El comando emite los siguientes tipos de vínculos de entrada:
      • reference: Un recurso depende de otro, lo describe o lo usa. Esto abarca las dependencias de dbt entre los nodos, una prueba y el recurso que prueba, un modelo semántico o una métrica y el recurso en el que se basa, un nodo y las macros del proyecto que llama, y un nodo y la tabla de BigQuery en la que se materializa.
      • schema-join: Son las columnas combinables declaradas por una prueba relationships de dbt.
    • --skip-bigquery-link: Omite las vinculaciones de reference (nodo de dbt → tabla física de BigQuery). De forma predeterminada, se emite un vínculo reference para cada nodo materializado de dbt (modelo, seed, instantánea) cuyo conjunto de datos de BigQuery se encuentra en la ubicación de importación (--location). Las fuentes de dbt no reciben un vínculo reference a su tabla de BigQuery. Los vínculos de entrada solo pueden hacer referencia a entradas de @bigquery en la misma región, por lo que los conjuntos de datos de otra región se omiten automáticamente. Para determinar la región de cada conjunto de datos, el comando llama a la API de BigQuery, por lo que la persona que llama necesita el permiso bigquery.datasets.get en esos conjuntos de datos. Sin él, el comando no puede omitir conjuntos de datos en otras regiones y los vínculos a ellos no se resuelven. Cuando las tablas de BigQuery no estén catalogadas en Knowledge Catalog, usa --skip-bigquery-link.
    • --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.
  • Las dependencias de dbt cambian, por ejemplo, cuando se agrega o quita una llamada a ref(), source(), una prueba o una macro. Las ejecuciones de --aspects-only no crean ni actualizan vínculos de entrada.
  • Cambias --include-entry-links o --skip-bigquery-link.

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 enumerar los vínculos de entrada de una entrada de dbt, llama al método projects.locations:lookupEntryLinks. Por ejemplo, para recuperar la tabla de BigQuery en la que se materializa un modelo de dbt, haz lo siguiente:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntryLinks?entry=ENTRY_NAME&entryMode=SOURCE&entryLinkTypes=projects/dataplex-types/locations/global/entryLinkTypes/reference"

ENTRY_NAME es el nombre completo del recurso de la entrada de dbt. Los resultados se paginan, con un máximo de 10 vínculos por página.

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.

¿Qué sigue?