Administra recursos con Knowledge Catalog

En este documento, se explica cómo buscar y administrar tus recursos de Spanner con Knowledge Catalog.

Knowledge Catalog cataloga los metadatos sobre las instancias, las bases de datos, las tablas, las columnas y las vistas de Spanner en Google Cloud, lo que permite que los agentes de IA y las herramientas de análisis recuperen contexto fundamentado y pertinente.

Acerca de Knowledge Catalog y Spanner

Knowledge Catalog se refiere a los recursos en Spanner y en otros servicios de Google Cloud como recursos. En Knowledge Catalog, cada recurso de Spanner, como una instancia, una base de datos, una tabla o una vista, se representa con una entrada de catálogo que almacena metadatos técnicos y empresariales (aspectos) sobre el recurso.

Puedes usar Knowledge Catalog en los siguientes flujos de trabajo para descubrir y comprender tus recursos de Spanner:

  • Análisis: Comprende las dependencias entre los recursos de datos y evalúa la idoneidad de los recursos para casos de uso específicos.
  • Administración de cambios: Realiza un seguimiento de las modificaciones estructurales en las bases de datos.
  • Movimiento de datos: Realiza un seguimiento de los orígenes y destinos de las canalizaciones.
  • Evolución del esquema: Supervisa las definiciones de tablas y columnas a lo largo del tiempo.
  • Fundamentación de IA contextual: Proporciona un esquema y un contexto empresarial a los agentes de IA.

Knowledge Catalog cataloga automáticamente los siguientes metadatos para los recursos de Spanner:

  • Nombre del recurso y nombre completamente calificado (FQN)
  • Ubicación (región)
  • Marcas de tiempo de creación y última modificación
  • Definiciones de esquemas (para tablas y vistas)
  • Tipos de datos de columnas, nulabilidad e indicadores de clave primaria
  • Descripciones y etiquetas de usuarios

El descubrimiento de metadatos de Knowledge Catalog es un proceso automatizado que analiza las fuentes de datos conectadas, como Spanner, para identificar los recursos de datos, como tablas, vistas y bases de datos. Luego, Knowledge Catalog extrae metadatos técnicos de los recursos, como esquemas, descripciones y ubicaciones.

Spanner sincroniza los metadatos con Knowledge Catalog a intervalos regulares, por lo general, cada seis horas, por lo que los cambios de metadatos realizados en los recursos de Spanner pueden tardar aproximadamente seis horas en propagarse.

Antes de comenzar

Antes de usar Knowledge Catalog con Spanner, completa las siguientes tareas de configuración:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Habilita la API de Dataplex para el proyecto.

    Habilitar la API de Dataplex

Roles obligatorios

Para obtener los permisos que necesitas para administrar los recursos de Spanner en Knowledge Catalog, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para administrar los recursos de Spanner en Knowledge Catalog. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para administrar los recursos de Spanner en Knowledge Catalog:

  • Crea un tipo de aspecto: dataplex.aspectTypes.create
  • Busca instancias de Spanner:
    • dataplex.projects.search
    • spanner.instances.get
  • Busca bases de datos, tablas y vistas de Spanner:
    • dataplex.projects.search
    • spanner.databases.get
  • Visualiza aspectos en las instancias de Spanner:
    • dataplex.aspectTypes.get
    • spanner.instances.get
  • Visualiza aspectos en las bases de datos, las tablas y las vistas de Spanner:
    • dataplex.aspectTypes.get
    • spanner.databases.get
  • Adjunta un aspecto a un recurso de Spanner con un tipo de aspecto:
    • dataplex.aspectTypes.use
    • dataplex.entries.update

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Knowledge Catalog admite la búsqueda semántica, que te ayuda a encontrar recursos con lenguaje cotidiano, lo que elimina la necesidad de una sintaxis de búsqueda compleja. Por ejemplo, ingresa una consulta como List all Spanner tables related to sales.

Si lo prefieres, puedes buscar recursos con palabras clave específicas, filtros y una sintaxis de búsqueda basada en predicados.

Para buscar recursos de Spanner en Knowledge Catalog, sigue estos pasos:

  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, en Sistemas, selecciona Spanner.

    Knowledge Catalog muestra todos los recursos de Spanner a los que tienes acceso en tus proyectos de Google Cloud .

  3. Usa el campo de búsqueda para ingresar una consulta en lenguaje natural, como List all Spanner tables related to sales.

  4. Opcional: Usa la búsqueda filtrada en la página Buscar. Selecciona filtros en Tipo, Proyectos, Ubicaciones y Tipos de aspectos.

  5. Opcional: En el campo de búsqueda, agrega un parámetro de búsqueda después de system=spanner. Separa varios parámetros con espacios o usa paréntesis y los operadores lógicos AND, OR y NOT.

    Por ejemplo, para ver solo las bases de datos, ingresa la siguiente consulta:

    system=spanner type=database

    También puedes usar type=service para buscar instancias o instance_config=CONFIGURATION_NAME para buscar una configuración de instancia.

    Para obtener más opciones de consulta, consulta Sintaxis de búsqueda para Knowledge Catalog.

  6. En la lista de resultados de la búsqueda, haz clic en el nombre de un recurso para abrir su página de detalles de la entrada en Knowledge Catalog.

