DBMS_CLOUD

44 DBMS_CLOUD

DBMS_CLOUDパッケージでは、オブジェクト・ストレージのデータを操作するための包括的なサポートを提供します。

この章のトピックは、次のとおりです:

44.1 DBMS_CLOUDの概要

オブジェクト・ストレージのデータ操作にDBMS_CLOUDを使用すると、次の操作を実行できます。

オブジェクト・ストアにアクセスするための資格証明を管理します。
データをそのままコピーします: 外部データは単一のワンステップ操作でデータベースにロードされ、データベースにオブジェクトを作成する必要はありません。ロード操作は、データベース内部で監視および追跡されます。
ロード操作に関する情報を管理します。
使用前に外部データの内容を検証します。外部データの使用前に、その内容を検証して、予期される外部データ形式に準拠していない行を特定します。
外部表を作成します。柔軟で継続的な使用のために必要なオブジェクトをデータベースに作成します。
オブジェクト・ストアとディレクトリ内のオブジェクトを操作します。

44.2 DBMS_CLOUDパッケージのインストール

DBMS_CLOUDパッケージでは、Oracle Database 19c以降のリリースでオブジェクト・ストレージのデータを操作するための包括的なサポートを提供します。ただし、このパッケージはOracle Databaseでは事前インストールされません。DBMS_CLOUDパッケージは手動でインストールして、このパッケージを使用するためのユーザーまたはロールを構成する必要があります。

DBMS_CLOUDパッケージのインストールとユーザー/ロールの構成の詳細は、ドキュメントID 2748362.1のMOS-NOTEを参照してください。

44.3 DBMS_CLOUDのセキュリティ・モデル

このパッケージのセキュリティは、選択したユーザーまたはロールにこのパッケージのEXECUTE権限を付与することで制御できます。

44.4 DBMS_CLOUDの例外

次の表に、DBMS_CLOUDの例外を示します。

例外	コード	説明
`reject_limit`	20003	外部表の拒否の制限に達しました。
`credential_not_exist`	20004	資格証明オブジェクトが存在しません。
`table_not_exist`	20005	表が存在しません。
`unsupported_obj_store`	20006	サポートされていないオブジェクト・ストアURIが指定されました。
`iden_too_long`	20008	識別子が長すぎます。
`invalid_format`	20009	フォーマット引数が無効です。
`missing_credential`	20010	必須の資格証明オブジェクト情報が指定されていません。
`invalid_object_uri`	20011	無効なオブジェクトURIが指定されました。
`invalid_partitioning_clause`	20012	パーティション化句がないか、指定されていません。
`unsupported_feature`	20013	現在のデータベース・バージョンには存在しない未サポートの機能が使用されました。
`part_not_exist`	20014	パーティションまたはサブパーティションが存在しないか、表がパーティション化外部表またはハイブリッド・パーティション表ではありません。
`invalid_table_name`	20016	無効な表名が使用されました。
`invalid_schema_name`	20017	無効なスキーマ名が使用されました。
`invalid_dir_name`	20018	無効なディレクトリ名が使用されました。
`invalid_file_name`	20019	無効なファイル名が使用されました。
`invalid_cred_attribute`	20020	無効な資格証明の属性が指定されました。
`table_exist`	20021	表がすでに存在しています。
`credential_exist`	20022	資格証明オブジェクトがすでに存在します。
`invalid_req_method`	20023	リクエスト・メソッドが長すぎるか、無効です。
`invalid_req_header`	20024	無効なリクエスト・ヘッダーが指定されました。
`file_not_exist`	20025	ファイルが存在しません。
`invalid_response`	20026	HTTP応答が無効でした。
`invalid_operation`	20027	無効なタスク・クラスまたはIDが指定されました。
`invalid_user_name`	20028	無効なユーザー名が指定されました。

44.5 DBMS_CLOUDサブプログラムの要約

この項では、Oracle Databaseに付随するDBMS_CLOUDのサブプログラムについて説明します。

サブプログラム	説明
COPY_DATAプロシージャ	このプロシージャでは、クラウド内のファイルから既存のOracle Database表にデータをロードします。
AvroまたはParquetのファイルに対応するCOPY_DATAプロシージャ	このプロシージャでは、`format`パラメータの`type`を値`avro`または`parquet`に設定すると、クラウド内のAvroまたはParquetファイルから既存のOracle Database表にデータがロードされます。テキスト・ファイルと同様に、データはソースのAvroまたはParquetファイルから既存の内部表にコピーされます。
CREATE_CREDENTIALプロシージャ	このプロシージャでは、クラウド・サービスの資格証明をOracle Databaseに格納します。
CREATE_EXTERNAL_TABLEプロシージャ	このプロシージャでは、クラウド内のファイルに外部表を作成します。これにより、Oracle Databaseから外部データに対する問合せを実行できるようになります。
AvroまたはParquetファイルに対応するCREATE_EXTERNAL_TABLEプロシージャ	このプロシージャでは、`format`パラメータの`type`を値`avro`または`parquet`に設定することで、クラウドにAvroまたはParquet形式のファイルによる外部表を作成します。これにより、Oracle Databaseから外部データに対する問合せを実行できるようになります。
CREATE_EXTERNAL_PART_TABLEプロシージャ	このプロシージャでは、クラウド内のファイルにパーティション化された外部表を作成します。これにより、Oracle Databaseから外部データに対する問合せを実行できるようになります。
CREATE_HYBRID_PART_TABLEプロシージャ	このプロシージャでは、ハイブリッド・パーティション表を作成します。これにより、Oracle Databaseからハイブリッド・パーションデータに対する問合せを実行できるようになります。
DELETE_ALL_OPERATIONSプロシージャ	このプロシージャでは、スキーマ内の`user_load_operations`表に記録されているすべてのデータ・ロード操作をクリアするか、`type`パラメータで指定したタイプのすべてのデータ・ロード操作をクリアします。
DELETE_FILEプロシージャ	このプロシージャでは、Oracle Databaseの指定したディレクトリから指定したファイルを削除します
DELETE_OBJECTプロシージャ	このプロシージャでは、オブジェクト・ストアの指定したオブジェクトを削除します。
DROP_CREDENTIALプロシージャ	このプロシージャでは、Oracle Databaseから既存の資格証明を削除します。
GET_OBJECTプロシージャ/ファンクション	このプロシージャはオーバーロードされています。プロシージャ形式では、Cloud Object Storageからオブジェクトを読み取り、そのオブジェクトをOracle Databaseにコピーします。ファンクション形式では、Cloud Object Storageからオブジェクトを読み取り、`BLOB`をOracle Databaseに返します。
LIST_FILESファンクション	このファンクションでは、指定されたディレクトリにあるファイルをリストします。結果には、ファイル名とファイルに関する追加のメタデータ(バイト単位のファイル・サイズ、作成タイムスタンプ、最終変更タイムスタンプなど)が含まれます。
LIST_OBJECTSファンクション	このファンクションでは、オブジェクト・ストア内の指定された場所にあるオブジェクトをリストします。結果には、オブジェクト名とオブジェクトに関する追加のメタデータ(サイズ、チェックサム、作成タイムスタンプ、最終変更タイムスタンプなど)が含まれます。
PUT_OBJECTプロシージャ	このプロシージャはオーバーロードされています。このプロシージャには、Oracle DatabaseからCloud Object Storageにファイルをコピーする形式があります。また、このプロシージャには、Oracle DatabaseからCloud Object Storageに`BLOB`をコピーする形式もあります。
UPDATE_CREDENTIALプロシージャ	このプロシージャでは、Oracle Database内のクラウド・サービス資格証明の属性を更新します。
VALIDATE_EXTERNAL_TABLEプロシージャ	このプロシージャでは、外部表のソース・ファイルを検証して、ログ情報を生成し、外部表に指定したフォーマット・オプションと一致しない行をOracle Databaseのbadfile表に格納します。
VALIDATE_EXTERNAL_PART_TABLEプロシージャ	このプロシージャでは、パーティション化された外部表のソース・ファイルを検証して、ログ情報を生成し、外部表に指定したフォーマット・オプションと一致しない行をOracle Databaseのbadfile表に格納します。
VALIDATE_HYBRID_PART_TABLEプロシージャ	このプロシージャでは、ハイブリッド・パーション表のソース・ファイルを検証して、ログ情報を生成し、ハイブリッド表に指定したフォーマット・オプションと一致しない行をOracle Databaseのbadfile表に格納します。

44.5.1 COPY_DATAプロシージャ

このプロシージャでは、クラウド内のファイルから既存のOracle Database表にデータをロードします。オーバーロードされた形式では、operation_idパラメータを使用できるようになります。

構文

DBMS_CLOUD.COPY_DATA (
	table_name        IN VARCHAR2,
	credential_name   IN VARCHAR2,		
	file_uri_list     IN CLOB,	
	schema_name       IN VARCHAR2,
	field_list        IN CLOB,
	format            IN CLOB);

DBMS_CLOUD.COPY_DATA (
	table_name        IN VARCHAR2,
	credential_name   IN VARCHAR2 DEFAULT NULL,		
	file_uri_list     IN CLOB DEFAULT NULL,	
	schema_name       IN VARCHAR2 DEFAULT NULL,
	field_list        IN CLOB DEFAULT NULL,
	format            IN CLOB DEFAULT NULL
	operation_id      OUT NOCOPY NUMBER);

パラメータ

