Oracle Cloud Infrastructureドキュメント

テキスト出力(CSV、JSON、ParquetまたはXML)のファイル・ネーミング

CSV、JSON、ParquetまたはXMLテキスト・ファイル出力を含むDBMS_CLOUD.EXPORT_DATAを使用した出力ファイルのネーミングについて説明します。

DBMS_CLOUD.EXPORT_DATAは、queryパラメータで指定された問合せを実行し、結果をクラウド・オブジェクト・ストア・バケットまたはディレクトリ内のテキスト・ファイルに送信します。出力形式は、指定したformatパラメータtype(CSV、JSON、ParquetまたはXMLのいずれか)によって異なります。

プロシージャを高速化し、出力を可能なかぎり高速に生成するために、DBMS_CLOUD.EXPORT_DATAはその作業を分割します。つまり、システム・リソースによっては、DBMS_CLOUD.EXPORT_DATAを実行すると、クラウド・オブジェクト・ストア・バケットまたはディレクトリ内に複数の出力ファイルが作成されます。

生成される各ファイルの形式は次のとおりです。

[FileNamePrefix client_info***module***action]***sequenceNum***timestamp.format_extension.[compression_extension]

  • FileNamePrefix: (オプション)FileNamePrefixが指定されている場合、DBMS_CLOUD.EXPORT_DATAはファイル名接頭辞を使用して結果のファイル名を生成します。FileNamePrefixは、file_uri_listパラメータ値のバケット名またはディレクトリ名の後に指定されたテキストを使用して指定します。

    file_uri_listでFileNamePrefixに複数の値を指定することはできません。

  • client_info***module***action: ファイル名の接頭辞がfile_uri_listパラメータで指定されていない場合、DBMS_CLOUD.EXPORT_DATAは、ファイル名接頭辞としてclient_info、アプリケーションmoduleおよびactionの組合せを使用します(この情報が使用可能な場合)。プロシージャは、問合せを実行するデータベース・セッションのアプリケーション情報からこれらの名前を取得します。client_info、module名およびaction名の詳細は、DBMS_APPLICATION_INFOを参照してください。

    ファイル名の接頭辞にfile_uri_listが指定されておらず、データベース・セッション属性が使用できない場合、DBMS_CLOUD.EXPORT_DATAはファイル名接頭辞"data"を使用します。

  • sequenceNum: DBMS_CLOUD.EXPORT_DATA問合せに関連付けられた順序番号。問合せ、データベース・サービスおよびECPU数(データベースがOCPUを使用している場合のOCPU)に応じて、1つ以上のsequenceNumがあります。また、結果のサイズによっては、sequenceNumごとに1つ以上の出力ファイルが存在します。

    データベース・サービスの詳細は、Autonomous AI Databaseでの同時実行性および優先度の管理を参照してください。

  • timestamp: ファイルのアップロード時のタイムスタンプ。

  • format_extension: デフォルト値は、format type値によって異なります。

    • CSVフォーマット: .csv

    • JSON形式: .json

    • PARQUET形式.parquet

    • XML形式: .xml

    詳細は、「EXPORT_DATA用のDBMS_CLOUDパッケージのフォーマット・オプション」のformatオプションfileextensionの説明を参照してください。

  • compression_extension: compressionオプションに値gzipを指定してformatパラメータを含める場合、これは"gz"です。

    format typeがparquetの場合、compression値snappyもサポートされ、これがデフォルトです。

たとえば、次のDBMS_CLOUD.EXPORT_DATAプロシージャのファイル名接頭辞は、dept_exportとしてfile_uri_listパラメータで指定されます。この例では、指定された形式で指定されたオブジェクト・ストアに出力を生成します。

BEGIN
  DBMS_CLOUD.EXPORT_DATA(
    credential_name => 'DEF_CRED_NAME',
    file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/dept_export',
    query           => 'SELECT * FROM DEPT',
    format          => JSON_OBJECT('type' value 'json'));
END;
/

ファイル名の接頭辞を指定すると、生成される出力ファイルには、次のようなファイル名接頭辞が含まれます。

dept_export_1_20210809T173033Z.json
dept_export_2_20210809T173034Z.json
dept_export_3_20210809T173041Z.json
dept_export_4_20210809T173035Z.json

