DBMS_CLOUD.CREATE_CREDENTIALプロシージャを使用してクラウド・オブジェクト・ストレージ資格証明を格納する方法について学習します。

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

DBMS_CLOUD.COPY_DATAプロシージャを使用してクラウドのテキスト・ファイルからAutonomous Databaseにデータをロードする方法について学習します。

S,Direct Sales,Direct
T,Tele Sales,Direct
C,Catalog,Indirect
I,Internet,Indirect
P,Partners,Others

1. DBMS_CREDENTIAL.CREATE_CREDENTIALプロシージャを使用して、クラウド・オブジェクト・ストレージ資格証明を格納します。詳細は、資格証明の作成を参照してください。
2. データを含める表を作成します。例:

   CREATE TABLE CHANNELS
      (channel_id CHAR(1),
       channel_desc VARCHAR2(20),
       channel_class VARCHAR2(20)
      );
   /

3. DBMS_CLOUD.COPY_DATAプロシージャを使用して、データを表にロードします。例:

   BEGIN
    DBMS_CLOUD.COPY_DATA(
       table_name =>'CHANNELS',
       credential_name =>'DEF_CRED_NAME',
       file_uri_list =>'https://swiftobjectstorage.us-phoenix-1.oraclecloud.com/v1/idthydc0kinr/mybucket/channels.txt',
       format => json_object('delimiter' value ',')
    );
   END;
   /
   

   パラメータは次のとおりです:

   • table_name: ターゲット表の名前です。

   • credential_name: 前のステップで作成された資格証明の名前です。

   • file_uri_list: ロードするソース・ファイルのカンマ区切りリストです。

     この例では、file_uri_listは、us-phoenix-1リージョンにあるmybucketバケット内のchannels.txtファイルを指定するOracle Cloud Infrastructure Swift URIです。(idthydc0kinrは、バケットが存在するオブジェクト・ストレージ・ネームスペースです。)サポートされているURIフォーマットの詳細は、クラウド・オブジェクト・ストレージのURIフォーマットを参照してください。

   • format: ソース・ファイルのフォーマットを説明するために指定するオプションを定義します。指定できるフォーマット・オプションの詳細は、フォーマット・パラメータを参照してください。

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

DBMS_CLOUD.COPY_DATAプロシージャを使用して、区切りドキュメントのJSONファイルをAutonomous Database内のコレクションにロードする方法について学習します。

{ "name" : "apple", "count": 20 }
{ "name" : "orange", "count": 42 }
{ "name" : "pear", "count": 10 }

1. DBMS_CLOUD.CREATE_CREDENTIALプロシージャを使用して、クラウド・オブジェクト・ストレージ資格証明を格納します。詳細は、資格証明の作成を参照してください。
2. DBMS_CLOUD.COPY_DATAプロシージャを使用して、データをコレクションにロードします。例:

   BEGIN 
     DBMS_CLOUD.COPY_COLLECTION(
       collection_name =>'fruit',
       credential_name =>'DEF_CRED_NAME',
       file_uri_list =>'https://objectstorage.us-ashburn-1.oraclecloud.com/n/namespace-string/b/fruit_bucket/o/myCollection.json',
       format => json_object('recorddelimiter' value '''\n''')
    );
   END;
   /
   

   パラメータは次のとおりです:

   • collection_name: ターゲット・コレクションの名前です。

   • credential_name: 前のステップで作成された資格証明の名前です。

   • file_uri_list: ロードするソース・ファイルのカンマ区切りリストです。

     この例では、file_uri_listは、us-phoenix-1リージョンにあるmybucketバケット内のmyCollection.jsonファイルを指定するOracle Cloud Infrastructure Swift URIです。サポートされているURIフォーマットの詳細は、クラウド・オブジェクト・ストレージのURIフォーマットを参照してください。

   • format: ソース・ファイルのフォーマットを説明するために指定するオプションを定義します。JSONデータのロードでは、フォーマット・オプションcharacterset、compression、ignoreblanklines、jsonpath、maxdocsize、recorddelimiter、rejectlimit、unpackarrayがサポートされています。これ以外のフォーマットを指定すると、エラーが発生します。指定できるフォーマット・オプションの詳細は、フォーマット・パラメータを参照してください。

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