パラメータ	説明
`table_name`	データベースのターゲット表の名前。ターゲット表は、`COPY_DATA`を実行する前に作成しておく必要があります。
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`file_uri_list`	ソース・ファイルURIのカンマ区切りリスト。URIのファイル名にはワイルドカードを使用できます。文字"*"は、複数の文字に対応するワイルドカードとして使用できます。文字"?"は、1文字に対応するワイルドカードとして使用できます。 URIの形式は、どのCloud Object Storageサービスを使用するかによって異なります。詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。
`schema_name`	ターゲット表が存在するスキーマの名前。デフォルト値は、NULLです。この値は、ターゲット表がプロシージャを実行するユーザーと同じスキーマ内にあることを意味します。
`field_list`	ソース・ファイル内のフィールドとそのデータ型を識別します。デフォルト値は、NULLです。この値は、フィールドとそのデータ型がターゲット表の定義によって決まることを意味します。この引数の構文は、通常のOracle外部表の`field_list`句と同じです。`field_list`の詳細は、『Oracle® Databaseユーティリティ』を参照してください。 `field_list`の使用例は、「CREATE_EXTERNAL_TABLEプロシージャ」を参照してください。
`format`	ソース・ファイルの形式を示すオプション。オプションのリストと値の指定方法は、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。 AvroまたはParquetファイル・フォーマットのオプションについては、「AvroまたはParquetに対応するDBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。
`operation_id`	このパラメータは、ロード操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビューの対応するIDとして追跡するために使用します。

44.5.2 AvroまたはParquetファイルに対応するCOPY_DATAプロシージャ

このプロシージャでは、formatパラメータのtypeを値avroまたはparquetに設定すると、クラウド内のAvroまたはParquetファイルから既存のOracle Database表にデータがロードされます。テキスト・ファイルと同様に、データはソースのAvroまたはParquetファイルから既存の内部表にコピーされます。

構文

DBMS_CLOUD.COPY_DATA (
	table_name        IN VARCHAR2,
	credential_name   IN VARCHAR2,		
	file_uri_list     IN CLOB,	
	schema_name       IN VARCHAR2 DEFAULT,
	field_list        IN CLOB DEFAULT,
	format            IN CLOB DEFAULT);

パラメータ

パラメータ	説明
`table_name`	データベースのターゲット表の名前。ターゲット表は、`COPY_DATA`を実行する前に作成しておく必要があります。
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`file_uri_list`	ソース・ファイルURIのカンマ区切りリスト。URIのファイル名にはワイルドカードを使用できます。文字"*"は、複数の文字に対応するワイルドカードとして使用できます。文字"?"は、1文字に対応するワイルドカードとして使用できます。 URIの形式は、どのCloud Object Storageサービスを使用するかによって異なります。詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。
`schema_name`	ターゲット表が存在するスキーマの名前。デフォルト値は、NULLです。この値は、ターゲット表がプロシージャを実行するユーザーと同じスキーマ内にあることを意味します。
`field_list`	AvroまたはParquetファイルの場合は無視されます。ソースのフィールドは、名前によって外部表の列と一致します。ソースのデータ型は、外部表の列データ型に変換されます。 Parquetファイルに対するマッピングの詳細は、「DBMS_CLOUDパッケージのParquetからOracleデータ型へのマッピング」を参照してください。 Avroファイルに対するマッピングの詳細は、「DBMS_CLOUDパッケージのAvroからOracleデータ型へのマッピング」を参照してください。
`format`	ソース・ファイルの形式を示すオプション。AvroまたはParquetファイルについては、「AvroまたはParquetに対応するDBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。

使用上のノート

その他のデータ・ファイルと同様に、AvroとParquetのデータ・ロードにより、表dba_load_operationsとuser_load_operationsで表示可能なログが生成されます。ロード操作ごとに、ログが含まれている表を示すレコードがdba[user]_load_operationsに追加されます。

このログ表では、ロードに関するサマリー情報が示されます。
AvroまたはParquetの場合、formatのパラメータtypeが値avroまたはparquetに設定されていると、BADFILE_TABLE表は常に空になります。
- Parquetファイルの場合は、PRIMARY KEY制約のエラーによってORAエラーがスローされます。
- 列のデータに変換エラーが発生した場合(たとえば、ターゲット列の大きさが変換後の値を保持するには不十分な場合)、その列の値はNULLに設定されます。これにより拒否されたレコードの生成がなくなります。

44.5.3 CREATE_CREDENTIALプロシージャ

このプロシージャでは、クラウド・サービスの資格証明をOracle Databaseに格納します。

格納されているクラウド・サービス資格証明はデータのロードやクラウドに存在する外部データの問合せのためにクラウド・サービスにアクセスする場合や、credential_nameパラメータを指定したDBMS_CLOUDプロシージャを使用する場合に使用します。このプロシージャはオーバーロードされています。Oracle Cloud Infrastructure関連のパラメータ(user_ocid、tenancy_ocid、private_key、fingerprintなど)は、Oracle Cloud Infrastructure署名キー認証を使用している場合にのみ使用します。

構文

DBMS_CLOUD.CREATE_CREDENTIAL (
	credential_name   IN VARCHAR2,
	username          IN VARCHAR2,
	password          IN VARCHAR2 DEFAULT NULL);


DBMS_CLOUD.CREATE_CREDENTIAL (
	credential_name IN VARCHAR2,
	user_ocid       IN VARCHAR2,
	tenancy_ocid    IN VARCHAR2,
	private_key     IN VARCHAR2,
	fingerprint     IN VARCHAR2);

パラメータ

パラメータ	説明
`credential_name`	格納する資格証明の名前。
`username`	`username`引数と`password`引数の両方で、クラウド・サービスの資格証明を指定します。様々なクラウド・サービスに対する`username`と`password`の指定内容については、次を参照してください。
`password`	`username`引数と`password`引数の両方で、クラウド・サービスの資格証明を指定します。
`user_ocid`	ユーザーのOCIDを指定します。ユーザーのOCIDを取得する方法の詳細は、テナンシのOCIDとユーザーのOCIDの取得場所に関する項を参照してください。
`tenancy_ocid`	テナンシのOCIDを指定します。テナンシのOCIDを取得する方法の詳細は、テナンシのOCIDとユーザーのOCIDの取得場所に関する項を参照してください。
`private_key`	生成した秘密キーを指定します。パスフレーズ付きで生成したプライベート・キーはサポートされていません。この秘密キーは、パスフレーズなしで生成する必要があります。PEM形式でキー・ペアを生成する方法の詳細は、API署名キーの生成方法に関する項を参照してください。
`fingerprint`	フィンガープリントを指定します。ユーザーのアカウントに生成した公開キーをアップロードすると、コンソールにフィンガープリントが表示されます。この引数には表示されたフィンガープリントを使用します。詳細は、キーのフィンガープリントの取得方法に関する項およびAPI署名キーの生成方法に関する項を参照してください。

使用上のノート

この操作では、資格証明が暗号化形式でデータベースに格納されます。
user_credentials表を問い合せると、自分のスキーマの資格証明を確認できます。
ADMINユーザーは、dba_credentials表を問い合せると、すべての資格証明を確認できます。
資格証明の作成は、クラウド・サービスの資格証明が変更されないかぎり1回のみ必要です。資格証明を格納すると、credential_nameパラメータが必要になるDBMS_CLOUDプロシージャに同じ名前の資格証明を使用できるようになります。
このプロシージャはオーバーロードされています。キー・ベース認証の属性user_ocid、tenancy_ocid、private_keyまたはfingerprintのいずれかを指定すると、コールはOracle Cloud Infrastructure署名キー・ベースの資格証明とみなされます。
Oracle Cloud Infrastructureでは、パスフレーズ付きで生成した秘密キーがサポートされません。この秘密キーは、パスフレーズなしで生成する必要があります。詳細は、API署名キーの生成方法に関する項を参照してください。

Oracle Cloud Infrastructure資格証明(認証トークン)

Oracle Cloud Infrastructureの場合、usernameはOracle Cloud Infrastructureユーザー名です。passwordは、Oracle Cloud Infrastructure認証トークンです。「認証トークンの使用」を参照してください。

Oracle Cloud Infrastructure Object Storage Classicの資格証明

ソース・ファイルがOracle Cloud Infrastructure Object Storage Classicにある場合、usernameはOracle Cloud Infrastructure Classicユーザー名になり、passwordはOracle Cloud Infrastructure Classicパスワードになります。

Amazon Web Services (AWS)資格証明

ソース・ファイルがAmazon S3にある場合やAWS APIをコールする場合、usernameはAWSアクセス・キーIDになり、passwordはAWSシークレット・アクセス・キーになります。「AWS IDとアクセス管理」を参照してください。

Microsoft Azure資格証明

ソース・ファイルがAzure Blob Storageにある場合やAzure APIをコールする場合、usernameはAzureストレージのアカウント名になり、passwordはAzureストレージのアカウント・アクセス・キーになります。「Azureストレージ・アカウントについて」を参照してください。

44.5.4 CREATE_EXTERNAL_TABLEプロシージャ

このプロシージャでは、クラウド内のファイルに外部表を作成します。これにより、Oracle Databaseから外部データに対する問合せを実行できるようになります。

構文

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
	table_name       IN VARCHAR2,
	credential_name  IN VARCHAR2,		
	file_uri_list    IN CLOB,	
	column_list      IN CLOB,
	field_list       IN CLOB DEFAULT,
	format           IN CLOB DEFAULT);

パラメータ

パラメータ	説明
`table_name`	外部表の名前。
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`file_uri_list`	ソース・ファイルURIのカンマ区切りリスト。URIのファイル名にはワイルドカードを使用できます。文字"*"は、複数の文字に対応するワイルドカードとして使用できます。文字"?"は、1文字に対応するワイルドカードとして使用できます。 URIの形式は、どのCloud Object Storageサービスを使用するかによって異なります。詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。
`column_list`	外部表の列名とデータ型のカンマ区切りリスト。
`field_list`	ソース・ファイル内のフィールドとそのデータ型を識別します。デフォルト値は、NULLです。この値は、フィールドとそのデータ型がcolumn_listパラメータによって決まることを意味します。この引数の構文は、通常のOracle外部表の`field_list`句と同じです。`field_list`の詳細は、『Oracle® Databaseユーティリティ』を参照してください。
`format`	ソース・ファイルの形式を示すオプション。オプションのリストと値の指定方法は、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。 AvroまたはParquet形式のファイルについては、「AvroまたはParquetファイルに対応するCREATE_EXTERNAL_TABLEプロシージャ」を参照してください。

