Metadatos de Dataplex

En esta guía, se describen los metadatos de Dataplex y cómo puedes usar las APIs de Dataplex para administrarlos.

Descripción general

Dataplex analiza lo siguiente:

  • Recursos de datos estructurados y semiestructurados dentro de 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 metadatos de Dataplex para hacer lo siguiente:

  • Cómo ver, editar y borrar metadatos de entidades de tablas y conjuntos de archivos
  • Crea tus propios metadatos de entidad de tabla o conjunto de archivos

Puedes analizar los metadatos de Dataplex con lo siguiente:

  • Data Catalog para la búsqueda y el etiquetado
  • Dataproc Metastore y BigQuery para consultar los metadatos de las tablas y procesar estadísticas

APIs de Dataplex

En esta sección, se resumen las APIs 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 activo.

  • Lago: Es una instancia de servicio de Dataplex 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 lago para organizar los datos en función de la preparación, la carga de trabajo o la estructura de la organización.

  • Recursos: 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 las entidades y particiones de tablas y conjuntos de archivos. Dataplex analiza los activos de datos, ya sea en un lake o que tú proporciones, para crear entidades y particiones. Las entidades y las particiones mantienen referencias a los activos asociados y a las ubicaciones de almacenamiento físicas.

Conceptos clave

Entidad de tabla:

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

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

Son metadatos sobre datos no estructurados, que suelen no tener esquemas. Los conjuntos de archivos se identifican de forma única por el ID de la entidad y la ubicación de los datos. Cada conjunto de archivos tiene un formato de datos.

Particiones:

Son los metadatos de un subconjunto de datos dentro de una entidad de tabla o conjunto de archivos, que se identifican con 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 las APIs de lakes.zones.entities y lakes.zones.partitions de Dataplex para ver los parámetros y campos asociados con cada API. Usa el panel Probar esta API que acompaña 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 crear, 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 metadatos de Dataplex.

Entidades

Cómo enumerar entidades

Para limitar la lista de entidades que muestra el servicio, agrega parámetros de consulta de filtro a la URL de solicitud list entities.

Cómo obtener una entidad

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

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

Cómo actualizar una entidad

Usa esta API para editar los metadatos de las entidades, incluido si tú o Dataplex los administrarán.

  • Esta API realiza un reemplazo completo de todos los campos mutables 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 del esquema, incluso si no se cambian los valores.
  • Proporciona el campo etag. Para obtener la etiqueta de estado, primero envía una solicitud entities.get, que muestra el etag de la entidad en la respuesta.
  • Actualización de campos de esquema: Puedes actualizar el esquema de tabla que descubrió Dataplex 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 configurar el campo userManaged del esquema para especificar si tú o Dataplex administras los metadatos de la tabla. La configuración predeterminada es administrada por Dataplex. Si userManaged se establece como verdadero, este parámetro de configuración se incluye en la información que se muestra de una solicitud entities.get si EntityView se establece en SCHEMA o FULL.
  • Actualización de campos de partición:
    • En el caso de los datos particionados sin estilo Hive, el descubrimiento de Dataplex genera automáticamente claves de partición. Por ejemplo, para la ruta de acceso a los 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 facilitar el descubrimiento de Dataplex. El descubrimiento de Dataplex 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. Completa los campos opcionales obligatorios y relevantes, o permite que el servicio de descubrimiento de Dataplex complete los campos opcionales.

Borrar entidad

  • Proporciona el campo etag. Para obtener la etiqueta de estado, primero envía una solicitud 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 de forma explícita la entidad de metadatos de la tabla a través de la API de metadatos.

Particiones

Cómo enumerar particiones

Para limitar la lista de particiones que muestra el servicio, agrega parámetros de consulta filter 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"

Cómo obtener una partición

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

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

Importante: Los valores de URL adjuntos deben estar codificados dos veces. Por ejemplo, url_encode(url_encode(value)) se puede usar 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 retiene 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 obligatorio de ubicación con una ruta de acceso de Cloud Storage.

Borra una partición

Para completar la URL de solicitud, agrega valores de clave de partición al final de la URL de solicitud, con el formato para que se lea como 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 adjuntos deben cumplir con RFC-1034 o deben tener doble codificación, por ejemplo, US:/CA#/Sunnyvale como US%3A/CA%3A/Sunnyvale.

¿Qué sigue?