DBMS_CLOUDパッケージのフォーマット・オプション

DBMS_CLOUDのフォーマット引数は、ソース・ファイルのフォーマットを指定します。

format引数を指定する場合、次の2つの方法があります。

format => '{"format_option" : "format_value" }'

AND

format => json_object('format_option' value 'format_value')

次に例を示します:

format => json_object('type' VALUE 'CSV')

複数のフォーマット・オプションを指定するには、値を「,」で区切ります。

format => json_object('ignoremissingcolumns' value 'true', 'removequotes' value 'true',
                           'dateformat' value 'YYYY-MM-DD-HH24-MI-SS', 'blankasnull' value 'true', 'logretention' value 7)

ノート: Avro、ORCまたはParquet形式オプションについては、「Avro、ORCまたはParquet用のDBMS_CLOUDパッケージの形式オプション」を参照。

「フォーマット・オプション」列に示されているように、format typeがJSONの場合は、DBMS_CLOUD.COPY_COLLECTIONまたはDBMS_CLOUD.COPY_DATAで、限られたフォーマット・オプション・セットが有効です。

書式オプション 説明 構文
blankasnull trueに設定すると、スペースで構成されたフィールドはnullとしてロードされます。

blankasnull : true

デフォルト値: False

characterset

format JSONおよびCOPY_DATAで有効

 ソース・ファイルのキャラクタ・セットを指定します

characterset: string

デフォルト値: データベースの文字セット

columnpath

format JSONおよびCOPY_DATAでのみ使用

JSONレコードから抽出する必要があるフィールドに対応するJSONパス式の配列。配列内の各JSONパス式は、Oracle Database 19c JSON開発者ガイドまたはOracle Database 26ai JSON開発者ガイドのSQL/JSONパス式で説明されているルールに従う必要があります。

JSON形式およびDBMS_CLOUD.COPY_DATAでのみ使用します。

文字列形式で表されたJSONパス式のJSON配列。例: 'columnpath' value '["$.WEATHER_STATION_ID", "$.WEATHER_STATION_NAME"]'

compression

JSONデータで有効なオプション

ソース・ファイルの圧縮タイプを指定します。

ZIPアーカイブ・フォーマットはサポートされていません。

値autoを指定すると、圧縮タイプgzip, zlib, std, bzip2がチェックされます。

compression: auto|gzip|zlib|bzip2

デフォルト値: 圧縮しないことを意味するNULL値。
conversionerrors データ型変換エラーのために行が拒否された場合、関連する列がnullとして格納されるか、行が拒否されます。

conversionerrors : reject_record | store_null

デフォルト値: reject_record
dateformat

ソース・ファイル内の日付フォーマットを指定します。フォーマット・オプションAUTOを指定すると、次のフォーマットが検索されます: 

J
MM-DD-YYYYBC
MM-DD-YYYY
YYYYMMDD HHMISS
YYMMDD HHMISS
YYYY.DDD
YYYY-MM-DD

dateformat : string

デフォルト値: データベースの日付書式
delimiter

フィールド・デリミタを指定します

特殊文字をデリミタとして使用する場合は、その文字のASCIIコードのHEX値を指定します。たとえば、次のようにTAB文字を区切り文字として指定します。

format => json_object('delimiter' value 'X''9''')

delimiter : character

デフォルト値: | (パイプ文字)

detectfieldorder

外部データ・ファイル内のフィールドが表の列とは異なる順序になるように指定します。各外部データ・ファイルの最初の行を使用してフィールドの順序を検出し、表の列にマッピングします。外部データ・ファイルのフィールド名は、表の列の名前と大/小文字を区別しない方法で比較されます。

この形式オプションは、次の手順に適用できます。

  • DBMS_CLOUD.COPY_DATA

  • DBMS_CLOUD.CREATE_EXTERNAL_TABLE

  • DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE

  • DBMS_CLOUD.CREATE_HYBRID_PART_TABLE