使用上のノート

プロシージャDBMS_CLOUD.CREATE_EXTERNAL_TABLEでは、次のものを含むサポート対象クラウド・オブジェクト・ストレージ・サービスでパーティション化された外部ファイルをサポートしています。
- Oracle Cloud Infrastructureオブジェクト・ストレージ
- Azure Blob Storage
- Amazon S3
資格証明は表レベルのプロパティであるため、外部ファイルは同じオブジェクト・ストアに存在している必要があります。

詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。

例

BEGIN  
   DBMS_CLOUD.CREATE_EXTERNAL_TABLE(   
      table_name =>'WEATHER_REPORT_DOUBLE_DATE',   
      credential_name =>'OBJ_STORE_CRED',   
      file_uri_list =>'&base_URL/Charlotte_NC_Weather_History_Double_Dates.csv',
      format => json_object('type' value 'csv', 'skipheaders' value '1'),   
      field_list => 'REPORT_DATE DATE''mm/dd/yy'',                   
                     REPORT_DATE_COPY DATE ''yyyy-mm-dd'',
                     ACTUAL_MEAN_TEMP,                 
                     ACTUAL_MIN_TEMP,                 
                     ACTUAL_MAX_TEMP,                 
                     AVERAGE_MIN_TEMP,                    
                     AVERAGE_MAX_TEMP,     
                     AVERAGE_PRECIPITATION',   
      column_list => 'REPORT_DATE DATE,   
                     REPORT_DATE_COPY DATE,
                     ACTUAL_MEAN_TEMP NUMBER,  
                     ACTUAL_MIN_TEMP NUMBER,  
                     ACTUAL_MAX_TEMP NUMBER,  
                     AVERAGE_MIN_TEMP NUMBER,   
                     AVERAGE_MAX_TEMP NUMBER,                  
                     AVERAGE_PRECIPITATION NUMBER');
   END;
/ 

SELECT * FROM WEATHER_REPORT_DOUBLE_DATE where         
   actual_mean_temp > 69 and actual_mean_temp < 74

44.5.5 AvroまたはParquetファイルに対応するCREATE_EXTERNAL_TABLEプロシージャ

このプロシージャでは、formatパラメータのtypeを値avroまたはparquetに設定することで、クラウドにAvroまたはParquet形式のファイルによる外部表を作成します。これにより、Oracle Databaseから外部データに対する問合せを実行できるようになります。

構文

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
	table_name       IN VARCHAR2,
	credential_name  IN VARCHAR2,		
	file_uri_list    IN CLOB,
	column_list      IN CLOB,
	field_list       IN CLOB DEFAULT,
	format           IN CLOB DEFAULT);

パラメータ

パラメータ	説明
`table_name`	外部表の名前。
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`file_uri_list`	ソース・ファイルURIのカンマ区切りリスト。URIのファイル名にはワイルドカードを使用できます。文字"*"は、複数の文字に対応するワイルドカードとして使用できます。文字"?"は、1文字に対応するワイルドカードとして使用できます。 URIの形式は、どのCloud Object Storageサービスを使用するかによって異なります。詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。
`column_list`	(オプション)このフィールドを指定すると、スキーマ、列およびデータ型の自動導出を指定する`format->schema`パラメータがオーバーライドされます。詳細は、formatパラメータを参照してください。 AvroまたはParquetソースに対して`column_list`を指定する場合は、列名がファイル内の列と一致する必要があります。Oracleデータ型は、AvroまたはParquetデータ型に適切にマップする必要があります。 Parquetファイルの詳細は、「DBMS_CLOUDパッケージのParquetからOracleデータ型へのマッピング」を参照してください。 Avroファイルの詳細は、「DBMS_CLOUDパッケージのAvroからOracleデータ型へのマッピング」を参照してください。
`field_list`	AvroまたはParquetファイルの場合は無視されます。ソースのフィールドは、名前によって外部表の列と一致します。ソースのデータ型は、外部表の列データ型に変換されます。 Parquetファイルの詳細は、「DBMS_CLOUDパッケージのParquetからOracleデータ型へのマッピング」を参照してください。 Avroファイルの詳細は、「DBMS_CLOUDパッケージのAvroからOracleデータ型へのマッピング」を参照してください。
`format`	AvroまたはParquetの場合、サポートされているパラメータは2つのみです。詳細は、「AvroまたはParquetに対応するDBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。

Avroの例

format => '{"type":"avro", "schema": "all"}'

format => json_object('type' value 'avro', 'schema' value 'first')

Parquetの例

format => '{"type":"parquet", "schema": "all"}'

format => json_object('type' value 'parquet', 'schema' value 'first')

AvroまたはParquet列名のOracle列名へのマッピング

Oracle SQLの列名のマッピング方法と列名の変換の使用方法の詳細は、「DBMS_CLOUDパッケージのAvroおよびParquetからOracle列名へのマッピング」を参照してください。

44.5.6 CREATE_EXTERNAL_PART_TABLEプロシージャ

このプロシージャでは、クラウド内のファイルにパーティション化された外部表を作成します。これにより、Oracle Databaseから外部データに対する問合せを実行できるようになります。

構文

DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE (
	table_name           IN VARCHAR2,
	credential_name      IN VARCHAR2,		
	partitioning_clause  IN CLOB,	
	column_list          IN CLOB,
	field_list           IN CLOB DEFAULT,
	format               IN CLOB DEFAULT);

パラメータ

パラメータ	説明
`table_name`	外部表の名前。
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`partitioning_clause`	個別のパーティションの場所情報を含む、完全なパーティション化句を指定します。
`column_list`	外部表の列名とデータ型のカンマ区切りリスト。
`field_list`	ソース・ファイル内のフィールドとそのデータ型を識別します。デフォルト値は、NULLです。この値は、フィールドとそのデータ型がcolumn_listパラメータによって決まることを意味します。この引数の構文は、通常のOracle外部表の`field_list`句と同じです。`field_list`の詳細は、『Oracle® Databaseユーティリティ』を参照してください。
`format`	ソース・ファイルの形式を示すオプション。オプションのリストと値の指定方法は、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。

使用上のノート

DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEを使用したAvro or Parquetのデータ・フォーマットには、schemaフォーマット・オプションを使用できません。column_listパラメータを指定する必要があります。schemaフォーマット・オプションは、DBMS_CLOUD.CREATE_EXTERNAL_TABLEで使用できます。
プロシージャDBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEでは、次のものを含むサポート対象クラウド・オブジェクト・ストレージ・サービスでパーティション化された外部ファイルをサポートしています。
- Oracle Cloud Infrastructureオブジェクト・ストレージ
- Azure Blob Storage
- Amazon S3
詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。

例

BEGIN  
   DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
      table_name =>'PET1',  
      credential_name =>'OBJ_STORE_CRED',
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),  
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) location
                                    ( ''&base_URL//file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000) location 
                                    ( ''&base_URL/file_31.txt'')
                                 )'
     );
   END;
/

44.5.7 CREATE_HYBRID_PART_TABLEプロシージャ

このプロシージャでは、ハイブリッド・パーティション表を作成します。これにより、Oracle Databaseからハイブリッド・パーションデータに対する問合せを実行できるようになります。

構文

DBMS_CLOUD.CREATE_HYBRID_PART_TABLE (
	table_name           IN VARCHAR2,
	credential_name      IN VARCHAR2,		
	partitioning_clause  IN CLOB,	
	column_list          IN CLOB,
	field_list           IN CLOB DEFAULT,
	format               IN CLOB DEFAULT);

パラメータ

パラメータ	説明
`table_name`	外部表の名前。
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`partitioning_clause`	個別のパーティションの場所情報を含む、完全なパーティション化句を指定します。
`column_list`	外部表の列名とデータ型のカンマ区切りリスト。
`field_list`	ソース・ファイル内のフィールドとそのデータ型を識別します。デフォルト値は、NULLです。この値は、フィールドとそのデータ型がcolumn_listパラメータによって決まることを意味します。この引数の構文は、通常のOracle外部表の`field_list`句と同じです。`field_list`の詳細は、『Oracle® Databaseユーティリティ』を参照してください。
`format`	ソース・ファイルの形式を示すオプション。オプションのリストと値の指定方法は、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。

使用上のノート

プロシージャDBMS_CLOUD.CREATE_HYBRID_PART_TABLEでは、次のものを含むサポート対象クラウド・オブジェクト・ストレージ・サービスでパーティション化された外部ファイルをサポートしています。
- Oracle Cloud Infrastructureオブジェクト・ストレージ
- Azure Blob Storage
- Amazon S3
資格証明は表レベルのプロパティであるため、外部ファイルは同じオブジェクト・ストアに存在している必要があります。

詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。

例

BEGIN  
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
      table_name =>'HPT1',  
      credential_name =>'OBJ_STORE_CRED',  
      format => json_object('delimiter' value ',', 'recorddelimiter' value 'newline', 'characterset' value 'us7ascii'),  
      column_list => 'col1 number, col2 number, col3 number',
      partitioning_clause => 'partition by range (col1)
                                (partition p1 values less than (1000) external location
                                    ( ''&base_URL/file_11.txt'')
                                 ,
                                 partition p2 values less than (2000) external location
                                    ( ''&base_URL/file_21.txt'')
                                 ,
                                 partition p3 values less than (3000)
                                 )'
     );
   END;
/

44.5.8 DELETE_ALL_OPERATIONSプロシージャ

