DBMS_CLOUD

48 DBMS_CLOUD

DBMS_CLOUDパッケージは、クラウド・リソースを使用するためのデータベース・ルーチンを提供します。

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

DBMS_CLOUDのインストール
この項では、DBMS_CLOUDパッケージのインストールについて説明します。
DBMS_CLOUDのエンドポイント管理
DBMS_CLOUDでの操作における事前構成済エンドポイントURIの形式について説明します。
DBMS_CLOUDのサブプログラムおよびREST API
この項では、Oracle Databaseに付随する、DBMS_CLOUDのサブプログラムおよびREST APIを説明します。
DBMS_CLOUDのURI形式
DBMS_CLOUDの操作でのソース・ファイルURIの形式について説明します。この形式は、どのオブジェクト記憶域サービスを使用するかによって異なります。
DBMS_CLOUDパッケージのフォーマット・オプション
DBMS_CLOUDのフォーマット引数では、ソース・ファイルの形式を指定します。
DBMS_CLOUDパッケージのEXPORT_DATA用フォーマット・オプション
テキスト・ファイル形式(CSV、JSONまたはXML)の場合とOracle Data Pumpの場合の、DBMS_CLOUD.EXPORT_DATAでの有効なフォーマット・パラメータ・オプションについて説明します。
DBMS_CLOUDのAvroおよびParquetのサポート
この項では、Oracle Databaseで提供されるDBMS_CLOUDのAvroおよびParquetのサポートについて説明します。
DBMS_CLOUDの例外
この項では、DBMS_CLOUDの例外について説明します。

48.1 DBMS_CLOUDのインストール

DBMS_CLOUDパッケージ・ファミリは、Oracle Databaseとともに事前インストールされず構成されません。DBMS_CLOUDパッケージは手動でインストールする必要があり、このパッケージを使用するにはユーザーまたはロールを構成する必要もあります。

Oracle Database 23.7でのインストールと構成については、DBMS_CLOUD Autonomous Databaseパッケージの使用を参照してください。

DBMS_CLOUD パッケージのインストールとユーザー/ロールの構成での、サポートされているその他のリリースについては、ドキュメントID 2748362.1のMOS-NOTEを参照してください。

48.2 DBMS_CLOUDのエンドポイント管理

DBMS_CLOUDでの操作における事前構成済エンドポイントURIsの形式について説明します。

DBMS_CLOUDパッケージは、多数のオブジェクト・ストアおよびRESTエンドポイントをサポートしています。それらはすべて、サービス用に事前構成されています。また、このパッケージを使用すると、ネットワーク・アクセス制御リスト(ACL)を介して、事前構成されていない追加のエンドポイントを適切に有効化した後、そのようなエンドポイントにアクセスできます。

事前構成済エンドポイントの認証は、DBMS_CLOUDで自動的に認識され導出されます。追加の顧客管理エンドポイントについて適切な認証タイプを知るために、DBMS_CLOUDは、URIエンドポイントの認証タイプを示すURIスキームをサポートしています。URIエンドポイントは、セキュアなHTTPリクエストのために、ポート443でのHTTPSをサポートしている必要があります。

事前構成済URIの詳細は、「DBMS_CLOUDのURI形式」を参照してください。
顧客管理URIの詳細は、「追加の顧客管理URI形式」を参照してください。

48.3 DBMS_CLOUDのサブプログラムおよびREST API

この項では、Oracle Databaseに付随する、DBMS_CLOUDのサブプログラムおよびREST APIを説明します。

DBMS_CLOUDパッケージは次のものからなります:

48.3.1 アクセス管理用のDBMS_CLOUD

DBMS_CLOUDパッケージ内の資格証明管理(資格証明の作成、削除および更新など)用のサブプログラム。

サブプログラム	説明
CREATE_CREDENTIALプロシージャ	このプロシージャでは、クラウド・サービスの資格証明をOracle Databaseに格納します。
DROP_CREDENTIALプロシージャ	このプロシージャでは、Oracle Databaseから既存の資格証明を削除します。
UPDATE_CREDENTIALプロシージャ	このプロシージャでは、Oracle Database内のクラウド・サービス資格証明の属性を更新します。

48.3.1.1 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`	格納する資格証明の名前。`credential_name`パラメータは、スペースやハイフンを使用できないOracleオブジェクトのネーミング規則に準拠している必要があります。
`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署名キー・ベースの資格証明とみなされます。
ALL_CREDENTIALSビューから資格証明をリストできます。たとえば、次のコマンドを実行して資格証明をリストします。
```
SELECT credential_name, username, comments FROM all_credentials;
```

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

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

たとえば:

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'DEF_CRED_NAME',
    username => 'adb_user@example.com',
    password => 'password' );
END;
/

OCIオブジェクト・ストレージのコールを認証しているときは、認証トークン・ベースの資格証明を使用します。他のタイプのOracle Cloud Infrastructureクラウド・サービスのコールの場合は、Oracle Cloud Infrastructure署名キー・ベースの資格証明を使用します。

OCIオブジェクト・ストレージの場合、usernameパラメータの値には、アイデンティティ・ドメイン、およびプロファイルにあるユーザー名を含める必要があります。ユーザーに関連付けられているアイデンティティ・ドメインは、Oracle Cloud Infrastructureコンソールで確認できます。

たとえば:

oracleidentitycloudservice/adb_user@example.com

デフォルトのアイデンティティ・ドメインの場合、ドメイン名Defaultを含める必要はありません。たとえば:

adb_user@example.com

Oracle Cloud Infrastructure署名キー・ベースの資格証明

Oracle Cloud Infrastructure署名キー認証では、Oracle Cloud Infrastructure署名キー関連のパラメータ(user_ocid、tenancy_ocid、private_key、fingerprintなど)を使用します。

たとえば:

BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL (
       credential_name => ‘OCI_KEY_CRED’,
       user_ocid       => ‘ocid1.user.oc1..aaaaaaaauq54mi7zdyfhw33ozkwuontjceel7fok5nq3bf2vwetkpqsoa’,
       tenancy_ocid    => ‘ocid1.tenancy.oc1..aabbbbbbaafcue47pqmrf4vigneebgbcmmoy5r7xvoypicjqqge32ewnrcyx2a’,
       private_key     => ‘MIIEogIBAAKCAQEAtUnxbmrekwgVac6FdWeRzoXvIpA9+0r1.....wtnNpESQQQ0QLGPD8NM//JEBg=’,
       fingerprint     => ‘f2:db:f9:18:a4:aa:fc:94:f4:f6:6c:39:96:16:aa:27’);
END;
/

パスフレーズ付きで生成したプライベート・キーはサポートされていません。この秘密キーは、パスフレーズなしで生成する必要があります。詳細は、API署名キーの生成方法に関する項を参照してください。

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ストレージ・アカウントについて」を参照してください。

GitHubの個人アクセス・トークン

ソース・ファイルがGitHubリポジトリにある場合、またはGitHub APIをコールする場合、usernameはGitHubの電子メールで、passwordはGitHubの個人アクセス・トークンです。詳細は、「個人用アクセストークンの作成」を参照してください。

たとえば:

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'MY_GITHUB_CRED',
    username => 'user@example.com',
    password => 'your_personal_access_token' );
END;
/

48.3.1.2 DROP_CREDENTIALプロシージャ

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

構文

DBMS_CLOUD.DROP_CREDENTIAL (
   credential_name     IN VARCHAR2);

パラメータ

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

48.3.1.3 UPDATE_CREDENTIALプロシージャ

このプロシージャは、指定されたcredential_nameについて、新しい値で属性を更新します。

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

構文

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

パラメータ

パラメータ説明

パラメータ	説明
`credential_name`	更新する資格証明の名前。
`attribute`	更新する属性の名前。ユーザー名/パスワード・タイプの資格証明の場合、有効な`attribute`値は`USERNAME`と`PASSWORD`です。詳細は、「CREATE_CREDENTIALプロシージャ」を参照してください。
`value`	指定した属性の新しい値。

credential_name

更新する資格証明の名前。

attribute

更新する属性の名前。

ユーザー名/パスワード・タイプの資格証明の場合、有効なattribute値はUSERNAMEとPASSWORDです。

詳細は、「CREATE_CREDENTIALプロシージャ」を参照してください。

value

指定した属性の新しい値。

使用上のノート

ユーザー名の値では大文字と小文字が区別されます。二重引用符または空白を含むことはできません。
DBA権限があるユーザーは、dba_credentialsを問い合せることで、すべての資格証明を表示できます。
資格証明の作成は、クラウド・サービスの資格証明が変更されないかぎり1回のみ必要です。資格証明を格納すると、credential_nameパラメータが必要になるDBMS_CLOUDプロシージャに同じ名前の資格証明を使用できるようになります。
ALL_CREDENTIALSビューから資格証明をリストできます。たとえば、次のコマンドを実行して資格証明をリストします。
```
SELECT credential_name, username, comments FROM all_credentials;
```

例

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

BEGIN
  DBMS_CLOUD.UPDATE_CREDENTIAL(
     credential_name => 'ARN_CRED',
     attribute => 'aws_role_arn',
     value => 'NEW_AWS_ARN'); 
END;
/

48.3.2 オブジェクトおよびファイル用のDBMS_CLOUD

DBMS_CLOUDパッケージ内のオブジェクト管理およびファイル管理用のサブプログラム。

サブプログラム	説明
COPY_COLLECTIONプロシージャ	このプロシージャは、Cloud Object Storageから、またはディレクトリ内のファイルから、既存のJSONコレクションにデータをロードします。
COPY_DATAプロシージャ	このプロシージャは、Cloud Object Storageから、またはディレクトリ内のファイルから、既存のOracle Database表にデータをロードします。
AvroまたはParquetのファイルに対応するCOPY_DATAプロシージャ	このプロシージャは、`format`パラメータの`type`が値`orc`、`parquet`または`avro`に設定されていると、クラウド内のORC、ParquetまたはAvroファイルから、またはディレクトリ内のORC、ParquetまたはAvroファイルから、既存のOracle Database表にデータをロードします。テキスト・ファイルと同様に、データは、ソースのORC、ParquetまたはAvroファイルから既存の内部表にコピーされます。
COPY_OBJECTプロシージャ	このプロシージャは、Cloud Object Storageバケット間でファイルをコピーします。
CREATE_EXTERNAL_TABLEプロシージャ	このプロシージャは、クラウド内のファイルに基づいて、またはディレクトリ内のファイルから外部表を作成します。これにより、Oracle Databaseから外部データに対する問合せを実行できるようになります。
Apache Icebergに対応するCREATE_EXTERNAL_TABLEプロシージャ	このプロシージャは、サポートされている構成でApache Iceberg表の外部表を作成します。
AvroまたはParquetファイルに対応するCREATE_EXTERNAL_TABLEプロシージャ	このプロシージャは、`format`パラメータの`type`が値`parquet`、`orc`または`avro`に設定されていると、クラウド内またはディレクトリ内の、Parquet、ORCまたはAvro形式のファイルを使用して外部表を作成します。これにより、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プロシージャ	このプロシージャでは、オブジェクト・ストアの指定したオブジェクトを削除します。
DELETE_OPERATIONプロシージャ	このプロシージャは、入力として`operation_id`を受け入れ、指定された`operation_id`に関連付けられているログを削除します。
EXPORT_DATAプロシージャ	このプロシージャは、問合せの結果に基づいてOracle Databaseからクラウド内のファイルにデータをエクスポートします。オーバーロードされた形式では、`operation_id`パラメータを使用できるようになります。このプロシージャは、指定された`format`パラメータの`type`オプションに応じて、行をテキストとしてクラウド・オブジェクト・ストアにエクスポートするか(オプションとしてCSV、JSONまたはXMLがある)、ORACLE_DATAPUMPアクセス・ドライバを使用してダンプ・ファイルにデータを書き込みます。
GET_OBJECTプロシージャ/ファンクション	このプロシージャはオーバーロードされています。プロシージャ形式では、Cloud Object Storageからオブジェクトを読み取り、そのオブジェクトをOracle Databaseにコピーします。ファンクション形式では、Cloud Object Storageからオブジェクトを読み取り、`BLOB`をOracle Databaseに返します。
LIST_FILESファンクション	このファンクションでは、指定されたディレクトリにあるファイルをリストします。結果には、ファイル名とファイルに関する追加のメタデータ(バイト単位のファイル・サイズ、作成タイムスタンプ、最終変更タイムスタンプなど)が含まれます。
LIST_OBJECTSファンクション	このファンクションでは、オブジェクト・ストア内の指定された場所にあるオブジェクトをリストします。結果には、オブジェクト名とオブジェクトに関する追加のメタデータ(サイズ、チェックサム、作成タイムスタンプ、最終変更タイムスタンプなど)が含まれます。
MOVE_OBJECTプロシージャ	このプロシージャは、Cloud Object Storageバケット間でオブジェクトを移動します。
PUT_OBJECTプロシージャ	このプロシージャはオーバーロードされています。このプロシージャには、Oracle DatabaseからCloud Object Storageにファイルをコピーする形式があります。また、このプロシージャには、Oracle DatabaseからCloud Object Storageに`BLOB`をコピーする形式もあります。
SYNC_EXTERNAL_PART_TABLEプロシージャ	このプロシージャは、クラウド内のファイルからの、パーティション化された外部表の更新を簡略化します。新しいパーティションを追加するたびに、またはパーティション化された外部表に対してオブジェクト・ストア・ソースからパーティションを削除するときに、このプロシージャを実行します。
VALIDATE_EXTERNAL_TABLEプロシージャ	このプロシージャでは、外部表のソース・ファイルを検証して、ログ情報を生成し、外部表に指定したフォーマット・オプションと一致しない行をOracle Databaseのbadfile表に格納します。
VALIDATE_EXTERNAL_PART_TABLEプロシージャ	このプロシージャでは、パーティション化された外部表のソース・ファイルを検証して、ログ情報を生成し、外部表に指定したフォーマット・オプションと一致しない行をOracle Databaseのbadfile表に格納します。
VALIDATE_HYBRID_PART_TABLEプロシージャ	このプロシージャでは、ハイブリッド・パーション表のソース・ファイルを検証して、ログ情報を生成し、ハイブリッド表に指定したフォーマット・オプションと一致しない行をOracle Databaseのbadfile表に格納します。

48.3.2.1 COPY_COLLECTIONプロシージャ

このプロシージャは、Cloud Object StorageまたはディレクトリからJSONコレクションにデータをロードします。指定されたJSONコレクションが存在しない場合、このプロシージャは、それを作成します。オーバーロードされた形式では、operation_idパラメータを使用できるようになります。

構文

DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL
);

DBMS_CLOUD.COPY_COLLECTION (
    collection_name   IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    file_uri_list     IN CLOB,
    format            IN CLOB     DEFAULT NULL,
    operation_id      OUT NOCOPY NUMBER
);

パラメータ

パラメータ	説明
`collection_name`	データのロード先となるJSONコレクションの名前。この名前のコレクションがすでに存在する場合は、指定したデータがロードされ、そうでない場合は新しいコレクションが作成されます。
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。 `file_uri_list`でディレクトリを指定する場合、このパラメータは使用されません。
`file_uri_list`	このパラメータでは、ソース・ファイルURIのカンマ区切りリスト、または1つ以上のディレクトリとソース・ファイルを指定します。クラウドのソース・ファイルURI クラウドのソース・ファイルURIでのファイル名には、ワイルドカードと正規表現を使用できます。正規表現を使用できるのは、`regexuri` `format`パラメータが`TRUE`に設定されている場合のみです。この`regexuri`パラメータが`FALSE`に設定されている場合、文字""と"?"はワイルドカード文字とみなされます。この`regexuri`パラメータが`TRUE`に設定されている場合、文字""と"?"は、指定された正規表現パターンの一部となります。正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされており、パターン・マッチングは`REGEXP_LIKE`ファンクションによって実行されるものと同じです。たとえば: `file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)year=[0-9]+(/)month=[0-9]+(/)[a-z]+[1-3]??.csv'` URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。 `REGEXP_LIKE`条件の詳細は、REGEXP_LIKE条件を参照してください。ディレクトリ 1つのディレクトリと1つ以上のファイル名を指定することも、ディレクトリとファイル名のカンマ区切りリストを使用することもできます。ディレクトリを指定する形式は、`'MY_DIR:filename.ext'`です。デフォルトでは、ディレクトリ名`MY_DIR`はデータベース・オブジェクトであり、大/小文字は区別されません。ファイル名は、大/小文字が区別されます。ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字""は、複数の文字に対応するワイルドカードとして使用できます。文字"?"は、1文字に対応するワイルドカードとして使用できます。例:`'MY_DIR:"`または`'MY_DIR:test?'` 複数のディレクトリを指定するには、ディレクトリのカンマ区切りリストを使用します。例:`'MY_DIR1:, MY_DIR2:test?'` 大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。例:`'"my_dir1":*, "my_dir2":Test?'` 引用符文字を含めるには、2つの引用符を使用します。例:`'MY_DIR:''filename.ext'`。これは、`filename`が引用符(`'`)で始まることを示します。
`format`	ソース・ファイルの形式を示すオプション。これらのオプションはJSON文字列として指定されます。サポートされているフォーマットは、`characterset、compression、ignoreblanklines、jsonpath、maxdocsize、recorddelimiter、rejectlimit、type、unpackarrays`、`keyassignment`および`keypath`です。前述したJSONデータのフォーマットとは別に、Autonomous AI Databaseでは他のフォーマットもサポートされています。Autonomous AI Databaseでサポートされているフォーマット引数のリストは、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。
`operation_id`	このパラメータは、ロード操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビューの対応するIDとして追跡するために使用します。

