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: If a file name prefix is not supplied with the file_uri_list parameter, DBMS_CLOUD.EXPORT_DATA uses the combination of client_info, application module and action as the file name prefix (when this information is available).このプロシージャは、問合せを実行するデータベース・セッションのアプリケーション情報からこれらの名前を取得します。See DBMS_APPLICATION_INFO for information on client_info, module name, and action name.

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

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

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

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

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

    • CSV形式: .csv
    • JSON形式: .json
    • PARQUET形式.parquet
    • XML形式: .xml

    詳細は、EXPORT_DATAのDBMS_CLOUDパッケージ形式オプションのformatオプションfileextensionの説明を参照してください。

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

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

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

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 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プロシージャのファイル名の接頭辞は、file_uri_listパラメータでdept_exportとして指定されます。この例では、指定されたディレクトリへの出力を指定された形式で生成します。 

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 Databaseインスタンスのデータベース・サービスおよびECPU数(データベースがOCPUを使用する場合はOCPU)に応じて、複数の出力ファイルがある場合があります。

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

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

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