detectfieldorderの制限事項:

  • データファイルのフィールド名は、最初のレコード行に表示する必要があり、フィールド名の間に空白を含めることはできません。

  • フィールド名レコードのフィールド・デリミタは、ファイル内のデータのフィールド・デリミタと同じである必要があります。

  • 引用符で囲まれたフィールド名はサポートされていません。データファイルのフィールド名は、大/小文字を区別せずに、外部表の列の名前と比較されます。

  • フィールド名には埋込みフィールド・デリミタを使用できません。

  • 表の列数は、データファイルのフィールド数と一致する必要があります。

  • このフォーマット・オプションは、バイナリ・ファイル形式の正確な列メタデータ情報があるため、BigdataまたはOracle Data Pumpフォーマットには適用されません。

    テキスト形式、CSV、JSON、ParquetまたはXMLは、最初の行にフィールド名が含まれている場合に、この自動フィールド順序検出を利用できます。

詳細は、『Oracle Database 19cユーティリティ』または『Oracle Database 23aiユーティリティ』のフィールド名に関する項およびALL FILESの説明を参照してください。

detectfieldorder: true

デフォルト値: false
enablelogs

フォーマット・オプションenablelogsは、次のDBMS_CLOUDプロシージャで使用されます。

  • COPY_DATA

  • COPY_COLLECTION

  • EXPORT_DATA

enablelogsはブール値を指定し、TRUEに設定すると、ログが生成されます。FALSEに設定すると、ログは生成されません。

たとえば:

format => JSON_OBJECT('enablelogs' value FALSE)

enablelogs: false

デフォルト値: true
encryption

フォーマット・オプションencryptionは、オブジェクト・ストアとの間でデータをエクスポートおよびインポートするための暗号化および復号化オプションを指定します。

encryptionを使用して、暗号化および復号化する次のパラメータを指定します。

  • user_defined_function: 指定したBLOB (バイナリ・ラージ・オブジェクト)を復号化または暗号化する完全修飾ユーザー定義関数を指定します。復号化または暗号化されたBLOBを返します。user_defined_functionは、encryptionの他のパラメータと相互に排他的です。

    たとえば、ADMIN.DECRYPTION_CALLBACKです。

  • type: 復号化または暗号化するDBMS_CRYPTO暗号化アルゴリズムを指定します。

    typeは、Block Cipher Algorithms + Block Cipher Chaining Modifiers + Block Cipher Padding Modifiers形式の値を受け入れます。

    サポートされているブロック暗号アルゴリズムは次のとおりです。

    • DBMS_CRYPTO.ENCRYPT_AES256

    サポートされているブロック暗号連鎖修飾子は次のとおりです。

    • DBMS_CRYPTO.CHAIN_CBC

    • DBMS_CRYPTO.CHAIN_CFB

    • DBMS_CRYPTO.CHAIN_ECB

    • DBMS_CRYPTO.CHAIN_OFB

    サポートされているブロック暗号パディング修飾子は次のとおりです。

    • DBMS_CRYPTO.PAD_PKCS5

    • DBMS_CRYPTO.PAD_NONE

    • DBMS_CRYPTO.PAD_ZERO

    • DBMS_CRYPTO.PAD_ORCL

  • credential_name: 暗号化キーの格納に使用する資格証明を指定します。

これらのパラメータに値を指定しない場合、ブロック暗号連鎖修飾子およびブロック暗号パディング修飾子の値は、デフォルトでDBMS_CRYPTO.CHAIN_CBCおよびDBMS_CRYPTO.PAD_PKCS5に設定されます。

フォーマット・オプションencryptionは、次のDBMS_CLOUDプロシージャで使用されます。

  • これらのプロシージャに対して復号化するためのパラメータを渡すために使用されます。

    • DBMS_CLOUD.COPY_DATA

    • DBMS_CLOUD.CREATE_EXTERNAL_TABLE

    • DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE

    • DBMS_CLOUD.CREATE_HYBRID_PART_TABLE

      DBMS_CLOUD.CREATE_HYBRID_PART_TABLEの場合、このオプションはオブジェクト・ストレージ・ファイルにのみ適用されます。

    • DBMS_CLOUD.COPY_COLLECTION

  • これらのプロシージャに対して暗号化するパラメータを渡すために使用されます。

    • DBMS_CLOUD.EXPORT_DATA

