Administra los metadatos de los lakes, las zonas y los recursos

En esta guía, se describen los metadatos de Knowledge Catalog (antes Dataplex Universal Catalog) para lakes, zonas y recursos, y cómo puedes usar la API de Dataplex para administrarlos.

Descripción general

Knowledge Catalog analiza lo siguiente:

  • Recursos de datos estructurados y semiestructurados en data lakes para extraer metadatos de tablas en entidades de tablas
  • Datos no estructurados, como imágenes y textos, para extraer metadatos de conjuntos de archivos en entidades de conjuntos de archivos

Puedes usar la API de Dataplex Metadata para hacer lo siguiente:

  • Ver, editar y borrar metadatos de entidades de tablas y conjuntos de archivos
  • Crear tus propios metadatos de entidades de tablas o conjuntos de archivos

Puedes analizar los metadatos de Knowledge Catalog con lo siguiente:

  • Data Catalog (obsoleto) para buscar y etiquetar
  • Dataproc Metastore y BigQuery para consultar metadatos de tablas y procesar estadísticas

API de Dataplex

En esta sección, se resumen los recursos de lake, zona y recurso en la API de Dataplex y los recursos clave con ellos.

API del plano de control

La API del plano de control de Dataplex permite la creación y administración de los recursos de lake, zona y recurso.

  • Lake: Es una instancia de servicio de Knowledge Catalog que permite administrar recursos de almacenamiento en proyectos dentro de una organización.

  • Zona: Es una agrupación lógica de recursos dentro de un lake. Usa varias zonas dentro de un lake para organizar los datos según la preparación, la carga de trabajo o la estructura de la organización.

  • Recursos: Son recursos de almacenamiento, con datos almacenados en buckets de Cloud Storage o conjuntos de datos de BigQuery, que se adjuntan a una zona dentro de un lake.

API de Metadata

Usa la API de Dataplex Metadata para crear y administrar metadatos dentro de entidades de tablas y conjuntos de archivos, y particiones. Knowledge Catalog analiza los recursos de datos, ya sea en un lake o proporcionados por ti, para crear entidades y particiones. Las entidades y las particiones mantienen referencias a los recursos asociados y las ubicaciones de almacenamiento físico.

Conceptos clave

Entidad de tabla:

Metadatos para datos estructurados con esquemas bien definidos. Las entidades de tablas se identifican de forma exclusiva por el ID de entidad y la ubicación de los datos. Los metadatos de las entidades de tablas se pueden consultar en BigQuery y Dataproc Metastore:

  • Objetos de Cloud Storage: Metadatos para objetos de Cloud Storage, a los que se accede a través de las APIs de Cloud Storage.
  • Tablas de BigQuery: Metadatos para tablas de BigQuery, a los que se accede a través de las APIs de BigQuery.
Entidad de conjunto de archivos:

Metadatos sobre datos no estructurados, por lo general, sin esquema. Los conjuntos de archivos se identifican de forma exclusiva por el ID de entidad y la ubicación de los datos. Cada conjunto de archivos tiene un formato de datos.

Particiones:

Metadatos para un subconjunto de datos dentro de una entidad de tabla o conjunto de archivos, identificados por un conjunto de pares clave-valor y una ubicación de datos.

Prueba la API

Usa las páginas de documentación de referencia de la API de Knowledge Catalog lakes.zones.entities y lakes.zones.partitions para ver los parámetros y campos asociados con cada API. Usa el panel Prueba esta API que acompaña la documentación de referencia de cada método de la API para realizar solicitudes a la API con diferentes parámetros y campos. Puedes construir, ver y enviar tus solicitudes sin necesidad de generar credenciales y, luego, ver las respuestas que muestra el servicio.

En las siguientes secciones, se proporciona información para ayudarte a comprender y usar las APIs de Knowledge Catalog Metadata.

Entidades

Enumerar entidades

Para limitar la lista de entidades que muestra el servicio, agrega filter parámetros de búsqueda a la URL de solicitud list entities.

Obtener entidades

De forma predeterminada, la respuesta Get Entity contiene metadatos básicos de la entidad. Para recuperar metadatos de esquema adicionales, agrega el view parámetro de búsqueda a la URL de solicitud.

Detalles de compatibilidad: Si bien los metadatos de Knowledge Catalog se registran de forma centralizada en la API de Metadata, solo los metadatos de la tabla de entidades que son compatibles con BigQuery y Apache Hive Metastore se publican en BigQuery y Dataproc Metastore. La API de Get Entity muestra un CompatibilityStatus mensaje, que indica si los metadatos de la tabla son compatibles con BigQuery y Hive Metastore, y si no lo son, el motivo de la incompatibilidad.

Actualizar entidad