En la página de detalles de la entrada, puedes hacer lo siguiente:

  • Para ver los resúmenes de los recursos y agregar una descripción, ve a la pestaña Detalles y, luego, en la sección Descripción general, haz clic en Agregar.
  • Para ver o adjuntar metadatos empresariales y operativos, ve a la pestaña Detalles y, luego, en la sección Aspectos, haz clic en Agregar junto a Aspectos opcionales.
  • Para ver las bases de datos de miembros de una instancia, haz clic en la pestaña Lista de entradas y, luego, en Mostrar todas las entradas secundarias en la búsqueda.
  • Para inspeccionar los tipos de datos, las claves y las definiciones de las columnas de una tabla, haz clic en la pestaña Esquema.

Caso de uso: Desglosa de instancia a columnas

En este caso de uso, buscas una instancia de Spanner y, luego, desglosas una de las bases de datos que se enumeran en la instancia para ver sus tablas y columnas.

  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, en Sistemas, selecciona Spanner.

  3. Para ver todas las instancias de Spanner en Knowledge Catalog, usa el campo de búsqueda para ingresar una consulta en lenguaje natural, como List all Spanner instances, y presiona Enter.

  4. Selecciona un nombre de la instancia.

  5. En la página Detalles de Spanner, haz clic en la pestaña Lista de entradas y, luego, en Mostrar todas las entradas secundarias en la búsqueda.

    Knowledge Catalog muestra las bases de datos en la instancia. Si no hay una pestaña Lista de entradas, regresa a la página Buscar y elige una instancia diferente.

  6. Selecciona un nombre de base de datos. En la página Detalles de la base de datos de Spanner, haz clic en la pestaña Lista de entradas y, luego, en Mostrar todas las entradas secundarias en la búsqueda.

    Knowledge Catalog muestra las tablas en la base de datos.

  7. Selecciona un nombre de tabla y, luego, en la página Detalles de la tabla de Spanner, haz clic en Esquema para ver las columnas de la tabla.

  8. Opcional: Para agregar un aspecto a una columna, selecciona la columna y haz clic en Agregar aspecto.

Enriquece los metadatos con aspectos

Para enriquecer los metadatos y buscar recursos por contexto personalizado, puedes crear aspectos basados en tipos de aspectos (plantillas reutilizables) y adjuntarlos a tus recursos de Spanner. Los aspectos te permiten agregar metadatos empresariales estructurados, como la propiedad de los datos, las clasificaciones de administración o las políticas de retención.

Por ejemplo, puedes adjuntar el siguiente aspecto a una columna que contiene un número de seguridad social, que es información de identificación personal (PII):

pii:true
pii_type:SSN

Para adjuntar un aspecto a un recurso de Spanner, sigue estos pasos:

  1. En la página Búsqueda de Knowledge Catalog, haz clic en el recurso que deseas enriquecer.
  2. En la página de detalles de la entrada, en la pestaña Detalles, ve a la sección Aspectos.
  3. Junto a Aspectos opcionales, haz clic en Agregar.
  4. Busca y selecciona el tipo de aspecto que deseas agregar, como un esquema personalizado para la administración de datos o la privacidad.
  5. En la ventana Agregar aspecto, especifica los campos de aspecto obligatorios.
  6. Haz clic en Guardar.

Para obtener instrucciones detalladas sobre cómo crear tipos de aspectos y administrarlos, consulta Administra aspectos y enriquece los metadatos.

Importa y exporta aspectos

Cuando mueves una instancia de Spanner a una configuración de instancia diferente, el proceso borra las entradas y los aspectos asociados con la configuración de la instancia de origen en Knowledge Catalog. Para conservar tus aspectos personalizados, debes hacer lo siguiente:

  1. Exporta los aspectos asociados con las entradas en la configuración de la instancia de origen.
  2. Mueve la instancia a la configuración de la instancia de destino.
  3. Importa los aspectos a la configuración de la instancia de destino.

Exporta aspectos de la configuración de la instancia de origen

Antes de mover la instancia, recupera los aspectos de tus entradas de Spanner en la configuración de la instancia de origen con la Google Cloud CLI, la API de Dataplex o un trabajo de exportación de metadatos:

gcloud

Para recuperar los aspectos de una entrada de Spanner en el grupo de entradas del sistema @spanner, usa el comando gcloud dataplex entries lookup:

gcloud dataplex entries lookup SOURCE_ENTRY_ID \
  --entry-group=@spanner \
  --location=LOCATION \
  --project=PROJECT_ID \
  --view=all

Reemplaza lo siguiente:

  • SOURCE_ENTRY_ID: Es el ID de entrada del recurso de Spanner en la configuración de la instancia de origen.

    Cómo encontrar el ID de entrada

    Para encontrar el nombre de la entrada o traducir un nombre completamente calificado (FQN), como spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID, usa el comando gcloud dataplex entries search.

  • LOCATION: Es la región de la configuración de la instancia de Spanner, como us-central1.

  • PROJECT_ID: Es el ID del proyecto de Google Cloud que contiene la instancia de Spanner.

