從雲端檔案載入資料

PL/SQL 套裝程式 DBMS_CLOUD 支援將資料從雲端中的檔案載入至專用 Exadata 基礎架構上的自治式 AI 資料庫中建立的表格。

您可以使用 DBMS_CLOUD 提供的下列 PL/SQL 程序，從不同的檔案格式載入資料：

• 雲端中的文字檔 (使用 DBMS_CLOUD.COPY_DATA 程序)

• 雲端中的 JSON 檔案 (使用 DBMS_CLOUD.COPY_TEXT 程序)

從檔案載入資料之前，請確定：

• 來源檔案可作為您從屬端電腦中的本機檔案，或上傳至雲端物件存放區 (例如 Oracle Cloud Infrastructure Object Storage)，並可供嘗試載入資料的資料庫使用者存取。

• 您的雲端物件儲存證明資料是使用 DBMS_CLOUD.CREATE_CREDENTIAL 程序儲存的。請參閱建立證明資料以瞭解詳細資訊。

套裝程式 DBMS_CLOUD 支援從下列雲端服務中的檔案載入：Oracle Cloud Infrastructure Object Storage、Oracle Cloud Infrastructure Object Storage Classic、Azure Blob Storage 及 Amazon S3。

建立證明資料

瞭解如何使用 DBMS_CLOUD.CREATE_CREDENTIAL 程序儲存您的雲端物件儲存證明資料。

使用任何資料庫工具 (例如 SQL*Plus、SQL Developer 或資料庫動作) (Web 型 SQL Developer 工具) 來執行 DBMS_CLOUD.CREATE_CREDENTIAL 程序。舉例而言：

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'DEF_CRED_NAME',
    username => '[e-mail]',
    password => 'password'
  );
END;
/

您為 username 和 password 提供的值取決於您使用的雲端物件儲存服務：

• Oracle Cloud Infrastructure Object Storage：username 是您的 Oracle Cloud Infrastructure 使用者名稱，password 是您的 Oracle Cloud Infrastructure 認證權杖。請參閱使用認證權杖。

• Oracle Cloud Infrastructure Object Storage Classic：username 是您的 Oracle Cloud Infrastructure Classic 使用者名稱，而 password 是您的 Oracle Cloud Infrastructure Classic 密碼。

此作業會以加密格式將證明資料儲存在資料庫中。您可以為證明資料名稱使用任何名稱。請注意，除非您的物件存放區證明資料變更，否則此步驟只需要執行一次。儲存證明資料之後，您就可以對所有資料載入使用相同的證明資料名稱。

從文字檔載入資料

瞭解如何使用 DBMS_CLOUD.COPY_DATA 程序，將資料從雲端中的文字檔載入至您的 Autonomous AI 資料庫。

此範例中的來源檔案 channels.txt 具有下列資料：

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

1. 使用 DBMS_CREDENTIAL.CREATE_CREDENTIAL 程序儲存您的雲端物件儲存證明資料。請參閱建立證明資料以瞭解詳細資訊。</span>

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 是 Oracle Cloud Infrastructure Swift URI，指定 us-phoenix-1 區域中 mybucket 儲存桶的 channels.txt 檔案。(idthydc0kinr 是儲存桶所在的物件儲存命名空間。) 如需支援 URI 格式的相關資訊，請參閱雲端物件儲存 URI 格式。

   • format：定義您指定來描述來源檔案格式的選項。如需您可以指定之格式選項的相關資訊，請參閱格式參數。

將分隔文件的 JSON 檔案載入集合中

瞭解如何使用 DBMS_CLOUD.COPY_DATA 程序，將分隔文件的 JSON 檔案載入 Autonomous AI Database 中的集合。

此範例會從以行分隔的檔案載入 JSON 值，並使用 JSON 檔案 myCollection.json。每個價值都會以單一文件的形式載入 Autonomous AI Database 上的集合中。

以下為這類檔案的範例。它有三行，每行一個物件。這些物件中的每個物件都會載入為個別的 JSON 文件。