例

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'OBJ_STORE_CRED',
            username        => 'user_name@oracle.com',
            password        => 'password'
            );

    DBMS_CLOUD.COPY_COLLECTION(
            collection_name => 'myCollection',
            credential_name => 'OBJ_STORE_CRED',
            file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/myCollection.json'  
            );
END;
/

48.3.2.2 COPY_DATAプロシージャ

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

構文

DBMS_CLOUD.COPY_DATA (
    table_name        IN VARCHAR2,
    credential_name   IN VARCHAR2 DEFAULT NULL,
    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`でディレクトリまたは事前認証済リクエスト(PAR) URLを指定しているときは、このパラメータは使用されません。
`file_uri_list`	このパラメータでは、次のいずれかを指定します: ソース・ファイルURIのカンマ区切りリスト事前認証済リクエスト(PAR) URLのカンマ区切りリスト 1つ以上のディレクトリおよびソース・ファイルクラウドのソース・ファイルURIでのファイル名には、ワイルドカードと正規表現を使用できます。クラウドのソース・ファイルURI このパラメータでは、ソース・ファイルURIのカンマ区切りリスト、または1つ以上のディレクトリとソース・ファイルを指定します。正規表現を使用できるのは、`regexuri` `format`パラメータが`TRUE`に設定されている場合のみです。この`regexuri`パラメータが`FALSE`に設定されている場合、文字""と"?"はワイルドカード文字とみなされます。この`regexuri`パラメータが`TRUE`に設定されている場合、文字""と"?"は、指定された正規表現パターンの一部となります。正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされており、パターン・マッチングは`REGEXP_LIKE`ファンクションによって実行されるものと同じです。たとえば: `file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)year=[0-9]+(/)month=[0-9]+(/)[a-z]+[1-3]??.csv'` URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。事前認証済リクエスト(PAR) URL 次のような外部表を作成できます: 1つの事前認証済リクエスト(PAR) URL。そのデータに対してフィルタと句も適用します。たとえば、`WHERE`句を使用してデータをフィルタすることや、`ORDER BY`句を使用してそれをソートすることができます。たとえば: `file_uri_list => 'https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6XExample/data'` 事前認証済リクエスト(PAR) URLのカンマ区切りリスト。含まれているPAR URLすべてで、列名、列の順序および列のデータ型が同じである必要があります。たとえば: `file_uri_list => 'https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6XExample/data','https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K7XExample/data'` ディレクトリ 1つのディレクトリと1つ以上のファイル名を指定することも、ディレクトリとファイル名のカンマ区切りリストを使用することもできます。ディレクトリを指定する形式は、`'MY_DIR:filename.ext'`です。デフォルトでは、ディレクトリ名`MY_DIR`はデータベース・オブジェクトであり、大/小文字は区別されません。ファイル名は、大/小文字が区別されます。ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字""は、複数の文字に対応するワイルドカードとして使用できます。文字"?"は、1文字に対応するワイルドカードとして使用できます。例:`'MY_DIR:"`または`'MY_DIR:test?'` 複数のディレクトリを指定するには、ディレクトリのカンマ区切りリストを使用します。例:`'MY_DIR1:, MY_DIR2:test?'` 大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。例:`'"my_dir1":*, "my_dir2":Test?'` 引用符文字を含めるには、2つの引用符を使用します。例:`'MY_DIR:''filename.ext'`。これは、`filename`が引用符(`'`)で始まることを示します。
`schema_name`	ターゲット表が存在するスキーマの名前。デフォルト値は、NULLです。この値は、ターゲット表がプロシージャを実行するユーザーと同じスキーマ内にあることを意味します。
`field_list`	ソース・ファイル内のフィールドとそのデータ型を識別します。デフォルト値は、NULLです。この値は、フィールドとそのデータ型がターゲット表の定義によって決まることを意味します。この引数の構文は、通常のOracle外部表の`field_list`句と同じです。 `field_list`の使用例は、「CREATE_EXTERNAL_TABLEプロシージャ」を参照してください。
`format`	ソース・ファイル、ログ・ファイルおよび不良ファイルの形式を示すオプション。オプションのリストと値の指定方法は、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。 AvroまたはParquetファイル・フォーマットのオプションについては、「AvroまたはParquetに対応するDBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。
`operation_id`	このパラメータは、ロード操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビューの対応するIDとして追跡するために使用します。

使用上のノート

デフォルトのレコード・デリミタはdetected newlineです。detected newlineを指定すると、DBMS_CLOUDは、レコード・デリミタとして使用する適切な改行文字を自動的に見つけようとします。DBMS_CLOUDは、最初にWindowsの改行文字\r\nを検索します。Windowsの改行文字が見つかると、それがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。Windowsの改行文字が見つからない場合、DBMS_CLOUDは、UNIX/Linuxの改行文字\nを検索し、見つかった場合は\nがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。ソース・ファイルで異なるレコード・デリミタの組合せが使用されている場合は、KUP-04020: found record longer than buffer size supportedなどのエラーが発生する可能性があります。この場合、同じレコード・デリミタを使用するようにソース・ファイルを変更するか、同じレコード・デリミタを使用するソース・ファイルのみを指定する必要があります。

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

例

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'DEF_CRED_NAME',
            username        => 'user_name@oracle.com',
            password        => 'password'
            );
END;
/

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

BEGIN
    DBMS_CLOUD.COPY_DATA(
            table_name      => 'ORDERS',
            schema_name     => 'TEST_SCHEMA',
            credential_name => 'DEF_CRED_NAME',
	     file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/adbexample/b/json/o/orde[r]s.tbl.1'
            format          =>  json_object('ignoreblanklines' value TRUE,
                                            'rejectlimit' value '0',
                                            'dateformat' value 'yyyy-mm-dd',
                                            'regexuri' value TRUE)
            );
END;
/

48.3.2.3 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 DEFAULT NULL,
    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`でディレクトリを指定する場合、このパラメータは使用されません。
`file_uri_list`	このパラメータでは、ソース・ファイルURIのカンマ区切りリスト、または1つ以上のディレクトリとソース・ファイルを指定します。クラウドのソース・ファイルURI クラウドのソース・ファイルURIでのファイル名には、ワイルドカードと正規表現を使用できます。正規表現を使用できるのは、`regexuri` `format`パラメータが`TRUE`に設定されている場合のみです。この`regexuri`パラメータが`FALSE`に設定されている場合、文字""と"?"はワイルドカード文字とみなされます。この`regexuri`パラメータが`TRUE`に設定されている場合、文字""と"?"は、指定された正規表現パターンの一部となります。正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされており、パターン・マッチングは`REGEXP_LIKE`ファンクションによって実行されるものと同じです。たとえば: `file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)year=[0-9]+(/)month=[0-9]+(/)[a-z]+[1-3]??.csv'` URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。ディレクトリ 1つのディレクトリと1つ以上のファイル名を指定することも、ディレクトリとファイル名のカンマ区切りリストを使用することもできます。ディレクトリを指定する形式は、`'MY_DIR:filename.ext'`です。デフォルトでは、ディレクトリ名`MY_DIR`はデータベース・オブジェクトであり、大/小文字は区別されません。ファイル名は、大/小文字が区別されます。ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字""は、複数の文字に対応するワイルドカードとして使用できます。文字"?"は、1文字に対応するワイルドカードとして使用できます。例:`'MY_DIR:"`または`'MY_DIR:test?'` 複数のディレクトリを指定するには、ディレクトリのカンマ区切りリストを使用します。例:`'MY_DIR1:, MY_DIR2:test?'` 大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。例:`'"my_dir1":*, "my_dir2":Test?'` 引用符文字を含めるには、2つの引用符を使用します。例:`'MY_DIR:''filename.ext'`。これは、`filename`が引用符(`'`)で始まることを示します。
`schema_name`	ターゲット表が存在するスキーマの名前。デフォルト値は、NULLです。この値は、ターゲット表がプロシージャを実行するユーザーと同じスキーマ内にあることを意味します。
`field_list`	AvroまたはParquetファイルの場合は無視されます。ソースのフィールドは、名前によって外部表の列と一致します。ソースのデータ型は、外部表の列データ型に変換されます。 Parquetファイルに対するマッピングの詳細は、「DBMS_CLOUDパッケージのParquetからOracleデータ型へのマッピング」を参照してください。 Avroファイルに対するマッピングの詳細は、「DBMS_CLOUDパッケージのAvroからOracleデータ型へのマッピング」を参照してください。
`format`	ソース・ファイルの形式を示すオプション。AvroまたはParquetのファイルについては、2つのオプションのみがサポートされています: 「DBMS_CLOUDパッケージのORCからOracleデータ型へのマッピング」を参照してください。

使用上のノート

その他のデータ・ファイルと同様に、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に設定されます。これにより拒否されたレコードの生成がなくなります。

48.3.2.4 COPY_OBJECTプロシージャ

このプロシージャは、一方のCloud Object Storageバケットまたはフォルダから他方にオブジェクトをコピーします。

ソースとターゲットのバケットまたはフォルダは、同一の、または異なるクラウド・オブジェクト・ストア・プロバイダに配置できます。

ソースとターゲットが、個別のオブジェクト・ストアにある場合や、同じクラウド・プロバイダでの別々のアカウントを使用している場合は、ソースの場所とターゲットの場所に別々の資格証明名を指定できます。

ソースの資格証明名は、デフォルトでは、ターゲットの資格証明名が指定されていない場合はターゲットの場所でも使用されます。

構文

DBMS_CLOUD.COPY_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

パラメータ

パラメータ	説明
`source_credential_name`	ソースCloud Object Storageにアクセスするための資格証明の名前。 `source_credential_name`の値を指定しなかった場合、`credential_name`は`NULL`に設定されます。
`source_object_uri`	ソースのオブジェクト・ストレージ・バケットまたはフォルダの場所を指すURIを指定します。このパラメータは必須です。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`target_object_uri`	ターゲットのオブジェクト・ストアのURIを指定します。このパラメータは必須です。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`target_credential_name`	ターゲットCloud Object Storageにアクセスするための資格証明の名前。 `target_credential_name`の値を指定しなかった場合、`target_object_uri`は`source_credential_name`の値に設定されます。

例

BEGIN 
DBMS_CLOUD.COPY_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

48.3.2.5 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);


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

パラメータ

パラメータ	説明
`table_name`	外部表の名前。
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`partitioning_clause`	個別のパーティションの場所情報を含む、完全なパーティション化句を指定します。 `partitioning_clause`パラメータを使用する場合、`file_uri_list`パラメータは許可されません。
`file_uri_list`	このパラメータでは、次のいずれかを指定します: ソース・ファイルURIのカンマ区切りリスト事前認証済リクエスト(PAR) URLのカンマ区切りリスト 1つ以上のディレクトリおよびソース・ファイルクラウドのソース・ファイルURI クラウドのソース・ファイルURIでのファイル名には、ワイルドカードと正規表現を使用できます。正規表現を使用できるのは、`regexuri` `format`パラメータが`TRUE`に設定されている場合のみです。この`regexuri`パラメータが`FALSE`に設定されている場合、文字""と"?"はワイルドカード文字とみなされます。この`regexuri`パラメータが`TRUE`に設定されている場合、文字""と"?"は、指定された正規表現パターンの一部となります。正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされており、パターン・マッチングは`REGEXP_LIKE`ファンクションによって実行されるものと同じです。このオプションは、オブジェクト・ストレージ内のファイルに作成される外部表の場合のみサポートされています。たとえば: `file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)year=[0-9]+(/)month=[0-9]+(/)*[a-z]+[1-3]??.csv'` パラメータ`file_uri_list`を使用する場合、`partitioning_clause`パラメータは許可されません。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。事前認証済リクエスト(PAR) URL 次のような外部表を作成できます: 1つのOracle Database事前認証済リクエスト(PAR) URL。そのデータにフィルタと句も適用します。たとえば、`WHERE`句を使用してデータをフィルタすることや、`ORDER BY`句を使用してそれをソートすることができます。たとえば: `file_uri_list => 'https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6XExample/data'` Oracle Databaseの事前認証済リクエスト(PAR) URLのカンマ区切りリスト。含まれているPAR URLすべてで、同一スキーマ内の、同一の列名、列の順序および列のデータ型が使用されている必要があります。たとえば: `file_uri_list => 'https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6XExample/data','https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K7XExample/data'`
`column_list`	外部表の列名とデータ型のカンマ区切りリスト。このパラメータには、`file_uri_list`パラメータで指定されたデータ・ファイルのタイプに応じて、次の要件があります。非構造化ファイルでは、`column_list`パラメータは必須です。非構造化ファイル(CSVテキスト・ファイルなど)を使用する場合、`column_list`パラメータでは、データ・ファイル内のすべての列名とデータ型、およびオブジェクト名から導出されたパーティション列を指定する必要があります。構造化ファイルでは、`column_list`パラメータはオプションです。たとえば、Avro、ORCまたはParquetデータ・ファイルでは、`column_list`は必要ありません。`column_list`を含めない場合、`format`パラメータの`partition_columns`オプションには、列名(`name`)とデータ型(`type`)の両方の指定を含める必要があります。
`field_list`	ソース・ファイル内のフィールドとそのデータ型を識別します。デフォルト値は、NULLです。この値は、フィールドとそのデータ型がcolumn_listパラメータによって決まることを意味します。この引数の構文は、通常のOracle外部表の`field_list`句と同じです。`field_list`の詳細は、『Oracle® Databaseユーティリティ』を参照してください。
`format`	フォーマット・オプション`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`オプションには列名(`name`副句)とデータ型(`type`副句)の両方が含まれます。たとえば、`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`パラメータで指定されたファイル・パスのオブジェクト名に表示される順序と一致する必要があります。ソース・ファイルの形式を説明するすべての`format`パラメータ・オプションを確認するには、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。

使用上のノート

partitioning_clauseパラメータとfile_uri_listパラメータの両方を使用してこのプロシージャをコールすることはできません。
Avro、ParquetまたはORCデータ・ファイルを含む構造化データ・ファイルでは、column_listパラメータの指定はオプションです。column_listを指定しない場合、formatパラメータのpartition_columnsオプションには、nameとtypeの両方を含める必要があります。
CSVテキスト・ファイルなどの非構造化データ・ファイルでは、column_listパラメータは必須です。
プロシージャDBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEでは、次のものを含むサポート対象クラウド・オブジェクト・ストレージ・サービスでパーティション化された外部ファイルをサポートしています。
- Oracle Cloud Infrastructureオブジェクト・ストレージ
- Azure Blob Storage
- Amazon S3
- GitHubリポジトリ
詳細は、「DBMS_CLOUDのURI形式」を参照してください。
プロシージャDBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEは、ローカル・ファイル・システムまたはネットワーク・ファイル・システムにあるディレクトリ内のパーティション化された外部ファイルをサポートしています。
file_uri_listパラメータを指定してDBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEをコールする場合、クラウド・オブジェクト・ストアのファイル名で指定される列の型は、次のいずれかの型である必要があります。
```
VARCHAR2(n)
NUMBER(n)
NUMBER(p,s)
NUMBER
DATE
TIMESTAMP(9)
```
デフォルトのレコード・デリミタはdetected newlineです。detected newlineを指定すると、DBMS_CLOUDは、レコード・デリミタとして使用する適切な改行文字を自動的に見つけようとします。DBMS_CLOUDは、最初にWindowsの改行文字\r\nを検索します。Windowsの改行文字が見つかると、それがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。Windowsの改行文字が見つからない場合、DBMS_CLOUDは、UNIX/Linuxの改行文字\nを検索し、見つかった場合は\nがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。ソース・ファイルで異なるレコード・デリミタの組合せが使用されている場合は、KUP-04020: found record longer than buffer size supportedなどのエラーが発生する可能性があります。この場合、同じレコード・デリミタを使用するようにソース・ファイルを変更するか、同じレコード・デリミタを使用するソース・ファイルのみを指定する必要があります。

recorddelmiterフォーマット・オプションの詳細は、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。
DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLEを使用して作成する外部パーティション表には、2つの非表示列file$pathおよびfile$nameが含まれます。これらの列は、レコードの取得元ファイルの識別に役立ちます。
- file$path: オブジェクト名の先頭までのファイル・パス・テキストを指定します。
- file$name: バケット名に続くすべてのテキストを含め、オブジェクト名を指定します。

例

partitioning_clauseパラメータを使用した例:

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;
/  