たとえば:

format => JSON_OBJECT('encryption' value json_object ('type' value DBMS_CRYPTO.ENCRYPT_AES256 + DBMS_CRYPTO.CHAIN_CBC + DBMS_CRYPTO.PAD_PKCS5, 'credential_name' value 'ENCRYPTION_CRED')) 		encryption:value

valueは、暗号化のための追加パラメータを提供するJSON文字列です。

type: 値

暗号化タイプを指定します。

credential_name: value

暗号化キーの格納に使用する資格証明を指定します。

user_defined_function: value

指定されたBLOB (バイナリ・ラージ・オブジェクト)を復号化または暗号化する完全修飾ユーザー定義関数を指定します。
endquote

データは、quoteおよびendquoteで指定された2つのデリミタで囲むことができます。指定した場合、quoteおよびendquote文字はロード中に削除されます。

たとえば:

format => JSON_OBJECT('quote' value '(', 'endquote' value ')')

endquote:character

デフォルト値: endquoteがないことを意味するNull。

escape 文字"\"は、指定するとエスケープ文字として使用されます。

escape : true

デフォルト値: false

ignoreblanklines

JSONデータで有効なオプション

 trueに設定すると、空白行は無視されます。

ignoreblanklines : true

デフォルト値: False
ignoremissingcolumns field_listの列がソース・ファイルの列より多い場合、余分な列はnullとして格納されます。

ignoremissingcolumns : true

デフォルト値: False

jsonpath

COPY_COLLECTIONでのみ使用

ロードするドキュメントを識別するJSONパス。

このオプションは、DBMS_CLOUD.COPY_COLLECTIONを含むJSONコレクション・データでのみ有効です。

jsonpath: 文字列

デフォルト値: Null
`キー割り当て`

`COPY_COLLECTION`でのみ使用

新しいコレクションをmongo互換のコレクションとして作成するか、SODAコレクションとして作成するかを指定します。

値がembedded_oidに設定されている場合、新しいコレクションがmongo互換のコレクションとして作成されます。

デフォルトでは、このパラメータは設定されていません。つまり、新しいコレクションがSODAコレクションとして作成されます。

keyassignment: embedded_oid

デフォルト: keyassignmentが設定されていません

keypath

COPY_COLLECTIONでのみ使用

ロードするデータ内の属性を'_id'値として指定します。

keypathを指定する場合は、keyassignment値もembedded_oidとして指定する必要があります。

パスの値を'_id'値として選択するには、値を'$.mykey'などのパスに設定します。

このパラメータはオプションで、mongo互換のコレクションへのロードにのみ有効です。

指定しない場合、Oracleは12バイトの一意のシステムIDを生成し、'_id'属性がロードされるデータにまだ存在しない場合は、それを'_id'属性として移入します。

keypath: string

デフォルト: keypathが設定されていません。

keypathが設定されている場合、デフォルトの文字列値はNULLです。

language ロケール依存の情報を導出できる言語名(FRENCHなど)を指定します。

language: 文字列

デフォルト値: Null

Oracleがサポートする言語の一覧は、『Oracle Database 19cデータベース・グローバリゼーション・サポート・ガイド』のロケール・データに関する項またはOracle Database 23aiデータベース・グローバリゼーション・サポート・ガイドのロケール・データに関する項を参照してください。

logdir

logfile_tableまたはbadfile_tableファイルが保存されるディレクトリ・オブジェクト名を決定する文字列値を指定します。

デフォルトでは、logdirは大/小文字を区別しませんが、指定された値が二重引用符で囲まれている場合は大/小文字が保持されます。

たとえば:

format => JSON_OBJECT ('logdir' value 'test_log')

上の例で指定したlogdirフォーマット・オプションでは、logfile_tableまたはbadfile_tableファイルがTEST_LOGディレクトリ・オブジェクトに保存されます。