DBMS_CLOUD.COPY_COLLECTIONプロシージャを使用して、JSONドキュメントの配列をAutonomous Database内のコレクションにロードする方法について学習します。

[{"name" : "apple", "count": 20 },
 {"name" : "orange", "count": 42 },
 {"name" : "pear", "count": 10 }]

1. DBMS_CLOUD.CREATE_CREDENTIALプロシージャを使用して、クラウド・オブジェクト・ストレージ資格証明を格納します。詳細は、資格証明の作成を参照してください。
2. DBMS_CLOUD.COPY_DATAプロシージャを使用して、データをコレクションにロードします。例:

   BEGIN 
     DBMS_CLOUD.COPY_COLLECTION(    
       collection_name => 'fruits',    
       credential_name => 'DEF_CRED_NAME',    
       file_uri_list => 'https://objectstorage.us-ashburn-1.oraclecloud.com/n/namespace-string/b/json/o/fruit_array.json',
       format => '{"recorddelimiter" : "0x''01''", "unpackarrays" : "TRUE", "maxdocsize" : "10240000"}'
     );
   END;
   /

   この例では、ファイル全体を占める単一のJSON値をロードします。そのため、レコード・デリミタを指定する必要はありません。レコード・デリミタがないことを示すために、入力ファイル内に出現しない文字を使用できます。たとえば、値"0x''01''"は、この文字がJSONテキスト内に直接出現しないため、使用できます。

   フォーマット値のunpackarraysパラメータがTRUEに設定されている場合、ドキュメントの配列は、配列全体としてではなく個々のドキュメントとしてロードされます。ただし、配列要素の解凍は単一レベルに制限されます。ドキュメント内にネストされた配列がある場合、これらの配列は解凍されません。

   パラメータは次のとおりです:

   • collection_name: ターゲット・コレクションの名前です。

   • credential_name: 前のステップで作成された資格証明の名前です。

   • file_uri_list: ロードするソース・ファイルのカンマ区切りリストです。

     この例では、file_uri_listは、us-phoenix-1リージョンにあるmybucketバケット内のmyCollection.jsonファイルを指定するOracle Cloud Infrastructure Swift URIです。サポートされているURIフォーマットの詳細は、クラウド・オブジェクト・ストレージのURIフォーマットを参照してください。

   • format: ソース・ファイルのフォーマットを説明するために指定するオプションを定義します。JSONデータのロードでは、フォーマット・オプションcharacterset、compression、ignoreblanklines、jsonpath、maxdocsize、recorddelimiter、rejectlimit、unpackarrayがサポートされています。これ以外のフォーマットを指定すると、エラーが発生します。指定できるフォーマット・オプションの詳細は、フォーマット・パラメータを参照してください。

   DBMS_CLOUD.COPY_COLLECTIONでフォーマット・オプションunpackarraysを使用してfruit_array.jsonをロードすると、プロシージャによってソース内の配列値が認識されます。そのため、デフォルトのようにデータが単一のドキュメントとしてロードされるのではなく、配列内の各値を単一のドキュメントとしてデータがコレクションfruitsにロードされます。

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

DBMS_CLOUD.COPY_DATAを使用して、クラウド内のJSONデータを表にロードします。

1. プロシージャDBMS_CLOUD.CREATE_CREDENTIALを使用してオブジェクト・ストアの資格証明を保存します。例:

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

   この操作によって、資格証明が暗号化された形式でデータベースに格納されます。資格証明には任意の名前を使用できます。オブジェクト・ストアの資格証明を変更しないかぎり、このステップが必要なのは1回のみです。資格証明を格納した後は、すべてのデータ・ロードで同じ資格証明名を使用できます。

   パラメータの詳細は、CREATE_CREDENTIALプロシージャを参照してください。