生成される出力ファイルの数は、結果のサイズ、データベース・サービス、およびAutonomous AI Databaseインスタンス内のECPU (データベースがOCPUを使用している場合のOCPU)の数によって異なります。

次の例では、file_uri_listパラメータにファイル名接頭辞が含まれず、compressionパラメータに値gzipが指定されています。

BEGIN
  DBMS_CLOUD.EXPORT_DATA(
    credential_name => 'DEF_CRED_NAME',
    file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/',
    query           => 'SELECT * FROM DEPT',
    format          => json_object('type' value 'json', 'compression' value 'gzip'));
END;
/

ファイル名の接頭辞がfile_uri_listパラメータにない場合、DBMS_CLOUD.EXPORT_DATAはclient_info***module***actionという形式のファイル名接頭辞を使用します。この例では、生成される出力ファイルには、DBMS_CLOUD.EXPORT_DATAが提供するファイル名接頭辞が含まれ、ファイルはgzipで圧縮され、ファイル拡張子.gzが次のように追加されます。

Client1_Module1_Action1_1_20210809T173033Z.json.gz
Client1_Module1_Action1_2_20210809T173034Z.json.gz
Client1_Module1_Action1_3_20210809T173041Z.json.gz
Client1_Module1_Action1_4_20210809T173035Z.json.gz

DBMS_CLOUD.EXPORT_DATAを実行するときに client_info*module*actionセッション情報を使用できない場合、ファイル名の接頭辞は dataに設定されます。次に例を示します。

data_1_20210809T173033Z.json.gz
data_2_20210809T173034Z.json.gz
data_3_20210809T173041Z.json.gz
data_4_20210809T173035Z.json.gz

たとえば、次のDBMS_CLOUD.EXPORT_DATAプロシージャのファイル名接頭辞は、dept_exportとしてfile_uri_listパラメータで指定されます。この例では、指定された形式で指定されたディレクトリに出力を生成します。

BEGIN
  DBMS_CLOUD.EXPORT_DATA(
    file_uri_list   => 'DATA_PUMP_DIR:sales.json',
    query           => 'SELECT * FROM SALES',
    format          => JSON_OBJECT('type' value 'json'));
END;
/

ファイル名の接頭辞を指定すると、生成される出力ファイルには、次のようなファイル名接頭辞が含まれます。

sales_1_20230705T124523275915Z.csv

DBMS_CLOUD.EXPORT_DATAを使用したファイル・ネーミングに関するノート:

  • DBMS_CLOUD.EXPORT_DATAはバケットまたはディレクトリを作成しません。

  • DBMS_CLOUD.EXPORT_DATAが生成するファイルの数は、ECPUの数(データベースがOCPUを使用している場合のOCPU)、データベース・サービスおよび結果データのサイズによって決まります。

  • file_uri_listパラメータにディレクトリ・オブジェクト名を指定する場合は、次のことが適用されます。

    • 指定されたディレクトリが存在し、そのディレクトリへのWRITEアクセス権を持っている必要があります。

    • ディレクトリ名は、二重引用符で囲むと大/小文字が区別されます。

    • 資格証明名パラメータを指定しないでください。

  • CSV、JSONまたはXML出力の場合、デフォルトでは、生成されたファイルに10MBのデータが含まれていると、新しい出力ファイルが作成されます。ただし、結果データが10MB未満の場合は、データベース・サービスおよびAutonomous AI DatabaseインスタンスのECPU (OCPUが使用されている場合はOCPU)の数に応じて、複数の出力ファイルが存在する可能性があります。

    CSV、JSONまたはXMLの場合、デフォルトの出力ファイル・チャンク・サイズは10MBです。この値は、formatパラメータのmaxfilesizeオプションを使用して変更できます。詳細は、「EXPORT_DATAのDBMS_CLOUDパッケージ形式オプション」を参照してください。

  • Parquet出力の場合、生成された各ファイルは128MB未満で、複数の出力ファイルが生成される可能性があります。ただし、結果データが128MB未満の場合は、データベース・サービスおよびAutonomous AI DatabaseインスタンスのECPU (OCPUが使用されている場合はOCPU)の数に応じて、複数の出力ファイルが存在する可能性があります。

    formatパラメータのmaxfilesizeオプションは、Parquetファイルには適用されません。