format => JSON_OBJECT ('logdir' value '"test_log"')

上の例で指定したlogdirフォーマット・オプションでは、logfile_tableまたはbadfile_tableファイルがtest_logディレクトリ・オブジェクトに保存されます。

logdir: 文字列

デフォルト値: DATA_PUMP_DIR
logprefix

logfile_tableおよびbadfile_tableファイルの接頭辞を決定する文字列値を指定します。

ログ表名の形式は、logprefix$operation_idです

デフォルトでは、logprefixは大文字ですが、指定された値が二重引用符で囲まれている場合は大/小文字が保持されます。

たとえば:

format => JSON_OBJECT ('logprefix' value 'TEST')

ログ・ファイルでは、TEST$2_LOGやTEST$2_BADのように、TEST接頭辞が使用されます。

logprefix: 文字列

デフォルト値: COPY
logretention

logfile_tableおよびbadfile_tableファイルが保持される、正の整数の期間を日数で指定します。

有効な値: 0から99999

たとえば:

format => JSON_OBJECT ('logretention' value 7)

logretention: 数値

デフォルト値: 2

maxdocsize

このオプションは、JSONデータでのみ有効です

 JSONドキュメントの最大サイズ。

maxdocsize: 数値

デフォルト値: 1Mバイト

最大許容値: 2Gバイト
numericcharacters

グループ・セパレータおよび小数点文字として使用する文字を指定します。

decimal_character: 小数点の整数部分と小数部分を区切ります。

group_separator: グループ・セパレータは、整数グループ(1,000、100万、100万など)を区切るものです。

numericcharacters: 'decimal_character group_separator'

デフォルト値:".,"

詳細については、NLS_NUMERIC_CHARACTERS Oracle Database 19c Databaseグローバリゼーション・サポート・ガイド Oracle Database 23ai Databaseグローバリゼーション・サポート・ガイドを参照してください。

numberformat

数値フォーマット・モデルを指定します。数値フォーマット・モデルを使用すると、数値が指定した有効桁数に丸められます。数値フォーマット・モデルは、1つ以上の数値フォーマット要素で構成されます。

これは、numericcharactersと組み合せて使用されます。

numberformat: number_format_model

デフォルト値: NLS_TERRITORYパラメータの設定から導出されます

詳細は、Oracle Database 19c SQL言語リファレンスの数値書式モデルまたはOracle Database 23ai SQL言語リファレンスを参照してください。

partition_columns

フォーマット・オプションpartition_columnsをDBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEとともに使用して、パーティション列がファイル・パス(構造化または非構造化)から導出されるときの、パーティション列がファイル・パスから導出されるときのディメンション列名とデータ型を指定できます。

  • DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEにcolumn_listパラメータが含まれ、データ・ファイルを非構造化(CSVテキスト・ファイルなど)の場合、partition_columnsはデータ型を含みません。たとえば、このタイプのpartition_columnsの指定では、次のような形式を使用します。 

    '"partition_columns":["state","zipcode"]'

    データ型は、DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEのcolumn_listパラメータで指定されるため、必須ではありません。

  • DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEにcolumn_listパラメータが含まれず、データ・ファイルが構造化される(Avro、ORC、Parquetファイルなど)場合、partition_columnsオプションにはデータ型が含まれます。たとえば、partition_columnsの指定を次に示します。 

    '"partition_columns":[{"name":"country", "type":"varchar2(10)"}, {"name":"year", "type":"number"}, {"name":"month", "type":"varchar2(10)"}]'

データ・ファイルが構造化されておらず、type副句がpartition_columnsで指定されている場合、type副句は無視されます。

Hive形式に基づかないオブジェクト名の場合、partition_columnsで指定された列の順序は、file_uri_listのオブジェクト名に表示される順序と一致する必要があります。

 
quote フィールドの引用符文字を指定し、quote文字は、指定するとロード中に削除されます。

quote: 文字

デフォルト値: NULL (引用符なしを意味する)

recorddelimiter

JSONデータで有効なオプション

レコード・デリミタを指定します。

