Importa metadatos de dbt Core

Knowledge Catalog (anteriormente, Dataplex Universal Catalog) te permite importar metadatos operativos, semánticos y de linaje de dbt Core, dbt Cloud y MetricFlow con Google Cloud CLI y tus archivos de artefactos de dbt. En lugar de dejar los metadatos de transformación aislados en el ecosistema de dbt, puedes centralizarlos para ayudar a los ingenieros de datos, los ingenieros de análisis y los administradores de datos a descubrir y administrar los datos empresariales.

Metadatos importados y casos de uso

Debido a 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 admite diferentes casos de uso. Importas metadatos de Oracle o PostgreSQL para responder "¿Qué datos sin procesar tenemos?" y, luego, importas metadatos de dbt Core para responder "¿Cómo se transforman nuestros datos, son confiables y qué significan para la empresa?".

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

  • Metadatos técnicos: Descubre datos empresariales explorando recursos clave (fuentes, seeds, modelos) y sus propiedades técnicas (nombres de columnas, tipos de datos, recuentos de filas).
  • Metadatos empresariales y semánticos: Proporcionan contexto para las herramientas de IE y los agentes de IA, ya que exploran las definiciones y la lógica empresariales con la tecnología de dbt MetricFlow, como los modelos semánticos, las métricas y las consultas guardadas.
  • Metadatos de calidad de los datos y operativos: Supervisa el estado de la canalización y soluciona problemas de datos explorando los metadatos de ejecución, como el tiempo, el estado de éxito o falla, la actualidad de los datos y los resultados de las pruebas.
  • Metadatos de linaje y relación: Realiza análisis de impacto descendente y seguimiento de la causa raíz explorando grafos de transformación (DAG) y dependencias entre recursos de dbt, linaje físico que hace un seguimiento y vincula bloques de transformación física, claves de unión y uniones dinámicas, y relaciones de superior-secundario.
  • Metadatos de consumo: Soluciona problemas relacionados con la forma en que las aplicaciones descendentes consumen datos transformados explorando los metadatos capturados en exposiciones que asignan cómo se usan los datos fuera de dbt.