{ "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 是 Oracle Cloud Infrastructure Swift URI，指定 us-phoenix-1 區域中 mybucket 儲存桶的 myCollection.json 檔案。如需支援 URI 格式的相關資訊，請參閱雲端物件儲存 URI 格式。

   • format：定義您指定來描述來源檔案格式的選項。支援載入 JSON 資料的格式選項 characterset, compression, ignoreblanklines, jsonpath, maxdocsize, recorddelimiter, rejectlimit, unpackarray。指定的任何其他格式都會導致錯誤。如需您可以指定之格式選項的相關資訊，請參閱格式參數。

將 JSON 文件陣列載入集合

瞭解如何使用 DBMS_CLOUD.COPY_COLLECTION 程序，將 JSON 文件陣列載入 Autonomous AI Database 中的集合。

此範例使用 JSON 檔案 fruit_array.json。以下顯示 fruit_array.json 檔案的內容：

[{"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 是 Oracle Cloud Infrastructure Swift URI，指定 us-phoenix-1 區域中 mybucket 儲存桶的 myCollection.json 檔案。如需支援 URI 格式的相關資訊，請參閱雲端物件儲存 URI 格式。

   • format：定義您指定來描述來源檔案格式的選項。支援載入 JSON 資料的格式選項 characterset, compression, ignoreblanklines, jsonpath, maxdocsize, recorddelimiter, rejectlimit, unpackarray。指定的任何其他格式都會導致錯誤。如需您可以指定之格式選項的相關資訊，請參閱格式參數。

   使用格式選項 unpackarrays 載入 fruit_array.json 與 DBMS_CLOUD.COPY_COLLECTION，讓程序能夠辨識來源中的陣列值。因此，資料會載入至集合 fruits，而陣列中的每個值則載入為單一文件，而非以單一文件載入資料。

將 JSON 資料複製到現有表格

使用 DBMS_CLOUD.COPY_DATA 將雲端中的 JSON 資料載入表格中。

此範例中的來源檔案是 JSON 資料檔。

程序

1. 使用 DBMS_CLOUD.CREATE_CREDENTIAL 程序儲存您的物件存放區證明資料。舉例而言：

    SET DEFINE OFF
    BEGIN
      DBMS_CLOUD.CREATE_CREDENTIAL(
        credential_name => 'DEF_CRED_NAME',
        username => '[e-mail]',
        password => 'password'
      );
    END;
    /
   

   此作業會以加密格式將證明資料儲存在資料庫中。您可以為證明資料名稱使用任何名稱。請注意，除非您的物件存放區證明資料變更，否則此步驟只需要執行一次。儲存證明資料之後，您就可以對所有資料載入使用相同的證明資料名稱。

   如需有關參數的詳細資訊，請參閱 CREATE_CREDENTIAL Procedure 。

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 中的檔案名稱中使用萬用字元。字元 "*" 可以作為多個字元的萬用字元使用，可以使用字元 "?" 作為單一字元的萬用字元。

   • format：對於含有 JSON 資料的 DBMS_CLOUD.COPY_DATA，type 為 json。指定其他格式值以定義描述 JSON 來源檔案格式的選項。請參閱 DBMS_CLOUD 套裝程式格式選項瞭解詳細資訊。

   在此範例中，namespace-string 是 Oracle Cloud Infrastructure 物件儲存命名空間，而 bucketname 是儲存桶名稱。請參閱瞭解物件儲存命名空間以瞭解詳細資訊。

   如需有關參數的詳細資訊，請參閱 COPY_DATA Procedure 。

監控及疑難排解資料載入

使用 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 中指定正確的格式選項來更正錯誤。

注意：每個載入作業都會儲存 LOGFILE_TABLE 和 BADFILE_TABLE 表格兩天，然後自動移除。

dbmscloud-for-objects-and-files.md#GUID-CEC0CA63-B77F-4D64-B70F-1E8476AE3ED6

請參閱 DELETE_ALL_OPERATIONS 程序，瞭解清除 user_load_operations 表格的相關資訊。

代表延伸定量值的文字 JSON 物件

原生二進位 JSON 資料 (OSON 格式) 可透過新增對應 SQL 類型且不屬於 JSON 標準的純量類型 (例如日期) 來擴充 JSON 語言。Oracle Database 也支援使用代表 JSON 純量值的文字 JSON 物件，包括這類非標準值。

當您從包含這類擴充物件的文字 JSON 資料建立原生二進位 JSON 資料時，可以選擇取代相對應 (原生二進位) JSON 純量值。

延伸物件的範例為 {"$numberDecimal":31}。它代表非標準類型小數的 JSON 純量值，當解譯為此值時，會以原生二進位格式的小數取代此值。

例如，當您使用 JSON 資料類型建構子 JSON 時，如果您使用關鍵字 EXTENDED，則文字輸入中可辨識的延伸物件會被原生二進位 JSON 結果中的對應純量值取代。如果您未包含關鍵字 EXTENDED，則不會進行這類取代；文字延伸 JSON 物件會直接以原生二進位格式轉換為 JSON 物件。

相反的，當您使用 SQL/JSON 函數 json_serialize 將二進位 JSON 資料序列化為文字 JSON 資料 (VARCHAR2、CLOB 或 BLOB) 時，您可以使用關鍵字 EXTENDED 將 JSON 純量值取代為對應的文字擴充 JSON 物件。

注意：如果您使用的資料庫是 Oracle Autonomous AI Database，則可以使用 PL/SQL 程序 DBMS_CLOUD.copy_collection，從一般 NoSQL 資料庫 (包括 Oracle NoSQL Database) 所產生的 JSON 資料檔案建立 JSON 文件集合。

如果您使用 ejson 作為程序的 type 參數值，則在產生的原生二進位 JSON 集合中，輸入檔案中可辨識的延伸 JSON 物件會被對應的純量值取代。另一方面，您可以將函數 json_serialize 與關鍵字 EXTENDED 搭配使用，以在產生的文字 JSON 資料中使用延伸 JSON 物件來取代純量值。

下列是擴充物件的兩個主要使用案例：

• 交換 (匯入 / 匯出)：

  • 擷取包含擴充物件的現有 JSON 資料 (從某個位置)。

  • 將原生二進位 JSON 資料序列化為具有擴充物件的文字 JSON 資料，以便在資料庫外部使用。

• 原生二進位 JSON 資料的檢查：查看對應的擴充物件以查看您的內容。

為了交換目的，您可以從一般 NoSQL 資料庫 (包括 Oracle NoSQL Database) 產生的檔案擷取 JSON 資料，將延伸物件轉換為原生二進位 JSON 純量。另一方面，您可以將原生二進位 JSON 資料匯出為文字資料，並以對應的文字擴充 JSON 物件取代 Oracle 特定純量 JSON 值。

提示：作為檢驗範例，請考慮將原生 JSON 資料序列化所產生的物件 (例如 {"dob" : "2000-01-02T00:00:00"})。"2000-01-02T00:00:00" 是將類型日期的原生二進位值序列化的結果，還是原生二進位值只是字串？使用 json_serialize 與關鍵字 EXTENDED 可讓您知道。

一般而言，延伸物件欄位與純量 JSON 類型的對應是多對一：可將一種以上的延伸 JSON 物件對應至指定的純量值。例如，延伸的 JSON 物件 {"$numberDecimal":"31"} 和 {"$numberLong:"31"} 都會轉譯為 JSON 語言純量類型編號的值 31，而項目方法 type() 會傳回每個 JSON 純量 "number"。

項目方法 type() 會報告其目標值的 JSON 語言純量類型 (作為 JSON 字串)。某些純量值可在內部區別，即使其純量類型相同也一樣。這通常允許函數 json_serialize (含關鍵字 EXTENDED) 重新建構原始延伸 JSON 物件。這類純量值可在內部使用不同的 SQL 類型來實行，或透過使用衍生它們的延伸 JSON 物件種類標記來區分。

當 json_serialize 重新建構原始延伸 JSON 物件時，結果不一定與原始物件文字相同，但一律基本上對等。例如，{"$numberDecimal":"31"} 和 {"$numberDecimal":31} 等同於語意，即使欄位值在類型 (字串和數字) 中不同。它們會轉譯為相同的內部值，且每個值都會標記為衍生自 $numberDecimal 延伸物件 (相同標記)。但如果序列化，兩者的結果會是 {"$numberDecimal":31}。Oracle 一律對欄位值使用最直接的相關類型，在此情況下，純量類型編號為 JSON 語言值 31。

下表顯示所使用各種類型的對應。它會對應 (1) 類型的延伸物件 (作為輸入)、(2) 項目方法報告的類型 type()、(3) 內部使用的 SQL 類型、(4) 標準 JSON 語言類型 (作為函數 json_serialize 的輸出)，以及 (5) 指定關鍵字 EXTENDED 時由 json_serialize 輸出的延伸物件類型。

擴充物件類型 (輸入)	Oracle JSON 純量類型 (按 type() 報告)	SQL 定量類型	標準 JSON 純量類型 (輸出)	擴充物件類型 (輸出)
$numberDouble，其值為 JSON 數字、代表數字的字串，或下列其中一個字串："Infinity"、"-Infinity"、"Inf"、"-Inf"、"Nan" (請參閱註腳 1)	雙精準數	BINARY_DOUBLE	數字	$numberDouble，其值為 JSON 數字或下列其中一個字串："Inf"、"-Inf"、"Nan" (請參閱註腳 2)
$numberFloat，其值與 $numberDouble 的值相同	浮點數	BINARY_FLOAT	數字	輸入 $numberFloat 的值與 $numberDouble 的值相同
輸入 $numberDecimal 的值與 $numberDouble 的值相同	數字	NUMBER	數字	輸入 $numberDecimal 的值與 $numberDouble 的值相同
$numberInt，其值為簽署的 32 位元整數或代表數字的字串	數字	NUMBER	數字	輸入 $numberInt 的值與 $numberDouble 的值相同
$numberLong，其值為 JSON 數字或代表數字的字串	數字	NUMBER	數字	$numberLong，其值與 $numberDouble 的值相同
$binary 與下列其中一個值： 已有 base-64 個字元的字串 具有 base64 和 subType 欄位的物件，其值分別是 base-64 字元的字串和數字 0 (任意二進位檔) 或 4 (UUID) 當值是基底 64 個字元的字串時，延伸物件也可以具有值為 0 或 4 的欄位 $subtype，以 1 位元組整數 (0-255) 或 2 個字元的十六進位字串表示。	二進位	BLOB 或 RAW	字串 轉換等同於使用 SQL 函數 rawtohex。	下列其中一項： $binary，值為 base-64 個字元的字串 如果輸入的 subType 值為 4 (UUID)，則值為 32 個十六進位字元的字串 $rawid
$oid，其值為 24 個十六進位字元的字串	二進位	RAW(12)	字串 轉換等同於使用 SQL 函數 rawtohex。	$rawid，其值為 24 個十六進位字元的字串
$rawhex (含值) 含有偶數十六進位字元的字串	二進位	RAW	字串 轉換等同於使用 SQL 函數 rawtohex。	$binary 值為基底 64 個字元的字串，以 = 字元填補右側
$rawid，其值為 24 或 32 個十六進位字元的字串	二進位	RAW	字串 轉換等同於使用 SQL 函數 rawtohex。	$rawid
值為 ISO 8601 日期字串的 $oracleDate	日期	DATE	字串	值為 ISO 8601 日期字串的 $oracleDate
值為 ISO 8601 時戳字串的 $oracleTimestamp	時戳	TIMESTAMP	字串	值為 ISO 8601 時戳字串的 $oracleTimestamp
值為 ISO 8601 時戳字串的 $oracleTimestampTZ，其時區位移為數值或 Z	時區時戳	TIMESTAMP WITH TIME ZONE	字串	值為 ISO 8601 時戳字串的 $oracleTimestampTZ，其時區位移為數值或 Z
$date 與下列其中一個值： 自 1990 年 1 月 1 日起的整數毫秒數 ISO 8601 時間戳記字串 自 1990 年 1 月 1 日起，欄位為 numberLong 且值為整數毫秒數的物件	時區時戳	TIMESTAMP WITH TIME ZONE	字串	值為 ISO 8601 時戳字串的 $oracleTimestampTZ，其時區位移為數值或 Z
$intervalDaySecond，其值為為 SQL 函數 to_dsinterval 指定的 ISO 8601 間隔字串	天數間隔	INTERVAL DAY TO SECOND	字串	$intervalDaySecond，其值為為 SQL 函數 to_dsinterval 指定的 ISO 8601 間隔字串
$intervalYearMonth，其值為為 SQL 函數 to_yminterval 指定的 ISO 8601 間隔字串	年月間隔	INTERVAL YEAR TO MONTH	字串	$intervalYearMonth，其值為為 SQL 函數 to_yminterval 指定的 ISO 8601 間隔字串
兩個欄位： 具有值之陣列的欄位 $vector，其元素為數字或字串 "Nan"、"Inf" 和 "-Inf" (代表非數字和無限值)。 字串值為 "float32" 或 "float64" 的欄位 $vectorElementType。這些數字分別對應至 IEEE 32 位元和 IEEE 64 位元數字。	向量	VECTOR	數字的陣列	兩個欄位： 具有值之陣列的欄位 $vector，其元素為數字或字串 "Nan"、"Inf" 和 "-Inf" (代表非數字和無限值)。 字串值為 "float32" 或 "float64" 的欄位 $vectorElementType。

註腳 1 字串值不區分大小寫。例如，接受 "NAN" "nan" 和 "nAn" 等效，類似於 "INF"、"inFinity" 和 "iNf"。接受無限大 ("Infinity" 或 "Inf") 和小 ("-Infinity" 或 "-Inf") 數字，可包含完整字或縮寫。

註腳 2 輸出時，只會使用這些字串值。沒有全字 Infinity 或字母大小寫變體。

相關內容

• COPY_COLLECTION 程序

• 複製資料程序

• 將資料放入物件儲存

• 物件儲存總覽

• 浮點算術 IEEE 標準 (IEEE 754)