Kolumna metadanych obiektu

Kolumna _object_metadata to ukryta kolumna metadanych, która udostępnia właściwości obiektu w chmurze dla każdego pliku odczytanego ze źródła danych opartego na plikach. W przeciwieństwie do _metadata (które zawierają informacje, takie jak ścieżka pliku, rozmiar i czas modyfikacji), _object_metadata zapewnia bogatsze właściwości warstwy magazynowania pobierane za pośrednictwem interfejsów API chmury — w tym za pomocą typu MIME, ETag, metadanych klucza zdefiniowanego przez użytkownika, metadanych zdefiniowanych przez system i tagów obiektów.

Kolumna wymaga _object_metadata Databricks Runtime 18.2 lub wyższego i jest dostępna dla wszystkich formatów plików wejściowych podczas odczytu z chmurowego magazynu obiektowego. Aby dołączyć kolumnę _object_metadata do zwróconej ramki danych, musisz jawnie wybrać ją w zapytaniu odczytu, w którym określono źródło.

Jeśli źródło danych zawiera kolumnę o nazwie _object_metadata, zapytania do _object_metadata zwracają kolumnę źródła danych, a nie metadane obiektu w chmurze. W takim przypadku, aby uzyskać dostęp do kolumny metadanych obiektu w chmurze, dodaj na początku dodatkowy znak podkreślenia (__object_metadata). Powtórz, jeśli __object_metadata również koliduje.

Typowe metadane pliku, takie jak ścieżka pliku lub rozmiar, można wykonywać zapytania przy użyciu kolumny _metadata . Aby uzyskać więcej informacji na temat kolumny _metadata , zobacz Kolumna metadanych pliku.

Schema

Kolumna _object_metadataSTRUCT zawiera następujące pola, dostępne począwszy od Databricks Runtime 18.2. Wszystkie pola mogą mieć wartość null.

Examples

Poniższe przykłady pokazują, jak odczytywać i odpytywać kolumnę _object_metadata przy użyciu różnych metod pozyskiwania danych.

Odczytaj partię plików

Poniższy przykład odczytuje plik CSV i wybiera kolumny _metadata i _object_metadata .

Python

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

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

Skala

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

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

Przesyłanie strumieniowe plików za pomocą Auto Loader

W poniższym przykładzie użyto Auto Loader do strumieniowego odczytu plików z magazynu w chmurze i zapisania kolumny _object_metadata do tabeli 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)

Skala

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)

Wybieranie określonych pól

Aby uniknąć błędów ewolucji schematu spowodowanych przyszłymi zmianami w _object_metadata, wybierz tylko te pola, których potrzebujesz.

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

Skala

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

Użyj z COPY INTO

W poniższym przykładzie używa się COPY INTO do ładowania plików do tabeli Delta przy jednoczesnym wybieraniu kolumny _object_metadata.

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

Wyodrębnianie wartości z VARIANT pól

Pola user_metadata, system_metadatai tags są VARIANT typami. Poniższy przykład wyodrębnia określone wartości przy użyciu operatora rzutowania :: . Możesz wyodrębnić konkretne wartości za pomocą operatora rzutowania :: lub funkcji VARIANT. Zobacz VARIANT typ.

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

Notatki

Podczas korzystania z elementu _object_metadatanależy pamiętać o następujących kwestiach.

• Kolumna _object_metadata współpracuje z usługami Amazon S3, Azure DFS, Azure Blob i GCP.
• Wybranie dowolnego pola z _object_metadata wyzwalaczy maksymalnie dwóch dodatkowych wywołań interfejsu API w chmurze na plik, dlatego zapytania dotyczące dużej liczby małych plików mogą powodować wzrost opóźnienia.
• _object_metadata.tags jest obsługiwany dla S3 i Azure Blob Storage (inne niż HNS, blob.core.windows.net). Na wszystkich innych dostawcach (Azure DFS, WASB, GCP), tags zwraca {}.
• W przypadku usługi S3 poświadczenie musi mieć uprawnienie s3:GetObjectTagging. Jeśli jest niedostępny, tags zwraca wartość null.
• Jeśli usługa Databricks napotka błąd podczas pobierania tagów od obsługiwanego dostawcy, tags zwraca wartość null.
• Metadane systemu, metadane użytkownika i tagi nie są dostępne dla magazynu zarządzanego przez usługę Databricks i są ustawione na wartość null.