BEGIN
    DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
       table_name          => 'PET',
       format              => json_object('delimiter'value ','),
       column_list         => 'name varchar2(20), gender varchar2(10), salary number',
       partitioning_clause => 'partition by range (salary)
              (   -- Use test1.csv in the DEFAULT DIRECTORY DATA_PUMP_DIR 
                  partition p1 values less than (100) LOCATION (''test1.csv''),
                   -- Use test2.csv in a specified directory MY_DIR
                  partition p2 values less than (300) DEFAULT DIRECTORY MY_DIR LOCATION (''test2.csv'')        )'   );                       
END;                     
/

非構造化データ・ファイルでfile_uri_listおよびcolumn_listパラメータを使用した例:

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
   table_name => 'MYSALES',
   credential_name => 'DEF_CRED_NAME',
   file_uri_list     => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.csv', 
   column_list       => 'product varchar2(100), units number, country varchar2(100), year number, month varchar2(2)', 
   field_list        => 'product, units', --[Because country, year and month are not in the file, they are not listed in the field list]
   format            => '{"type":"csv", "partition_columns":["country","year","month"]}');
END;
/

構造化データ・ファイルでcolumn_listパラメータを指定せずにfile_uri_listを使用した例:

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
  table_name => 'MYSALES',
  credential_name => 'DEF_CRED_NAME',
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
    table_name      => 'MYSALES',
    credential_name => 'DEF_CRED_NAME',
    file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/*.parquet',
    format          => 
        json_object('type' value 'parquet', 'schema' value 'first',
                    'partition_columns' value 
                          json_array(
                                json_object('name' value 'country', 'type' value 'varchar2(100)'),
                                json_object('name' value 'year', 'type' value 'number'),
                                json_object('name' value 'month', 'type' value 'varchar2(2)')
                          )
         )
    );
END;
/

48.3.2.6 CREATE_EXTERNAL_TABLEプロシージャ

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

構文

DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       IN VARCHAR2,
    credential_name  IN VARCHAR2 DEFAULT NULL,
    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`でディレクトリまたは事前認証済リクエスト(PAR) URLを指定しているときは、このパラメータは使用されません。
`file_uri_list`	このパラメータでは、次のいずれかを指定します: ソース・ファイルURIのカンマ区切りリスト。事前認証済リクエスト(PAR) URLのカンマ区切りリスト。 1つ以上のディレクトリおよびソース・ファイル。クラウドのソース・ファイルURI クラウドのソース・ファイルURIでのファイル名には、ワイルドカードと正規表現を使用できます。正規表現を使用できるのは、`regexuri` `format`パラメータが`TRUE`に設定されている場合のみです。この`regexuri`パラメータが`FALSE`に設定されている場合、文字""と"?"はワイルドカード文字とみなされます。この`regexuri`パラメータが`TRUE`に設定されている場合、文字""と"?"は、指定された正規表現パターンの一部となります。正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされており、パターン・マッチングは`REGEXP_LIKE`ファンクションによって実行されるものと同じです。このオプションは、オブジェクト・ストレージ内のファイルに作成される外部表の場合のみサポートされています。たとえば: `file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)year=[0-9]+(/)month=[0-9]+(/)[a-z]+[1-3]??.csv'` URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。事前認証済リクエスト(PAR) URL 次のような外部表を作成できます: 1つのOracle Database事前認証済リクエスト(PAR) URL。そのデータにフィルタと句も適用します。たとえば、`WHERE`句を使用してデータをフィルタすることや、`ORDER BY`句を使用してそれをソートすることができます。たとえば: `file_uri_list => 'https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6XExample/data'` Oracle Databaseの事前認証済リクエスト(PAR) URLのカンマ区切りリスト。含まれているPAR URLすべてで、同一スキーマ内の、同一の列名、列の順序および列のデータ型が使用されている必要があります。たとえば: `file_uri_list => 'https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K6XExample/data','https://dataaccess.adb.us-chicago-1.oraclecloudapps.com/adb/p/K7XExample/data'` ディレクトリ 1つのディレクトリと1つ以上のファイル名を指定することも、ディレクトリとファイル名のカンマ区切りリストを使用することもできます。ディレクトリを指定する形式は、`'MY_DIR:filename.ext'`です。デフォルトでは、ディレクトリ名`MY_DIR`はデータベース・オブジェクトであり、大/小文字は区別されません。ファイル名は、大/小文字が区別されます。ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字""は、複数の文字に対応するワイルドカードとして使用できます。文字"?"は、1文字に対応するワイルドカードとして使用できます。例:`'MY_DIR:"`または`'MY_DIR:test?'` 複数のディレクトリを指定するには、ディレクトリのカンマ区切りリストを使用します。例:`'MY_DIR1:, MY_DIR2:test?'` 大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。例:`'"my_dir1":*, "my_dir2":Test?'` 引用符文字を含めるには、2つの引用符を使用します。例:`'MY_DIR:''filename.ext'`。これは、`filename`が引用符(`'`)で始まることを示します。
`column_list`	外部表の列名とデータ型のカンマ区切りリスト。
`field_list`	ソース・ファイル内のフィールドとそのデータ型を識別します。デフォルト値は、NULLです。この値は、フィールドとそのデータ型が`column_list`パラメータによって決まることを意味します。この引数の構文は、通常のOracle Database外部表での`field_list`句と同じです。`field_list`の詳細は、Oracle AI DatabaseユーティリティのORACLE_LOADERアクセス・ドライバfield_definitions句の下のfield_listを参照してください。
`format`	ソース・ファイルの形式を示すオプション。オプションのリストと値の指定方法は、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。 AvroまたはParquet形式のファイルについては、「AvroまたはParquetファイルに対応するCREATE_EXTERNAL_TABLEプロシージャ」を参照してください。

使用上のノート

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

詳細は、「DBMS_CLOUDのURI形式」を参照してください。
デフォルトのレコード・デリミタはdetected newlineです。detected newlineを指定すると、DBMS_CLOUDは、レコード・デリミタとして使用する適切な改行文字を自動的に見つけようとします。DBMS_CLOUDは、最初にWindowsの改行文字\r\nを検索します。Windowsの改行文字が見つかると、それがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。Windowsの改行文字が見つからない場合、DBMS_CLOUDは、UNIX/Linuxの改行文字\nを検索し、見つかった場合は\nがプロシージャのすべてのファイルのレコード・デリミタとして使用されます。ソース・ファイルで異なるレコード・デリミタの組合せが使用されている場合は、KUP-04020: found record longer than buffer size supportedなどのエラーが発生する可能性があります。この場合、同じレコード・デリミタを使用するようにソース・ファイルを変更するか、同じレコード・デリミタを使用するソース・ファイルのみを指定する必要があります。

recorddelimiterフォーマット・オプションについては、「DBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。

例

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

48.3.2.7 Apache Icebergに対応するCREATE_EXTERNAL_TABLEプロシージャ

このプロシージャは、サポートされている構成でApache Iceberg表の外部表を作成します。

サポートされている構成の説明は、Apache Iceberg表の問合せについてを参照してください

構文

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

パラメータ

パラメータ	説明
`table_name`	外部表の名前。
`credential_name`	データ・ファイル、メタデータ・ファイルおよびIcebergカタログ(使用されている場合)へのアクセスに使用される資格証明の名前。 AWS構成とOCI構成の場合は、「CREATE_CREDENTIALプロシージャ」の説明に従って資格証明を作成する必要があります。 AWS Amazon Resource Names (ARN)の資格証明は現在サポートされていません。
`file_uri_list`	Icebergカタログが指定されている場合はNULLである必要があります(次の`format`パラメータを参照)。Icebergカタログを使用しない場合、`file_uri_list`にはIcebergメタデータ・ファイルへのURIが含まれている必要があります。
`column_list`	NULLである必要があります。これは、列の名前と型が自動的にIcebergメタデータから導出されるためです。これらの列名は、基にあるデータ・ファイル(Parquet、Avro、ORC)内の名前と一致します。これらのOracleデータ型は、Icebergデータ型とParquetデータ型、Avroデータ型およびORCデータ型との間のParquet/Avro/ORCマッピングを使用して導出されます。そのため、ユーザーは`column_list`を指定できません。
`field_list`	NULLである必要があります。これは、列の名前とデータ型が自動的にIcebergメタデータから導出されるためです。
`format`	`format`パラメータの構造は、Iceberg表のタイプ(AWSまたはOCI)、および外部表の作成に使用される情報(たとえば、データ・カタログまたは直接メタデータURIからの情報)によって異なります。例と詳細は、次の例、OCIデータ・フロー・サンプルでのIcebergサポート、「DBMS_CLOUDのURI形式」を参照してください。

AWS Glueカタログを使用したAWS Iceberg表の例

AWS Glueカタログを使用してAWS Iceberg表の上に表を作成する場合のformatパラメータは次のとおりです:

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg',
                   'protocol_config' value
                    json_object('iceberg_catalog_type' value 'aws_glue',
                                'iceberg_glue_region'  value 'glue region',
                                'iceberg_table_path'   value 'database_name.table_name')));

ここでのaccess_protocolパラメータには、次の2つの要素があるJSONオブジェクトが含まれています:

protocol_type: 'iceberg'である必要があります
protocol_config: icebergカタログの詳細を示す、ネストされたJSONオブジェクト。
- iceberg_catalog_type: 'aws_glue'である必要があります
- iceberg_glue_region: カタログ・リージョン('us-west-1'など)
- iceberg_table_path: glue database.glue table nameというパス。

メタデータ・ファイルURIを使用したAWS Iceberg表の例

メタデータ・ファイルURIを使用してAWS Iceberg表の上に表を作成する場合のformatパラメータは次のとおりです:

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg')

HadoopCatalogカタログを使用したOCI Iceberg表の例

HadoopCatalogカタログを使用してOCIデータ・フローによって作成されたOCI Iceberg表の上に表を作成する場合のformatパラメータは次のとおりです:

format => json_object('access_protocol' value
       json_object('protocol_type'   value 'iceberg',
                   'protocol_config' value
                   json_object('iceberg_catalog_type'  value 'hadoop',
                               'iceberg_warehouse'     value '<OCI folder URI>',
                               'iceberg_table_path'    value 'database_name.table_name')));

ここでのaccess_protocolパラメータには、次の2つの要素があるJSONオブジェクトが含まれています:

protocol_type: 'iceberg'である必要があります
protocol_config: icebergカタログの詳細を示す、ネストされたJSONオブジェクト。
- iceberg_catalog_type: 'hadoop'である必要があります
- iceberg_warehouse: その表の生成時に使用されたウェアハウス・ディレクトリ・パス(ネイティブURI形式)。
- iceberg_table_path: その表の作成時に使用されたdatabase_name.table nameというパス。

メタデータ・ファイルのURIを使用したOCI Iceberg表の例

メタデータ・ファイルのURIを使用してOCI Iceberg表の上に表を作成する場合のformatパラメータは次のとおりです:

format => json_object('access_protocol' value
       json_object('protocol_type' value 'iceberg')

ここでのaccess_protocolパラメータには、次の1つの要素があるJSONオブジェクトが含まれています:

protocol_type: 'iceberg'である必要があります

48.3.2.8 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 DEFAULT NULL,
    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`でディレクトリを指定する場合、このパラメータは使用されません。
`file_uri_list`	このパラメータでは、ソース・ファイルURIのカンマ区切りリスト、または1つ以上のディレクトリとソース・ファイルを指定します。クラウドのソース・ファイルURI クラウドのソース・ファイルURIでのファイル名には、ワイルドカードと正規表現を使用できます。正規表現を使用できるのは、`regexuri` `format`パラメータが`TRUE`に設定されている場合のみです。この`regexuri`パラメータが`FALSE`に設定されている場合、文字""と"?"はワイルドカード文字とみなされます。この`regexuri`パラメータが`TRUE`に設定されている場合、文字""と"?"は、指定された正規表現パターンの一部となります。正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされており、パターン・マッチングは`REGEXP_LIKE`ファンクションによって実行されるものと同じです。このオプションは、オブジェクト・ストレージ内のファイルに作成される外部表の場合のみサポートされています。たとえば: `file_uri_list => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)year=[0-9]+(/)month=[0-9]+(/)[a-z]+[1-3]??.parquet'` URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。ディレクトリ 1つのディレクトリと1つ以上のファイル名を指定することも、ディレクトリとファイル名のカンマ区切りリストを使用することもできます。ディレクトリを指定する形式は、`'MY_DIR:filename.ext'`です。デフォルトでは、ディレクトリ名`MY_DIR`はデータベース・オブジェクトであり、大/小文字は区別されません。ファイル名は、大/小文字が区別されます。ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字""は、複数の文字に対応するワイルドカードとして使用できます。文字"?"は、1文字に対応するワイルドカードとして使用できます。例:`'MY_DIR:"`または`'MY_DIR:test?'` 複数のディレクトリを指定するには、ディレクトリのカンマ区切りリストを使用します。例:`'MY_DIR1:, MY_DIR2:test?'` 大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。例:`'"my_dir1":*, "my_dir2":Test?'` 引用符文字を含めるには、2つの引用符を使用します。例:`'MY_DIR:''filename.ext'`。これは、`filename`が引用符(`'`)で始まることを示します。
`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の`type`のソース・ファイルについては、「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列名へのマッピング」を参照してください。

48.3.2.9 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`	個別のパーティションの場所情報を含む、完全なパーティション化句を指定します。ディレクトリを使用するために、このパーティション化句では`LOCATION`値と`DEFAULT DIRECTORY`値がサポートされています。クラウドのソース・ファイルURIでのファイル名には、ワイルドカードと正規表現を使用できます。正規表現を使用できるのは、`regexuri` `format`パラメータが`TRUE`に設定されている場合のみです。この`regexuri`パラメータが`FALSE`に設定されている場合、文字""と"?"はワイルドカード文字とみなされます。この`regexuri`パラメータが`TRUE`に設定されている場合、文字""と"?"は、指定された正規表現パターンの一部となります。正規表現パターンはURI内のファイル名またはサブフォルダ・パスでのみサポートされており、パターン・マッチングは`REGEXP_LIKE`ファンクションによって実行されるものと同じです。ディレクトリ名に対して正規表現パターンはサポートされていません。たとえば: `partitioning_clause => 'partition by range (col1) (partition p1 values less than (1000) external location ( ''https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o(/)year=[0-9]+(/)month=[0-9]+(/)*[a-z]+[1-3]??.txt''),….` 次のように、事前認証済リクエスト(PAR) URLを使用して外部表を作成できます: 単一のOracle Database事前認証済リクエスト(PAR) URLを指定し、データにフィルタと句を適用します。たとえば、`WHERE`句を使用してデータをフィルタすることや、`ORDER BY`句を使用してそれをソートすることができます。 Oracle Databaseの事前認証済リクエスト(PAR) URLのカンマ区切りリストを指定します。含まれているPAR URLすべてで、列名、列の順序および列のデータ型が同じである必要があります。
`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
- GitHubリポジトリ
資格証明は表レベルのプロパティであるため、外部ファイルは同じオブジェクト・ストアに存在している必要があります。

詳細は、「DBMS_CLOUDのURI形式」を参照してください。
プロシージャDBMS_CLOUD.CREATE_HYBRID_PART_TABLEは、ローカル・ファイル・システムまたはネットワーク・ファイル・システムにあるディレクトリ内のハイブリッド・パーション・ファイルをサポートしています。
DBMS_CLOUD.CREATE_HYBRID_PART_TABLEを使用して作成する外部パーティション表には、2つの非表示列file$pathおよびfile$nameが含まれます。これらの列は、レコードの取得元ファイルの識別に役立ちます。
- file$path: オブジェクト名の先頭までのファイル・パス・テキストを指定します。
- file$name: バケット名に続くすべてのテキストを含め、オブジェクト名を指定します。

例

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;
/ 


BEGIN
   DBMS_CLOUD.CREATE_HYBRID_PART_TABLE(
    table_name  => 'HPT1',
    format      => json_object('delimiter'value ',', 'recorddelimiter'value 'newline'),
    column_list => 'NAME VARCHAR2(30), GENDER VARCHAR2(10), BALANCE number',
    partitioning_clause => 'partition by range (B  2  ALANCE)
               (partition p1 values less than (1000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Scott_male_1000.csv''),
                partition p2 values less than (2000) external DEFAULT DIRECTORY DATA_PUMP_DIR LOCATION (''Mary_female_3000.csv''),
                partition p3 values less than (3000))' );
END;
/

48.3.2.10 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では、現在実行中の操作(「実行中」ステータスの操作)は削除されません。

48.3.2.11 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;
/

48.3.2.12 DELETE_OBJECTプロシージャ

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

構文

DBMS_CLOUD.DELETE_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       force                IN BOOLEAN DEFAULT FALSE);

パラメータ

パラメータ	説明
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。
`object_uri`	削除するオブジェクトのオブジェクトまたはファイルURI。URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`force`	オブジェクトが存在しない場合、エラーを無視して報告しません。有効な値は`TRUE`および`FALSE`です。デフォルト値は`FALSE`です。

例

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;
/

48.3.2.13 DELETE_OPERATIONプロシージャ

このプロシージャは、スキーマ内のuser_load_operations表またはdba_load_operations表に記録されている、指定された操作IDのデータ・ロード・エントリをクリアします。

構文

DBMS_CLOUD.DELETE_OPERATION (
	id      IN NUMBER);

パラメータ

パラメータ	説明
`id`	削除するログ・ファイル・エントリに関連付けられている操作IDを指定します。

例

SELECT id FROM user_load_operations WHERE type LIKE '%BAD%';
EXEC DBMS_CLOUD.DELETE_OPERATION(id);

48.3.2.14 EXPORT_DATAプロシージャ

このプロシージャは、問合せの結果に基づいてOracle Databaseからデータをエクスポートします。このプロシージャはオーバーロードされており、クラウドまたはディレクトリへのファイルの書込みをサポートしています。

このプロシージャは、format typeパラメータに基づいて、ファイルをCSV、JSONまたはXML形式でテキスト・ファイルとしてクラウドまたはディレクトリの場所にエクスポートするか、ORACLE_DATAPUMPアクセス・ドライバを使用してOracle Datapumpダンプ・ファイルにデータを書き込みます。

構文

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB,
      format            IN CLOB,
      query             IN CLOB);

DBMS_CLOUD.EXPORT_DATA (
      credential_name   IN VARCHAR2 DEFAULT NULL,
      file_uri_list     IN CLOB DEFAULT NULL,
      format            IN CLOB DEFAULT NULL,
      query             IN CLOB DEFAULT NULL,
      operation_id      OUT NOCOPY NUMBER);

パラメータ

パラメータ	説明
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。この資格証明パラメータが含まれていない場合は、これにより、ディレクトリへの出力を指定します。
`file_uri_list`	formatパラメータの値に応じて、また、資格証明パラメータを含めるかどうかに応じて、形式が異なります: `format`パラメータの`type`の値が`json`である場合: `file_uri_list`パラメータの値に基づいて、オブジェクト・ストアにあるJSON、または指定したディレクトリの場所が、生成されたファイル名とともに保存されます。詳細は、テキスト出力(CSV、JSON、ParquetまたはXML)のファイル・ネーミングを参照してください。 `format`パラメータの`type`の値が`datapump`である場合、`file_uri_list`はダンプ・ファイルのカンマ区切りリストです。これにより、オブジェクト・ストア上に作成するファイルを指定します。`file_uri_list`では、ワイルドカードおよび置換文字の使用はサポートされていません。 `credential_name`パラメータを指定しない場合は、`file_uri_list`にディレクトリ名を指定します。 URIの形式は、使用しているCloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`format`	エクスポート・フォーマット・オプションを示すJSON文字列。サポートされているオプションは次のとおりです: `type`: `type` `format`オプションは必須であり、値`csv` \| `datapump` \| `json` \| `xml`のどれかを指定する必要があります。
`query`	このパラメータを使用して、必要なデータのみがエクスポートされるように`SELECT`文を指定します。この問合せにより、テキスト・ファイル(CSV、JSONまたはXML)として、またはダンプ・ファイルとしてエクスポートするファイルのコンテンツが決まります。たとえば: `SELECT warehouse_id, quantity FROM inventories` `format` `type`値が`json`である場合は、各問合せ結果がチェックされ、ファンクション`JSON_OBJECT_T.parse()`でそれがJSONでないと判断されると、`DBMS_CLOUD.EXPORT_DATA`によって、その行をJSONに変換する`JSON_OBJECT`ファンクションを含むようにその問合せが変換されます。たとえば: `SELECT JSON_OBJECT(* RETURNING CLOB) from(SELECT warehouse_id, quantity FROM inventories)`
`operation_id`	このパラメータは、エクスポート操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビュー内の対応するIDとして追跡するために使用します。

使用上のノート:

指定するqueryパラメータ値は、必要に応じて、拡張問合せ(結合や副問合せを含む問合せなど)にできます。
指定されたフォーマット・パラメータに応じて、DBMS_CLOUD.EXPORT_DATAは、指定された問合せの結果を、クラウド・オブジェクト・ストアまたはディレクトリの場所に、次のいずれかの形式で出力します:
- CSV、JSONまたはXMLファイル。
  
  CSV、JSONまたはXML出力ファイルでのDBMS_CLOUD.EXPORT_DATAの使用の詳細は、テキストとしてのオブジェクト・ストアへのデータのエクスポートおよびディレクトリへのデータのエクスポートを参照してください。
- ORACLE_DATAPUMPアクセス・ドライバを使用してダンプ・ファイルにデータを書き込みます。
CSV、JSONまたはXML出力の場合、デフォルトでは、生成されたファイルにデータが10MB含まれていると、新しい出力ファイルが作成されます。ただし、結果データが10MB未満である場合にも、データベース・サービス、およびAutonomous AI DatabaseインスタンスのECPUの数(データベースでOCPUが使用されている場合はOCPU)に応じて、複数の出力ファイルになることがあります。

詳細は、テキスト出力(CSV、JSON、ParquetまたはXML)のファイル・ネーミングを参照してください。

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

ORACLE_DATAPUMPの出力についての使用上のノート(formatパラメータのtypeオプションにdatapumpを指定したDBMS_CLOUD.EXPORT_DATA):

EXPORT_DATAは、デフォルトのロギング・ディレクトリとしてDATA_PUMP_DIRを使用します。そのため、ORACLE_DATAPUMPの出力を使用する場合は、DATA_PUMP_DIRに対する書込み権限が必要です。
formatパラメータのtypeオプションにdatapumpを指定したDBMS_CLOUD.EXPORT_DATAの使用によるOracle Databaseエクスポートでは、Oracle Cloud Infrastructure Object Storage、Oracle Cloud Infrastructure Object Storage Classicオブジェクト・ストアまたはディレクトリ出力のみがサポートされています。
Oracle Data Pumpは、アップロードを高速化するために、各ダンプ・ファイル部分を複数の小さいチャンクに分割します。Oracle Cloud Infrastructure Object Storageコンソールには、エクスポートするダンプ・ファイル部分ごとに複数のファイルが表示されます。実際のダンプ・ファイルのサイズはゼロ(0)と表示され、その関連するファイル・チャンクは10MB以下と表示されます。次に例を示します:
```
exp01.dmp
exp01.dmp_aaaaaa
exp02.dmp
exp02.dmp_aaaaaa
```
Oracle Cloud InfrastructureコンソールまたはOracle Cloud Infrastructure CLIを使用してゼロ・バイトのダンプ・ファイルをダウンロードしても、完全なダンプ・ファイルは得られません。オブジェクト・ストアから完全なダンプ・ファイルをダウンロードするには、Swiftをサポートするツール(curlなど)を使用し、ユーザー・ログインとSwift認証トークンを指定します。
```
curl -O -v -X GET -u 'user1@example.com:auth_token' \
   https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/namespace-string/bucketname/exp01.dmp
```
formatパラメータのtypeの値'datapump'をサポートしているDBMS_CLOUDプロシージャを使用してファイルをインポートする場合は、プライマリ・ファイル名のみを指定する必要があります。'datapump'形式タイプをサポートしているプロシージャは、チャンクを自動的に検出しダウンロードします。

DBMS_CLOUD.DELETE_OBJECTを使用する場合、このプロシージャは、プライマリ・ファイルを削除するときにチャンクを自動的に検出して削除します。
DBMS_CLOUD.EXPORT_DATAプロシージャは、次のように、指定されたfile_uri_list値からダンプ・ファイルを作成します:
- より多くのファイルが必要な場合、このプロシージャは、file_uri_listからファイルをさらに作成します。
- このプロシージャは、ファイルを上書きしません。file_uri_list内にダンプ・ファイルがある場合、DBMS_CLOUD.EXPORT_DATAはエラーを報告します。
- DBMS_CLOUD.EXPORT_DATAはバケットを作成しません。
DBMS_CLOUD.EXPORT_DATAによって生成されるダンプ・ファイルの数は、このプロシージャの実行時に決まります。生成されるダンプ・ファイルの数は、file_uri_listパラメータで指定したファイル名の数によって異なります。
DBMS_CLOUD.EXPORT_DATAを使用して作成したダンプ・ファイルは、Oracle Data Pumpのimpdpを使用してインポートできません。データベースに応じて、次のようにこれらのファイルを使用できます:
- Oracle Databaseインスタンスでは、formatパラメータのtypeの値datapumpをサポートしているDBMS_CLOUDプロシージャでそれらのダンプ・ファイルを使用できます。DBMS_CLOUD.COPY_DATAを使用してそれらのダンプ・ファイルをインポートするか、DBMS_CLOUD.CREATE_EXTERNAL_TABLEをコールして外部表を作成することができます。
- 他のどのOracle Databaseでも、ORACLE_DATAPUMPアクセス・ドライバを使用してプロシージャDBMS_CLOUD.EXPORT_DATAで作成されたダンプ・ファイルをインポートできます。
指定するqueryパラメータ値は、必要に応じて、拡張問合せ(結合や副問合せを含む問合せなど)にできます。

ディレクトリに出力する場合のDBMS_CLOUD.EXPORT_DATAの使用上のノート

指定したディレクトリが存在する必要があり、ADMINユーザーとしてログインしているか、そのディレクトリへのWRITEアクセス権がある必要があります。
DBMS_CLOUD.EXPORT_DATAはディレクトリを作成しません。
このプロシージャは、ファイルを上書きしません。たとえば、file_uri_list内にダンプ・ファイルがある場合、DBMS_CLOUD.EXPORT_DATAは次のようなエラーを報告します:
```
ORA-31641: unable to create dump file  "/u02/exports/123.dmp"
ORA-27038: created file already exists
```

例

次の例は、format typeパラメータに値datapumpを指定したDBMS_CLOUD.EXPORT_DATAを示しています:

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name =>'OBJ_STORE_CRED',
      file_uri_list =>'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp1.dmp',
      format => json_object('type' value 'datapump', 'compression' value 'basic', 'version' value 'latest'),
      query => 'SELECT warehouse_id, quantity FROM inventories'
     );
   END;
/

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

次の例は、format typeパラメータに値jsonを指定したDBMS_CLOUD.EXPORT_DATAを示しています:

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

次の例は、format typeパラメータに値xmlを指定したDBMS_CLOUD.EXPORT_DATAを示しています:

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

次の例は、format typeパラメータに値csvを指定したDBMS_CLOUD.EXPORT_DATAを示しています:

BEGIN  
   DBMS_CLOUD.EXPORT_DATA(
      credential_name => 'OBJ_STORE_CRED',
      file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/exp.csv', 
      query           => 'SELECT * FROM DEPT',
      format          => JSON_OBJECT('type' value 'csv', 'delimiter' value '|', 'compression' value 'gzip', 'header' value true, 'encryption' value ('user_defined_function' value 'ADMIN.decryption_callback')));
     );
   END;
/

次の例は、typeパラメータに値datapumpを指定した、ディレクトリの場所にデータをエクスポートするDBMS_CLOUD.EXPORT_DATAを示しています:

BEGIN
 DBMS_CLOUD.EXPORT_DATA(
    file_uri_list => 'export_dir:sales.dmp',
    format        => json_object('type' value 'datapump'),
    query         => 'SELECT * FROM sales'
 );
END;
/

48.3.2.15 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 次のように、事前認証済リクエスト(PAR) URLを使用して外部表を作成できます: 単一のOracle Database事前認証済リクエスト(PAR) URLを指定し、データにフィルタと句を適用します。たとえば、`WHERE`句を使用してデータをフィルタすることや、`ORDER BY`句を使用してそれをソートすることができます。 Oracle Databaseの事前認証済リクエスト(PAR) URLのカンマ区切りリストを指定します。含まれているPAR URLすべてで、同一スキーマ内の、同一の列名、列の順序および列のデータ型が使用されている必要があります。
`file_name`	作成するファイルの名前を指定します。ファイル名の指定がない場合、ファイル名は`object_uri`パラメータの最後のスラッシュの後から取得されます。ファイル名にスラッシュが含まれている場合などの特殊なケースに、`file_name`パラメータを使用します。
`startoffset`	プロシージャが読取りを開始する場所のオフセット(バイト単位)。
`endoffset`	プロシージャが読取りを終了する場所のオフセット(バイト単位)。
`compression`	オブジェクトの格納に使用する圧縮を指定します。`compression`が`'AUTO'`に設定されている場合、ファイルは圧縮解除されます(値`'AUTO'`は、`object_uri`で指定されたオブジェクトがGzipで圧縮されることを意味します)。

^脚注1

ノート:

DBMS_CLOUD.GET_OBJECTを実行するには、そのユーザーにそのディレクトリに対するWRITE権限を付与する必要があります。たとえば、次のコマンドを特権ユーザーとして実行して、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;
/

48.3.2.16 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

48.3.2.17 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	タイムスタンプが戻されます	タイムスタンプが戻されます
Oracle Cloud Infrastructure Swift	`NULL`が戻されます	タイムスタンプが戻されます
Oracle Cloud Infrastructure Classic	`NULL`が戻されます	タイムスタンプが戻されます
Amazon S3	`NULL`が戻されます	タイムスタンプが戻されます
Azure	タイムスタンプが戻されます	タイムスタンプが戻されます
GitHubリポジトリ

チェックサム値は、MD5チェックサムです。これは、オブジェクトの内容に対して計算される32文字の16進数です。
これは、戻り値のタイプが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

48.3.2.18 MOVE_OBJECTプロシージャ

このプロシージャは、一方のCloud Object Storageバケットまたはフォルダから他方にオブジェクトを移動します。

ソースとターゲットのバケットまたはフォルダは、同一の、または異なるクラウド・オブジェクト・ストア・プロバイダに配置できます。

ソースの資格証明名は、デフォルトでは、ターゲットの資格証明名が指定されていない場合はターゲットの場所でも使用されます。

構文

DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name  IN  VARCHAR2 DEFAULT NULL,
    source_object_uri       IN  VARCHAR2,
    target_object_uri       IN  VARCHAR2,
    target_credential_name  IN  VARCHAR2 DEFAULT NULL
);

パラメータ

パラメータ	説明
`source_credential_name`	ソースCloud Object Storageにアクセスするための資格証明の名前。 `source_credential_name`の値を指定しなかった場合、`credential_name`は`NULL`に設定されます。
`source_object_uri`	ソースのオブジェクト・ストレージ・バケットまたはフォルダの場所を指すURIを指定します。このパラメータは必須です。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`target_object_uri`	ファイルを移動する必要があるターゲット・オブジェクト・ストレージ・バケットまたはフォルダのURIを指定します。このパラメータは必須です。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`target_credential_name`	ターゲットCloud Object Storageにアクセスするための資格証明の名前。 `target_credential_name`の値を指定しなかった場合、`target_object_uri`は`source_credential_name`の値に設定されます。

例

BEGIN 
DBMS_CLOUD.MOVE_OBJECT (
    source_credential_name => 'OCI_CRED',
    source_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/bgfile.csv',
    target_object_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/myfile.csv'
);
END;
/

48.3.2.19 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
       compression          IN VARCHAR2 DEFAULT  NULL);


DBMS_CLOUD.PUT_OBJECT (
       credential_name      IN VARCHAR2,
       object_uri           IN VARCHAR2,
       contents             IN BLOB
       compression          IN VARCHAR2 DEFAULT  NULL);

パラメータ

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

^脚注2

ノート:

DBMS_CLOUD.PUT_OBJECTを実行するには、そのユーザーにそのディレクトリに対する読取り権限を付与する必要があります。たとえば、次のコマンドを特権ユーザーとして実行して、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形式」を参照してください。

48.3.2.20 SYNC_EXTERNAL_PART_TABLEプロシージャ

このプロシージャは、クラウド内のファイルからの、パーティション化された外部表の更新を簡略化します。新しいパーティションを追加するたびに、またはパーティション化された外部表に対してオブジェクト・ストア・ソースからパーティションを削除するときに、このプロシージャを実行します。

構文

DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE (
	table_name        IN VARCHAR2,
	schema_name       IN VARCHAR2 DEFAULT,
	update_columns    IN BOOLEAN DEFAULT);

パラメータ

パラメータ説明

パラメータ	説明
`table_name`	ターゲット表の名前ターゲット表は、`DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE`を実行する前に作成する必要があります。
`schema_name`	ターゲット表が存在するスキーマの名前。デフォルト値は、NULLです。この値は、ターゲット表がプロシージャを実行するユーザーと同じスキーマ内にあることを意味します。
`update_columns`	新しいファイルによって、そのスキーマに変化が生じる場合があります。サポートされている更新としては、新しい列、削除された列があります。既存の列に対する更新(たとえば、データ型の変更)ではエラーがスローされます。デフォルト値: False

table_name

ターゲット表の名前ターゲット表は、DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLEを実行する前に作成する必要があります。

schema_name

ターゲット表が存在するスキーマの名前。デフォルト値は、NULLです。この値は、ターゲット表がプロシージャを実行するユーザーと同じスキーマ内にあることを意味します。

update_columns

新しいファイルによって、そのスキーマに変化が生じる場合があります。サポートされている更新としては、新しい列、削除された列があります。既存の列に対する更新(たとえば、データ型の変更)ではエラーがスローされます。

デフォルト値: False

48.3.2.21 VALIDATE_EXTERNAL_PART_TABLEプロシージャ

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

構文

DBMS_CLOUD.VALIDATE_EXTERNAL_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_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,
       subpartition_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`に達するまで、すべてのパーティションを順次読み取ります。
`subpartition_name`	定義した場合、特定のサブパーティションのみが検証されます。指定しない場合は、`rowcount`に達するまで、すべての外部パーティションまたはサブパーティションから順次読み取ります。
`schema_name`	外部表が存在するスキーマの名前。デフォルト値は、NULLです。この値は、外部表がプロシージャを実行するユーザーと同じスキーマ内にあることを意味します。
`rowcount`	スキャンされる行数デフォルト値は、NULLです。ソース・ファイルのすべての行がスキャンされることを意味します。
`partition_key_validation`	内部使用のみに対応しています。このパラメータは使用しないでください。
`stop_on_error`	行が拒否されたときに検証を停止するかどうかを決定します。デフォルト値は、`TRUE`です。この値は、検証が最初に拒否された行で停止することを意味します。この値を`FALSE`に設定すると、検証が最初に拒否された行で停止せずに、`rowcount`パラメータで指定された値までのすべての行が検証されます。

48.3.2.22 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が適用されるまで、すべての外部パーティションからデータを読み取る可能性があります。読み取るパーティションまたはパーティションの部分の順序は制御できません。

48.3.2.23 VALIDATE_HYBRID_PART_TABLEプロシージャ

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

構文

DBMS_CLOUD.VALIDATE_HYBRID_PART_TABLE (
       table_name                 IN VARCHAR2,
       partition_name             IN CLOB DEFAULT,
       subpartition_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,
       subpartition_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`に達するまで、すべての外部パーティションから順次読み取ります。
`subpartition_name`	定義した場合、特定のサブパーティションのみが検証されます。指定しない場合は、`rowcount`に達するまで、すべての外部パーティションまたはサブパーティションから順次読み取ります。
`schema_name`	外部表が存在するスキーマの名前。デフォルト値は、NULLです。この値は、外部表がプロシージャを実行するユーザーと同じスキーマ内にあることを意味します。
`rowcount`	スキャンされる行数デフォルト値は、NULLです。ソース・ファイルのすべての行がスキャンされることを意味します。
`partition_key_validation`	内部使用のみに対応しています。このパラメータは使用しないでください。
`stop_on_error`	行が拒否されたときに検証を停止するかどうかを決定します。デフォルト値は、`TRUE`です。この値は、検証が最初に拒否された行で停止することを意味します。この値を`FALSE`に設定すると、検証が最初に拒否された行で停止せずに、`rowcount`パラメータで指定された値までのすべての行が検証されます。

48.3.3 一括ファイル管理用のDBMS_CLOUD

DBMS_CLOUDパッケージ内の一括ファイル操作用のサブプログラム。

サブプログラム	説明
BULK_COPYプロシージャ	このプロシージャは、Cloud Object Storageバケット間でファイルをコピーします。
BULK_DELETEプロシージャ	このプロシージャは、Cloud Object Storageバケットまたはフォルダからファイルを削除します。
BULK_DOWNLOADプロシージャ	このプロシージャは、クラウド・オブジェクト・ストア・バケットからAutonomous Database内のディレクトリにファイルをダウンロードします。
BULK_MOVEプロシージャ	このプロシージャは、Cloud Object Storageバケット間でファイルを移動します。
BULK_UPLOADプロシージャ	このプロシージャは、Autonomous Database内のディレクトリからCloud Object Storageにファイルをアップロードします。

48.3.3.1 BULK_COPYプロシージャ

このプロシージャは、Cloud Object Storageバケット間で複数のファイルを一括でコピーします。オーバーロードされた形式では、operation_idパラメータを使用できるようになります。

REGEXP_LIKE演算子と互換性のある正規表現パターンを使用して、削除するファイルのリストをフィルタできます。

ソースとターゲットのバケットまたはフォルダは、同一の、または異なるクラウド・オブジェクト・ストア・プロバイダに配置できます。

デフォルトでは、ソース資格証明名はターゲットの場所でも使用されます。

構文

DBMS_CLOUD.BULK_COPY (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_COPY (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL,
      operation_id            OUT NUMBER
);

パラメータ

パラメータ	説明
`source_credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。 `source_credential_name`の値を指定しなかった場合、`credential_name`は`NULL`に設定されます。
`source_location_uri`	ソースのオブジェクト・ストレージ・バケットまたはフォルダの場所を指すURIを指定します。このパラメータは必須です。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`target_location_uri`	ファイルをコピーする必要があるターゲット・オブジェクト・ストレージ・バケットまたはフォルダのURIを指定します。このパラメータは必須です。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`target_credential_name`	ターゲットCloud Object Storageにアクセスするための資格証明の名前。 `target_credential_name`の値を指定しなかった場合、`target_location_uri`は`source_credential_name`の値に設定されます。
`regex_filter`	ファイルをフィルタするためのREGEX式を指定します。このREGEX式パターンは、`REGEXP_LIKE`演算子と互換性が必要です。 `regex_filter`の値を指定しなかった場合、`regex_filter`は`NULL`に設定されます。
`format`	そのファイル操作について構成オプションを追加指定します。これらのオプションはJSON文字列として指定されます。サポートされているフォーマット・オプションは次のとおりです: `logretention`: これには、ステータス表をバルク操作のために保持する期間(日数)を決める、整数値を指定します。デフォルト値は2 daysです。 `logprefix`: これには、バルク操作のステータス表の名前の接頭辞文字列を決める、文字列値を指定します。操作タイプがそのデフォルト値です。`BULK_COPY`の場合、デフォルトの`logprefix`値は`COPYOBJ`です。 `format`の値を指定しなかった場合、`format`は`NULL`に設定されます。
`operation_id`	このパラメータは、ロード操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビューの対応するIDとして追跡するために使用します。

使用上のノート

ソースURIとターゲットURIで同じオブジェクト・ストレージ・バケットまたはフォルダが指し示されている場合は、エラーが戻されます。

例

BEGIN 
DBMS_CLOUD.BULK_COPY (
     source_credential_name => 'OCI_CRED',
     source_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/o',
     target_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
     format       => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
);
END;
/

48.3.3.2 BULK_DELETEプロシージャ

このプロシージャは、Cloud Object Storageから複数のファイルを一括で削除します。オーバーロードされた形式では、operation_idパラメータを使用できるようになります。REGEXP_LIKE演算子と互換性のある正規表現パターンを使用して、削除するファイルのリストをフィルタできます。

構文

 DBMS_CLOUD.BULK_DELETE(
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_DELETE (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

パラメータ

パラメータ	説明
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。 `credential_name`の値を指定しなかった場合、`credential_name`は`NULL`に設定されます。
`location_uri`	Autonomous Database内のオブジェクト・ストレージの場所を指すURIを指定します。このパラメータは必須です。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`regex_filter`	ファイルをフィルタするためのREGEX式を指定します。このREGEX式パターンは、`REGEXP_LIKE`演算子と互換性が必要です。 `regex_filter`の値を指定しなかった場合、`regex_filter`は`NULL`に設定されます。
`format`	そのファイル操作について構成オプションを追加指定します。これらのオプションはJSON文字列として指定されます。サポートされているフォーマット・オプションは次のとおりです: `logretention`: これには、ステータス表をバルク操作のために保持する期間(日数)を決める、整数値を指定します。デフォルト値は2 daysです。 `logprefix`: これには、バルク操作のステータス表の名前の接頭辞文字列を決める、文字列値を指定します。操作タイプがそのデフォルト値です。`BULK_DELETE`の場合、デフォルトの`logprefix`値は`DELETE`です。 `format`の値を指定しなかった場合、`format`は`NULL`に設定されます。
`operation_id`	このパラメータは、ロード操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビューの対応するIDとして追跡するために使用します。

例

BEGIN
DBMS_CLOUD.BULK_DELETE (    
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     format          => JSON_OBJECT ('logretention' value 5, 'logprefix' value 'BULKDEL')
);
END;
/

48.3.3.3 BULK_DOWNLOADプロシージャ

このプロシージャは、Cloud Object StorageからAutonomous Databaseのディレクトリにファイルをダウンロードします。オーバーロードされた形式では、operation_idパラメータを使用できるようになります。REGEXP_LIKE演算子と互換性のある正規表現パターンを使用して、ダウンロードするファイルのリストをフィルタできます。

構文

DBMS_CLOUD.BULK_DOWNLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_DOWNLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

パラメータ

パラメータ	説明
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。 `credential_name`の値を指定しなかった場合、`credential_name`は`NULL`に設定されます。
`location_uri`	Autonomous Database内のオブジェクト・ストレージの場所を指すURIを指定します。このパラメータは必須です。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`directory_name`	ファイルのダウンロード元である、Autonomous Database上のディレクトリの名前。このパラメータは必須です。
`regex_filter`	ファイルをフィルタするためのREGEX式を指定します。このREGEX式パターンは、`REGEXP_LIKE`演算子と互換性が必要です。 `regex_filter`の値を指定しなかった場合、`regex_filter`は`NULL`に設定されます。
`format`	そのファイル操作について構成オプションを追加指定します。これらのオプションはJSON文字列として指定されます。サポートされているフォーマット・オプションは次のとおりです: `logretention`: これには、ステータス表をバルク操作のために保持する期間(日数)を決める、整数値を指定します。デフォルト値は2 daysです。 `logprefix`: これには、バルク操作のステータス表の名前の接頭辞文字列を決める、文字列値を指定します。`BULK_DOWNLOAD`の場合、デフォルトの`logprefix`値は`DOWNLOAD`です。操作タイプがそのデフォルト値です。 `format`の値を指定しなかった場合、`format`は`NULL`に設定されます。
`operation_id`	このパラメータは、ロード操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビューの対応するIDとして追跡するために使用します。

例

BEGIN
DBMS_CLOUD.BULK_DOWNLOAD (    
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     directory_name  => 'BULK_TEST',
     format          => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKOP')
 );
END;
/

48.3.3.4 BULK_MOVEプロシージャ

このプロシージャは、一方のCloud Object Storageバケットまたはフォルダから他方に、複数のファイルを一括で移動します。オーバーロードされた形式では、operation_idパラメータを使用できるようになります。

REGEXP_LIKE演算子と互換性のある正規表現パターンを使用して、削除するファイルのリストをフィルタできます。

ソースとターゲットのバケットまたはフォルダは、同一の、または異なるクラウド・オブジェクト・ストア・プロバイダに配置できます。

ソースの資格証明名は、デフォルトでは、ターゲットの資格証明名が指定されていない場合はターゲットの場所でも使用されます。

ファイルを移動する際の最初のステップは、ターゲットの場所にそれらをコピーすることであり、それらが正常にコピーされた後、ソース・ファイルを削除します。

オブジェクト・ストアでソースの場所とターゲットの場所の間での操作の名前変更が許可されている場合、オブジェクトは移動されるのではなく名前変更されます。

構文

DBMS_CLOUD.BULK_MOVE (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_MOVE (
      source_credential_name  IN  VARCHAR2 DEFAULT NULL,
      source_location_uri     IN  VARCHAR2,
      target_location_uri     IN  VARCHAR2,
      target_credential_name  IN  VARCHAR2 DEFAULT NULL,
      regex_filter            IN  VARCHAR2 DEFAULT NULL,
      format                  IN  CLOB     DEFAULT NULL,
      operation_id            OUT NUMBER
);

パラメータ

パラメータ	説明
`source_credential_name`	ソースCloud Object Storageにアクセスするための資格証明の名前。 `source_credential_name`の値を指定しなかった場合、`credential_name`は`NULL`に設定されます。
`source_location_uri`	ソースのオブジェクト・ストレージ・バケットまたはフォルダの場所を指すURIを指定します。このパラメータは必須です。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`target_location_uri`	ファイルを移動する必要があるターゲット・オブジェクト・ストレージ・バケットまたはフォルダのURIを指定します。このパラメータは必須です。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`target_credential_name`	ターゲットCloud Object Storageにアクセスするための資格証明の名前。 `target_credential_name`の値を指定しなかった場合、`target_location_uri`は`source_credential_name`の値に設定されます。
`regex_filter`	ファイルをフィルタするためのREGEX式を指定します。このREGEX式パターンは、`REGEXP_LIKE`演算子と互換性が必要です。 `regex_filter`の値を指定しなかった場合、`regex_filter`は`NULL`に設定されます。
`format`	そのファイル操作について構成オプションを追加指定します。これらのオプションはJSON文字列として指定されます。サポートされているフォーマット・オプションは次のとおりです: `logretention`: これには、ステータス表をバルク操作のために保持する期間(日数)を決める、整数値を指定します。デフォルト値は2 daysです。 `logprefix`: これには、バルク操作のステータス表の名前の接頭辞文字列を決める、文字列値を指定します。操作タイプがそのデフォルト値です。`BULK_MOVE`の場合、デフォルトの`logprefix`値は`MOVE`です。 `format`の値を指定しなかった場合、`format`は`NULL`に設定されます。
`operation_id`	このパラメータは、ロード操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビューの対応するIDとして追跡するために使用します。

例

BEGIN 
DBMS_CLOUD.BULK_MOVE (    
     source_credential_name => 'OCI_CRED',
     source_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname1/o',
     target_location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname2/o',
     format                 => JSON_OBJECT ('logretention' value 7, 'logprefix' value 'BULKMOVE')
);
END;
/

ノート:

ソースURIとターゲットURIで同じオブジェクト・ストレージ・バケットまたはフォルダが指し示されている場合は、エラーが戻されます。

48.3.3.5 BULK_UPLOADプロシージャ

このプロシージャは、Autonomous DatabaseディレクトリからCloud Object Storageにファイルをコピーします。オーバーロードされた形式では、operation_idパラメータを使用できるようになります。

構文

DBMS_CLOUD.BULK_UPLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL
);

DBMS_CLOUD.BULK_UPLOAD (
     credential_name  IN  VARCHAR2 DEFAULT NULL,
     location_uri     IN  VARCHAR2,
     directory_name   IN  VARCHAR2,
     regex_filter     IN  VARCHAR2 DEFAULT NULL,
     format           IN  CLOB     DEFAULT NULL,
     operation_id     OUT NUMBER
);

パラメータ

パラメータ	説明
`credential_name`	Cloud Object Storageにアクセスするための資格証明の名前。 `credential_name`の値を指定しなかった場合、`credential_name`は`NULL`に設定されます。
`location_uri`	ファイルをアップロードするオブジェクト・ストレージの場所を指すURIを指定します。このパラメータは必須です。 URIの形式は、Cloud Object Storageサービスによって異なります。詳細は、「DBMS_CLOUDのURI形式」を参照してください。
`directory_name`	ファイルのアップロード元である、Autonomous Database上のディレクトリの名前。このパラメータは必須です。
`regex_filter`	ファイルをフィルタするためのREGEX式を指定します。このREGEX式パターンは、`REGEXP_LIKE`演算子と互換性が必要です。 `regex_filter`の値を指定しなかった場合、`regex_filter`は`NULL`に設定されます。
`format`	そのファイル操作について構成オプションを追加指定します。これらのオプションはJSON文字列として指定されます。サポートされているフォーマット・オプションは次のとおりです: `logretention`: これには、ステータス表をバルク操作のために保持する期間(日数)を決める、整数値を指定します。デフォルト値は2 daysです。 `logprefix`: これには、バルク操作のステータス表の名前の接頭辞文字列を決める、文字列値を指定します。操作タイプがそのデフォルト値です。`BULK_UPLOAD`の場合、デフォルトの`logprefix`値は`UPLOAD`です。 `format`の値を指定しなかった場合、`format`は`NULL`に設定されます。
`operation_id`	このパラメータは、ロード操作の進行状況および最終ステータスを`USER_LOAD_OPERATIONS`ビューの対応するIDとして追跡するために使用します。

例

BEGIN
DBMS_CLOUD.BULK_UPLOAD ( 
     credential_name => 'OCI_CRED',
     location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o',
     directory_name  => 'BULK_TEST',
     format          => JSON_OBJECT ('logretention' value 5, 'logprefix' value 'BULKUPLOAD')
 );
END;
/

48.3.4 DBMS_CLOUD REST API

この項では、Autonomous AI Databaseに付随する、DBMS_CLOUD REST APIについて説明します。

REST API	説明
GET_RESPONSE_HEADERSファンクション	このファンクションは、Oracle DatabaseにおいてHTTPレスポンス・ヘッダーをJSONオブジェクト内のJSONデータとして戻します。
GET_RESPONSE_RAWファンクション	このファンクションは、HTTPレスポンスを、Oracle DatabaseのRAW形式で戻します。これは、HTTPレスポンスがバイナリ形式であると想定されている場合に役立ちます。
GET_RESPONSE_STATUS_CODEファンクション	このファンクションは、Oracle DatabaseにおいてHTTPレスポンス・ステータス・コードを整数として戻します。このステータス・コードは、そのリクエストが成功したかどうかを識別するのに役立ちます。
GET_RESPONSE_TEXTファンクション	このファンクションは、Oracle DatabaseにおいてHTTPレスポンスをTEXT形式(`VARCHAR2`または`CLOB`)で戻します。通常、ほとんどのクラウドREST APIは、JSONレスポンスをテキスト形式で戻します。このファンクションは、HTTPレスポンスがテキスト形式であることを想定している場合に役立ちます。
GET_API_RESULT_CACHE_SIZEファンクション	このファンクションは、構成されている結果キャッシュ・サイズを戻します。
SEND_REQUESTファンクションおよびプロシージャ	このファンクションは、Oracle Databaseにおいて、HTTPリクエストを開始し、そのレスポンスを取得し、そのレスポンスを終了します。このファンクションは、引数があるクラウドREST APIリクエストを送信するためのワークフローを提供し、戻り値のレスポンス・コードおよびペイロードを提供します。
SET_API_RESULT_CACHE_SIZEプロシージャ	このプロシージャは、現行セッションの最大キャッシュ・サイズを設定します。

48.3.4.1 DBMS_CLOUD REST APIの概要

アプリケーションでPL/SQLを使用しているときに、クラウドREST APIをコールする必要がある場合は、DBMS_CLOUD.SEND_REQUESTを使用してREST APIリクエストを送信できます。

DBMS_CLOUD REST APIファンクションを使用すると、DBMS_CLOUD.SEND_REQUESTを使用してHTTPリクエストを作成し、結果を取得し保存できます。これらのファンクションは、サポートされている次のクラウド・サービスを使用して任意のREST APIをコールできる、汎用APIを提供します:

Oracle Cloud Infrastructure
Oracle Cloud Infrastructure REST APIについては、「APIリファレンスとエンドポイント」を参照してください。
Amazon Web Services (AWS)
Amazon Web Services REST APIについては、「Guides and API References」を参照してください。
Azure Cloud ^脚注3
Azure REST APIについては、「Azure REST API Reference」を参照してください。
Oracle Cloud Infrastructure Classic
Oracle Cloud Infrastructure Classic REST APIについては、「すべてのRESTエンドポイント」を参照してください。
GitHubリポジトリ
詳細は、GitHub REST APIを参照してください。

48.3.4.2 DBMS_CLOUD REST APIの定数

DBMS_CLOUD.SEND_REQUESTを使用してHTTPリクエストを行うためのDBMS_CLOUD定数について説明します。

DBMS_CLOUDでは、GET、PUT、POST、HEADおよびDELETE HTTPメソッドがサポートされています。HTTPリクエストに使用されるREST APIメソッドは、通常は、クラウドREST APIのドキュメントに記載されています。

名前	タイプ	値
`METHOD_DELETE`	`VARCHAR2(6)`	`'DELETE'`
`METHOD_GET`	`VARCHAR2(3)`	`'GET'`
`METHOD_HEAD`	`VARCHAR2(4)`	`'HEAD'`
`METHOD_POST`	`VARCHAR2(4)`	`'POST'`
`METHOD_PUT`	`VARCHAR2(3)`	`'PUT'`

48.3.4.3 DBMS_CLOUD REST APIの結果キャッシュ

DBMS_CLOUD.SEND_REQUESTでcacheパラメータをtrueに設定すると、DBMS_CLOUD REST APIの結果を保存できます。SESSION_CLOUD_API_RESULTSビューでは、REST APIの結果が保存されているときに使用可能な列が示されます。

デフォルトでは、DBMS_CLOUD REST APIのコールでセッションに対して結果が保存されることはありません。この場合は、DBMS_CLOUD.SEND_REQUESTファンクションを使用して結果を戻します。

DBMS_CLOUD.SEND_REQUESTを使用し、そのcacheパラメータをTRUEに設定すると、結果が保存されます。SESSION_CLOUD_API_RESULTSビューで過去の結果を表示できます。DBMS_CLOUD REST APIリクエストの過去の結果を保存し問い合せると、アプリケーションで以前の結果を使用する必要があるときに役立つ可能性があります。

たとえば、最近のDBMS_CLOUD REST APIの結果を問い合せるには、ビューSESSION_CLOUD_API_RESULTSを使用します:

SELECT timestamp FROM SESSION_CLOUD_API_RESULTS;

DBMS_CLOUD REST APIの結果をDBMS_CLOUD.SEND_REQUESTで保存した場合、保存したデータは、同じセッション(接続)内でのみ使用できます。そのセッションが終了すると、保存したデータを使用できなくなります。

DBMS_CLOUD REST APIのキャッシュ・サイズの表示と設定には、また、キャッシュの無効化には、DBMS_CLOUD.GET_API_RESULT_CACHE_SIZEとDBMS_CLOUD.SET_API_RESULT_CACHE_SIZEを使用します。

48.3.4.4 GET_RESPONSE_HEADERSファンクション

このファンクションは、HTTPレスポンス・ヘッダーをJSONオブジェクト内のJSONデータとして戻します。

構文

DBMS_CLOUD.GET_RESPONSE_HEADERS(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN JSON_OBJECT_T;

パラメータ

パラメータ	説明
`resp`	`DBMS_CLOUD.SEND_REQUEST`から戻されるHTTPレスポンスのタイプ。

例外

例外	エラー	説明
`invalid_response`	`ORA-20025`	無効なレスポンス・タイプのオブジェクトが`DBMS_CLOUD.GET_RESPONSE_HEADERS`に渡されました。

48.3.4.5 GET_RESPONSE_RAWファンクション

このファンクションは、HTTPレスポンスをRAW形式で戻します。これは、HTTPレスポンスがバイナリ形式であると想定されている場合に役立ちます。

構文

DBMS_CLOUD.GET_RESPONSE_RAW(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN BLOB;

パラメータ

パラメータ	説明
`resp`	`DBMS_CLOUD.SEND_REQUEST`から戻されるHTTPレスポンスのタイプ。

例外

例外	エラー	説明
`invalid_response`	`ORA-20025`	無効なレスポンス・タイプのオブジェクトが`DBMS_CLOUD.GET_RESPONSE_RAW`に渡されました。

48.3.4.6 GET_RESPONSE_STATUS_CODEファンクション

このファンクションは、HTTPレスポンス・ステータス・コードを整数として戻します。このステータス・コードは、そのリクエストが成功したかどうかを識別するのに役立ちます。

構文

DBMS_CLOUD.GET_RESPONSE_STATUS_CODE(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN PLS_INTEGER;

パラメータ

パラメータ	説明
`resp`	`DBMS_CLOUD.SEND_REQUEST`から戻されるHTTPレスポンスのタイプ。

例外

例外	エラー	説明
`invalid_response`	`ORA-20025`	無効なレスポンス・タイプのオブジェクトが`DBMS_CLOUD.GET_RESPONSE_STATUS_CODE`に渡されました。

48.3.4.7 GET_RESPONSE_TEXTファンクション

このファンクションは、HTTPレスポンスをTEXT形式(VARCHAR2またはCLOB)で戻します。通常、ほとんどのクラウドREST APIは、JSONレスポンスをテキスト形式で戻します。このファンクションは、HTTPレスポンスがテキスト形式であることを想定している場合に役立ちます。

構文

DBMS_CLOUD.GET_RESPONSE_TEXT(
       resp          IN DBMS_CLOUD_TYPES.resp)
   RETURN CLOB;

パラメータ

パラメータ	説明
`resp`	`DBMS_CLOUD.SEND_REQUEST`から戻されるHTTPレスポンスのタイプ。

例外

例外	エラー	説明
`invalid_response`	`ORA-20025`	無効なレスポンス・タイプのオブジェクトが`DBMS_CLOUD.GET_RESPONSE_TEXT`に渡されました。

48.3.4.8 GET_API_RESULT_CACHE_SIZEファンクション

このファンクションは、構成されている結果キャッシュ・サイズを戻します。このキャッシュ・サイズ値は、現行セッションにのみ適用されます。

構文

DBMS_CLOUD.GET_API_RESULT_CACHE_SIZE()
   RETURN NUMBER;

48.3.4.9 SEND_REQUESTファンクションおよびプロシージャ

このファンクションおよびプロシージャは、HTTPリクエストを開始し、そのレスポンスを取得し、そのレスポンスを終了します。このファンクションは、引数があるクラウドREST APIリクエストを送信するためのワークフローを提供します。このファンクションは、レスポンス・コードおよびペイロードを戻します。このプロシージャを使用すると、SESSION_CLOUD_API_RESULTSビューにより、保存されている結果から結果とレスポンス詳細を表示できます。

構文

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL)
   RETURN DBMS_CLOUD_TYPES.resp;

DBMS_CLOUD.SEND_REQUEST(
       credential_name    IN VARCHAR2,
       uri                IN VARCHAR2,
       method             IN VARCHAR2,
       headers            IN CLOB DEFAULT NULL,
       async_request_url  IN VARCHAR2 DEFAULT NULL,
       wait_for_states    IN DBMS_CLOUD_TYPES.wait_for_states_t DEFAULT NULL,
       timeout            IN NUMBER DEFAULT 0,
       cache              IN PL/SQL BOOLEAN DEFAULT FALSE,
       cache_scope        IN VARCHAR2 DEFAULT 'PRIVATE',
       body               IN BLOB DEFAULT NULL);

パラメータ

パラメータ	説明
`credential_name`	対応するクラウド・ネイティブAPIで認証するための資格証明の名前。
`uri`	リクエストを作成するためのHTTP URI。
`method`	HTTPリクエスト・メソッド: `GET`、`PUT`、`POST`、`HEAD`、`DELETE`。このメソッドを指定するには、`DBMS_CLOUD`パッケージの定数を使用します。詳細は、「DBMS_CLOUD REST APIの定数」を参照してください。
`headers`	JSON形式での、対応するクラウド・ネイティブAPIのHTTPリクエスト・ヘッダー。この認証ヘッダーは自動的に設定されます。カスタム・ヘッダーのみ渡します。
`async_request_url`	非同期リクエストのURL。このURLを取得するには、APIのリストからリクエストAPIを選択します(https://docs.cloud.oracle.com/en-us/iaas/api/を参照)。その後、左ペインに移動してそのリクエストのAPIを見つけます。たとえば、「データベース・サービスAPI、「Autonomous Database」、「StopAutonomousDatabase」の順に選択します。このページには、APIホームが表示されます(ベース・エンドポイントも表示される)。その後、そのベース・エンドポイントに、作業リクエストWorkRequestリンク用に取得した相対パスを追加します。
`wait_for_states`	待機する状態は、タイプのステータス`DBMS_CLOUD_TYPES.wait_for_states_t`です。想定されている状態については、有効な値は'`ACTIVE`'、'`CANCELED`'、'`COMPLETED`'、'`DELETED`'、'`FAILED`'、'`SUCCEEDED`'です。 `wait_for_states`には、複数の状態を指定できます。`wait_for_states`のデフォルト値は、想定されている状態'`ACTIVE`'、'`CANCELED`'、'`COMPLETED`'、'`DELETED`'、'`FAILED`'、'`SUCCEEDED`'のどれかの待機です。
`timeout`	パラメータ`async_request_url`および`wait_for_states`を使用した非同期リクエストについて、タイムアウトを秒単位で指定します。デフォルト値は`0`です。これにより、タイムアウトなしでリクエストの完了を待つことを示します。
`cache`	`TRUE`の場合は、リクエストをREST結果APIキャッシュにキャッシュする必要があることが指定されます。デフォルト値は`FALSE`であり、これは、REST APIリクエストをキャッシュしないということです。
`cache_scope`	すべてのユーザーにこのリクエストの結果キャッシュへのアクセスを可能にするかどうかを指定します。有効な値は、`"PRIVATE"`と`"PUBLIC"`です。デフォルト値は`"PRIVATE"`です。
`body`	`PUT`リクエストと`POST`リクエストのHTTPリクエスト本文。

例外

例外	エラー	説明
`invalid_req_method`	`ORA-20023`	`DBMS_CLOUD.SEND_REQUEST`に渡されたリクエスト・メソッドが無効です。
`invalid_req_header`	`ORA-20024`	`DBMS_CLOUD.SEND_REQUEST`に渡されたリクエスト・ヘッダーが、有効なJSON形式ではありません。

使用上のノート

Oracle Cloud Infrastructureを使用している場合は、credential_nameに署名キー・ベースの資格証明値を使用する必要があります。詳細は、「CREATE_CREDENTIALプロシージャ」を参照してください。
オプションのパラメータasync_request_url、wait_for_statesおよびtimeoutを使用すると、長時間実行リクエストに対応できます。この非同期形式のsend_requestを使用すると、このファンクションは、wait_for_statesで指定された完了ステータスを待ってから戻ります。送信リクエストでこれらのパラメータを使用し、想定されている戻り状態をwait_for_statesパラメータで渡し、関連する作業リクエストをasync_request_urlパラメータを使用して指定した場合、そのリクエストはすぐには戻りません。そうではなく、そのリクエストは、戻り状態が想定状態のいずれかになるか、timeoutを超えるまで(timeoutはオプション)、async_request_urlをプローブします。timeoutが指定されていない場合、そのリクエストは、wait_for_statesにある状態になるまで待ちます。

48.3.4.10 SET_API_RESULT_CACHE_SIZEプロシージャ

このプロシージャは、現行セッションの最大キャッシュ・サイズを設定します。このキャッシュ・サイズ値は、現行セッションにのみ適用されます。

構文

DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(
       cache_size          IN NUMBER);

パラメータ

パラメータ説明

パラメータ	説明
`cache_size`	最大キャッシュ・サイズを、指定された値`cache_size`に設定します。新しい最大キャッシュ・サイズが現在のキャッシュ・サイズより小さい場合は、指定された最大キャッシュ・サイズと行数が等しくなるまで、古いレコードが削除されます。最大値は`10000`です。キャッシュ・サイズが`0`に設定されている場合は、そのセッションでキャッシュが無効になります。デフォルトのキャッシュ・サイズは`10`です。

cache_size

最大キャッシュ・サイズを、指定された値cache_sizeに設定します。新しい最大キャッシュ・サイズが現在のキャッシュ・サイズより小さい場合は、指定された最大キャッシュ・サイズと行数が等しくなるまで、古いレコードが削除されます。最大値は10000です。

キャッシュ・サイズが0に設定されている場合は、そのセッションでキャッシュが無効になります。

デフォルトのキャッシュ・サイズは10です。

例外

例外	エラー	説明
`invalid API result cache size`	`ORA-20032`	最小値は0であり、最大値は10000です。この例外は、入力値が0より小さいか10000より大きい場合に表示されます。

例

EXEC DBMS_CLOUD.SET_API_RESULT_CACHE_SIZE(101);

48.3.4.11 DBMS_CLOUD REST APIの例

DBMS_CLOUD.SEND_REQUESTを使用してOracle Cloud Infrastructureオブジェクト・ストレージ・バケットを作成および削除する例と、テナンシ内のすべてのコンパートメントをリストする例を示します。

ノート:

これらの例では、Oracle Cloud InfrastructureのリクエストAPIを示しており、credential_nameに署名キー・ベースの資格証明を使用する必要があります。Oracle Cloud Infrastructureの署名キー・ベースの資格証明には、private_key引数とfingerprint引数が含まれています。

たとえば:

BEGIN
   DBMS_CLOUD.CREATE_CREDENTIAL (
       credential_name => ‘OCI_KEY_CRED’,
       user_ocid       => ‘ocid1.user.oc1..aaaaaaaauq54mi7zdyfhw33ozkwuontjceel7fok5nq3bf2vwetkpqsoa’,
       tenancy_ocid    => ‘ocid1.tenancy.oc1..aabbbbbbaafcue47pqmrf4vigneebgbcmmoy5r7xvoypicjqqge32ewnrcyx2a’,
       private_key     => ‘MIIEogIBAAKCAQEAtUnxbmrekwgVac6FdWeRzoXvIpA9+0r1.....wtnNpESQQQ0QLGPD8NM//JEBg=’,
       fingerprint     => ‘f2:db:f9:18:a4:aa:fc:94:f4:f6:6c:39:96:16:aa:27’);
END;
/

DBMS_CLOUD.CREATE_CREDENTIALについては、「CREATE_CREDENTIALプロシージャ」を参照してください。

バケット作成の例

DBMS_CLOUD.SEND_REQUESTをHTTP POSTメソッドとともに使用してbucketnameという名前のオブジェクト・ストア・バケットを作成する例を示します。

この例のOracle Cloud Infrastructureオブジェクト・ストレージ・サービスAPIの詳細は、CreateBucketを参照してください。

SET SERVEROUTPUT ON
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
BEGIN
  -- Send request
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://objectstorage.region.oraclecloud.com/n/namespace-string/b/',
            method => DBMS_CLOUD.METHOD_POST,
            body => UTL_RAW.cast_to_raw(
                        JSON_OBJECT('name' value 'bucketname',
                                    'compartmentId' value 'compartment_OCID'))
          );
 
  -- Response Body in TEXT format
  dbms_output.put_line('Body: ' || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_text(resp) || CHR(10));
  
  -- Response Headers in JSON format
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
 
  -- Response Status Code
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_status_code(resp));
 
END;
/

ノート:

この例では、namespace-stringは、Oracle Cloud Infrastructureオブジェクト・ストレージ・ネームスペースです。また、bucketnameはバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの概要に関する項を参照してください。
ここでは、regionはエンドポイント・リージョンです。詳細は、「APIリファレンスとエンドポイント」のオブジェクト・ストレージAPIリファレンスを参照してください。たとえば、regionはus-phoenix-1です。

バケット削除の例

DBMS_CLOUD.SEND_REQUESTをHTTP DELETEメソッドとともに使用してbucketnameという名前のオブジェクト・ストア・バケットを削除する例を示します。

この例のOracle Cloud Infrastructureオブジェクト・ストレージ・サービスAPIの詳細は、DeleteBucketを参照してください。

SET SERVEROUTPUT ON
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
BEGIN
  -- Send request
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://objectstorage.region.oraclecloud.com/n/namespace-string/b/bucketname',
            method => DBMS_CLOUD.METHOD_DELETE
          );
 
  -- Response Body in TEXT format
  dbms_output.put_line('Body: ' || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_text(resp) || CHR(10));
  
  -- Response Headers in JSON format
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
 
  -- Response Status Code
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) ||
  DBMS_CLOUD.get_response_status_code(resp));
 
END;
/

ノート:

この例では、namespace-stringは、Oracle Cloud Infrastructureオブジェクト・ストレージ・ネームスペースです。また、bucketnameはバケット名です。詳細は、オブジェクト・ストレージ・ネームスペースの概要に関する項を参照してください。
ここでは、regionはエンドポイント・リージョンです。詳細は、「APIリファレンスとエンドポイント」のオブジェクト・ストレージAPIリファレンスを参照してください。たとえば、regionはus-phoenix-1です。

コンパートメントのリストの例

DBMS_CLOUD.SEND_REQUESTをHTTP GETメソッドとともに使用してテナンシ(ルート・コンパートメント)内のすべてのコンパートメントをリストする例を示します。この例は、DBMS_CLOUD.SEND_REQUESTでリクエスト・ヘッダーを渡す方法を示しています。

この例のOracle Cloud Infrastructure Identity and Access Management Service APIの詳細は、ListCompartmentsを参照してください。

--
-- List compartments
--
DECLARE
  resp DBMS_CLOUD_TYPES.resp;
  root_compartment_ocid VARCHAR2(512) := '&1';
BEGIN
  -- Send request
  dbms_output.put_line('Send Request');
  resp := DBMS_CLOUD.send_request(
            credential_name => 'OCI_KEY_CRED',
            uri => 'https://identity.region.oraclecloud.com/20160918/compartments?compartmentId=' || root_compartment_ocid,
            method => DBMS_CLOUD.METHOD_GET,
            headers => JSON_OBJECT('opc-request-id' value 'list-compartments')
          );
  dbms_output.put_line('Body: ' || '------------' || CHR(10) || DBMS_CLOUD.get_response_text(resp) || CHR(10));
  dbms_output.put_line('Headers: ' || CHR(10) || '------------' || CHR(10) || DBMS_CLOUD.get_response_headers(resp).to_clob || CHR(10));
  dbms_output.put_line('Status Code: ' || CHR(10) || '------------' || CHR(10) || DBMS_CLOUD.get_response_status_code(resp));
  dbms_output.put_line(CHR(10));
END;
/

ここでは、regionはエンドポイント・リージョンです。詳細は、「APIリファレンスとエンドポイント」のIdentity and Access Management (IAM) APIリファレンスを参照してください。たとえば、regionはuk-london-1です。

非同期リクエストの例

DBMS_CLOUD.SEND_REQUESTをHTTP POSTメソッドとともに使用してAutonomous Database停止操作を実行しステータスを待機する例を示します。この例は、DBMS_CLOUD.SEND_REQUESTをasync_request_url、wait_for_statesおよびtimeoutパラメータとともに使用する方法を示しています。

--
-- Sent Work Request Autonomous Database Stop Request with Wait for Status
DECLARE
    l_resp DBMS_CLOUD_TYPES.resp;
    l_resp_json JSON_OBJECT_T;
    l_key_shape JSON_OBJECT_T;
    l_body JSON_OBJECT_T;
    status_array DBMS_CLOUD_TYPES.wait_for_states_t;
BEGIN
  status_array := DBMS_CLOUD_TYPES.wait_for_states_t('SUCCEEDED');
  l_body := JSON_OBJECT_T('{}');
  l_body.put('autonomousDatabaseId', 'ocid');
-- Send request
  dbms_output.put_line(l_body.to_clob);
  dbms_output.put_line('Send Request');
  l_resp := DBMS_CLOUD.send_request(
                       credential_name    => 'NATIVE_CRED_OCI',
                       uri                => 'https://database.region.oraclecloud.com/20160918/autonomousDatabases/ocid/actions/stop',
                       method             => DBMS_CLOUD.METHOD_POST,
                       body               => UTL_RAW.cast_to_raw(l_body.to_clob),
                       async_request_url  => 'https://iaas.region.oraclecloud.com/20160918/workRequests',
                       wait_for_states    => status_array,
                       timeout            => 600
                  );
   dbms_output.put_line('resp body: '||DBMS_CLOUD.get_response_text(l_resp));
   dbms_output.put_line('resp headers: '||DBMS_CLOUD.get_response_headers(l_resp).to_clob);
END;
/

ocidは、Oracle Cloud Infrastructureリソース識別子です。詳細は、「リソース識別子」を参照してください。

48.4 DBMS_CLOUDのURI形式

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

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

48.4.1 Oracle Cloud Infrastructure Object Storage NativeのURI形式

ソース・ファイルがOracle Cloud Infrastructure Object Storageの商用レルム(OC1)にある場合は、オブジェクト・ストレージ専用エンドポイントを使用する次のURI形式を使用することをお薦めします。詳細は、オブジェクト・ストレージの専用エンドポイントを参照してください。

https://namespace-string.objectstorage.region.oci.customer-oci.com/n/namespace-string/b/bucketname/o/filename

ノート:

OCIオブジェクト・ストア専用エンドポイントのURLは、商用レルム(OC1)でのみサポートされています。

ソース・ファイルがOracle Cloud Infrastructure Object Storageにあり、商用レルム(OC1)にない場合は、次の形式を使用する必要があります:

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

たとえば、商用レルム(OC1)での、Phoenixデータ・センター内のbucketnameバケットにあるファイルchannels.txtのネイティブURIは、次のとおりです:

https://namespace.objectstorage.region.oci.customer-oci.com/n/namespace/b/bucketname/o/channels.txt

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

Oracle Cloudの横にあるをクリックすることで、Oracle Cloud Infrastructureコンソールを開きます。
Oracle Cloud Infrastructureの左側のナビゲーション・メニューから、「コア・インフラストラクチャ」をクリックします。「オブジェクト・ストレージ」の下で、「オブジェクト・ストレージ」をクリックします。
「リスト範囲」の下で、「コンパートメント」を選択します。
「名前」列からバケットを選択します。
「オブジェクト」領域で、「オブジェクト詳細の表示」をクリックします。

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

ノート:

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

48.4.2 Oracle Cloud Infrastructure Object Storage SwiftのURI形式

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

ノート:

OCIオブジェクト・ストア専用エンドポイントのURLは、商用レルム(OC1)でのみサポートされています。

ソース・ファイルがOracle Cloud Infrastructure Object Storageにあり、商用レルム(OC1)にない場合は、次の形式を使用する必要があります:

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

たとえば、商用レルム(OC1)での、Phoenixデータ・センター内のbucketnameバケットにあるファイルchannels.txtのSwift URIは、次のとおりです:

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

ノート:

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

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

ノート:

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

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

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

ノート:

OCIオブジェクト・ストア専用エンドポイントのURLは、商用レルム(OC1)でのみサポートされています。

ソース・ファイルがOracle Cloud Infrastructure Object Storageにあり、商用レルム(OC1)にない場合は、次の形式を使用する必要があります:

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

たとえば、商用レルム(OC1)での、Phoenixデータ・センター内のbucketnameバケットにあるファイルchannels.txtの事前認証済URIの例は、次のとおりです:

https://namespace-string.objectstorage.us-phoenix-1.oci.customer-oci.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を無視します。

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

48.4.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パブリック・バケットの使用方法の詳細は、パブリック・バケットに関する項を参照してください。

48.4.5 Oracle Cloud Infrastructure Object Storage ClassicのURI形式

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

48.4.6 Amazon S3のURI形式

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

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

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

資格証明を作成する必要なく、Amazon S3オブジェクト・ストア内のファイルにアクセスするために、URLを取得するどのDBMS_CLOUDプロシージャでも署名付きURLを使用できます。DBMS_CLOUDプロシージャで署名付きURLを使用するには、credential_nameパラメータをNULLとして指定するか、credential_nameパラメータを指定しないようにします。

ノート:

DBMS_CLOUDでは、バケットにアクセスするための標準のAmazon S3エンドポイント構文がサポートされています。DBMS_CLOUDでは、Amazon S3のレガシー・エンドポイントはサポートされていません。

48.4.7 Amazon S3互換のURI形式

DBMS_CLOUDは、次のサービスを含め、Amazon S3互換URLをサポートするオブジェクト・ストレージ・サービス実装をサポートしています:

Amazon S3互換URLを使用するOracle Cloud Infrastructure Object Storage
Amazon S3互換URLを使用するGoogle Cloud Storage
Amazon S3互換URLを使用するWasabi Hot Cloud Storage

ノート:

Amazon S3互換オブジェクト・ストアとともにDBMS_CLOUDを使用するには、有効な資格証明を指定する必要があります。詳細は、「CREATE_CREDENTIALプロシージャ」を参照してください。

Amazon S3互換URIをサポートするサービスにソース・ファイルが存在する場合は、次のURI形式を使用してファイルにアクセスします:

Oracle Cloud Infrastructure Object StorageのS3互換URL

ソース・ファイルがOracle Cloud Infrastructure Object Storageの商用レルム(OC1)にある場合、商用レルム(OC1)には、次に示すオブジェクトURL形式とバケットURL形式を使用することをお薦めします。詳細は、オブジェクト・ストレージの専用エンドポイントを参照してください。

ノート:
OCIオブジェクト・ストア専用エンドポイントのURLは、商用レルム(OC1)でのみサポートされています。

オブジェクトURL形式
- 商用レルム(OC1)でのみサポートされています:
```
https://mynamespace.compat.objectstorage.region.oci.customer-oci.com/bucket_name/object_name
```
- すべてのゾーンでサポートされています:
```
https://mynamespace.compat.objectstorage.region.oraclecloud.com/bucket_name/object_name
```
バケットURL形式:
- 商用レルム(OC1)でのみサポートされています:
```
https://mynamespace.compat.objectstorage.region.oci.customer-oci.com/bucket_name
```
- すべてのゾーンでサポートされています:
```
https://mynamespace.compat.objectstorage.region.oraclecloud.com/bucket_name
```
詳細は、Amazon S3互換およびオブジェクト・ストレージ・サービスAPIを参照してください。
Google Cloud Storage S3互換URL

オブジェクトURL形式:
```
https://bucketname.storage.googleapis.com/object_name
```
バケットURL形式:
```
https://bucketname.storage.googleapis.com/
```
詳細は、Amazon S3からクラウド・ストレージへの移行およびリクエスト・エンドポイントを参照してください。
Wasabi S3互換URL

オブジェクトURL形式:
```
https://bucketname.s3.region.wasabisys.com/object_name
```
バケットURL形式:
```
https://bucketname.s3.region.wasabisys.com/
```
詳細は、Wasabi S3 APIリファレンスおよびWasabiのストレージ・リージョンのサービスURLを参照してください。

48.4.8 GitHub RAW URL形式

DBMS_CLOUDは、GitHubリポジトリにあるデータにアクセスするためのGitHub RAW URLをサポートしています。

ノート:

GitHub RAW URLを使用したDBMS_CLOUDアクセスの場合、リポジトリ・アクセスは、読取り専用機能に限定されます。データの書込みを行うDBMS_CLOUD.PUT_OBJECTなどのDBMS_CLOUD APIは、GitHubリポジトリにあるDBMS_CLOUD APIではサポートされていません。

別の方法として、DBMS_CLOUD_REPO.PUT_FILEを使用してデータをGitHubリポジトリにアップロードします。

GitHub RAW URLをDBMS_CLOUD APIとともに使用して、GitHubリポジトリにあるソース・ファイルにアクセスします。GitHubにあるファイルを参照し、「RAW」リンクをクリックすると、GitHub RAW URLが表示されます。raw.githubusercontent.comドメインでは、GitHubリポジトリに格納されているファイルの未処理バージョンが提供されます。

たとえば、DBMS_CLOUD.GET_OBJECTを使用します:

BEGIN
 DBMS_CLOUD.GET_OBJECT(
   credential_name => 'MY_CRED',
   object_uri      => 'https://raw.githubusercontent.com/myaccount/myrepo/master/data-management-library/autonomous-database/adb-loading.csv',
   directory_name  => 'DATA_PUMP_DIR'
  );
END;
/

たとえば、DBMS_CLOUD.CREATE_EXTERNAL_TABLEを使用します:

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    credential_name => 'MY_CRED',
    table_name      => 'EMPLOYEES_EXT',
    file_uri_list   => 'https://raw.githubusercontent.com/myaccount/myrepo/master/data-management-library/autonomous-database/*.csv',
    column_list     => 'name varchar2(30), gender varchar2(30), salary number',
    format          => JSON_OBJECT('type' value 'csv')
  );
END;
/
SELECT * FROM employees_ext;

GitHubリポジトリにアクセスするためのURLを取得するDBMS_CLOUDプロシージャでは、パブリック可視性のGitHubリポジトリについては資格証明は必要ありません。パブリック可視性URLを使用するには、credential_nameパラメータをNULLとして指定するか、credential_nameパラメータを指定しないようにします。詳細は、リポジトリの可視性の設定を参照してください。

48.4.9 追加の顧客管理URI形式

完全修飾ドメイン名(FQDN)がある、事前構成され認識されているURIの他に、DBMS_CLOUDは、顧客管理エンドポイントのURIについて、適切な認証スキームを判断できません。そのような場合、DBMS_CLOUDは、顧客管理エンドポイントの認証スキームの特定を、その適切なURIスキームに依存します。

URIスキーム	認証タイプ	アクセス方法の説明	URIの例
basic://	Basic認証	データベース資格証明オブジェクトに格納されているユーザー名とパスワードが、HTTPリクエストの認証に使用されます	`basic://api.github.com/users/myaccount`
bearer://	Bearerトークン認証	データベース資格証明オブジェクト内のパスワード・フィールドに格納されているBearerトークンが、HTTPリクエストの認可ヘッダーを指定するために使用されます	`bearer://api.sendgrid.com/v3/resource`
oci://	OCIネイティブ	OCI認証プロトコルを使用してリクエストに署名するために格納され使用されるデータベース資格証明オブジェクトから取得されるOCI署名キー	`oci://objectstorage.us-ashburn-1.oraclecloud.com`
public://	認証なし	パブリックURL	`public://cms.data.gov/`
s3://	Amazon Web Services S3互換	データベース資格証明オブジェクトのユーザー名/パスワード・フィールドから取得されたアクセス・キーと秘密キー、およびHTTPリクエストのために実行されるS3互換認証。	`s3://bucket.myprivatesite.com/file1.csv`

例:

S3互換認証を使用する顧客管理エンドポイント。

この例では、新しいURIについて、どのようにお客様がDBMS_NETWORK_ACL_ADMINパッケージを使用してパブリックまたはプライベートのホスト名パターンを追加できるかを示します。ユーザーADMINによって実行されるこのコード・ブロックにより、ドメイン*.myprivatesite.com内のエンドポイントへの、ユーザーSCOTTのHTTPSアクセスが可能になります。その後、新しく有効になったエンドポイントにどのようにユーザーSCOTTがアクセスするかを示します。なお、ユーザーSCOTTの資格証明MY_CREDには、URI接頭辞で示されたそのHTTPリクエストに対して実行されるS3互換認証のためのアクセス・キーと秘密キーが格納されている必要があります。


BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
         host => '*.myprivatesite.com',
         ace => xs$ace_type(privilege_list => xs$name_list('http'),
                            principal_name => 'SCOTT',
                            principal_type => xs_acl.ptype_db),
         private_target => TRUE   );
END;
/

BEGIN
   DBMS_CLOUD.get_object(
       credential_name => 'MY_CRED',
       object_uri      => 's3://bucket.myprivatesite.com/file1.csv',
       directory_name  => 'MY_DIR'  );
END;
/

パブリック・アクセス権がある顧客管理エンドポイント

この例では、パブリックREST APIにアクセスするためのSCOTTユーザーの登録方法を示します。ADMINユーザーが、SCOTTユーザーにアクセス権を提供するようにそのホスト用のネットワークACLを作成します。


BEGIN
   DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
         host => 'data.cms.gov',
         ace => xs$ace_type(privilege_list => xs$name_list('http'),
                            principal_name => 'SCOTT',
                            principal_type => xs_acl.ptype_db)
   );
END;
/

SELECT DBMS_CLOUD.get_response_text(
          DBMS_CLOUD.send_request(
              uri     => 'public://data.cms.gov/provider-data/api/1/datastore/imports/a',
              method  => DBMS_CLOUD.METHOD_GET,
              headers => JSON_OBJECT('Accept' VALUE 'application/json')
          )
       )
   FROM DUAL;
/

48.5 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', 'logretention' value 7)

ノート:

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

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

access_protocol

Apache Iceberg表のタイプ(AWSやOCI Object Storageなど)と、外部表の作成に使用される情報(データ・カタログや直接メタデータURIからの情報など)を指定します。

access_protocol構文の詳細は、「Apache Icebergに対応するCREATE_EXTERNAL_TABLEプロシージャ」を参照してください。

blankasnull

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

blankasnull : true

デフォルト値: False

characterset

format JSONおよびCOPY_DATAで有効

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

characterset: string

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

columnpath

format JSONおよびCOPY_DATAでのみ使用

JSONレコードから抽出する必要があるフィールドに対応するJSONパス式の配列。配列内の各JSONパス式は、「SQL/JSONパス式」で説明されているルールに従っている必要があります。

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

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

compression

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

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

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

compression: auto|gzip|zlib|zstd|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 : 文字

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

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には、先頭行にフィールド名が含まれている場合にこの自動フィールド順序検出が役立ちます。

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には、ブロック暗号アルゴリズム+ブロック暗号連鎖の修飾子+ブロック暗号パディングの修飾子という形式で値を指定します。

サポートされているブロック暗号アルゴリズムは次のとおりです:
- 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: value

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

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

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

ignoreblanklines : true

デフォルト値: False

ignoremissingcolumns

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

ignoremissingcolumns : true

デフォルト値: False

implicit_partition_columns

DBMS_CLOUD.CREATE_EXTERNAL_TABLEとともにimplicit_partition_columnsフォーマット・オプションを使用することで、暗黙的パーティション化を有効にしパーティション列名を指定します。

暗黙的パーティション化は次の方法で有効化されます:

implicit_partition_columnsを使用してパーティション列のリストを指定し、implicit_partition_typeを指定します。たとえば:
```
format => '{"implicit_partition_type":"hive",
      "implicit_partition_columns":["country","year","month"]}'
```
パーティション・タイプを指定せずに、implicit_partition_columnsを使用してパーティション列のリストを指定します。パーティション・タイプは、自動的にhiveまたはhive以外として検出されます。たとえば:
```
format => '{"implicit_partition_columns":["country","year","month"]}'
```
パーティション列のリストを指定せずに、implicit_partition_typeを使用してパーティション列のタイプを指定します。HIVE形式のパーティション化データ内のパーティション・キーの自動検出がトリガーされて列名が特定されます。たとえば:
```
format => '{"partition_type":"hive"}'
```

implicit_partition_columns : 文字列の配列

デフォルト値: implicit_partition_typeが指定されている場合は、列名が、HIVE形式のパーティション化データ内のパーティション・キーの自動検出によって導出されます。それ以外の場合は、デフォルトはnullであり、暗黙的パーティション化は有効になりません。

implicit_partition_type

DBMS_CLOUD.CREATE_EXTERNAL_TABLEとともにimplicit_partition_typeフォーマット・オプションを使用することで、暗黙的パーティション化を有効にしパーティション列のデータ・タイプを指定します。

implicit_partition_type : hive

デフォルト値: implicit_partition_columnsが指定されている場合は、タイプが自動的にhiveまたはhive以外として検出されます。それ以外の場合は、デフォルトはnullであり、暗黙的パーティション化は有効になりません。

keyassignment

COPY_COLLECTIONでのみ使用します

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

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

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

keyassignment: embedded_oid

デフォルト: keyassignmentは設定されません

keypath

COPY_COLLECTIONでのみ使用します

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

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

この値をパスに設定して('$.mykey'など)そのパスの値を'_id'値として選択します。

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

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

keypath: string

デフォルト: keypathは設定されません。

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

language

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

language: 文字列

デフォルト値: Null

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: string

デフォルト値: 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: string

デフォルト値: COPY

logretention

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

有効な値: 0から99999

たとえば:

format => JSON_OBJECT ('logretention' value 7)

logretention: number

デフォルト値: 2

numericcharacters

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

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

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

numericcharacters: 'decimal_character group_separator'

デフォルト値: ".,"

numberformat

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

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

numberformat: number_format_model

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

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

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

デフォルトでは、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)

regexuri: True

デフォルト値: False

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

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

trimspaces: rtrim| ltrim| notrim| lrtrim| ldrtrim

デフォルト値: notrim

truncatecol

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

truncatecol:true

デフォルト値: False

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

テキスト・ファイル形式(CSV、JSONまたはXML)の場合とOracle Data Pumpの場合の、DBMS_CLOUD.EXPORT_DATAでの有効なフォーマット・パラメータ・オプションについて説明します。

これらは、DBMS_CLOUD.EXPORT_DATAで使用する有効なformatパラメータです。format typeオプションを使用しており、その値がcsv、jsonまたはxmlのどれかである場合は、テキスト・ファイル出力を指定しています。これは、format typeがdatapumpである場合のformatオプションも示しています。

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

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

および

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

次に例を示します。

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

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

たとえば:

format => json_object('compression' value 'gzip', 'type' value 'json')

この表は、formatパラメータのtypeオプションがCSV、JSONまたはXMLのどれかである場合の、DBMS_CLOUD.EXPORT_DATAのフォーマット・オプションを説明しています。他のプロシージャと他の出力タイプについては、「DBMS_CLOUDパッケージのフォーマット・オプション」でフォーマット・オプションのリストを参照してください。

フォーマット・オプション	説明	構文
`compression`	ソース・ファイルの圧縮タイプを指定しますノート: ZIPアーカイブ形式はサポートされていません。 `format` `type`が`csv`、`json`または`xml`である場合、デフォルトのcompressionはNullです(つまり、圧縮なし)。 `format` `type`が`datapump`である場合は、サポートされている次のOracle Data Pumpアクセス・パラメータを指定できます: `compression`: 有効な値は、`BASIC`、`LOW`、`MEDIUM`および`HIGH`です。 `version`: 有効な値は、`COMPATIBLE`、`LATEST`、および指定した`version_number`です。	`type`が`csv` \| `json` \| `xml`である場合 `compression:gzip, zlib, zstd, bzip2` デフォルト値: 圧縮しないことを意味するNULL値。 `compression:` `gzip` \| `snappy` デフォルト値: `snappy` typeが`datapump`である場合 `compression`: `BASIC\|LOW\|MEDIUM\|HIGH`
`delimiter`	カスタム・フィールド・デリミタを指定します。 `format => json_object('delimiter' value '\|')` このデリミタ値は、ASCIIコードやエスケープ文字にはできません。ノート: このオプションは、`type`が`csv`の場合のみ適用されます。	`delimiter` : 文字デフォルト値: , (カンマ)
`endquote`	フィールドを2つのデリミタ(`quote`と`endquote`を使用)で囲むことができるように指定します。`endquote`を指定しなかった場合は、デフォルトで、`quote`文字が`endquote`文字として使用されます。たとえば: `format => JSON_OBJECT(‘quote’ value ‘(’, ‘endquote’ value ‘)’)` ノート: このオプションは、`type`が`csv`の場合のみ適用されます。	`endquote`:文字デフォルト値: `endquote`がないことを意味するNull。
`escape`	`"\"`文字を使用してフィールド値での引用符文字の出現を示します。ノート: このオプションは、`type`が`csv`の場合のみ適用されます。	`escape` `: true` デフォルト値: `false`
`encryption`	フォーマット・オプション`encryption`では、オブジェクト・ストアとの間でデータをエクスポートおよびインポートするための暗号化オプションと復号化オプションを指定します。 `encryption`を使用して、暗号化と復号化のための次のパラメータを指定します: `user_defined_function`: 指定されたBLOB (バイナリ・ラージ・オブジェクト)を復号化または暗号化するための完全修飾ユーザー定義ファンクションを指定します。これは、復号化または暗号化されたBLOBを戻します。このパラメータは、`encryption`のその他のパラメータと相互に排他的です。たとえば、`ADMIN.DECRYPTION_CALLBACK`です。 `type`: 復号化または暗号化するための組込み暗号化アルゴリズムを指定します。`user_defined_function`と`type`は相互に排他的です。 `type`には、ブロック暗号アルゴリズム+ブロック暗号連鎖の修飾子+ブロック暗号パディングの修飾子という形式で値を指定します。サポートされているブロック暗号アルゴリズムは次のとおりです: `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_HYBRID_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`: value 暗号化タイプを指定します。 `credential_name`: `value` 暗号化キーの格納に使用される資格証明を指定します。 `user_defined_function: value` 指定されたBLOB (バイナリ・ラージ・オブジェクト)を復号化または暗号化するための完全修飾ユーザー定義ファンクションを指定します。
`header`	`csv`タイプの出力ファイルにおいて先頭行として列名を書き込みます。 `header`オプションには、`boolean`値または`string`値を指定できます。有効な値は次のとおりです。 `false`: ヘッダー行をスキップします。 `true`: ヘッダー行を含めます。これらの列名は、`query`パラメータでの`SELECT`文に基づきます。仮想列または仮想式を使用する場合は、`SELECT`文で列の別名を指定する必要があります。 `カスタム・ヘッダー名を定義する文字列`: ヘッダー行をカスタム名で定義できます。この文字列値での列数とデリミタ数は、`SELECT`文での列数とデリミタ数と一致している必要があります。デフォルトのデリミタはカンマ(,)です。たとえば: `format => JSON_OBJECT('type' value 'csv', 'delimiter' value '\|', 'compression' value 'gzip', 'header' value true)` ノート: このオプションは、`type`が`csv`の場合のみ適用されます。	`header: true\| false\| String to define custom header names` デフォルト値: `false`
`fileextension`	format typeのデフォルトの選択肢を上書きするためのカスタム・ファイル拡張子。これは、`DBMS_CLOUD.EXPORT_DATA`でのテキスト形式(CSV、JSON、ParquetまたはXML)に適用されます。指定した文字列の先頭がピリオド(ドット)でない場合は、最終的なファイル名において、ファイル拡張子の前に自動的にドットが挿入されます。ファイル拡張子が不要な場合は、値`fileextension` =`'none'`を使用します	有効な値: 任意のファイル拡張子。デフォルト値: `format` `type`オプションによって異なります: CSV形式: `.csv` JSON形式: `.json` XML形式: `.xml`
`maxfilesize`	生成される出力の最大サイズのバイト数。これは、`format` `type`オプションが`csv`、`json`または`xml`に設定されている場合の、`DBMS_CLOUD.EXPORT_DATA`によるデータ・エクスポートのためのテキスト・ベース形式に適用されます。	最小値: `10485760` (10 MB) 最大値: 1 GB デフォルト値: `10485760` (10 MB)
`quote`	CSV形式では、フィールドを2つのデリミタで囲むことができます。`quote`と`endquote`でデリミタを指定します。`endquote`を指定しなかった場合は、デフォルトで、`quote`文字が`endquote`文字として使用されます。ノート: このオプションは、`type`が`csv`の場合のみ適用されます。	`quote`: 文字デフォルト値: NULL (つまり、フィールドを引用符で囲まない)
`trimspaces`	CSV形式の場合の、フィールドの先頭と末尾の空白の切捨て方法を指定します。`quote`パラメータが指定されている場合は、フィールドを引用符で囲む前にトリム・スペースが適用されます。ノート: このオプションは、`type`が`csv`の場合のみ適用されます。	`trimspaces`: `rtrim\| ltrim\| notrim\| lrtrim\| ldrtrim` デフォルト値: `notrim`

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

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

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

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

regexuri

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

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

たとえば:

format => JSON_OBJECT('regexuri' value TRUE)

REGEXP_LIKE条件の詳細は、REGEXP_LIKE条件を参照してください。

regexuri: True

デフォルト値:False

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

48.7.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複合タイプ」を参照してください。

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

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

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

ORCの型	Oracleタイプ	詳細情報
array	VARCHAR2(n) JSON形式	DBMS_CLOUDパッケージのAvroおよびParquet複合タイプ
bigint (64ビット)	NUMBER(19)
binary	BLOB
boolean (1ビット)	NUMBER(1)
CHAR	CHAR(n)
date	DATE
DOUBLE	BINARY_DOUBLE
FLOAT	BINARY_FLOAT
int (32ビット)	NUMBER(10)
list	VARCHAR2(n) JSON形式	DBMS_CLOUDパッケージのAvroおよびParquet複合タイプ
map	VARCHAR2(n) JSON形式	DBMS_CLOUDパッケージのAvroおよびParquet複合タイプ
smallint (16ビット)	NUMBER(5)
string	VARCHAR2(4000)またはVARCHAR2(32767)	formatパラメータ・オプション`maxvarchar`の値と、`MAX_STRING_SIZE`の値に応じて異なります。詳細は、「AvroまたはParquetに対応するDBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。
struct	VARCHAR2(n) JSON形式	DBMS_CLOUDパッケージのAvroおよびParquet複合タイプ
timestamp	TIMESTAMP
tinyint (8ビット)	NUMBER(3)
union	VARCHAR2(n) JSON形式	DBMS_CLOUDパッケージのAvroおよびParquet複合タイプ
varchar	VARCHAR2(n)

48.7.4 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)またはVARCHAR2(32767) formatパラメータ・オプション`maxvarchar`の値と、Autonomous AI Databaseの`MAX_STRING_SIZE`の値に応じて異なります。詳細は、「AvroまたはParquetに対応するDBMS_CLOUDパッケージのフォーマット・オプション」を参照してください。
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複合タイプ」を参照してください。

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

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

Oracleタイプ	Parquetタイプ
BINARY_DOUBLE	DBL
BINARY_FLOAT	FLT
DATE	DATE
NUMBER(p,s)	DECIMAL(p,s)
NUMBER(p)	DECIMAL(p)
TIMESTAMP(3)	TIMESTAMP_MILLIS
TIMESTAMP(3)	TIMESTAMP_MILLIS_UTC
TIMESTAMP(6)	TIMESTAMP_MICROS
TIMESTAMP(6)	TIMESTAMP_MICROS_UTC
TIMESTAMP(9)	TIMESTAMP_NANOS
VARCHAR2(4000)	STRING

NLSセッション・パラメータ

NLSセッション・パラメータNLS_DATE_FORMAT、NLS_TIMESTAMP_FORMAT、NLS_TIMESTAMP_TZ_FORMATおよびNLS_NUMERIC_CHARACTERSは、日付、タイムスタンプ、タイム・ゾーン形式のタイムスタンプ、および小数点記号ありのタイムスタンプの場合の基数セパレータが、これらの列型がある表を問い合せたときにどのように表示される必要があるかを定義します。

また、DBMS_CLOUD.EXPORT_DATAを使用してデータをエクスポートし、Parquet出力を指定した場合は、Oracle Databaseによって、これらのパラメータの値がNLS_SESSION_PARAMETERS表から読み取られます。Oracle Databaseにより、これらの値を使用してOracleデータ型DATEまたはTIMESTAMPがParquet型に変換されます。

NLS_SESSION_PARAMETERSパラメータでは、RR書式マスク(2文字の年指定)がサポートされています。

DBMS_CLOUD.EXPORT_DATAを使用してParquetにデータをエクスポートする場合は、これらのパラメータで、年のRR書式マスクはサポートされていません。Parquetにエクスポートしようとしたときに、NLS_SESSION_PARAMETERSがRR書式マスクを使用するように設定されている場合は、アプリケーション・エラーが発生します(RR書式のデフォルト値はNLS_TERRITORYパラメータの値によって異なる)。

パラメータNLS_DATE_FORMAT、NLS_TIMESTAMP_FORMATまたはNLS_TIMESTAMP_TZ_FORMATのどれかでRR書式マスクが使用されている場合、DBMS_CLOUD.EXPORT_DATAを使用してParquetにデータをエクスポートするには、その書式値を、サポートされている値に変更する必要があります。たとえば:

ALTER SESSION SET NLS_DATE_FORMAT = "MM/DD/YYYY";
ALTER SESSION SET NLS_TIMESTAMP_FORMAT = 'YYYY-MM-DD HH:MI:SS.FF';
ALTER SESSION SET  NLS_TIMESTAMP_TZ_FORMAT='YYYY-MM-DD HH:MI:SS.FF TZH:TZM';

その値を変更した後に、NLS_SESSION_PARAMETERSビューを問い合せることで、その変更内容を確認できます:

SELECT value FROM NLS_SESSION_PARAMETERS 
       WHERE parameter IN ('NLS_DATE_FORMAT','NLS_TIMESTAMP_FORMAT','NLS_TIMESTAMP_TZ_FORMAT');

NLS_DATE_FORMATが設定されている場合、それは、DATEデータ型の列に適用されます。NLS_TIMESTAMP_FORMATが設定されている場合、それは、TIMESTAMPデータ型の列に適用されます。NLS_TIMESTAMP_TZ_FORMATが設定されている場合、それは、TIMESTAMP WITH TIME ZONEデータ型の列に適用されます。

48.7.6 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形式)

48.7.7 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内で参照するときは常に二重引用符で囲む必要があります。

48.8 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	無効なユーザー名が指定されました。

脚注の凡例

脚注3: Azure Cloud REST APIコールのサポートは、ドメイン"blob.windows.net"に限定されています。