このプロシージャでは、スキーマ内のuser_load_operations表に記録されているすべてのデータ・ロード操作をクリアするか、typeパラメータで指定したタイプのすべてのデータ・ロード操作をクリアします。

構文

DBMS_CLOUD.DELETE_ALL_OPERATIONS (
	type      IN VARCHAR DEFAULT NULL);

パラメータ

パラメータ説明

パラメータ	説明
`type`	削除する操作のタイプを指定します。Typeの値は、`user_load_operations`表の`TYPE`列でわかります。 `type`の指定がない場合は、すべての行が削除されます。

type

削除する操作のタイプを指定します。Typeの値は、user_load_operations表のTYPE列でわかります。

typeの指定がない場合は、すべての行が削除されます。

使用上のノート

DBMS_CLOUD.DELETE_ALL_OPERATIONSでは、現在実行中の操作(「実行中」ステータスの操作)は削除されません。

44.5.9 DELETE_FILEプロシージャ

このプロシージャでは、Oracle Databaseの指定したディレクトリから指定したファイルを削除します。

構文

 DBMS_CLOUD.DELETE_FILE ( 
       directory_name     IN VARCHAR2,
       file_name          IN VARCHAR2);

パラメータ

パラメータ	説明
`directory_name`	Oracle Databaseインスタンスにあるディレクトリの名前。
`file_name`	削除するファイルの名前。

ノート:

DBMS_CLOUD.DELETE_FILEを実行するには、そのユーザーに対象ファイルを格納しているディレクトリに対する書込み権限を付与する必要があります。たとえば、次のコマンドをADMINとして実行し、db_userに書込み権限を付与します。

GRANT WRITE ON DIRECTORY data_pump_dir TO db_user;

例

BEGIN
   DBMS_CLOUD.DELETE_FILE(
      directory_name =>  'DATA_PUMP_DIR',
      file_name => 'exp1.dmp' );
   END;
/

44.5.10 DELETE_OBJECTプロシージャ

このプロシージャでは、オブジェクト・ストアの指定したオブジェクトを削除します。

構文

DBMS_CLOUD.DELETE_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2);

パラメータ

パラメータ	説明
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`object_uri`	削除するオブジェクトのオブジェクトまたはファイルURI。URIの形式は、どのCloud Object Storageサービスを使用するかによって決まります。詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。

例

BEGIN
   DBMS_CLOUD.DELETE_OBJECT(
       credential_name => 'DEF_CRED_NAME',
       object_uri => 'https://objectstorage.us-ashburn-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.dmp');
   END;
/

44.5.11 DROP_CREDENTIALプロシージャ

このプロシージャでは、Oracle Databaseから既存の資格証明を削除します。

構文

DBMS_CLOUD.DROP_CREDENTIAL (
   credential_name     IN VARCHAR2);

パラメータ

パラメータ	説明
`credential_name`	削除する資格証明の名前。

44.5.12 GET_OBJECTプロシージャ/ファンクション

このプロシージャはオーバーロードされています。プロシージャ形式では、Cloud Object Storageからオブジェクトを読み取り、そのオブジェクトをOracle Databaseにコピーします。ファンクション形式では、Cloud Object Storageからオブジェクトを読み取り、BLOBをOracle Databaseに返します。

構文

DBMS_CLOUD.GET_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2 DEFAULT  NULL,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL);


DBMS_CLOUD.GET_OBJECT(
       credential_name      IN VARCHAR2 DEFAULT NULL,
       object_uri           IN VARCHAR2,
       startoffset          IN NUMBER DEFAULT  0,
       endoffset            IN NUMBER DEFAULT  0,
       compression          IN VARCHAR2 DEFAULT  NULL)
RETURN BLOB;

パラメータ

パラメータ	説明
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`object_uri`	オブジェクトまたはファイルURI。URIの形式は、どのCloud Object Storageサービスを使用するかによって決まります。詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。
`directory_name`	データベースにあるディレクトリの名前。 ^脚注 1
`file_name`	作成するファイルの名前を指定します。ファイル名の指定がない場合、ファイル名は`object_uri`パラメータの最後のスラッシュの後から取得されます。ファイル名にスラッシュが含まれている場合などの特殊なケースに、`file_name`パラメータを使用します。
`startoffset`	プロシージャが読取りを開始する場所のオフセット(バイト単位)。
`endoffset`	プロシージャが読取りを終了する場所のオフセット(バイト単位)。
`compression`	オブジェクトの格納に使用する圧縮を指定します。`compression`が`'AUTO'`に設定されている場合、ファイルは圧縮解除されます(値`'AUTO'`は、`object_uri`で指定されたオブジェクトがGzipで圧縮されることを意味します)。

^脚注1

ノート:

DBMS_CLOUD.GET_OBJECTを実行するには、そのユーザーにそのディレクトリに対する書込み権限を付与する必要があります。たとえば、次のコマンドをADMINとして実行し、db_userに書込み権限を付与します。

GRANT WRITE ON DIRECTORY data_pump_dir TO db_user;

戻り値

ファンクション形式では、オブジェクト・ストアから読み取り、DBMS_CLOUD.GET_OBJECTはBLOBを戻します。

例

BEGIN 
   DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt',
     directory_name => 'DATA_PUMP_DIR'); 
END;
/

オブジェクト・ストア内のファイルから文字データを読み取るには:

SELECT to_clob(
     DBMS_CLOUD.GET_OBJECT(
       credential_name => 'OBJ_STORE_CRED',
       object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/file.txt'))
FROM DUAL;

オブジェクト・ストア内に格納されているイメージをデータベース内のBLOBに追加するには:


DECLARE
   l_blob BLOB := NULL;
BEGIN
   l_blob := DBMS_CLOUD.GET_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/MyImage.gif' );
END;
/

この例では、namespace-stringは、Oracle Cloud Infrastructureオブジェクト・ストレージ・ネームスペースです。また、bucketnameはバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの概要に関する項を参照してください。

44.5.13 LIST_FILESファンクション

このファンクションでは、指定されたディレクトリにあるファイルをリストします。結果には、ファイル名とファイルに関する追加のメタデータ(バイト単位のファイル・サイズ、作成タイムスタンプ、最終変更タイムスタンプなど)が含まれます。

構文

DBMS_CLOUD.LIST_FILES (
	directory_name      IN VARCHAR2)
       RETURN TABLE;

パラメータ

パラメータ	説明
`directory_name`	データベースにあるディレクトリの名前。

使用上のノート

DBMS_CLOUD.LIST_FILESは、Oracle File System (OFS)またはデータベース・ファイル・システム(DBFS)のファイル・システムへのディレクトリ・オブジェクト・マッピングでのみサポートされます。
DBMS_CLOUD.LIST_FILESを実行するには、そのユーザーにそのディレクトリに対する読取り権限を付与する必要があります。たとえば、次のコマンドをADMINとして実行し、db_userに読取り権限を付与します。
```
GRANT READ ON DIRECTORY data_pump_dir TO db_user;
```
これは、戻り値のタイプがDBMS_CLOUD_TYPES.list_object_ret_tのパイプライン・テーブル・ファンクションです。
DBMS_CLOUD.LIST_FILESはチェックサム値を取得せず、このフィールドに対してNULLを返します。

例

これは、各ファイルの行を返すパイプライン関数です。たとえば、このファンクションを使用するには、次の問合せを使用します。

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR');

OBJECT_NAME       BYTES   CHECKSUM      CREATED              LAST_MODIFIED
------------ ---------- ----------    ---------------------  ---------------------
cwallet.sso        2965               2018-12-12T18:10:47Z   2019-11-23T06:36:54Z

44.5.14 LIST_OBJECTSファンクション

このファンクションでは、オブジェクト・ストア内の指定された場所にあるオブジェクトをリストします。結果には、オブジェクト名とオブジェクトに関する追加のメタデータ(サイズ、チェックサム、作成タイムスタンプ、最終変更タイムスタンプなど)が含まれます。

構文

DBMS_CLOUD.LIST_OBJECTS (
       credential_name      IN VARCHAR2,
       location_uri         IN VARCHAR2)
   RETURN TABLE;

パラメータ

パラメータ	説明
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`location_uri`	オブジェクトまたはファイルURI。URIの形式は、どのCloud Object Storageサービスを使用するかによって決まります。詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。

使用上のノート

オブジェクト・ストアの機能によって、DBMS_CLOUD.LIST_OBJECTSが特定の属性の値を返さないことがあります。その場合、フィールドの戻り値はNULLになります。

サポートされているすべてのオブジェクト・ストアは、OBJECT_NAME、BYTESおよびCHECKSUMフィールドの戻り値を返します。

次の表に、オブジェクト・ストアごとのフィールドCREATEDおよびLAST_MODIFIEDのサポートを示します。

オブジェクト・ストア	`CREATED`	`LAST_MODIFIED`
Oracle Cloud Infrastructure Native	タイムスタンプが戻されます	`NULL`が戻されます
Oracle Cloud Infrastructure Swift	`NULL`が戻されます	タイムスタンプが戻されます
Oracle Cloud Infrastructure Classic	`NULL`が戻されます	タイムスタンプが戻されます
Amazon S3	`NULL`が戻されます	タイムスタンプが戻されます
Azure	タイムスタンプが戻されます	タイムスタンプが戻されます

チェックサム値は、MD5チェックサムです。これは、オブジェクトの内容に対して計算される32文字の16進数です。OCI$RESOURCE_PRINCIPAL資格証明を使用する場合、チェックサム値は異なる必要があります。
これは、戻り値のタイプがDBMS_CLOUD_TYPES.list_object_ret_tのパイプライン・テーブル・ファンクションです。

例

これは、オブジェクトごとの行を返すパイプライン関数です。たとえば、このファンクションを使用するには、次の問合せを使用します。

SELECT * FROM DBMS_CLOUD.LIST_OBJECTS('OBJ_STORE_CRED', 
    'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/');


OBJECT_NAME   BYTES              CHECKSUM                       CREATED         LAST_MODIFIED
------------ ---------- -------------------------------- --------------------- --------------------
cwallet.sso   2965      2339a2731ba24a837b26d344d643dc07 2019-11-23T06:36:54Z

44.5.15 PUT_OBJECTプロシージャ

このプロシージャはオーバーロードされています。このプロシージャには、Oracle DatabaseからCloud Object Storageにファイルをコピーする形式があります。また、このプロシージャには、Oracle DatabaseからCloud Object StorageにBLOBをコピーする形式もあります。

構文

DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       directory_name       IN VARCHAR2,
       file_name            IN VARCHAR2);


DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       contents             IN BLOB,
       file_name            IN VARCHAR2);