デフォルトでは、DBMS_CLOUDは、デリミタとしての正しい改行文字の自動検出を試行します。まず、ファイルでWindows改行文字\r\nが検索されます。Windowsの改行文字が見つかると、それがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。Windowsの改行文字が見つからない場合は、UNIX/Linuxの改行文字"\n"が検索され、見つかった場合は"\n"がプロシージャのすべてのファイルのレコード・デリミタとして使用されます。

デフォルトの動作をオーバーライドする場合は、この引数を明示的に指定します。たとえば:

format => json_object('recorddelimiter' VALUE '''\r\n''')

レコード区切り文字がないことを示すには、入力ファイルにないrecorddelimiterを指定できます。たとえば、デリミタが存在しないことを示すには、recorddelimiterの値として制御文字0x01 (SOH)を指定し、recorddelimiter値を"0x''01''"に設定します(この文字はJSONテキストでは使用されません)。たとえば: 

format => '{"recorddelimiter" : "0x''01''"}'

recorddelimiterは、プロシージャ・コールごとに1回設定されます。デフォルト値のdetected newlineを使用している場合、すべてのファイルで同じレコード・デリミタが使用されます(検出された場合)。

recorddelimiter: 文字

デフォルト値: detected newline
regexuri

フォーマット・オプションregexuriは、次のDBMS_CLOUDプロシージャで使用されます。

  • COPY_COLLECTION

  • COPY_DATA

  • CREATE_EXTERNAL_TABLE

  • CREATE_EXTERNAL_PART_TABLE

  • CREATE_HYBRID_PART_TABLE

regexuriの値がTRUEに設定されている場合、クラウドのソース・ファイルURIのファイル名にワイルドカードと正規表現を使用できます。

regexuriパラメータがFALSEに設定されている場合、文字"*"および"?"はワイルドカード文字とみなされます。regexuriパラメータがTRUEに設定されている場合、文字"*"および"?"は、指定された正規表現パターンの一部です。

正規表現パターンは、URI内のファイル名またはサブフォルダ・パスでのみサポートされ、パターン一致はREGEXP_LIKE関数によって実行されるものと同じです。ディレクトリ名では正規表現パターンはサポートされていません。

外部表の場合、このオプションは、オブジェクト・ストレージ内のファイルに作成される表でのみサポートされます。

たとえば:

format => JSON_OBJECT('regexuri' value TRUE)

REGEXP_LIKE条件の詳細は、Oracle Database 19c SQL言語リファレンスのREGEXP_LIKE条件またはOracle Database 23ai SQL言語リファレンスを参照してください。

regexuri: True

デフォルト値: False
rejectlimit 指定した数の行が拒否されると、操作はエラーになります。

rejectlimit: 数値

デフォルト値: 0
removequotes ソース・ファイル内のフィールドを囲む引用符を削除します。

removequotes: true

デフォルト値: False
skipheaders ファイルの先頭からスキップする行数を指定します。

skipheaders: 数値

デフォルト値: 指定しない場合は0、値なしで指定した場合は1
territory 入力データ特性をさらに判別するためのテリトリ名を指定します。

territory: 文字列

デフォルト値: Null

Oracleでサポートされている言語の一覧は、『Oracle Database 19cデータベース・グローバリゼーション・サポート・ガイド』のロケール・データに関する項または『Oracle Database 23aiデータベース・グローバリゼーション・サポート・ガイド』を参照してください。

timestampformat

ソース・ファイル内のタイムスタンプ・フォーマットを指定します。フォーマット・オプションAUTOを指定すると、次のフォーマットが検索されます: 

YYYY-MM-DD HH:MI:SS.FF
YYYY-MM-DD HH:MI:SS.FF3
YYYY-MM-DD HH24:MI:SS.FF3
MM/DD/YYYY HH:MI:SS.FF3

timestampformat : 文字列

デフォルト値: データベースのタイムスタンプ書式

この文字列には、"$"などのワイルドカード文字を含めることができます。
timestampltzformat