Limitaciones

  • Admite dbt Core v1 (validado con 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 Knowledge Catalog. Para instalar o actualizar la CLI, consulta Instala Google Cloud CLI.
  • No hay una 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 ejecuciones de dbt Cloud.
  • Los esquemas muy grandes o con un nivel de anidamiento profundo se truncan: un solo aspecto no puede superar el límite de tamaño por aspecto, por lo que los esquemas con un nivel de anidamiento profundo pueden perder campos finales.
  • --aspects-only puede agregar y actualizar metadatos, pero no puede quitarlos. Borrar un recurso de dbt requiere una ejecución completa.
  • Esta integración solo admite eventos de linaje de dbt en recursos de BigQuery en la API de Data Lineage y el gráfico. Las entradas de dbt (fuentes, seeds y 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 Dataplex.
  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 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:

Si tienes los permisos necesarios para administrar el acceso de 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 de 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: Es 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

Habilitar la API de Dataplex

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 de forma correcta sin ellos:

  • manifest.json (obligatorio): Es la estructura principal del proyecto y el gráfico de ejecución. También contiene los modelos semánticos, las métricas y las consultas guardadas de MetricFlow.
  • catalog.json: Son los nombres de las columnas y los 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 en 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 de Cloud Storage distintas que tienen propósitos diferentes y no deben confundirse:

  • Entrada (artefactos de origen de dbt): Es donde residen los archivos JSON de dbt generados. Puede ser una ruta de 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. El emisor 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 etapa de pruebas de importación de Knowledge Catalog): Es un prefijo de URI del 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 transformado (dbt_metadata.jsonl) y desde el que lee el trabajo de importación de Knowledge Catalog durante la transferencia. Debes proporcionar este URI con la marca --storage-uri. El emisor 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. Debido a que un trabajo de dbt Cloud genera los mismos archivos de artefactos que dbt Core, puedes importar metadatos de 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 de artefactos completo. 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 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:
    • Para los segmentos de dbt Core 2.x y dbt Fusion: agrega dbt parse --write-catalog como un comando de trabajo.
    • Para los segmentos de dbt Core 1.x: agrega dbt docs generate --no-compile como un comando de trabajo en lugar de seleccionar la opción Generar documentos en la ejecución. La casilla de verificación Generar documentos en la ejecución ejecuta dbt docs generate sin --no-compile, lo que reemplaza los resultados de la prueba de dbt build, como se describe en Requisitos previos de dbt. Ten en cuenta que, si falla un paso de comando, el trabajo también falla, mientras que el paso de casilla de verificación no hace que falle el trabajo.

Si dbt build falla, por ejemplo, porque falla una prueba, dbt Cloud omite los comandos que se encuentran después de él y la ejecución no tiene catalog.json. Para producir siempre uno, agrega el comando catalog 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 de la consola de dbt Google Cloud

Para descargar artefactos de forma manual desde una ejecución completada en la consola de Google 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 Artefactos 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 descrito 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 Visibilidad de la ejecución en la documentación de dbt.

Descarga artefactos con la CLI de la plataforma de dbt

La CLI de la plataforma de dbt (antes, 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 los 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 de almacenamiento 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 de administración de dbt

Puedes usar la API de administración de dbt para recuperar artefactos de manera programática desde cualquier ejecución de trabajo completada. El extremo List Run Artifacts devuelve las rutas de acceso de los archivos generadas por una ejecución, y el extremo Retrieve Run Artifact descarga un archivo de artefacto específico de 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 las 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 el 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 artefacto 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 de ejecución. 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 de forma programada para identificar la última ejecución correcta, descargar sus artefactos y ejecutar el comando de importación de 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 la ejecución de un 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.
    • Extremo: Ingresa la URL HTTPS de un servicio que ejecutes (por ejemplo, un servicio de Cloud Run 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 de la carga útil de JSON, descarga los artefactos de la ejecución con la API de administración como se describió antes y ejecuta el comando gcloud dataplex dbt metadata-jobs create.

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

  • dbt Cloud espera un máximo de 10 segundos para obtener una respuesta. Debido a 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 con errores, por lo que se siguen importando las ejecuciones con pruebas con errores. No te suscribas a job.run.errored, ya que puede activarse 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 para tus trabajos 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 se puede acceder a ellos, el proceso de importación realiza las siguientes acciones:

  1. Lee 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. Transforma los metadatos: Transforma el contenido en el 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 transformado a la ubicación de Cloud Storage de etapa de pruebas de salida especificada en --storage-uri.
  4. Activa el trabajo de importación: Activa un trabajo de importación de metadatos de Knowledge Catalog que indique al agente de servicio de Knowledge Catalog que lea y transfiera los metadatos almacenados en etapa intermedia 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 Conectores, selecciona la tarjeta dbt Core y MetricFlow.

  4. Para ver tus recursos de dbt importados, ve a la página Búsqueda o consulta la página Grupos de entradas 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 un bucket de Cloud Storage de etapa de pruebas de salida configurado con los permisos adecuados para el emisor y el agente de servicio de Knowledge Catalog.

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

    gcloud 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: Es el prefijo del URI de Cloud Storage (salida/etapa de pruebas) (gs://bucket/path/) al que se sube el JSONL transformado y desde el que lee el trabajo de importación durante la transferencia. El emisor 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 emisor debe tener acceso de lectura (roles/storage.objectViewer o roles/storage.objectAdmin) al bucket de entrada.
    • --async: Se muestra de inmediato, sin necesidad de 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 cambia de nivel superior ninguna entrada, no se emite ningún vínculo de entrada y un aspecto cuyo artefacto de dbt estuvo ausente de esta ejecución conserva el valor que le dio una ejecución anterior. Usa esta opción para la transferencia rutinaria y repetida. Consulta Vuelve 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 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 que se pueden unir declaradas por una prueba de dbt relationships.
    • --skip-bigquery-link: Omite los vínculos reference (nodo de dbt → tabla de BigQuery física). De forma predeterminada, se emite un vínculo reference para cada nodo de dbt materializado (modelo, origen, 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 esa 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 el emisor 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 archivo JSON, y valida el trabajo de metadatos, pero no realices la transferencia.

  4. Confirma que recibiste el estado Creado.

REST

Para importar metadatos de dbt con la API de REST, sigue estos pasos:

  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 etapa de pruebas de Cloud Storage (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 de 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 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 entradas, por lo que es seguro ejecutarlo de forma repetida, en cualquier programa y desde más de un trabajo.

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

  • La primera transferencia a un grupo de entradas.
  • Se agrega, cambia de nombre o borra un recurso de dbt.
  • Cambia el nombre visible, la descripción o las etiquetas de una entrada.
  • Cambia la jerarquía de entradas.
  • Las dependencias de dbt cambian, por ejemplo, cuando se agrega o quita una llamada ref(), source(), de prueba o 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 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 realizar actualizaciones de rutina:

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

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

Busca y visualiza 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 por recursos de dbt:

    • En la sección Sistema, selecciona Contexto importado.
    • En el apartado Conectores administrados que aparece, selecciona dbt.

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

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

gcloud

  1. Para buscar entradas de dbt en todo 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 de 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 de dbt específicos, 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 de 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 Busca recursos en Knowledge Catalog. Para obtener más información sobre las expresiones y los filtros de consulta, consulta Sintaxis de búsqueda para Knowledge Catalog.

¿Qué sigue?