メインコンテンツまでスキップ
に最終更新

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

備考

ベータ版

この機能はベータ版です。ワークスペース管理者は、 プレビュー ページからこの機能へのアクセスを制御できます。Databricksのプレビューを管理するを参照してください。

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

クラウドオブジェクトストレージから読み込む場合、 _object_metadata列はすべての入力ファイル形式で利用可能です。返されるDataFrameに_object_metadata列を含めるには、読み込みクエリで明示的に選択する必要があります。

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

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

警告

今後のリリースでは、 _object_metadata列に新しいフィールドが追加される可能性があります。_object_metadata列が更新された場合にスキーマ進化エラーを防ぐには、クエリでその列から特定のフィールドを選択できます。例を参照してください。

スキーマ​

_object_metadata列は、Databricks Runtime 18.1以降で利用可能な、以下のフィールドを含むSTRUCTです。すべてのフィールドはnullを許容します。

名前

Type

説明

例

mime_type

STRING

オブジェクトのMIMEタイプ（コンテンツタイプ）。例えばapplication/parquetまたはtext/csv 。

application/parquet

etag

STRING

オブジェクトのETag。ETagは、変更の検出やバージョン管理に役立ちます。

"abc123def456"

ユーザーメタデータ

VARIANT

オブジェクトに格納される、ユーザー定義のメタデータキーと値のペア。例えば、S3ではこれらはユーザー定義のメタデータヘッダーです。AWSドキュメントの「ユーザー定義メタデータヘッダー」を参照してください。Azure Blobでは、これらはユーザー定義のメタデータです。Azure ドキュメントの「.NET を使用して BLOB プロパティとメタデータを管理する」を参照してください。

{"my_key":"my_value"}

システムメタデータ

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

Auto Loaderを使用したストリーム ファイル​

次の例では、 Auto Loaderを使用してクラウド ストレージからファイルをストリームし、 _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)

特定のフィールドを選択してください​

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

使用方法 COPY INTO​

次の例では、 COPY INTOを使用してファイルを Delta テーブルにロードし、 _object_metadata列を選択します。

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

注意​

_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に設定されています。
このページの見出し