API de REST

Para recuperar los aspectos de una entrada de Spanner en el grupo de entradas del sistema @spanner, envía una solicitud GET al extremo projects.locations.lookupEntry.

curl -X GET \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntry?entry=projects/PROJECT_ID/locations/LOCATION/entryGroups/@spanner/entries/SOURCE_ENTRY_ID&view=ALL"

Reemplaza lo siguiente:

  • ACCESS_TOKEN: Es el token de acceso que usa tu aplicación para autenticarse en el servicio. Por ejemplo, usa $(gcloud auth print-access-token).

  • PROJECT_ID: Es el ID del proyecto de Google Cloud que contiene la instancia de Spanner.

  • LOCATION: Es la región de la configuración de la instancia de Spanner, como us-central1.

  • SOURCE_ENTRY_ID: Es el ID de entrada del recurso de Spanner en la configuración de la instancia de origen.

    Cómo encontrar el ID de entrada

    Para encontrar el nombre de la entrada o traducir un nombre completamente calificado (FQN), como spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID, usa el comando gcloud dataplex entries search.

Trabajo de exportación

Para exportar metadatos de varias entradas en un lote a Cloud Storage, ejecuta un trabajo de exportación de metadatos.

Mueve la instancia a la configuración de la instancia de destino

Antes de importar aspectos a la configuración de la instancia de destino, haz lo siguiente:

  1. Mueve la instancia de Spanner a la configuración de la instancia de destino. Espera a que los metadatos de Spanner de la instancia trasladada se sincronicen con Knowledge Catalog, lo que puede tardar aproximadamente seis horas.

  2. Para verificar que se haya completado la sincronización, busca la instancia que se movió con uno de los siguientes métodos:

    • En la página Búsqueda de Knowledge Catalog, ingresa la siguiente consulta:

      system=spanner instance_config=DESTINATION_CONFIG_NAME

    • Ejecuta el comando gcloud dataplex entries search:

      gcloud dataplex entries search "fqn=spanner:PROJECT_ID.DESTINATION_CONFIG_ID.INSTANCE_ID" \
    --project=PROJECT_ID

    Cuando el comando devuelva la entrada para la configuración de la instancia de destino, la sincronización se habrá completado.

Importa aspectos a la configuración de la instancia de destino

Después de que se sincronicen los metadatos, adjunta los aspectos copiados a las entradas en la configuración de la instancia de destino:

gcloud

Para adjuntar los aspectos copiados a la entrada en la configuración de la instancia de destino, usa el comando gcloud dataplex entries update-aspects:

gcloud dataplex entries update-aspects DESTINATION_ENTRY_ID \
  --entry-group=@spanner \
  --location=DESTINATION_LOCATION \
  --project=PROJECT_ID \
  --aspects=ASPECTS_FILE

Reemplaza lo siguiente:

  • DESTINATION_ENTRY_ID: Es el ID de entrada del recurso de Spanner movido en la configuración de la instancia de destino.

  • DESTINATION_LOCATION: Es la región de la configuración de la instancia de Spanner de destino, como us-central1.

  • PROJECT_ID: Es el ID del proyecto de Google Cloud que contiene la instancia de Spanner.

  • ASPECTS_FILE: Es la ruta de acceso a un archivo JSON o YAML que contiene los aspectos que se agregarán o actualizarán.

API de REST

Para adjuntar los aspectos exportados a la entrada en la configuración de la instancia de destino, usa el método de la API de REST projects.locations.entryGroups.entries.patch, como se muestra en el siguiente ejemplo:

curl -X PATCH \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"aspects":{"ASPECT_KEY":{"data":{"FIELD_NAME":"FIELD_VALUE"}}}}' \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/DESTINATION_LOCATION/entryGroups/@spanner/entries/DESTINATION_ENTRY_ID?updateMask=aspects"

Reemplaza lo siguiente:

  • ACCESS_TOKEN: Es el token de acceso que usa tu aplicación para autenticarse en el servicio. Por ejemplo, usa $(gcloud auth print-access-token).

  • ASPECT_KEY: Es la clave del aspecto en el formato PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID para un aspecto de nivel de entrada o PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID@Schema.COLUMN_NAME para un aspecto de nivel de columna.

  • FIELD_NAME y FIELD_VALUE: el nombre y el valor del campo definidos por tu tipo de aspecto.

  • PROJECT_ID: Es el ID del proyecto que contiene la instancia de Spanner.

  • DESTINATION_LOCATION: Es la región de la configuración de la instancia de Spanner de destino, como us-central1.

  • DESTINATION_ENTRY_ID: Es el ID de entrada del recurso de Spanner movido en la configuración de la instancia de destino.

Trabajo de importación

Para importar aspectos de varias entradas por lotes desde Cloud Storage, ejecuta un trabajo de importación de metadatos.

¿Qué sigue?