オブジェクト メタデータ列

_object_metadata列は、ファイル ベースのデータ ソースによって読み取られた各ファイルのクラウド オブジェクト レベルのプロパティを公開する非表示のメタデータ列です。 _metadata (ファイル パス、サイズ、変更時間などの情報を含む) とは異なり、_object_metadataは、MIME の種類、ETag、ユーザー定義キー値メタデータ、システム定義メタデータ、オブジェクト タグなど、クラウド API を介してフェッチされる豊富なストレージ層プロパティを提供します。

_object_metadata列はDatabricks Runtime 18.2以上が必要で、クラウドオブジェクトストレージから読み取る際にすべての入力ファイル形式に対応しています。 返された DataFrame に _object_metadata 列を含めるには、ソースを指定する読み取りクエリで明示的に選択する必要があります。

データ ソースに _object_metadata という名前の列が含まれている場合、 _object_metadata に対するクエリでは、クラウド オブジェクトのメタデータではなく、データ ソース列が返されます。 この場合、クラウド オブジェクト メタデータ列にアクセスするには、追加のアンダースコア (__object_metadata) を付加します。 __object_metadataも競合する場合は繰り返します。

ファイル パスやサイズなどの一般的なファイル メタデータは、 _metadata 列を使用して照会できます。 _metadata列の詳細については、「ファイル メタデータ列」を参照してください。

Schema

_object_metadata列は、Databricks Runtime 18.2から利用可能な以下のフィールドを含むSTRUCTです。 すべてのフィールドは null にできるです。

例示

次の例では、さまざまなインジェスト方法を使用して、 _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 を使用して、 _object_metadata 列を選択しながら Delta テーブルにファイルを読み込みます。

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から任意のフィールドを選択すると、ファイルごとに最大 2 つのクラウド API 呼び出しがトリガーされるため、多数の小さなファイルに対するクエリで待機時間が長くなる可能性があります。
• _object_metadata.tags は、S3 と Azure Blob Storage (HNS 以外、blob.core.windows.net) でサポートされています。 その他のすべてのプロバイダー (AZURE DFS、WASB、GCP) では、tags は {} を返します。
• S3 の場合、資格情報には s3:GetObjectTagging アクセス許可が必要です。 使用できない場合、 tags は nullを返します。
• Databricks でサポートされているプロバイダーからタグをフェッチ中にエラーが発生した場合、 tags は nullを返します。
• システム メタデータ、ユーザー メタデータ、およびタグは、Databricks で管理されるストレージでは使用できません。また、 nullに設定されています。