Columna de metadatos de objeto

La _object_metadata columna es una columna de metadatos oculta que expone propiedades de nivel de objeto en la nube para cada archivo leído por un origen de datos basado en archivos. A diferencia de _metadata (que contiene información como la ruta del archivo, el tamaño y la hora de modificación), _object_metadata proporciona propiedades de la capa de almacenamiento más completas, obtenidas mediante APIs en la nube, como el tipo MIME, el ETag, metadatos de clave-valor definidos por el usuario, metadatos definidos por el sistema y etiquetas de objeto.

La columna _object_metadata requiere Databricks Runtime 18.2 o posterior y está disponible para todos los formatos de archivo de entrada al leerlos desde el almacenamiento de objetos en la nube. Para incluir la _object_metadata columna en el dataframe devuelto, debe seleccionarla explícitamente en la consulta de lectura donde especifique el origen.

Si el origen de datos contiene una columna denominada _object_metadata, las consultas de _object_metadata devuelven la columna de origen de datos, no los metadatos del objeto en la nube. Para acceder a la columna de metadatos del objeto en la nube en este caso, anteponga un carácter de subrayado adicional (__object_metadata). Repita si __object_metadata también colisiona.

Los metadatos de archivo comunes, como la ruta de acceso o el tamaño del archivo, se pueden consultar mediante la _metadata columna . Para obtener más información sobre la _metadata columna, vea Columna de metadatos de archivo.

Schema

La columna _object_metadata es una STRUCT que contiene los siguientes campos, disponibles a partir de Databricks Runtime 18.2. Todos los campos admiten valores NULL.

Ejemplos

Los siguientes ejemplos muestran cómo leer y consultar la columna _object_metadata utilizando distintos métodos de ingesta.

Leer un lote de archivos

En el ejemplo siguiente se lee un archivo CSV y se seleccionan las columnas _metadata y _object_metadata.

Python

path = "<path-to-load-from>"

df = spark.read.format("csv").load(path)
display(df.select("*", "_metadata", "_object_metadata"))

Scala

val path = "<path-to-load-from>"

val df = spark.read.format("csv").load(path)
display(df.select("*", "_metadata", "_object_metadata"))

Transmisión de archivos con cargador automático

En el ejemplo siguiente se usa Auto Loader para transmitir archivos desde el almacenamiento en la nube y se escribe la _object_metadata columna en una tabla Delta.

Python

path = "<path-to-load-from>"
checkpoint = "<checkpoint-path>"
schema_location = "<schema-location-path>"
table = "<output-table-path>"

dsw = (spark.readStream
    .format("cloudFiles")
    .option("cloudFiles.format", "text")
    .option("cloudFiles.schemaLocation", schema_location)
    .option("header", "true")
    .load(path)
    .selectExpr("*", "_metadata as md", "_object_metadata as obj_md")
    .writeStream
    .format("delta")
    .option("checkpointLocation", checkpoint)
    .trigger(once=True)
    .start(table)
)

dsw.awaitTermination()

df = spark.read.format("delta").load(table).select("value", "md", "obj_md")
display(df)

Scala

val path = "<path-to-load-from>"
val checkpoint = "<checkpoint-path>"
val schemaLocation = "<schema-location-path>"
val table = "<output-table-path>"

val dsw = spark.readStream
    .format("cloudFiles")
    .option("cloudFiles.format", "text")
    .option("cloudFiles.schemaLocation", schemaLocation)
    .option("header", "true")
    .load(path)
    .selectExpr("*", "_metadata as md", "_object_metadata as obj_md")
    .writeStream
    .format("delta")
    .option("checkpointLocation", checkpoint)
    .trigger(Trigger.Once)
    .start(table)

dsw.awaitTermination()

val df = spark.read.format("delta").load(table).select("value", "md", "obj_md")
display(df)

Selección de campos específicos

Para evitar errores de evolución del esquema debidos a cambios futuros en _object_metadata, seleccione solo los campos específicos que necesita.

Python

path = "<path-to-load-from>"

(spark.read
   .format("csv")
   .schema(schema)
   .load(path)
   .select("_object_metadata.user_metadata", "_object_metadata.tags", "_object_metadata.etag"))

Scala

val path = "<path-to-load-from>"

spark.read
  .format("csv")
  .schema(schema)
  .load(path)
  .select("_object_metadata.user_metadata", "_object_metadata.tags", "_object_metadata.etag")

Uso con COPY INTO

En el ejemplo siguiente se usa COPY INTO para cargar archivos en una tabla Delta al seleccionar la _object_metadata columna.

COPY INTO my_delta_table
FROM (
  SELECT *, _object_metadata FROM '<path-to-load-from>'
)
FILEFORMAT = CSV

Extracción de valores de VARIANT campos

Los campos user_metadata, system_metadata y tags son de tipo VARIANT. En el ejemplo siguiente se extraen valores específicos mediante el operador de conversión ::. Puede extraer valores específicos mediante el operador de conversión :: o las funciones VARIANT. Ver VARIANT tipo.

Python

path = "<path-to-load-from>"

(spark.read
   .format("csv")
   .schema(schema)
   .load(path)
   .selectExpr(
     "*",
     "_object_metadata.user_metadata:my_key::string as my_key",
     "_object_metadata.tags:environment::string as env_tag"
   ))

SQL

SELECT
  *,
  _object_metadata.user_metadata:my_key::STRING AS my_key,
  _object_metadata.tags:environment::STRING AS env_tag
FROM csv.`<path-to-load-from>`

Notas

Tenga en cuenta lo siguiente al usar _object_metadata.

• La columna _object_metadata funciona con Amazon S3, Azure DFS, Azure Blob y GCP.
• Al seleccionar cualquier campo de _object_metadata desencadena hasta dos llamadas API en la nube adicionales por archivo, por lo que las consultas en un gran número de archivos pequeños pueden experimentar un aumento de la latencia.
• _object_metadata.tags se admite para S3 y Azure Blob Storage (no HNS, blob.core.windows.net). En todos los demás proveedores (Azure DFS, WASB, GCP), tags devuelve {}.
• En S3, la credencial debe tener el permiso s3:GetObjectTagging. Si no está disponible, tags devuelve null.
• Si Databricks encuentra un error al capturar etiquetas de un proveedor compatible, tags devuelve null.
• Los metadatos del sistema, los metadatos de usuario y las etiquetas no están disponibles para el almacenamiento administrado por Databricks y se establecen en null.