ソース・ファイル内のローカル・タイムゾーン付きタイムスタンプ・フォーマットを指定します。フォーマット・オプションAUTOを指定すると、次のフォーマットが検索されます: 

DD Mon YYYY HH:MI:SS.FF TZR
MM/DD/YYYY HH:MI:SS.FF TZR
YYYY-MM-DD HH:MI:SS+/-TZR
YYYY-MM-DD HH:MI:SS.FF3
DD.MM.YYYY HH:MI:SS TZR

timestampltzformat : 文字列

デフォルト値: ローカル・タイムゾーン形式のデータベース・タイムスタンプ
timestamptzformat

ソース・ファイル内のタイムゾーン付きタイムスタンプ・フォーマットを指定します。フォーマット・オプションAUTOを指定すると、次のフォーマットが検索されます: 

DD Mon YYYY HH:MI:SS.FF TZR  MM/DD/YYYY HH:MI:SS.FF TZR  YYYY-MM-DD HH:MI:SS+/-TZR  YYYY-MM-DD HH:MI:SS.FF3  DD.MM.YYYY HH:MI:SS TZR

timestamptzformat: 文字列

デフォルト値: タイムゾーン形式のデータベース・タイムスタンプ
trimspaces

フィールドの先頭と末尾のスペースをどのように切り捨てるかを指定します。

Oracle Database 19cユーティリティまたはOracle Database 23aiユーティリティのtrim_specの説明を参照してください。

trimspaces: rtrim| ltrim| notrim| lrtrim| ldrtrim

デフォルト値: notrim
truncatecol ファイル内のデータがフィールドに対して長すぎる場合、このオプションによって、行を拒否せずにフィールドの値を切り捨てます。

truncatecol:true

デフォルト値: False
type

ソース・ファイル・タイプを指定します。

Oracle Database 19cユーティリティまたはOracle Database 23aiユーティリティのCSVの説明を参照してください。

typeがdatapumpである場合、他の有効な形式オプションはrejectlimitのみです。

typeがdatapumpである場合、サポートされるオブジェクト・ストアはOracle Cloud Infrastructure Object StorageおよびOracle Cloud Infrastructure Object Storage Classicのみです。

type値avro、orcまたはparquetについては、「Avro、ORCおよびParquet用のDBMS_CLOUDパッケージ・フォーマット・オプション」を参照してください

For JSON data with DBMS_CLOUD.COPY_COLLECTION type has two valid values: json (default) and ejson. DBMS_CLOUD.COPY_COLLECTIONの場合、これらの値はどちらも入力がJSONデータであることを指定します。値ejsonに設定すると、テキストのJSON入力データの拡張オブジェクトがネイティブのバイナリJSONコレクションのスカラーJSON値に変換されます。値jsonは、この変換を実行せず、入力データ内のすべてのオブジェクトがバイナリJSON形式に変換されます。

DBMS_CLOUD.COPY_DATAを含むJSONデータの場合、typeに有効な値が1つあります: json。この値は、入力がJSONデータであることを指定します。

type: csv | csv with embedded | csv without embedded | avro | datapump| orc | parquet

ノート:すべてのDBMS_CLOUDプロシージャがこれらのタイプのすべてをサポートしているわけではありません。

csvは、csv without embeddedと同じです。

デフォルト値: Null

JSONデータには、DBMS_CLOUD.COPY_COLLECTIONで使用する2つの有効なtype値(json|ejson)があります。この場合、デフォルト値はjsonです。DBMS_CLOUD.COPY_DATAを含むJSONデータの場合、jsonのみが有効です。

unpackarrays

COPY_COLLECTIONでのみ使用

trueに設定すると、ロードされたドキュメントが配列の場合、配列の内容は配列自体ではなくドキュメントとしてロードされます。これは、最上位の配列にのみ適用されます。

trueに設定すると、配列全体が単一のドキュメントとして挿入されます。

このオプションは、DBMS_CLOUD.COPY_COLLECTIONを含むJSONコレクション・データでのみ有効です。

unpackarrays: true

デフォルト値: False

関連コンテンツ