2. DBMS_CLOUD.COPY_DATAプロシージャを使用して、既存の表にJSONデータをロードします。

   例:

   CREATE TABLE WEATHER2
       (WEATHER_STATION_ID VARCHAR2(20),
        WEATHER_STATION_NAME VARCHAR2(50));
   / 
   
   BEGIN 
     DBMS_CLOUD.COPY_DATA(
         table_name      => 'WEATHER2',
         credential_name => 'DEF_CRED_NAME',
         file_uri_list   => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/jsonfiles*',
         format          =>  JSON_OBJECT('type' value 'json', 'columnpath' value '["$.WEATHER_STATION_ID",
             "$.WEATHER_STATION_NAME"]')
       );
   END;
   / 
   

   パラメータは次のとおりです:

   • table_name: ターゲット表の名前です。

   • credential_name: 前のステップで作成された資格証明の名前です。

   • file_uri_list: ロードするソース・ファイルのカンマ区切りリストです。URIのファイル名にワイルドカードを使用できます。文字"*"は複数の文字を表すワイルドカードとして、文字"?"は1つの文字を表すワイルドカードとして使用できます。

   • format: JSONデータを含むDBMS_CLOUD.COPY_DATAの場合、typeはJSONです。他のフォーマット値を指定して、JSONソース・ファイルのフォーマットを説明するオプションを定義します。詳細は、DBMS_CLOUD Package Format Optionsを参照してください。

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

   パラメータの詳細は、COPY_DATAプロシージャを参照してください。

ネイティブ・バイナリJSONデータ(OSON形式)は、SQL型に対応し、JSON標準に含まれないスカラー型(日付など)を追加することで、JSON言語を拡張します。Oracle Databaseでは、表現するテキストJSONオブジェクト(このような非標準値を含む)の使用もサポートされています。

このような拡張オブジェクトを含むテキストJSONデータからネイティブ・バイナリJSONデータを作成する場合、必要に応じて、対応する(ネイティブ・バイナリ) JSONスカラー値に置換できます。

拡張オブジェクトの例は、{"$numberDecimal":31}です。これは、非標準の10進数型のJSONスカラー値を表し、そのように解釈されると、ネイティブ・バイナリ形式の10進数に置換されます。

たとえば、JSONデータ・タイプ・コンストラクタJSONを使用する場合、キーワードEXTENDEDを使用すると、テキストの入力で認識された拡張オブジェクトがネイティブ・バイナリJSONの結果では対応するスカラー値に置き換えられます。キーワードEXTENDEDを含めなければ、このような置換は発生しません。テキストの拡張JSONオブジェクトは、ネイティブ・バイナリ形式のJSONオブジェクトにそのまま変換されるだけです。

逆に、Oracle SQLファンクションjson_serializeを使用してバイナリJSONデータをテキストJSONデータ(VARCHAR2、CLOBまたはBLOB)としてシリアライズする場合は、キーワードEXTENDEDを使用して、(ネイティブ・バイナリ) JSONスカラー値を対応するテキスト拡張JSONオブジェクトに置き換えることができます。

拡張オブジェクトには、主に次の2つのユースケースがあります:

• 交換(インポート/エクスポート):

  • 拡張オブジェクトを含む既存のJSONデータを(任意の場所から)取り込みます。

  • ネイティブ・バイナリJSONデータは、データベース外で使用するために、拡張オブジェクトを含むテキストJSONデータとしてシリアル化します。

• ネイティブ・バイナリJSONデータの検査: 対応する拡張オブジェクトを参照して、内容を確認します。

交換目的の場合は、Oracle NoSQL Databaseなどの一般的なNoSQLデータベースによって生成されたファイルからJSONデータを取り込み、拡張オブジェクトをネイティブ・バイナリJSONスカラーに変換できます。一方、ネイティブ・バイナリJSONデータをテキスト・データとしてエクスポートし、Oracle固有スカラーJSON値を対応するテキスト拡張JSONオブジェクトに置き換えることができます。