パラメータ

パラメータ	説明
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`object_uri`	オブジェクトまたはファイルURI。URIの形式は、どのCloud Object Storageサービスを使用するかによって決まります。詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。
`directory_name`	Oracle Databaseにあるディレクトリの名前。 ^脚注 2
`file_name`	指定したディレクトリ内のファイルの名前。

^脚注2

ノート:

DBMS_CLOUD.PUT_OBJECTを実行するには、そのユーザーにそのディレクトリに対する読取り権限を付与する必要があります。たとえば、次のコマンドをADMINとして実行し、db_userに読取り権限を付与します。

GRANT READ ON DIRECTORY data_pump_dir TO db_user;

例

データベース内処理後にBLOBデータを処理して、そのデータをオブジェクト・ストアのファイルに直接格納するには:

DECLARE
      my_blob_data BLOB;
BEGIN 
 /* Some processing producing BLOB data and populating my_blob_data */
DBMS_CLOUD.PUT_OBJECT(
     credential_name => 'OBJ_STORE_CRED',
     object_uri => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/my_new_file',
     contents => my_blob_data)); 
END;
/

使用上のノート

Cloud Object Storageに応じて、転送するオブジェクトのサイズが次のように制限されます。

Cloud Object Storageサービス	オブジェクトの転送サイズ制限
Oracle Cloud Infrastructureオブジェクト・ストレージ	50GB
Amazon S3	5GB
Azure Blob Storage	256MB

Oracle Cloud Infrastructureオブジェクト・ストアでは、資格証明を指定していないとパブリック・バケットにファイルを書き込むことができません(Oracle Cloud Infrastructureでは、パブリック・バケットからユーザーがオブジェクトをダウンロードできます)。そのため、PUT_OBJECTを使用してOracle Cloud Infrastructureパブリック・バケットにオブジェクトを格納するには、有効な資格証明が含まれている資格証明の名を指定する必要があります。

詳細は、「DBMS_CLOUDパッケージ・ファイルURIの形式」を参照してください。

44.5.16 UPDATE_CREDENTIALプロシージャ

このプロシージャでは、Oracle Database内のクラウド・サービス資格証明の属性を更新します。

格納した資格証明は、データのロードやクラウドに存在する外部データを問い合せる場合や、DBMS_CLOUDプロシージャの使用時にcredential_nameパラメータを指定する場合に使用します。このプロシージャを使用すると、指定したcredential_nameの属性を新しい値で更新できます。

構文

DBMS_CLOUD.UPDATE_CREDENTIAL (
	credential_name   IN VARCHAR2,
	attribute         IN VARCHAR2,
	value             IN VARCHAR2);

パラメータ

パラメータ	説明
`credential_name`	格納する資格証明の名前。
`attribute`	更新する属性の名前: `USERNAME`または`PASSWORD`。
`value`	選択した属性の新しい値。

使用上のノート

ユーザー名では大文字と小文字が区別されます。二重引用符または空白を含むことはできません。
資格証明の作成は、クラウド・サービスの資格証明が変更されないかぎり1回のみ必要です。資格証明を格納すると、credential_nameパラメータが必要になるDBMS_CLOUDプロシージャに同じ名前の資格証明を使用できるようになります。

例

BEGIN
  DBMS_CLOUD.UPDATE_CREDENTIAL(
     credential_name => 'OBJ_STORE_CRED',
     attribute => 'PASSWORD',
     value => 'password'); 
END;
/

44.5.17 VALIDATE_EXTERNAL_TABLEプロシージャ

このプロシージャでは、外部表のソース・ファイルを検証して、ログ情報を生成し、外部表に指定したフォーマット・オプションと一致しない行をOracle Databaseのbadfile表に格納します。オーバーロードされた形式では、operation_idパラメータを使用できるようになります。

構文

DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE (
	table_name      IN VARCHAR2,
	schema_name     IN VARCHAR2 DEFAULT,		
	rowcount        IN NUMBER DEFAULT,
	stop_on_error   IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE(
	table_name      IN VARCHAR2,
	operation_id    OUT NOCOPY NUMBER,
	schema_name     IN VARCHAR2 DEFAULT NULL,		
	rowcount        IN NUMBER DEFAULT 0,
	stop_on_error   IN BOOLEAN DEFAULT TRUE);

パラメータ

パラメータ	説明
`table_name`	外部表の名前。
`operation_id`	このパラメータは、ロード操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビューの対応するIDとして追跡するために使用します。
`schema_name`	外部表が存在するスキーマの名前。デフォルト値は、NULLです。この値は、外部表がプロシージャを実行するユーザーと同じスキーマ内にあることを意味します。
`rowcount`	スキャンされる行数デフォルト値は、NULLです。ソース・ファイルのすべての行がスキャンされることを意味します。
`stop_on_error`	行が拒否されたときに検証を停止するかどうかを決定します。デフォルト値は、`TRUE`です。この値は、検証が最初に拒否された行で停止することを意味します。この値を`FALSE`に設定すると、検証が最初に拒否された行で停止せずに、`rowcount`パラメータで指定された値までのすべての行が検証されます。外部表がAvroまたはParquetファイルを参照している場合は、最初に拒否された行で検証が停止します。外部表で`format`パラメータの`type`が値`avro`または`parquet`に設定されている場合、実質的にパラメータ`stop_on_error`の値は常に`TRUE`になります。そのため、AvroまたはParquetファイルを参照する外部表については、表badfileが常に空の状態になります。

使用上のノート

DBMS_CLOUD.VALIDATE_EXTERNAL_TABLEは、パーティション化された外部表とハイブリッド・パーティション表の両方に機能します。これは、rowcountに達するか、stop_on_errorが適用されるまで、すべての外部パーティションからデータを読み取る可能性があります。読み取るパーティションまたはパーティションの部分の順序は制御できません。

44.5.18 VALIDATE_EXTERNAL_PART_TABLEプロシージャ

このプロシージャでは、パーティション化された外部表のソース・ファイルを検証して、ログ情報を生成し、外部表に指定したフォーマット・オプションと一致しない行をOracle Databaseのbadfile表に格納します。オーバーロードされた形式では、operation_idパラメータを使用できるようになります。

構文

DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

パラメータ

パラメータ	説明
`table_name`	外部表の名前。
`operation_id`	このパラメータは、ロード操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビューの対応するIDとして追跡するために使用します。
`partition_name`	定義すると場合、特定のパーティションのみが検証されます。指定がない場合は、`rowcount`に達するまで、すべてのパーティションを順次読み取ります。
`schema_name`	外部表が存在するスキーマの名前。デフォルト値は、NULLです。この値は、外部表がプロシージャを実行するユーザーと同じスキーマ内にあることを意味します。
`rowcount`	スキャンされる行数デフォルト値は、NULLです。ソース・ファイルのすべての行がスキャンされることを意味します。
`partition_key_validation`	内部使用のみに対応しています。このパラメータは使用しないでください。
`stop_on_error`	行が拒否されたときに検証を停止するかどうかを決定します。デフォルト値は、`TRUE`です。この値は、検証が最初に拒否された行で停止することを意味します。この値を`FALSE`に設定すると、検証が最初に拒否された行で停止せずに、`rowcount`パラメータで指定された値までのすべての行が検証されます。外部表がAvroまたはParquetファイルを参照している場合は、最初に拒否された行で検証が停止します。外部表で`format`パラメータの`type`が値`avro`または`parquet`に設定されている場合、実質的にパラメータ`stop_on_error`の値は常に`TRUE`になります。そのため、AvroまたはParquetファイルを参照する外部表については、表badfileが常に空の状態になります。

44.5.19 VALIDATE_HYBRID_PART_TABLEプロシージャ

このプロシージャでは、ハイブリッド・パーション表のソース・ファイルを検証して、ログ情報を生成し、ハイブリッド表に指定したフォーマット・オプションと一致しない行をOracle Databaseのbadfile表に格納します。オーバーロードされた形式では、operation_idパラメータを使用できるようになります。

構文

DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);


DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       operation_id               OUT NUMBER,
       partition_name             IN CLOB DEFAULT,
       schema_name                IN VARCHAR2 DEFAULT,
       rowcount                   IN NUMBER DEFAULT,
       partition_key_validation   IN BOOLEAN DEFAULT,
       stop_on_error              IN BOOLEAN DEFAULT);

パラメータ

パラメータ	説明
`table_name`	外部表の名前。
`operation_id`	このパラメータは、ロード操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビューの対応するIDとして追跡するために使用します。
`partition_name`	定義すると場合、特定のパーティションのみが検証されます。指定がない場合は、`rowcount`に達するまで、すべての外部パーティションから順次読み取ります。
`schema_name`	外部表が存在するスキーマの名前。デフォルト値は、NULLです。この値は、外部表がプロシージャを実行するユーザーと同じスキーマ内にあることを意味します。
`rowcount`	スキャンされる行数デフォルト値は、NULLです。ソース・ファイルのすべての行がスキャンされることを意味します。
`partition_key_validation`	内部使用のみに対応しています。このパラメータは使用しないでください。
`stop_on_error`	行が拒否されたときに検証を停止するかどうかを決定します。デフォルト値は、`TRUE`です。この値は、検証が最初に拒否された行で停止することを意味します。この値を`FALSE`に設定すると、検証が最初に拒否された行で停止せずに、`rowcount`パラメータで指定された値までのすべての行が検証されます。外部表がAvroまたはParquetファイルを参照している場合は、最初に拒否された行で検証が停止します。外部表で`format`パラメータの`type`が値`avro`または`parquet`に設定されている場合、実質的にパラメータ`stop_on_error`の値は常に`TRUE`になります。そのため、AvroまたはParquetファイルを参照する外部表については、表badfileが常に空の状態になります。

