Столбец метаданных объекта

Important

Эта функция доступна в общедоступной предварительной версии.

Столбец _object_metadata — это скрытый столбец метаданных, предоставляющий свойства уровня облачных объектов для каждого файла, считываемого источником данных на основе файлов. В отличие от _metadata (который содержит такие сведения, как путь к файлу, размер и время изменения), _object_metadata предоставляет более богатые свойства уровня хранения, получаемые через облачные API, включая MIME-тип, ETag, пользовательские метаданные в формате «ключ — значение», системные метаданные и теги объектов.

Столбец _object_metadata требует Databricks Runtime 18.2 или выше и доступен для всех входных форматов при чтении из облачного объектного хранилища. Чтобы включить _object_metadata столбец в возвращаемый кадр данных, необходимо явно выбрать его в запросе на чтение, где указан источник.

Если источник данных содержит столбец с именем _object_metadata, запросы к _object_metadata возвращают столбец из источника данных, а не метаданные облачного объекта. Чтобы получить доступ к столбцу метаданных облачного объекта в этом случае, добавьте дополнительный символ подчеркивания (__object_metadata). Повторите, если __object_metadata также сталкивается.

Общие метаданные файла, такие как путь к файлу или размер, можно запрашивать с помощью столбца _metadata . Дополнительные сведения о столбце _metadata см. в статье Столбец метаданных файла.

Предупреждение

Новые поля могут быть добавлены в _object_metadata столбец в будущих выпусках. Чтобы предотвратить ошибки, связанные с изменением схемы, если обновляется столбец _object_metadata, можно выбирать в запросах конкретные поля из этого столбца. См. примеры .

Схема

Столбец _object_metadataSTRUCT содержит следующие поля, доступные начиная с Databricks Runtime 18.2. Все поля имеют значение NULL.

Name Тип Description Example
mime_type STRING Тип MIME (тип контента) объекта, например application/parquet или text/csv. application/parquet
etag STRING ETag объекта. ETags полезны для обнаружения изменений или управления версиями. "abc123def456"
user_metadata VARIANT Определяемые пользователем пары "ключ-значение метаданных", хранящиеся в объекте. Например, в S3 эти заголовки метаданных определяются пользователем. См. заголовки метаданных, определяемые пользователем , в документации AWS. В Azure BLOB-объекте эти метаданные определяются пользователем. См. в документации Azure статью Управление свойствами и метаданными BLOB-объектов с помощью .NET. {"my_key":"my_value"}
system_metadata VARIANT Пары ключ-значение, определяемые системой и задаваемые поставщиком облачного хранилища. {"Content-Length":"1024", ...}
Теги VARIANT Пары «ключ-значение» тега объекта, заданные пользователем, сохранённые в объекте. Например, в S3 эти теги являются тегами объектов. См. раздел "Классификация объектов" с помощью тегов в документации AWS. Не все облачные службы хранилища поддерживают теги объектов. См. Примечания для сведений о поведении каждого поставщика. {"my_tag":"my_value"}

Примеры

В следующих примерах показано, как читать столбец _object_metadata и выполнять запросы к нему с помощью различных методов приема данных.

Чтение пакета файлов

В следующем примере считывается CSV-файл и выбираются столбцы _metadata и _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"))

Потоковая передача файлов с помощью автозагрузчика

В следующем примере автозагрузчик используется для потоковой передачи файлов из облачного хранилища и записи столбца _object_metadata в таблицу 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)

Выбор определенных полей

Чтобы избежать ошибок, связанных с изменением схемы из-за будущих изменений в _object_metadata, выбирайте только конкретные поля, которые вам нужны.

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")

Использование с COPY INTO

В следующем примере используется COPY INTO для загрузки файлов в таблицу Delta при выборе столбца _object_metadata .

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

Извлечение значений из VARIANT полей

Поля user_metadata, system_metadata и tags имеют тип VARIANT. В следующем примере извлекаются конкретные значения с помощью оператора приведения ::. Вы можете извлечь определенные значения с помощью :: оператора или VARIANT функций приведения. См. тип VARIANT.

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>`

Примечания.

При использовании _object_metadataследует учитывать следующее.

  • Столбец _object_metadata работает с Amazon S3, Azure DFS, Azure Blob и GCP.
  • Выбор любого поля из _object_metadata вызывает до двух дополнительных вызовов облачного API на файл, поэтому запросы к большому числу небольших файлов могут выполняться с несколько большей задержкой.
  • _object_metadata.tags поддерживается для S3 и Хранилище BLOB-объектов Azure (не HNS, blob.core.windows.net). У всех остальных поставщиков (Azure DFS, WASB, GCP) tags возвращает {}.
  • Для S3 учетные данные должны иметь s3:GetObjectTagging разрешение. Если недоступно, tags возвращает null.
  • Если при получении тегов от поддерживаемого поставщика в Databricks возникает ошибка, tags возвращает null.
  • Системные метаданные, пользовательские метаданные и теги недоступны для управляемого хранилищем Databricks и имеют значение null.
  • Last updated on