拡張オブジェクト・フィールドのスカラーJSON型へのマッピングは、一般に多対1です。複数の種類の拡張JSONオブジェクトを特定の1つのスカラー値にマップできます。たとえば、拡張JSONオブジェクト{"$numberDecimal":"31"}および{"$numberLong:"31"}は、両方とも値31 of JSON-languageスカラー型numberとして変換され、項目メソッドtype()はこれらの各JSONスカラーについて"number"を返します。

項目メソッドtype()は、対象値のJSON言語スカラー型を(JSON文字列として)報告します。一部のスカラー値は、同じスカラー型であっても内部的に区別できます。これにより、通常、ファンクションjson_serialize (キーワードEXTENDEDを指定)は元の拡張JSONオブジェクトを再構築できます。このようなスカラー値は、異なるSQL型を使用して実装するか、導出元の拡張JSONオブジェクトの種類でタグ付けすることで、内部的に区別されます。

json_serializeで元の拡張JSONオブジェクトを再構築する場合、結果は必ずしもオリジナルとテキスト的に同じではありませんが、常にセマンティクス的に同等です。たとえば、{"$numberDecimal":"31"}と{"$numberDecimal":31}は、フィールド値のタイプ(文字列と数値)が異なっていても、セマンティクスは同じです。これらは同じ内部値に変換され、それぞれが$numberDecimal拡張オブジェクト(同じタグ)から導出されたものとしてタグ付けされます。ただし、シリアライズされると、両方の結果は{"$numberDecimal":31}になります。Oracleでは常に、最も直接関連する型がフィールド値に使用されます。この場合は、スカラー型numberのJSON言語値31です。

表4-1に、使用される様々な型間の対応関係を示します。(1)入力として使用される拡張オブジェクトのタイプ、(2)項目メソッドtype()によって報告されるタイプ、(3)内部で使用されるSQLタイプ、(4)ファンクションjson_serializeによる出力として使用される標準のJSON言語タイプ、および(5)キーワードEXTENDEDが指定されている場合のjson_serializeによる拡張オブジェクト出力のタイプの間でマップします。

^脚注1 文字列値は大/小文字を区別せずに解釈されます。たとえば、"NAN"、"nan"および"nAn"は同等として受け入れられ、"INF"、"inFinity"および"iNf"も同様です。無限に大きい数値("Infinity"または"Inf")および小さい数値("-Infinity"または"-Inf")は、フルワードまたは略語で受け入れられます。

^脚注2 出力では、これらの文字列値のみが使用されます。フルワードInfinityまたは大小文字のバリアントは使用されません。

PL/SQLパッケージDBMS_CLOUDを使用して実行されたデータ・ロード操作は、表dba_load_operationsおよびuser_load_operationsに記録されます:

• dba_load_operations: すべてのロード操作が表示されます。

• user_load_operations: 自分のスキーマのロード操作が表示されます。

これらの表を問い合せると、進行中または完了済のデータ・ロードに関する情報が表示されます。たとえば、TYPE列のWHERE句述語でSELECT文を使用すると、タイプがCOPYのロード操作が表示されます:

SELECT table_name, owner_name, type, status, start_time, update_time, logfile_table, badfile_table 
   FROM user_load_operations WHERE type = 'COPY';

TABLE_NAME OWNER_NAME  TYPE   STATUS     START_TIME                            UPDATE_TIME                          LOGFILE_TABLE   BADFILE_TABLE
---------- ----------- ------- ---------- ---------------------- --------------------- --------------- ------------- ------------- -------------
CHANNELS   SH          COPY   COMPLETED  04-MAR-21 07.38.30.522711000 AM GMT    04-MAR-21 07.38.30.522711000 AM GMT  COPY$1_LOG     COPY$1_BAD

LOGFILE_TABLE列には、ロード操作のログを確認するための問合せを実行できる表の名前が表示されます。たとえば、次の問合せでは、ロード操作のログが表示されます:

select * from COPY$21_LOG;

BADFILE_TABLE列には、ロード中にエラーが発生した行を確認するための問合せを実行できる表の名前が表示されます。たとえば、次の問合せでは、ロード操作で拒否されたレコードが表示されます:

select * from COPY$21_BAD;

ログに示されたエラーと、指定したBADFILE_TABLE表に示された行に応じて、DBMS_CLOUD.COPY_DATAで適切なフォーマット・オプションを指定することにより、エラーを修正できます。

user_load_operations表のクリアの詳細は、DELETE_ALL_OPERATIONSプロシージャを参照してください。