44.6 DBMS_CLOUDパッケージ・ファイルURIの形式

DBMS_CLOUDの操作におけるソース・ファイルURIの形式について説明します。この形式は、どのオブジェクト記憶域サービスを使用するかによって異なります。

DBMS_CLOUDでは、セキュアな通信が保証され、URIの指定にはHTTPS (URIの接頭辞がhttps://)を使用する必要があります。

トピック

44.6.1 Oracle Cloud Infrastructure Object Storage NativeのURI形式

ソース・ファイルがOracle Cloud Infrastructure Object Storageに存在する場合は、次の形式でOracle Cloud InfrastructureネイティブURIを使用できます。

https://objectstorage.region.oraclecloud.com/n/namespace-string/b/bucket/o/filename

たとえば、Phoenixデータ・センターのbucketnameバケット内にあるファイルchannels.txtの場合、Native URIは次のようになります。

https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/channels.txt

このURIは、オブジェクト・ストアの右側の省略記号メニューにあるOracle Cloud Infrastructure Object Storageの「オブジェクトの詳細」から確認できます。

Oracle Cloud Infrastructureの左側にあるリストから、「オブジェクト・ストレージ」→「オブジェクト・ストレージ」をクリックします。
「名前」列からバケットを選択します。
「オブジェクト」領域で、「オブジェクト詳細の表示」をクリックします。

図ad_oci_view_object_details.pngの説明
「オブジェクトの詳細」ページの「URLパス(URI)」フィールドに、オブジェクトにアクセスするためのURIが表示されます。

ノート:

ソース・ファイルは、オブジェクト・ストレージ層バケットに格納されている必要があります。Oracle Databaseでは、アーカイブ・ストレージ層のバケットはサポートされません。詳細は、オブジェクト・ストレージの概要に関する項を参照してください。

44.6.2 Oracle Cloud Infrastructure Object Storage SwiftのURI形式

ソース・ファイルがOracle Cloud Infrastructure Object Storageに存在する場合は、次の形式でOracle Cloud Infrastructure Swift URIを使用できます。

https://swiftobjectstorage.region.oraclecloud.com/v1/namespace-string/bucket/filename

たとえば、Phoenixデータ・センターのbucketnameバケット内にあるファイルchannels.txtの場合、Swift URIは次のようになります。

https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/namespace-string/bucketname/channels.txt

ノート:

44.6.3 事前認証済リクエストURLを使用したOracle Cloud Infrastructure Object StorageのURI形式

ソース・ファイルがOracle Cloud Infrastructure Object Storageに存在する場合は、Oracle Cloud Infrastructure事前認証済URIを使用できます。事前認証済リクエストの作成時に、一意のURLが生成されます。この一意のURLを組織内のユーザー、パートナーまたはサード・パーティに提供することで、事前認証済リクエストで識別されるオブジェクト・ストレージ・リソースのターゲットにアクセスできるようにします。

ノート:

事前認証済アクセスのビジネス要件とセキュリティへの影響は慎重に評価してください。事前認証済リクエストURLの作成時には、有効期限とアクセス・タイプをメモして、使用目的に適していることを確認します。

事前認証済リクエストURLは、リクエストがアクティブであるかぎり、そのURLを持つすべてのユーザーにリクエストで特定されるターゲットへのアクセス権を与えます。事前認証済アクセスの運用ニーズについて考慮することに加えて、その配布について管理することも同様に重要です。

次に、事前認証済リクエストのURLの形式を示します。

https://objectstorage.region.oraclecloud.com/p/encrypted_string/n/namespace-string/b/bucket/o/filename

たとえば、Phoenixデータ・センターのbucketnameバケット内にあるファイルchannels.txtの場合、事前認証済URIの例は次のようになります。

https://objectstorage.us-phoenix-1.oraclecloud.com/p/2xN-uDtWJNsiD910UCYGue/n/namespace-string/b/bucketname/o/channels.txt

事前認証済URLは、資格証明を作成することなくOracle Cloud Infrastructureオブジェクト・ストア内のファイルにアクセスするURLを取得するために、どのDBMS_CLOUDプロシージャでも使用できます。credential_nameパラメータをNULLとして指定するか、credential_nameパラメータの指定を省略する必要があります。

たとえば:

BEGIN
  DBMS_CLOUD.COPY_DATA(
     table_name =>'CHANNELS',
     file_uri_list =>'https://objectstorage.us-phoenix-1.oraclecloud.com/p/unique-pre-authenticated-string/n/namespace-string/b/bucketname/o/channels.txt',
     format => json_object('delimiter' value ',') );
END;
/

ノート:

URLの混在しているリストは有効です。URLリストに事前認証済URLと認証が必要なURLの両方が含まれているときに、DBMS_CLOUDは、認証が必要なURLにアクセスする場合には指定されたcredential_nameを使用し、事前認証済URLについては指定されたcredential_nameを無視します。

詳細は、事前認証済リクエストの使用方法に関する項を参照してください。

44.6.4 パブリックURLを使用したURI形式

ソース・ファイルがパブリックURLを提供するオブジェクト・ストアに存在している場合は、DBMS_CLOUDプロシージャでパブリックURLを使用できます。パブリックとは、オブジェクト・ストレージ・サービスが、オブジェクト・ストア・ファイルへの匿名の未認証アクセスをサポートすることを意味します。サポートされているオブジェクト・ストアでオブジェクトをパブリックにする方法の詳細は、対象のCloud Object Storageサービスを参照してください。

ノート:

パブリックURLの使用に関して、ビジネス要件とセキュリティへの影響は慎重に評価してください。パブリックURLの使用時にはファイル・コンテンツが認証されなくなるため、これが使用目的に適していることを確認してください。

パブリックURLは、資格証明を作成することなくオブジェクト・ストア内のファイルにアクセスするURLを取得するために、どのDBMS_CLOUDプロシージャでも使用できます。credential_nameパラメータをNULLとして指定するか、credential_nameパラメータの指定を省略する必要があります。

次の例では、credential_nameの指定なしでDBMS_CLOUD.COPY_DATAを使用しています。

BEGIN
  DBMS_CLOUD.COPY_DATA(
     table_name =>'CHANNELS',
     file_uri_list =>'https://objectstorage.us-ashburn-1.oraclecloud.com/n/namespace-string/b/bucketname/o/chan_v3.dat',
     format => json_object('delimiter' value ',') );
END;
/

ノート:

URLの混在しているリストは有効です。URLリストにパブリックURLと認証が必要なURLの両方が含まれているときに、DBMS_CLOUDは、認証が必要なURLにアクセスする場合には指定されたcredential_nameを使用し、パブリックURLについては指定されたcredential_nameを無視します。

Oracle Cloud Infrastructureパブリック・バケットの使用方法の詳細は、パブリック・バケットに関する項を参照してください。

44.6.5 Oracle Cloud Infrastructure Object Storage ClassicのURI形式

ソース・ファイルがOracle Cloud Infrastructure Object Storage Classicにある場合は、ファイルにアクセスするためのURI形式の説明について、RESTのページ(Oracle Cloud Infrastructure Object Storage ClassicリソースのREST URLの概要に関する項)を参照してください。

44.6.6 Amazon S3のURI形式

ソース・ファイルがAmazon S3にある場合、ファイルにアクセスするためのURI形式の説明は「バケットへのアクセス」を参照してください。

次の例では、us-west-2地域のadbバケット内にあるファイルchannels.txtを参照します。

https://s3-us-west-2.amazonaws.com/adb/channels.txt

ノート:

DBMS_CLOUDはネイティブのS3ストレージのみをサポートし、S3非準拠のAPIまたはストレージ・デバイスはサポートしません。

44.6.7 Azure BlobストレージのURI形式

ソース・ファイルがAzure Blob Storageにある場合、ファイルにアクセスするためのURI形式の説明は、リソースURIの構文に関する項を参照してください。

たとえば、次の例では、ストレージ・アカウントdb_userのadbコンテナ内にあるファイルchannels.txtを参照します。

https://db_user.blob.core.windows.net/adb/channels.txt

ノート:

Shared Access Signatures (SAS) URLは、資格証明を作成することなくAzure Blob Storage内のファイルにアクセスするURLを取得するために、どのDBMS_CLOUDプロシージャでも使用できます。Shared Access Signature (SAS) URLを使用するには、credential_nameパラメータをNULLとして指定するか、credential_nameパラメータの指定を省略する必要があります。

詳細は、Shared Access Signatures (SAS)を使用してAzure Storageリソースへの制限されたアクセス権を付与する方法に関する項を参照してください。

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

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

format引数は、次の2つの方法で指定します。

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

および

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

ノート:

AvroまたはParquetのフォーマット・オプションについては、「AvroまたはParquetに対応するDBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。

フォーマット・オプション説明構文

フォーマット・オプション	説明	構文
`blankasnull`	`true`に設定すると、空白で構成されるフィールドがNULLとしてロードされます。	`blankasnull` `: true` デフォルト値: `False`
`characterset`	ソース・ファイルの文字セットを指定します	`characterset`: string デフォルト値: データベースの文字セット
`compression`	ソース・ファイルの圧縮タイプを指定します Zipアーカイブ形式はサポートされていません。この値に`auto`を指定すると、圧縮タイプの`gzip、zlib、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` : 文字列デフォルト値: データベースの日付書式
`delimiter`	フィールド・デリミタを指定します特殊文字をデリミタとして使用する場合は、その文字のASCIIコードのHEX値を指定します。たとえば、次のようにタブ文字をデリミタとして指定します。 `format => json_object('delimiter' value 'X''9''')`	`delimiter` : 文字デフォルト値: `\|` (パイプ文字)
`escape`	指定時にはエスケープ文字として文字"\"が使用されます。	`escape` `: true` デフォルト値: `False`
`ignoreblanklines`	trueに設定すると、空白行は無視されます。	`ignoreblanklines` `: true` デフォルト値: `False`
`ignoremissingcolumns`	`field_list`内の列がソース・ファイル内の列より多い場合に、余分な列をNULLとして格納します。	`ignoremissingcolumns` `: true` デフォルト値: `False`
`language`	ロケールに依存する情報を導出可能な言語名(FRENCHなど)を指定します。	`language`: 文字列デフォルト値: Null Oracleがサポートする言語の一覧は、『Oracle Databaseグローバリゼーション・サポート・ガイド』のロケール・データに関する項を参照してください。
`numericcharacters`	グループ・セパレータおよび小数点として使用する文字を指定します。 decimal_character: 小数点では、数値の整数部と小数部を区切ります。 group_separator: グループ・セパレータは、整数グループ(千、100万、10億など)を区切ります。	`numericcharacters: 'decimal_character group_separator'` デフォルト値: `".,"` 詳細は、『Oracle Databaseグローバリゼーション・サポート・ガイド』のNLS_NUMERIC_CHARACTERSに関する項を参照してください。
`numberformat`	数値書式モデルを指定します。数値書式モデルでは、指定された有効桁数に数値が丸められます。数値書式モデルは、1つ以上の数値書式要素で構成されます。 `numericcharacters`と組み合せて使用します。	`numberformat: number_format_model` デフォルト値: `NLS_TERRITORY`パラメータの設定から導出されます詳細は、『SQL言語リファレンス』の数値書式モデルに関する項を参照してください。
`quote`	フィールドの引用符文字を指定して、ロード時には指定の引用符文字を削除します。	`quote`: 文字デフォルト値: NULL (引用符なしを意味します)
`recorddelimiter`	レコード・デリミタを指定しますデフォルトでは、`DBMS_CLOUD`は、デリミタとして適切な改行文字を自動的に見つけようとします。最初に、ファイルからWindowsの改行文字「`\r\n`」が検索されます。Windowsの改行文字が見つかると、その文字がファイルのレコード・デリミタとして使用されます。Windowsの改行文字が見つからなかった場合は、UNIX/Linuxの改行文字「`\n`」を検索し、その文字が見つかった場合はファイルのレコード・デリミタとして使用します。この引数は、デフォルトの動作をオーバーライドする場合に明示的に指定します。たとえば: `format => json_object('recorddelimiter' VALUE '''\r\n''')` レコード・デリミタが存在しないことを示すために、入力ファイルに出現しない`recorddelimiter`を指定できます。たとえば、デリミタが存在しないことを示すには、`recorddelimiter`の値として制御文字0x01 (SOH)を指定し、`recorddelimiter`値を`"0x''01''"`に設定します(この文字はJSONテキストには出現しません)。たとえば: `format => '{"recorddelimiter" : "0x''01''"}'`	`recorddelimiter`: 文字デフォルト値: newline
`rejectlimit`	指定した数の行が拒否された後で、操作をエラー終了します。	`rejectlimit`: 数値デフォルト値: `0`
`removequotes`	ソース・ファイル内のフィールドを囲む引用符を削除します。	`removequotes`: `true` デフォルト値: `False`
`skipheaders`	ファイルの先頭からスキップする行数を指定します。	`skipheaders`: 数値デフォルト値: 未指定の場合は0、値なしで指定した場合は1
`territory`	入力データの特性をさらに判断するために地域名を指定します。	`territory`: 文字列デフォルト値: Null Oracleがサポートするテリトリの一覧は、『Oracle Databaseグローバリゼーション・サポート・ガイド』のロケール・データに関する項を参照してください。
`timestampformat`	ソース・ファイル内のタイムスタンプ書式を指定します。フォーマット・オプション`AUTO`では、次の書式が検索されます。 YYYY-MM-DD HH:MI:SS.FF YYYY-MM-DD HH: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`	フィールドの先頭と末尾の空白を切り捨てる方法を指定します。 trim_specの説明を参照してください。	`trimspaces`: `rtrim\| ltrim\| notrim\| lrtrim\| ldrtrim` デフォルト値: `notrim`
`truncatecol`	ファイルのデータがフィールドに対して長すぎる場合、このオプションでは、行を拒否するかわりにフィールドの値を切り捨てます。	`truncatecol`: `true` デフォルト値: `False`
`type`	ソース・ファイルのタイプを指定します。 field_definitions句の`CSV`の説明を参照してください。 `type`の値`avro`または`parquet`については、「AvroまたはParquetに対応するDBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。	`type`: `csv\|csv` `with embedded`\|`csv` `without embedded` `csv`は、`csv` `without embedded`と同じです。デフォルト値: Null

blankasnull

trueに設定すると、空白で構成されるフィールドがNULLとしてロードされます。

blankasnull : true

デフォルト値: False

characterset

ソース・ファイルの文字セットを指定します

characterset: string

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

compression

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

Zipアーカイブ形式はサポートされていません。

この値にautoを指定すると、圧縮タイプのgzip、zlib、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 : 文字列

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

delimiter

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

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

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

delimiter : 文字

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

escape

指定時にはエスケープ文字として文字"\"が使用されます。

escape : true

デフォルト値: False

ignoreblanklines

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

ignoreblanklines : true

デフォルト値: False

ignoremissingcolumns

field_list内の列がソース・ファイル内の列より多い場合に、余分な列をNULLとして格納します。

ignoremissingcolumns : true

デフォルト値: False

language

ロケールに依存する情報を導出可能な言語名(FRENCHなど)を指定します。

language: 文字列

デフォルト値: Null

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

numericcharacters

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

decimal_character: 小数点では、数値の整数部と小数部を区切ります。

group_separator: グループ・セパレータは、整数グループ(千、100万、10億など)を区切ります。

numericcharacters: 'decimal_character group_separator'

デフォルト値: ".,"

詳細は、『Oracle Databaseグローバリゼーション・サポート・ガイド』のNLS_NUMERIC_CHARACTERSに関する項を参照してください。

numberformat

数値書式モデルを指定します。数値書式モデルでは、指定された有効桁数に数値が丸められます。数値書式モデルは、1つ以上の数値書式要素で構成されます。

numericcharactersと組み合せて使用します。

numberformat: number_format_model

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

詳細は、『SQL言語リファレンス』の数値書式モデルに関する項を参照してください。

quote

フィールドの引用符文字を指定して、ロード時には指定の引用符文字を削除します。

quote: 文字

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

recorddelimiter

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

デフォルトでは、DBMS_CLOUDは、デリミタとして適切な改行文字を自動的に見つけようとします。最初に、ファイルからWindowsの改行文字「\r\n」が検索されます。Windowsの改行文字が見つかると、その文字がファイルのレコード・デリミタとして使用されます。Windowsの改行文字が見つからなかった場合は、UNIX/Linuxの改行文字「\n」を検索し、その文字が見つかった場合はファイルのレコード・デリミタとして使用します。

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

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

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

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

recorddelimiter: 文字

デフォルト値: newline

rejectlimit

指定した数の行が拒否された後で、操作をエラー終了します。

rejectlimit: 数値

デフォルト値: 0

removequotes

ソース・ファイル内のフィールドを囲む引用符を削除します。

removequotes: true

デフォルト値: False

skipheaders

ファイルの先頭からスキップする行数を指定します。

skipheaders: 数値

デフォルト値: 未指定の場合は0、値なしで指定した場合は1

territory

入力データの特性をさらに判断するために地域名を指定します。

territory: 文字列

デフォルト値: Null

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

timestampformat

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

YYYY-MM-DD HH:MI:SS.FF 
YYYY-MM-DD HH: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

フィールドの先頭と末尾の空白を切り捨てる方法を指定します。

trim_specの説明を参照してください。

trimspaces: rtrim| ltrim| notrim| lrtrim| ldrtrim

デフォルト値: notrim

truncatecol

ファイルのデータがフィールドに対して長すぎる場合、このオプションでは、行を拒否するかわりにフィールドの値を切り捨てます。

truncatecol: true

デフォルト値: False

type

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

field_definitions句のCSVの説明を参照してください。

typeの値avroまたはparquetについては、「AvroまたはParquetに対応するDBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。

type: csv|csv with embedded|csv without embedded

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

デフォルト値: Null

44.8 DBMS_CLOUDのAvroおよびParquetのサポート

この項では、Oracle Databaseで提供されるDBMS_CLOUDのAvroおよびParquetのサポートについて説明します。

トピック

44.8.1 AvroまたはParquetに対応するDBMS_CLOUDパッケージのフォーマット・オプション

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

format引数は、次の2つの方法で指定します。

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

および

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

フォーマット・オプション説明構文

フォーマット・オプション	説明	構文
`type`	ファイル・タイプを指定します。	`type : avro \| parquet`
`schema`	スキーマが`first`または`all`に設定されているときには、AvroまたはParquetファイルのメタデータから外部表の列およびデータ型が自動的に導出されます。列名はAvroまたはParquetにある列名と一致します。データ型は、AvroまたはParquetのデータ型からOracleデータ型に変換されます。すべての列が表に追加されます。値`first`は、`file_uri_list`の最初のAvroまたはParquetファイルから得られるメタデータを使用して、列と列のデータ型を自動生成することを指定します。すべてのファイルのスキーマが同じ場合は、`first`を使用します。値`all`は、`file_uri_list`のすべてのAvroまたはParquetファイルから得られるメタデータを使用して、列と列のデータ型を自動生成することを指定します。ファイルのスキーマが異なる可能性がある場合は、`all`を使用します(低速)。デフォルト: `column_list`を指定した場合は、`schema`値(指定した場合)が無視されます。`column_list`を指定しない場合は、`schema`のデフォルト値が`first`になります。ノート: AvroまたはParquet形式のファイルの場合、`schema`フォーマット・オプションは使用できなくなり、`DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE`プロシージャを使用してパーティション化された外部表についての`column_list`パラメータを指定する必要があります。	`schema` : `first \| all`

type

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

type : avro | parquet

schema

スキーマがfirstまたはallに設定されているときには、AvroまたはParquetファイルのメタデータから外部表の列およびデータ型が自動的に導出されます。

列名はAvroまたはParquetにある列名と一致します。データ型は、AvroまたはParquetのデータ型からOracleデータ型に変換されます。すべての列が表に追加されます。

値firstは、file_uri_listの最初のAvroまたはParquetファイルから得られるメタデータを使用して、列と列のデータ型を自動生成することを指定します。すべてのファイルのスキーマが同じ場合は、firstを使用します。

値allは、file_uri_listのすべてのAvroまたはParquetファイルから得られるメタデータを使用して、列と列のデータ型を自動生成することを指定します。ファイルのスキーマが異なる可能性がある場合は、allを使用します(低速)。

デフォルト: column_listを指定した場合は、schema値(指定した場合)が無視されます。column_listを指定しない場合は、schemaのデフォルト値がfirstになります。

ノート: AvroまたはParquet形式のファイルの場合、schemaフォーマット・オプションは使用できなくなり、DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEプロシージャを使用してパーティション化された外部表についてのcolumn_listパラメータを指定する必要があります。

schema : first | all

44.8.2 DBMS_CLOUDパッケージのAvroからOracleデータ型へのマッピング

Avroデータ型からOracleデータ型へのマッピングについて説明します。

ノート:

複合タイプ(マップ、配列、構造体など)は、Oracle Database 19c以降でサポートされます。Avro複合タイプの使用方法の詳細は、「DBMS_CLOUDパッケージのAvroおよびParquet複合タイプ」を参照してください。

Avroタイプ	Oracleタイプ
INT	NUMBER(10)
LONG	NUMBER(19)
BOOL	NUMBER(1)
UTF8 BYTE_ARRAY	RAW(2000)
FLT	BINARY_FLOAT
DBL	BINARY_DOUBLE
DECIMAL(p)	NUMBER(p)
DECIMAL(p,s)	NUMBER(p,s)
DATE	DATE
STRING	VARCHAR2
TIME_MILLIS	VARCHAR2(20バイト)
TIME_MICROS	VARCHAR2(20バイト)
TIMESTAMP_MILLIS	TIMESTAMP(3)
TIMESTAMP_MICROS	TIMESTAMP(6)
ENUM	VARCHAR2( n)。"n"はAVRO ENUMの使用可能な値の実際の最大長です
DURATION	RAW(2000)
FIXED	RAW(2000)
NULL	VARCHAR2(1)バイト

Avro複合タイプの使用方法の詳細は、「DBMS_CLOUDパッケージのAvroおよびParquet複合タイプ」を参照してください。

44.8.3 DBMS_CLOUDパッケージのParquetからOracleデータ型へのマッピング

Parquetデータ型からOracleデータ型へのマッピングについて説明します。

ノート:

複合タイプ(マップ、配列、構造体など)は、Oracle Database 19c以降でサポートされます。Parquet複合タイプの使用方法の詳細は、「DBMS_CLOUDパッケージのAvroおよびParquet複合タイプ」を参照してください。

Parquetタイプ	Oracleタイプ
UINT_64	NUMBER(20)
INT_64	NUMBER(19)
UINT_32	NUMBER(10)
INT_32	NUMBER(10)
UINT_16	NUMBER(5)
INT_16	NUMBER(5)
UINT_8	NUMBER(3)
INT_8	NUMBER(3)
BOOL	NUMBER(1)
UTF8 BYTE_ARRAY	VARCHAR2(4000バイト)
FLT	BINARY_FLOAT
DBL	BINARY_DOUBLE
DECIMAL(p)	NUMBER(p)
DECIMAL(p,s)	NUMBER(p,s)
DATE	DATE
STRING	VARCHAR2(4000)
TIME_MILLIS	VARCHAR2(20バイト)
TIME_MILLIS_UTC	VARCHAR2(20バイト)
TIME_MICROS	VARCHAR2(20バイト)
TIME_MICROS_UTC	VARCHAR2(20バイト)
TIMESTAMP_MILLIS	TIMESTAMP(3)
TIMESTAMP_MILLIS_UTC	TIMESTAMP(3)
TIMESTAMP_MICROS	TIMESTAMP(6)
TIMESTAMP_MICROS_UTC	TIMESTAMP(6)
TIMESTAMP_NANOS	TIMESTAMP(9)

Parquet複合タイプの使用方法の詳細は、「DBMS_CLOUDパッケージのAvroおよびParquet複合タイプ」を参照してください。

44.8.4 DBMS_CLOUDパッケージのAvroおよびParquet複合タイプ

AvroおよびParquet複合データ型からOracleデータ型へのマッピングについて説明します。

Oracle Databaseは複合データ型をサポートしています。次の複合データ型が含まれます。

struct
list
map
union
array

AvroまたはParquetのソース・ファイル・タイプを指定したときに、ソース・ファイルに複合列が含まれている場合、Oracle Databaseの問合せは複合列に対応するJSONを返します。これにより、問合せ結果の処理が簡略化されます。つまり、Oracleの強力なJSON解析機能をファイル・タイプおよびデータ・タイプのすべてに一貫して使用できるということです。次の表に、Oracle Databaseの複合タイプに対応するフォーマットを示します。

ノート:

複合フィールドはVARCHAR2列にマップされ、VARCHAR2のサイズ制限が適用されます。

タイプ	Parquet	Avro	Oracle
List: 値のシーケンス	List	Array	`VARCHAR2` (JSON形式)
Map: 単一のキーが付いたオブジェクトのリスト	Map	Map	`VARCHAR2` (JSON形式)
Union: 異なるタイプの値	該当なし	Union	`VARCHAR2` (JSON形式)
Object: ゼロ個以上のキー/値のペア	Struct	Record	`VARCHAR2` (JSON形式)

44.8.5 DBMS_CLOUDパッケージのAvroおよびParquetのOracle列名へのマッピング

AvroおよびParquetの列名をOracleの列名に変換する方法のルールについて説明します。

AvroおよびParquet列名については次のものがサポートされていますが、外部表におけるOracle SQL参照には二重引用符の使用が必要になることがあります。そのため、AvroおよびParquet列名では、次の項目を使用しないようにして、列名の参照時に二重引用符を使用しなくて済むようにします。

埋込みの空白
先頭の数字
先頭のアンダースコア
Oracle SQLの予約語

次の表に、AvroおよびParquetの列名の様々なタイプと、外部表内でOracle列名の列名を使用するためのルールを示します。

AvroまたはParquetの名前	CREATE TABLEの名前	Oracle CATALOG	有効なSQL	ノート
part、PartまたはPART	part、Part、PART	PART	`select part` `select Part` `select paRt` `select PART`	Oracleでは引用符で囲まれていない列名を暗黙的に大文字にします
Ord No	"Ord No"	Ord No	`select "Ord No"`	二重引用符は埋込みの空白がある場合に必要になり、文字の大/小文字を維持することにもなります
__index_key__	"__index_key__"	__index_key__	`select "__index_key__"`	二重引用符は先頭にアンダースコアがある場合に必要になり、文字の大/小文字を維持することにもなります
6Way	"6Way"	6Way	`select "6Way"`	二重引用符は先頭に数字がある場合に必要になり、文字の大/小文字を維持することにもなります
create、Create、CREATEなど(あらゆる大/小文字のバリエーション)。partition、Partition、PARTITIONなど(Oracleの予約語)	"CREATE" "PARTITION"	CREATE PARTITION	`select "CREATE"` `select "PARTITION"`	Oracle SQLの予約語を囲む二重引用符が必要です。それらは大文字に強制されますが、SQLで使用する場合は常に二重引用符で囲む必要があります
rowid、Rowid、ROWidなど(ROWIDのノートを参照)	rowid		`select "rowid"` `select "Rowid"` `select "ROWid"` `select "rowid"`	ROWIDの場合は、ROWIDの大/小文字混在や小文字のバリエーションを保持するため、常に二重引用符で囲むことで元の大/小文字のバリエーションを使用する必要があります。表のOracle ROWIDとの特有の競合があるため、大文字で指定したROWIDは自動的に小文字のROWIDとして格納されるため、参照時には常に二重引用符で囲む必要があります。

ノート:

一般に、外部表の列名は二重引用符なしで参照できます。
列名に埋込みの空白、先頭のアンダースコア("_")または先頭の数字("0"から"9")が含まれていない場合は、列名の元の大/小文字が維持されるため、常に二重引用符で囲むことでAvroまたはParquetの列名の元の大/小文字を使用して参照する必要があります。
フォーマットとしてavroまたはparquetを指定したDBMS_CLOUD.CREATE_EXTERNAL_TABLEを使用して外部表を作成したら、SQL*PlusのDESCRIBEコマンドを使用して表の列名を表示します。
AvroまたはParquetの列名にOracle SQLの予約語が使用されている場合、その列名をSQL内で参照するときは常に二重引用符で囲む必要があります。詳細は、Oracle SQLの予約語に関する項を参照してください。