Usa esta API para editar los metadatos de la entidad, incluso si tú o Knowledge Catalog administrarán los metadatos de la entidad.

  • Esta API realiza un reemplazo completo de todos los mutables campos de entidad. Los siguientes campos de entidad son inmutables y, si los especificas en una solicitud de actualización, se ignorarán:
  • Especifica un valor para todos los campos de entidad mutables, incluidos todos los campos de esquema, incluso si los valores no se cambian.
  • Proporciona el campo etag. Para obtener el etag, primero debes enviar una entities.get, que muestra el etag de la entidad en la respuesta.
  • Actualiza los campos de esquema: Puedes actualizar el esquema de la tabla que descubrió Knowledge Catalog para mejorar su precisión:
    • Si el esquema es un conjunto de archivos, deja todos los campos de esquema vacíos.
    • Para definir un campo repetido, establece el modo en REPEATED. Para definir un campo de struct, establece el tipo en RECORD.
    • Puedes establecer el userManaged campo del esquema para especificar si tú o Knowledge Catalog administran los metadatos de la tabla. La configuración predeterminada es Knowledge Catalog administrado. Si userManaged se establece en verdadero, esta configuración se incluye en la información que se muestra de una solicitud entities.get si EntityView se establece en SCHEMA o FULL.
  • Actualiza los campos de partición:
    • Para los datos particionados que no son de estilo Hive, Knowledge Catalog Discovery genera automáticamente claves de partición. Por ejemplo, para la ruta de acceso de datos gs://root/2020/12/31, se generan las claves de partición p0, p1 y p2. Para que las consultas sean más intuitivas, puedes actualizar p0, p1 y p2 a year, month y day, respectivamente.
    • Si actualizas el estilo de partición a estilo HIVE, el campo de partición es inmutable.
  • Actualiza otros campos de metadatos: Puedes actualizar los campos mimeType, CompressionFormat, CsvOptions y JsonOptions generados automáticamente para ayudar al descubrimiento de Knowledge Catalog. Knowledge Catalog Discovery usará valores nuevos en su próxima ejecución.

Crear entidad

Usa la API de entities.create para crear entidades de metadatos de tablas o conjuntos de archivos. Propaga los campos obligatorios y los campos opcionales pertinentes, o permite que el servicio de descubrimiento de Knowledge Catalog complete los campos opcionales.

Borrar entidad

  • Proporciona el campo etag. Para obtener el etag, primero debes enviar una entities.get, que muestra el etag de la entidad en la respuesta.

Si se borran los datos subyacentes de una tabla o un conjunto de archivos en una zona sin procesar, los metadatos de la tabla o el conjunto de archivos se borran automáticamente en el siguiente análisis de Discovery. Si se borran los datos subyacentes de una tabla en una zona seleccionada, los metadatos de la tabla no se borran de forma correspondiente, sino que se informa una acción de datos faltantes. Para resolver este problema, borra explícitamente la entidad de metadatos de la tabla a través de la API de Metadata.

Particiones

Enumerar particiones

Para limitar la lista de particiones que muestra el servicio, agrega filter parámetros de búsqueda a la URL de solicitud list partitions.

Ejemplos:

  • ?filter="Country=US AND State=CA AND City=Sunnyvale"
  • ?filter="year < 2000 AND month > 12 AND Date > 10"

Obtener partición

Para obtener una partición, debes completar la URL de solicitud agregando los valores de la clave de partición al final de la URL, con el formato partitions/value1/value2/…./value10.

Ejemplo: Si una partición tiene valores, {Country=US, State=CA, City=Sunnyvale}, la URL de solicitud get debe terminar con /partitions/US/CA/Sunnyvale.

Importante: Los valores de URL agregados deben estar codificados dos veces. Por ejemplo, se puede usar url_encode(url_encode(value)) para codificar "US:CA/CA#Sunnyvale" de modo que la URL de solicitud termine con /partitions/US%253ACA/CA%2523Sunnyvale. El campo de nombre en la respuesta conserva el formato codificado.

Crear una partición

Para crear una partición personalizada para tu fuente de datos, usa la API de partitions.create. Especifica el campo de ubicación obligatorio con una ruta de acceso de Cloud Storage.

Borra una partición

Completa la URL de solicitud agregando los valores de la clave de partición al final de la URL de solicitud, con el formato partitions/value1/value2/…./value10.

Ejemplo: Si una partición tiene valores, {Country=US, State=CA, City=Sunnyvale}, la URL de solicitud debe terminar con /partitions/US/CA/Sunnyvale.

Importante: Los valores de URL agregados deben cumplir con RFC-1034 o deben estar codificados dos veces, por ejemplo, US:/CA#/Sunnyvale como US%3A/CA%3A/Sunnyvale.

¿Qué sigue?