物件和檔案的 DBMS_CLOUD

本節涵蓋用於處理物件和檔案的 DBMS_CLOUD 子程式。

必備條件

身為開發人員，您可以將 DBMS_CLOUD 程序與部署在 Oracle Public Cloud、Multicloud 或 Exadata Cloud@Customer 上的 Autonomous AI 資料庫搭配使用。

視部署選項而定，必須符合下列先決條件，才能將 DBMS_CLOUD 程序與 Amazon S3、Azure Blob Storage 及 Google Cloud Storage 服務提供者搭配使用。

Oracle Public Cloud 或多雲端 Exadata 客戶私有雲

您的機組管理員必須使用 NAT 閘道設定輸出連線，如下所述：

• 請依照 Oracle Cloud Infrastructure 文件中 Create a NAT Gateway 的指示，在您自治式 AI 資料庫資源所在的虛擬雲端網路 (VCN) 中建立 NAT 閘道。

• 建立 NAT 閘道之後，請在自治式 AI 資料庫資源所在的每個子網路 (VCN 中) 新增路由規則和輸出安全規則，讓這些資源能夠使用閘道從您的 Azure AD 執行處理取得公開金鑰：

  1. 移至子網路的子網路詳細資訊頁面。

  2. 在子網路資訊頁籤中，按一下子網路的路由表名稱，以顯示其路由表詳細資訊頁面。

  3. 在現有路由規則的表格中，檢查是否已有具有下列特性的規則：

     • 目的地：0.0.0.0/0

     • 目標類型：NAT 閘道

     • 目標：您剛剛在 VCN 中建立的 NAT 閘道名稱

     如果沒有這樣的規則，請按一下新增路由規則，然後新增具有這些特性的路由規則。

  4. 返回子網路的子網路詳細資訊頁面。

  5. 在子網路的安全清單表格中，按一下子網路安全清單的名稱，以顯示其安全清單詳細資訊頁面。

  6. 在側邊功能表的資源底下，按一下傳出規則。

  7. 在現有傳出規則的表格中，檢查是否已有具有下列特性的規則：

     • 目的地類型： CIDR

     • 目的地：0.0.0.0/0

     • IP 協定： TCP

     • 來源連接埠範圍：443

     • 目的地連接埠範圍：全部

     如果沒有這類規則，請按一下新增傳出規則，然後新增含有這些特性的傳出規則。

您環境中的 HTTP 代理主機設定值必須允許資料庫存取雲端服務提供者。

這些設定值是由機組管理員在建立 Exadata Cloud@Customer 基礎架構時所定義，如使用主控台在 Cloud@Customer 上佈建 Exadata 資料庫服務中所述。

注意：只有在 Exadata 基礎架構處於需要啟用狀態時，才能編輯包含 HTTP 代理主機的網路組態。啟用之後，就無法編輯這些設定值。

若為已經佈建的 Exadata 基礎架構設定 HTTP 代理主機，在 My Oracle Support 中需要服務要求 (SR)。請參閱 在 My Oracle Support 中建立服務要求，瞭解詳細資訊。

物件和檔案的 DBMS_CLOUD 子程式

DBMS_CLOUD 套裝程式內物件和檔案管理的子程式。

子程式	描述
COPY_COLLECTION 程序	此程序會從雲端物件儲存或目錄中的檔案，將資料載入現有的 SODA 集合。
複製資料程序	此程序會從雲端物件儲存或目錄中的檔案，將資料載入現有的自治式 AI 資料庫表格。
Avro、ORC 或 Parquet 檔案的 COPYDATA 程序	此程序的 format 參數 type 設為值 orc、parquet 或 avro，會將資料從雲端中的 ORC、Parquet 或 Avro 檔案或目錄中的 ORC、Parquet 或 Avro 檔案載入現有的自治式 AI 資料庫表格。 與文字檔類似，資料會從來源 ORC、Parquet 或 Avro 檔案複製到既有的內部表格中。
COPY_OBJECT 程序	此程序會將檔案從一個雲端物件儲存的儲存桶複製到另一個儲存桶。
CREATE_EXTERNAL_TABLE 程序	此程序會在雲端的檔案或目錄中的檔案上建立外部表格。這可讓您從自治式 AI 資料庫對外部資料執行查詢。
Avro、ORC 或 Parquet 檔案的 CREATE_EXTERNAL_TABLE 程序	此程序的 format 參數 type 設為值 parquet、orc 或 avro，會在雲端或目錄中建立含有 Parquet、ORC 或 Avro 格式檔案的外部表格。 這可讓您從自治式 AI 資料庫對外部資料執行查詢。
CREATE_EXTERNAL_TEXT_INDEX 程序	此程序會在物件存放區檔案上建立文字索引。
CREATE_HYBRID_PART_TABLE 程序	此程序會建立混合分割表格。這可讓您對自治式 AI 資料庫的混合分割資料執行查詢。
DELETE_ALL_OPERATIONS 程序	此程序會清除綱要中 user_load_operations 表格中記錄的所有資料載入作業，或清除指定類型的所有資料載入作業 (如 type 參數所示)。
DeleteE_FILE 程序	此程序會從「自治式 AI 資料庫」上的指定目錄移除指定的檔案
DELETE_OBJECT 程序	此程序會刪除物件存放區上的指定物件。
DELETE_OPERATION 程序	此程序接受 operation_id 作為輸入，並刪除與指定 operation_id 關聯的日誌。
DROP_EXTERNAL_TEXT_INDEX 程序	此程序會刪除物件存放區檔案的文字索引。
匯出資料程序	此程序會根據查詢的結果，將資料從自治式 AI 資料庫匯出至雲端中的檔案。超載表單可讓您使用 operation_id 參數。根據指定的 format 參數 type 選項，程序會以 CSV、JSON、Parquet 或 XML 選項的文字，將資料列匯出至「雲端物件」存放區
GET_OBJECT 程序和函數	此程序已超載。程序表單會從 Cloud Object Storage 讀取物件，並將其複製到 Autonomous AI Database。函數表單會從 Cloud Object Storage 讀取物件，並將 BLOB 傳回至 Autonomous AI Database。
LIST_FILES 函數	此函數會列出指定目錄中的檔案。結果包括檔案名稱和檔案的其他描述資料，例如檔案大小 (位元組)、建立時戳以及上次修改時戳。
LIST_OBJECTS 函數	此函數會列出物件存放區中指定位置的物件。結果會包含物件名稱，以及物件的其他描述資料，例如大小、總和檢查、建立時戳以及上次修改時戳。
MOVE_OBJECT 程序	此程序會將物件從一個雲端物件儲存的儲存桶移至另一個儲存桶。
PUT_OBJECT 程序	此程序已超載。程序會以一種形式從自治式 AI 資料庫將檔案複製到雲端物件儲存。另一種形式，此程序會將 BLOB 從自治式 AI 資料庫複製到雲端物件儲存。
SYNC_EXTERNAL_PART_TABLE 程序	此程序可簡化從雲端檔案更新外部分割的表格。每當新增分割區，或從外部分割表格的「物件存放區」來源移除分割區時，執行此程序。
VALIDATE_EXTERNAL_TABLE 程序	此程序會驗證外部表格的來源檔案、產生日誌資訊，並且將不符合為外部表格指定之格式選項的資料列儲存在「自治式 AI 資料庫」的錯誤表格中。
VALIDATE_EXTERNAL_PART_TABLE 程序	此程序會驗證外部分割表格的來源檔案、產生日誌資訊，以及將與「自治式 AI 資料庫」之錯誤表格中為外部表格指定之格式選項不相符的資料列儲存。
VALIDATE_HYBRID_PART_TABLE 程序	此程序會驗證混合分割表格的來源檔案、產生日誌資訊，以及將與「自治式 AI 資料庫」之錯誤檔案表格中為混合表格指定的格式選項不相符的資料列儲存。

COPY_COLLECTION 程序

此程序會將資料從 Cloud Object Storage 或目錄載入 SODA 集合中。如果指定的 SODA 集合不存在，程序會建立該集合。超載表單可讓您使用 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
);

參數

Parameter - 參數	描述
collection_name	將載入資料的 SODA 集合名稱。如果已有此名稱的集合存在，將會載入指定的資料，否則會建立新的集合。
credential_name	存取雲端物件儲存的證明資料名稱。 當您使用 file_uri_list 指定目錄時，不會使用此參數。
file_uri_list	此參數指定以逗號分隔的來源檔案 URI 清單，或一或多個目錄與來源檔案。 雲端來源檔案 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 的格式取決於您使用的雲端物件儲存服務，如需詳細資訊，請參閱雲端物件儲存 URI 格式。 請參閱 Oracle Database 19c SQL Language Reference 或 Oracle Database 26ai SQL Language Reference 中的 REGEXP_LIKE Condition ，瞭解 REGEXP_LIKE 條件的詳細資訊。 目錄 您可以指定一個目錄和一或多個檔案名稱，或使用以逗號分隔的目錄和檔案名稱清單。指定目錄的格式為：'MY_DIR:filename.ext'。依照預設，目錄名稱 MY_DIR 是資料庫物件，不區分大小寫。檔案名稱有大小寫之別。 您可以使用萬用字元指定目錄中的檔案名稱。字元 "*" 可以作為多個字元的萬用字元使用，而字元 "?" 可以用來作為單一字元的萬用字元。例如：'MY_DIR:*" 或 'MY_DIR:test?' 若要指定多個目錄，請使用以逗號分隔的目錄清單：例如：'MY_DIR1:*, MY_DIR2:test?' 使用雙引號來指定區分大小寫的目錄名稱。例如：'"my_dir1":*, "my_dir2":Test?' 若要包含引號字元，請使用兩個引號。例如：'MY_DIR:''filename.ext'。這會指定以引號 (') 為開頭的 filename。
format	描述來源檔案格式的選項。這些選項被指定為 JSON 字串。 支援的格式包括：characterset, compression, ignoreblanklines, jsonpath, maxdocsize, recorddelimiter, rejectlimit, unpackarray、keyassignment 和 keypath。 除了上述的 JSON 資料格式之外，自治式 AI 資料庫也支援其他格式。如需 Autonomous AI Database 支援的格式引數清單，請參閱格式參數。
operation_id	使用此參數可追蹤載入作業的進度和最終狀態，作為 USER_LOAD_OPERATIONS 視觀表中對應的 ID。

範例

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'OBJ_STORE_CRED',
            username        => '[e-mail]',
            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;
/

複製資料程序

此程序會從雲端中的檔案或目錄中的檔案，將資料載入現有的自治式 AI 資料庫表格。超載表單可讓您使用 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);

參數

Parameter - 參數	描述
table_name	資料庫中目標表格的名稱。您必須先建立目標表格，才能執行 COPY_DATA。
credential_name	存取雲端物件儲存的證明資料名稱。 當您使用 file_uri_list 指定目錄時，不會使用此參數。
file_uri_list	您可以在雲端來源檔案 URI 的檔案名稱中使用萬用字元以及正規表示式。 雲端來源檔案 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 的格式取決於您使用的雲端物件儲存服務，如需詳細資訊，請參閱雲端物件儲存 URI 格式。 請參閱 Oracle Database 19c SQL Language Reference 或 Oracle Database 26ai SQL Language Reference 中的 REGEXP_LIKE Condition ，瞭解 REGEXP_LIKE 條件的詳細資訊。 目錄 您可以指定一個目錄和一或多個檔案名稱，或是使用以逗號分隔的目錄和檔案名稱清單。指定目錄的格式為：'MY_DIR:filename.ext'。依照預設，目錄名稱 MY_DIR 是資料庫物件，不區分大小寫。檔案名稱有大小寫之別。 您可以使用萬用字元指定目錄中的檔案名稱。字元 "*" 可以作為多個字元的萬用字元使用，而字元 "?" 可以用來作為單一字元的萬用字元。例如：'MY_DIR:*" 或 'MY_DIR:test?' 若要指定多個目錄，請使用以逗號分隔的目錄清單：例如：'MY_DIR1:*, MY_DIR2:test?' 使用雙引號來指定區分大小寫的目錄名稱。例如：'"my_dir1":*, "my_dir2":Test?' 若要包含引號字元，請使用兩個引號。例如：'MY_DIR:''filename.ext'。這會指定以引號 (') 為開頭的 filename。
schema_name	目標表格所在的綱要名稱。預設值為 NULL，表示目標表格與執行程序的使用者位於相同的綱要中。
field_list	識別來源檔案中的欄位及其資料類型。預設值為 NULL，表示欄位及其資料類型是由 column_list 參數所決定。此引數的語法與一般 Oracle 外部表格中的 field_list 子句相同。如需詳細資訊，請參閱 Oracle Database 19c Utilities 或 Oracle Database 26ai Utilities 中的 field_list 。 當 format 參數 type 選項值為 json 時，會忽略此參數。 如需使用 field_list 的範例，請參閱 CREATE_EXTERNAL_TABLE Procedure 。
format	描述來源、日誌及錯誤檔案格式的選項。如需選項清單與如何指定值，請參閱格式參數。 如需 Avro、ORC 或 Parquet 檔案格式選項，請參閱 DBMS_CLOUD Package Format Options for Avro，ORC，or Parquet 。
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 格式選項的相關資訊。

範例

BEGIN
    DBMS_CLOUD.CREATE_CREDENTIAL(
            credential_name => 'DEF_CRED_NAME',
            username        => '[e-mail]',
            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;
/

Avro、ORC 或 Parquet 檔案的 COPYDATA 程序

此程序的 format 參數 type 設為值 avro、orc 或 parquet，會將資料從雲端的 Avro、ORC 或 Parquet 檔案或目錄中的檔案載入現有的自治式 AI 資料庫表格。

與文字檔類似，資料會從來源 Avro、ORC 或 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);

參數

Parameter - 參數	描述
table_name	資料庫中目標表格的名稱。您必須先建立目標表格，才能執行 COPY_DATA。
credential_name	存取雲端物件儲存的證明資料名稱。 當您使用 file_uri_list 指定目錄時，不會使用此參數。
file_uri_list	此參數指定以逗號分隔的來源檔案 URI 清單，或一或多個目錄與來源檔案。 雲端來源檔案 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 的格式取決於您使用的雲端物件儲存服務，如需詳細資訊，請參閱雲端物件儲存 URI 格式。 請參閱 Oracle Database 19c SQL Language Reference 或 Oracle Database 26ai SQL Language Reference 中的 REGEXP_LIKE Condition ，瞭解 REGEXP_LIKE 條件的詳細資訊。 目錄 您可以指定一個目錄和一或多個檔案名稱，或使用以逗號分隔的目錄和檔案名稱清單。指定目錄的格式為：'MY_DIR:filename.ext'。依照預設，目錄名稱 MY_DIR 是資料庫物件，不區分大小寫。檔案名稱有大小寫之別。 您可以使用萬用字元指定目錄中的檔案名稱。字元 "*" 可以作為多個字元的萬用字元使用，而字元 "?" 可以用來作為單一字元的萬用字元。例如：'MY_DIR:*" 或 'MY_DIR:test?' 若要指定多個目錄，請使用以逗號分隔的目錄清單：例如：'MY_DIR1:*, MY_DIR2:test?' 使用雙引號來指定區分大小寫的目錄名稱。例如：'"my_dir1":*, "my_dir2":Test?' 若要包含引號字元，請使用兩個引號。例如：'MY_DIR:''filename.ext'。這會指定以引號 (') 為開頭的 filename。
schema_name	目標表格所在的綱要名稱。預設值為 NULL，表示目標表格與執行程序的使用者位於相同的綱要中。
field_list	在 Avro、ORC 或 Parquet 檔案中忽略。 來源中的欄位會依名稱比對外部表格資料欄。來源資料類型會轉換成外部表格資料欄資料類型。 若為 ORC 檔案，請參閱 DBMS_CLOUD Package ORC to Oracle Data Type Mapping 。 如需有關 Parquet 檔案的詳細資訊，請參閱 DBMS_CLOUD Package Parquet to Oracle Data Type Mapping 。 如需 Avro 檔案的詳細資訊，請參閱 DBMS_CLOUD Package Avro to Oracle Data Type Mapping 。
format	描述來源檔案格式的選項。對於 Avro、ORC 或 Parquet 檔案，只支援兩個選項：請參閱 DBMS_CLOUD Package Format Options for Avro、ORC 或 Parquet 。

使用注意事項

• 與其他資料檔一樣，Avro、ORC 和 Parquet 資料載入會產生可在 dba_load_operations 和 user_load_operations 表格中檢視的日誌。每個載入作業都會新增記錄至 dba[ user ]_load_operations，以指出包含日誌的表格。

  日誌表格提供載入的相關摘要資訊。

• 若為 Avro、ORC 或 Parquet，當 format 參數 type 設為值 avro、orc 或 parquet 時，BADFILE_TABLE 表格一律為空白。

  • 對於 Parquet 檔案，PRIMARY KEY 限制條件錯誤會發出 ORA 錯誤。

  • 如果資料欄的資料發生轉換錯誤 (例如，目標資料欄的大小不足以保留轉換的值)，則資料欄的值會設為 NULL。這不會產生被拒絕的記錄。

COPY_OBJECT 程序

此程序會將一個雲端物件儲存的儲存桶或資料夾的物件複製到另一個雲端物件儲存的儲存桶或資料夾。

來源和目標儲存桶或資料夾可以位於相同或不同的雲端物件存放區提供者中。

當來源和目標位於不同的物件存放區或具有相同雲端提供者的不同帳戶時，您可以為來源和目標位置提供個別的證明資料名稱。

未提供目標證明資料名稱時，目標位置預設也會使用來源證明資料名稱。

語法

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

參數

Parameter - 參數	描述
source_credential_name	用以存取來源雲端物件儲存的證明資料名稱。 如果未提供 source_credential_name 值，則 credential_name 會設為 NULL。
source_object_uri	指定指向來源物件儲存的儲存桶或資料夾位置的 URI。 此參數為必要參數。 URI 的格式取決於雲端物件儲存服務。如需詳細資訊，請參閱雲端物件儲存 URI 格式。
target_object_uri	指定目標「物件存放區」的 URI。 此參數為必要參數。 URI 的格式取決於雲端物件儲存服務。如需詳細資訊，請參閱雲端物件儲存 URI 格式。
target_credential_name	用以存取目標雲端物件儲存位置的證明資料名稱。 如果未提供 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;
/

CREATE_EXTERNAL_PART_TABLE 程序

此程序會在雲端的檔案或目錄中的檔案建立外部分割表格。這可讓您從自治式 AI 資料庫對外部資料執行查詢。

語法

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

參數

Parameter - 參數	描述
table_name	外部表格的名稱。
credential_name	存取雲端物件儲存的證明資料名稱。
partitioning_clause	指定完整的分割子句，包括個別分割區的位置資訊。 如果您使用 partitioning_clause 參數，則不允許使用 file_uri_list 參數。
file_uri_list	此參數指定以逗號分隔的來源檔案 URI 清單，或一或多個目錄與來源檔案。 雲端來源檔案 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 的格式取決於雲端物件儲存服務。如需詳細資訊，請參閱雲端物件儲存 URI 格式。 請參閱 Oracle Database 19c SQL Language Reference 或 Oracle Database 26ai SQL Language Reference 中的 REGEXP_LIKE Condition ，瞭解 REGEXP_LIKE 條件的詳細資訊。
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 子句相同。如需詳細資訊，請參閱 Oracle Database 19c Utilities 或 Oracle Database 26ai Utilities 中的 field_list 。
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 參數選項，請參閱雲端物件儲存 URI 格式。

使用注意事項

• 您無法同時使用 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 Object Storage
  • Azure Blob 儲存

  如需詳細資訊，請參閱雲端物件儲存 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 格式選項的相關資訊，請參閱雲端物件儲存 URI 格式。

• 您使用 DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE 建立的外部分割表格包含兩個不顯示的資料欄 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;
/

範例：使用儲存在 C3 物件儲存的儲存桶中的物件建立外部分割表格。

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_PART_TABLE(
     table_name => 'USAGE_EXTP',
     credential_name => 'OBJECT_STORAGE_CREDENTIAL',
     file_uri_list => 'https://objectstorage.mydomain.com/n/mytenancy/b/mybucket/o/usage-data/*usage-data*.parquet',
     format => json_object(
          'type' value 'parquet', 'schema' value 'first',
          'partition_columns' value json_array(
                json_object('name' value 'year', 'type' value 'number'),         
                json_object('name' value 'month', 'type' value 'number'),
                json_object('name' value 'day', 'type' value 'number')
          )
     )
   );
END;
/

CREATE_EXTERNAL_TABLE 程序

此程序會在雲端中的檔案或目錄中的檔案建立外部表格。這可讓您從自治式 AI 資料庫對外部資料執行查詢。

語法

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

參數

Parameter - 參數	描述
table_name	外部表格的名稱。
credential_name	存取雲端物件儲存的證明資料名稱。 當您指定含有 file_uri_list 的目錄或表格超連結 URL 時，不會使用此參數。
file_uri_list	此參數指定以逗號分隔的來源檔案 URI 清單，或一或多個目錄與來源檔案。 雲端來源檔案 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 的格式取決於您使用的雲端物件儲存服務，如需詳細資訊，請參閱雲端物件儲存 URI 格式。 請參閱 Oracle Database 19c SQL Language Reference 或 Oracle Database 26ai SQL Language Reference 中的 REGEXP_LIKE Condition ，瞭解 REGEXP_LIKE 條件的詳細資訊。 目錄 您可以指定一個目錄和一或多個檔案名稱，或是使用以逗號分隔的目錄和檔案名稱清單。指定目錄的格式為：'MY_DIR:filename.ext'。依照預設，目錄名稱 MY_DIR 是資料庫物件，不區分大小寫。檔案名稱有大小寫之別。 您可以使用萬用字元指定目錄中的檔案名稱。字元 "*" 可以作為多個字元的萬用字元使用，可以使用字元 "?" 作為單一字元的萬用字元。例如：'MY_DIR:*" 或 'MY_DIR:test?' 若要指定多個目錄，請使用以逗號分隔的目錄清單：例如：'MY_DIR1:*, MY_DIR2:test?' 使用雙引號來指定區分大小寫的目錄名稱。例如：'"my_dir1":*, "my_dir2":Test?' 若要包含引號字元，請使用兩個引號。例如：'MY_DIR:''filename.ext'。這會指定以引號 (') 為開頭的 filename。
column_list	外部表格的資料欄名稱和資料類型清單 (以逗號區隔)。
field_list	識別來源檔案中的欄位及其資料類型。預設值為 NULL，表示欄位及其資料類型是由 column_list 參數決定。此引數的語法與一般 Oracle Database 外部表格中的 field_list 子句相同。如需有關 field_list 的詳細資訊，請參閱 Oracle Database 19c Utilities 或 Oracle Database 26ai Utilities 中的 field_definitions 子句底下的 ORACLE_LOADER Access Driver field_list 。
format	描述來源檔案格式的選項。如需選項清單與如何指定值，請參閱格式參數。 若為 Avro、ORC 或 Parquet 格式檔案，請參閱 CREATE_EXTERNAL_TABLE Procedure for Avro、ORC 或 Parquet Files 。

使用注意事項

• DBMS_CLOUD.CREATE_EXTERNAL_TABLE 程序支援所支援雲端物件儲存服務 (包括 Azure Blob 儲存體) 中的外部分割檔案。

  證明資料是表格層次特性；因此，外部檔案必須位於相同的物件存放區。

  如需詳細資訊，請參閱雲端物件儲存 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 格式選項的相關資訊。

範例

範例：從物件儲存中的 CSV 檔案建立外部表格。

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

範例：使用儲存在 C3 物件儲存的儲存桶中的物件建立外部表格。

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
     table_name =>'CHANNELS_EXT',
     credential_name =>'OBJECT_STORAGE_CREDENTIAL',
     file_uri_list => '<https://objectstorage.mydomain.com/n/mytenancy/b/mybucket/o/channels.txt>',
     format => json_object('delimiter' value ','),
     column_list => 'CHANNEL_ID NUMBER, CHANNEL_DESC VARCHAR2(20), CHANNEL_CLASS VARCHAR2(20)'
  );
END;
/

Apache Iceberg 的 CREATE_EXTERNAL_TABLE 程序

此程序會為所支援組態中的 Apache Iceberg 表格建立外部表格。

支援下列特定組態：

• AWS 的 Iceberg 表格：

  • 在 AWS Glue Data Catalog 註冊的 Iceberg 表格，使用 Spark 或 Athena 建立。

    如需詳細資訊，請參閱使用 AWS Glue 連接器來讀取和寫入含有 ACID 交易的 Apache Iceberg 表格，並執行時間旅行和使用 Iceberg 表格。

  • 透過直接提供根中繼資料檔案的 URL，儲存在 AWS S3 上的 Iceberg 表格。

• OCI 上的 Iceberg 表格：

  • 使用 Hadoop 目錄使用 OCI 資料流程產生的 Iceberg 表格。

    如需詳細資訊，請參閱 Oracle 資料流程範例和使用 Hadoop 目錄。

  • 透過直接提供根中繼資料檔案的 URL，儲存在 OCI Object Storage 中的 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
);

參數

Parameter - 參數	描述
table_name	外部表格的名稱。
credential_name	用來存取資料檔、中繼資料檔案及 Iceberg 目錄 (如有使用) 的憑證名稱。 若為 AWS 和 OCI 組態，應依 CREATE_CREDENTIAL 程序中所述建立證明資料。 目前不支援 AWS Amazon 資源名稱 (ARN) 證明資料。
file_uri_list	如果指定 Iceberg 目錄，則必須為 NULL (請參閱下面的 format 參數)。如果未使用 iceberg 目錄，則 file_uri_list 必須包含 iceberg 中繼資料檔案的 URI。
column_list	因為欄位名稱與型態會自動衍生自 Iceberg 中繼資料，所以必須為 NULL。 資料欄名稱與基礎資料檔 (Parquet、Avro、ORC) 中找到的名稱相符。Oracle 資料類型是使用 Iceberg 和 Parquet、Avro 和 ORC 資料類型之間的 Parquet/Avro/ORC 對應所衍生。因此使用者無法指定 column_list。
field_list	必須是空值，因為欄名稱和資料類型是自動從 Iceberg 中繼資料衍生而來。
format	format 參數的結構不同，取決於 Iceberg 表格的類型，以及用來建立外部表格的資訊，例如來自資料目錄或直接中繼資料 URI 的資訊。 如需詳細資訊，請參閱 Iceberg Support on OCI Data Flow Samples 和 DBMS_CLOUD URI Formats 。

範例格式參數

• 使用 AWS Glue Catalog 透過 AWS Iceberg 表格建立表格時如下所示：

  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 參數包含具有下列兩個元素的 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 路徑。

• 透過 AWS Iceberg 表格使用中繼資料檔案 URI 建立表格時，如下所示：

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

• 透過 OCI Data Flow 使用 HadoopCatalog 目錄建立的 OCI Iceberg 表格建立表格時，如下所示：

  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 參數包含具有下列兩個元素的 JSON 物件：

  • protocol_type：必須是 'iceberg'
  • protocol_config：指定 iceberg 目錄詳細資訊的巢狀 JSON 物件。
    • iceberg_catalog_type：必須是 'hadoop'
    • iceberg_warehouse：以原生 URI 格式產生表格時所使用的倉儲目錄路徑。
    • iceberg_table_path：建立表格時使用的 database_name.table name 路徑。

• 在 OCI Iceberg 表格上使用中繼資料檔案的 URI 建立表格時，如下所示：

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

  其中 access_protocol 參數包含含有一個元素的 JSON 物件，protocol_type 必須是 'iceberg'。

Avro、ORC 或 Parquet 檔案的 CREATE_EXTERNAL_TABLE 程序

此程序的 format 參數 type 設為值 avro、orc 或 parquet，會在雲端或目錄中建立含有 Avro、ORC 或 Parquet 格式檔案的外部表格。

這可讓您從自治式 AI 資料庫對外部資料執行查詢。

語法

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

參數

Parameter - 參數	描述
table_name	外部表格的名稱。
credential_name	存取雲端物件儲存的證明資料名稱。 當您使用 file_uri_list 指定目錄時，不會使用此參數。
file_uri_list	此參數指定以逗號分隔的來源檔案 URI 清單，或一或多個目錄與來源檔案。 雲端來源檔案 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 的格式取決於您使用的雲端物件儲存服務，如需詳細資訊，請參閱雲端物件儲存 URI 格式。 請參閱 Oracle Database 19c SQL Language Reference 或 Oracle Database 26ai SQL Language Reference 中的 REGEXP_LIKE Condition ，瞭解 REGEXP_LIKE 條件的詳細資訊。 目錄 您可以指定一個目錄和一或多個檔案名稱，或是使用以逗號分隔的目錄和檔案名稱清單。指定目錄的格式為：'MY_DIR:filename.ext'。依照預設，目錄名稱 MY_DIR 是資料庫物件，不區分大小寫。檔案名稱有大小寫之別。 您可以使用萬用字元指定目錄中的檔案名稱。字元 "*" 可以作為多個字元的萬用字元使用，可以使用字元 "?" 作為單一字元的萬用字元。例如：'MY_DIR:*" 或 'MY_DIR:test?' 若要指定多個目錄，請使用以逗號分隔的目錄清單：例如：'MY_DIR1:*, MY_DIR2:test?' 使用雙引號來指定區分大小寫的目錄名稱。例如：'"my_dir1":*, "my_dir2":Test?' 若要包含引號字元，請使用兩個引號。例如：'MY_DIR:''filename.ext'。這會指定以引號 (') 為開頭的 filename。
column_list	(選擇性) 指定此欄位時，會覆寫指定自動衍生綱要、資料欄和資料類型的 format->schema 參數。請參閱格式參數瞭解詳細資訊。 為 Avro、ORC 或 Parquet 來源指定 column_list 時，資料欄名稱必須與檔案中找到的資料欄相符。Oracle 資料類型必須適當地對應至 Avro、ORC 或 Parquet 資料類型。 如需 Parquet 檔案的詳細資訊，請參閱 DBMS_CLOUD Package Parquet to Oracle Data Type Mapping 。 如需 ORC 檔案的詳細資訊，請參閱 DBMS_CLOUD Package ORC to Oracle Data Type Mapping 。 若為 Avro 檔案，請參閱 DBMS_CLOUD Package Avro to Oracle Data Type Mapping 瞭解詳細資訊。
field_list	在 Avro、ORC 或 Parquet 檔案中忽略。 來源中的欄位會依名稱比對外部表格資料欄。來源資料類型會轉換成外部表格資料欄資料類型。 若為 ORC 檔案，請參閱 DBMS_CLOUD Package ORC to Oracle Data Type Mapping 如需 Parquet 檔案的詳細資訊，請參閱 DBMS_CLOUD Package Parquet to Oracle Data Type Mapping 。 若為 Avro 檔案，請參閱 DBMS_CLOUD Package Avro to Oracle Data Type Mapping 瞭解詳細資訊。
format	若為 Avro、ORC 或 Parquet type 來源檔案，請參閱 DBMS_CLOUD Package Format Options for Avro、ORC 或 Parquet 以瞭解詳細資訊。

範例

• ORC

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

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

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

秘訣：請參閱 DBMS_CLOUD Package Avro、ORC 和 Parquet to Oracle Column Name Mapping ，瞭解 Oracle SQL 中的資料欄名稱對應和資料欄名稱轉換用法。

CREATE_EXTERNAL_TEXT_INDEX 程序

此程序會在物件儲存檔案上建立文字索引。

CREATE_EXTERNAL_TEXT_INDEX 程序會在 location_uri 位置指定的物件儲存檔案上建立文字索引。對於在位置 URI 上使用檔案進行的任何新增或刪除，會定期重新整理索引。

語法

DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
      credential_name  IN  VARCHAR2 DEFAULT NULL,
      location_uri     IN  VARCHAR2,
      index_name       IN  VARCHAR2,
      format           IN  CLOB     DEFAULT NULL
);

參數

Parameter - 參數	描述
credential_name	用以存取雲端物件儲存位置的證明資料名稱。對於公用、預先認證或預先簽署的儲存桶 URI，可以指定 NULL。 如果未提供 credential_name 值，則 credential_name 會設為 NULL 值。
location_uri	此參數指定以逗號分隔的來源檔案 URI 清單。 您可以在雲端來源檔案 URI 的檔案名稱中使用萬用字元以及正規表示式。 此參數為必要參數。 雲端來源檔案 URI 此參數指定以逗號分隔的來源檔案 URI 清單，或一或多個目錄與來源檔案。 只有在 regexuri format 參數設為 TRUE 時，才能使用正規表示式。 當 regexuri 參數設為 FALSE 時，字元 "*" 和 "?" 會被視為萬用字元。當 regexuri 參數設為 TRUE 時，字元 "*" 與 "?" 為指定之正規表示式樣式的一部分。 只有您 URI 中的檔案名稱或子資料夾路徑才支援正規表示式樣式，而且樣式比對與 REGEXP_LIKE 函數所執行的樣式相同。 使用一般運算式的範例： location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o(/)*year=[0-9]+(/)*month=[0-9]+(/)*[a-z]+[1-3]??.csv' 使用萬用字元的範例： location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv URI 的格式取決於您使用的雲端物件儲存服務，如需詳細資訊，請參閱雲端物件儲存 URI 格式。 如需 REGEXP_LIKE 條件的詳細資訊，請參閱 REGEXP_LIKE 條件。
index_name	指定您要在 `location_uri` 位置的檔案上建立的索引名稱。 此參數為必要參數。
format	指定其他組態選項。選項被指定為 JSON 字串。 支援的格式選項為： refresh_rate：指定重新整理區域索引的頻率 (分鐘)。新的檔案上傳和刪除會導致索引重新整理。預設值為 5 分鐘。 binary_files：指定要編製索引的檔案內容是否為二進位檔案。例如，PDF、MS-Word、預設值為 FALSE。 stop_words：指定建立索引時可以提供的停止字清單。 stop_words 值會指出其是否為停止字詞清單或停止字詞表格。提供 JSON 陣列時，會將 stop word 參數視為清單，否則會將 stop word 參數視為表格名稱，其資料欄 "STOP_WORDS" 會被用來讀取 stop word 清單中。 您可以使用下列方法指定停用字： JSON 陣列：例如：format := '{"stop_words":["king","queen"]}' 停止文字表格名稱：例如：format := '{"stop_words":"STOP_WORDS_TABLE"}' 如果您未提供 format 參數，則 format 會設為 NULL 值。

範例

BEGIN
DBMS_CLOUD.CREATE_EXTERNAL_TEXT_INDEX (
        credential_name => 'DEFAULT_CREDENTIAL',
        location_uri    => 'https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace-string/b/bucketname/o/ts_data/'
        index_name      => 'EMP',
        format          => JSON_OBJECT ('refresh_rate' value 10)
);
END;
/

CREATE_HYBRID_PART_TABLE 程序

此程序會建立混合分割表格。這可讓您使用雲端中的資料庫物件和檔案，或目錄中的資料庫物件和檔案，對自主 AI 資料庫的混合分割資料執行查詢。

語法

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

參數

Parameter - 參數	描述
table_name	外部表格的名稱。
credential_name	存取雲端物件儲存的證明資料名稱。
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''),... 請參閱 Oracle Database 19c SQL Language Reference 或 Oracle Database 26ai SQL Language Reference 中的 REGEXP_LIKE Condition ，瞭解 REGEXP_LIKE 條件的詳細資訊。
column_list	外部表格的資料欄名稱和資料類型清單 (以逗號區隔)。
field_list	識別來源檔案中的欄位及其資料類型。預設值為 NULL，表示欄位及其資料類型由 column_list 參數決定。此引數的語法與一般 Oracle 外部表格中的 field_list 子句相同。如需詳細資訊，請參閱 Oracle Database 19c Utilities 或 Oracle Database 26ai Utilities 中的 field_list 。
format	描述來源檔案格式的選項。如需選項清單與如何指定值，請參閱格式參數。

使用注意事項

• DBMS_CLOUD.CREATE_HYBRID_PART_TABLE 程序支援所支援雲端物件儲存服務 (包括 Azure Blob 儲存體) 中的外部分割檔案。

  證明資料是表格層次特性；因此，外部檔案必須位於相同的物件存放區。

  如需詳細資訊，請參閱雲端物件儲存 URI 格式。

• DBMS_CLOUD.CREATE_HYBRID_PART_TABLE 程序支援目錄中 (位於本機檔案系統或網路檔案系統中) 的混合分割檔案。

• 您使用 DBMS_CLOUD.CREATE_HYBRID_PART_TABLE 建立的外部分割表格包含兩個不顯示的資料欄 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;
/

DELETE_ALL_OPERATIONS 程序

此程序會清除綱要中 user_load_operations 表格中記錄的所有資料載入作業，或清除指定類型的所有資料載入作業 (如 type 參數所示)。

語法

DBMS_CLOUD.DELETE_ALL_OPERATIONS (
	type      IN VARCHAR DEFAULT NULL);

參數

Parameter - 參數	描述
type	指定要刪除的作業類型。您可以在 user_load_operations 表格的 TYPE 資料欄中找到類型值。 如果未指定 type，則會刪除所有資料列。

用途注意事項

DBMS_CLOUD.DELETE_ALL_OPERATIONS 不會刪除目前執行中的作業 (狀態為「執行中」的作業)。

DeleteE_FILE 程序

此程序會從「自治式 AI 資料庫」的指定目錄中移除指定的檔案。

語法

DBMS_CLOUD.DELETE_FILE (
      directory_name     IN VARCHAR2,
      file_name          IN VARCHAR2,
      force              IN BOOLEAN DEFAULT FALSE);

參數

Parameter - 參數	描述
directory_name	自治式 AI 資料庫執行處理上目錄的名稱。
file_name	要移除的檔案名稱。
force	如果檔案不存在，請忽略並不要報告錯誤。有效值為：TRUE 和 FALSE。預設值為 FALSE。

注意：若要以 ADMIN 以外的使用者執行 DBMS_CLOUD.DELETE_FILE，您必須將包含該檔案的目錄寫入權限授與該使用者。例如，以 ADMIN 身分執行下列命令，將寫入權限授與 atpc_user：

GRANT WRITE ON DIRECTORY data_pump_dir TO atpc_user;

範例

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

DELETE_OBJECT 程序

此程序會刪除物件存放區上的指定物件。

語法

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

參數

Parameter - 參數	描述
credential_name	存取雲端物件儲存的證明資料名稱。
object_uri	要刪除之物件的物件或檔案 URI。URI 的格式視您使用的雲端物件儲存服務而定，如需詳細資訊，請參閱雲端物件儲存 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;
/

DELETE_OPERATION 程序

此程序會清除您綱要中 user_load_operations 或 dba_load_operations 表格中所記錄之指定作業 ID 的資料載入項目。

語法

DBMS_CLOUD.DELETE_OPERATION (
	id      IN NUMBER);

參數

Parameter - 參數	描述
id	指定與您要刪除之日誌檔項目關聯的作業 ID。

範例

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

DROP_EXTERNAL_TEXT_INDEX 程序

此程序會刪除物件儲存檔案的文字索引。

DROP_EXTERNAL_TEXT_INDEX 程序會刪除使用 CREATE_EXTERNAL_TEXT_INDEX 程序建立的指定索引。

語法

DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
      index_name       IN  VARCHAR2,
);

參數

Parameter - 參數	描述
index_name	指定要刪除之索引的名稱。 索引名稱必須與建立索引時提供的名稱相符。 此參數為必要參數。

範例

BEGIN
DBMS_CLOUD.DROP_EXTERNAL_TEXT_INDEX (
        index_name => 'EMP',
);
END;
/

匯出資料程序

此程序會根據查詢的結果，從自治式 AI 資料庫匯出資料。此程序已超載，並支援將檔案寫入雲端或目錄。

根據 format type 參數，程序會以 CSV、JSON、Parquet 或 XML 格式的文字檔將檔案匯出至雲端或目錄位置。

語法

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

參數

Parameter - 參數	描述
credential_name	存取雲端物件儲存的證明資料名稱。 若未包含證明資料參數，這會指定目錄的輸出。
file_uri_list	視格式參數的值以及是否包含證明資料參數而定，會有不同的表單： 當 format 參數 type 值為 json 時：物件存放區上的 JSON 或指定的目錄位置會根據 file_uri_list 參數的值，以產生的檔案名稱儲存。如需詳細資訊，請參閱文字輸出的檔案命名 (CSV、JSON、Parquet 或 XML) 。 當 format 參數 type 值為 datapump 時，file_uri_list 是以逗號分隔的傾印檔案清單。這會指定要在物件存放區上建立的檔案。file_uri_list 中不支援使用萬用字元和替代字元。 若未指定 credential_name 參數，請在 file_uri_list 中提供目錄名稱。 URI 的格式取決於您使用的雲端物件儲存服務，如需詳細資訊，請參閱雲端物件儲存 URI 格式。
format	提供匯出格式選項的 JSON 字串。 支援的選項為： type：type format 選項為必要選項，且必須具有下列其中一個值：csv | datapump | json | parquet | xml。 請參閱 EXPORT_DATA 的 DBMS_CLOUD 套件格式選項。
query	您可以使用此參數指定 SELECT 敘述句，只匯出必要的資料。查詢決定匯出為文字檔 CSV、JSON、Parquet 或 XML 或傾印檔的檔案內容。舉例而言： SELECT warehouse_id, quantity FROM inventories 當 format type 值為 json 時，會檢查每個查詢結果，如果不是 JSON，則由以下函數決定：JSON_OBJECT_T.parse()，DBMS_CLOUD.EXPORT_DATA 會將查詢轉換為包含 JSON_OBJECT 函數，以便將資料列轉換為 JSON。See JSON_OBJECT in Oracle Database 19c SQL Language Reference or Oracle Database 26ai SQL Language Reference and JSON_OBJECT_T Object Type in Oracle Database 19c PL/SQL Packages and Types Reference or Oracle Database 26ai PL/SQL Packages and Types Reference for more information. 舉例而言： 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、Parquet 或 XML 檔案格式的目錄位置。

  請參閱使用 DBMS_CLOUD.EXPORT_DATA 將資料以文字形式匯出至物件存放區和使用 DBMS_CLOUD.EXPORT_DATA 將資料匯出至目錄，瞭解有關使用 DBMS_CLOUD.EXPORT_DATA 與 CSV、JSON、Parquet 或 XML 輸出檔案的詳細資訊。

• 對於 CSV、JSON 或 XML 輸出，當產生的檔案包含 10MB 的資料時，預設會建立新的輸出檔案。不過，如果結果資料少於 10MB，則可能會有多個輸出檔案，這取決於資料庫服務和自治式 AI 資料庫執行處理的 ECPU 數目 (若資料庫使用 OCPU，則為 OCPU)。

  如需詳細資訊，請參閱文字輸出的檔案命名 (CSV、JSON、Parquet 或 XML) 。

  CSV、JSON 或 XML 的預設輸出檔案區塊大小為 10MB。您可以使用 format 參數 maxfilesize 選項來變更這個值。請參閱 DBMS_CLOUD Package Format Options for EXPORT_DATA 以瞭解詳細資訊。

• 對於 CSV、JSON 或 XML 輸出，當產生的檔案包含 10MB 的資料時，預設會建立新的輸出檔案。不過，如果結果資料少於 10MB，則可能會有多個輸出檔案，這取決於資料庫服務和自治式 AI 資料庫執行處理的 ECPU 數目 (若資料庫使用 OCPU，則為 OCPU)。

  如需詳細資訊，請參閱文字輸出的檔案命名 (CSV、JSON、Parquet 或 XML) 。

• parquet 輸出格式只能與專用 Exadata 基礎架構上自治式 AI 資料庫的高中資料庫服務搭配使用。

`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

範例

範例：DBMS_CLOUD.EXPORT_DATA，其格式為 type 參數，值為 json。

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

範例：DBMS_CLOUD.EXPORT_DATA，其格式為 type 參數，值為 xml。

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

範例：DBMS_CLOUD.EXPORT_DATA，其格式為 type 參數，值為 csv。

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

GET_OBJECT 程序與功能

此程序已超載。程序表單會從 Cloud Object Storage 讀取物件，並將其複製到 Autonomous AI Database。函數表單會從 Cloud Object Storage 讀取物件，並將 BLOB 傳回至 Autonomous AI 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;

參數

Parameter - 參數	描述
credential_name	存取雲端物件儲存的證明資料名稱。
object_uri	物件或檔案 URI。URI 的格式視您使用的雲端物件儲存服務而定，如需詳細資訊，請參閱雲端物件儲存 URI 格式。
directory_name	資料庫上的目錄名稱。(請參閱下面的註腳 1)
file_name	指定要建立之檔案的名稱。如果未指定檔案名稱，則會從 object_uri 參數的最後一個斜線之後取得檔案名稱。例如，如果檔案名稱包含斜線，請使用 file_name 參數。
startoffset	程序開始讀取的偏移量 (位元組)。
endoffset	程序停止讀取的位移 (位元組)。
compression	指定用來儲存物件的壓縮。當 compression 設為 'AUTO' 時，檔案會解除壓縮 (值 'AUTO' 代表以 object_uri 指定的物件會以 Gzip 壓縮)。

Footnote 1

注意：若要以 ADMIN 以外的使用者執行 DBMS_CLOUD.GET_OBJECT，您必須將目錄的 WRITE 權限授與該使用者。例如，以 ADMIN 身分執行下列命令，將寫入權限授與 atpc_user：

GRANT WRITE ON DIRECTORY data_pump_dir TO atpc_user;

傳回值

函數表單會從物件存放區讀取，而 DBMS_CLOUD.GET_OBJECT 會傳回 BLOB。

範例

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

範例：從物件存放區中的檔案讀取字元資料。

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

範例：在資料庫的 BLOB 中新增儲存在物件存放區中的影像。

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

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

LIST_FILES 函數

此函數會列出指定目錄中的檔案。結果會包含檔案名稱和檔案的其他描述資料，例如檔案大小 (位元組)、建立時戳以及上次修改時戳。

語法

DBMS_CLOUD.LIST_FILES (
	directory_name      IN VARCHAR2)
       RETURN TABLE;

參數

Parameter - 參數	描述
directory_name	資料庫上的目錄名稱。此參數支援萬用字元。

使用注意事項

• 若要以 ADMIN 以外的使用者執行 DBMS_CLOUD.LIST_FILES，您必須將目錄的讀取權限授與該使用者。例如，以 ADMIN 身分執行下列命令，將讀取權限授與 atpc_user：

  GRANT READ ON DIRECTORY data_pump_dir TO atpc_user;
  

• 這是傳回類型為 DBMS_CLOUD_TYPES.list_object_ret_t 的管線表格函數。
• DBMS_CLOUD.LIST_FILES 未取得總和檢查值，並傳回此欄位的 NULL。
• DBMS_CLOUD.LIST_FILES 支援使用 directory:filename 語法選擇性地篩選檔案。檔案名稱中支援萬用字元。

範例

範例：使用下列查詢以使用 DBMS_CLOUD.LIST_FILES 作為管線函數，傳回每個檔案的資料列。

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

您也可以使用 DBMS_CLOUD.LIST_FILES 與 DIRECTORY:FILE 語法，方法是指定檔案或使用萬用字元。* 與 ？是支援的萬用字元。

範例：使用萬用字元列出目錄 DATA_PUMP_DIR 中以 "f" 開頭的所有 CSV 檔案。

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR:f*.csv');

範例：列出指定檔案名稱之 DATA_PUMP_DIR 目錄中的 f1.csv 檔案。

SELECT * FROM DBMS_CLOUD.LIST_FILES('DATA_PUMP_DIR:f1.csv');

LIST_OBJECTS 函數

此函數會列出物件存放區中指定位置的物件。結果會包含物件名稱，以及物件的其他描述資料，例如大小、總和檢查、建立時戳以及上次修改時戳。

語法

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

參數

Parameter - 參數	描述
credential_name	存取雲端物件儲存的證明資料名稱。
location_uri	物件儲存的儲存桶或資料夾 URI。URI 的格式取決於您使用的雲端物件儲存服務，如需詳細資訊，請參閱雲端物件儲存 URI 格式。 支援使用萬用字元，選擇性地列出 URI 中的檔案或子資料夾。字元 "*" 和 "?" 會被視為萬用字元。 使用萬用字元的範例： location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv'

使用注意事項

• 視物件存放區的功能而定，DBMS_CLOUD.LIST_OBJECTS 不會傳回特定屬性的值，而在此情況下，欄位的傳回值為 NULL。

  所有支援的「物件存放區」都會傳回 OBJECT_NAME、BYTES 和 CHECKSUM 欄位的值。下表顯示「物件存放區」對 CREATED 和 LAST_MODIFIED 欄位的支援：

  物件存放區	CREATED	LAST_MODIFIED
  Oracle Cloud Infrastructure 原生	傳回時戳	傳回時戳
  Oracle Cloud Infrastructure Swift	傳回 NULL	傳回時戳
  Amazon S3	傳回 NULL	傳回時戳
  Amazon S3 相容	傳回 NULL	傳回時戳
  Azure	傳回時戳	傳回時戳

• 總和檢查值為 MD5 總和檢查。這是物件內容上計算的 32 個字元十六進位數字。

• 這是傳回類型為 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

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

MOVE_OBJECT 程序

此程序會將物件從一個雲端物件儲存的儲存桶或資料夾移至另一個儲存桶。

來源和目標儲存桶或資料夾可以位於相同或不同的雲端物件存放區提供者中。

當來源和目標位於不同的物件存放區或具有相同雲端提供者的不同帳戶時，您可以為來源和目標位置提供個別的證明資料名稱。

未提供目標證明資料名稱時，目標位置預設也會使用來源證明資料名稱。

語法

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

參數

Parameter - 參數	描述
source_credential_name	用以存取來源雲端物件儲存的證明資料名稱。 如果未提供 source_credential_name 值，則 credential_name 會設為 NULL。
source_object_uri	指定指向來源物件儲存的儲存桶或資料夾位置的 URI。 此參數為必要參數。 URI 的格式取決於雲端物件儲存服務。如需詳細資訊，請參閱雲端物件儲存 URI 格式。
target_object_uri	指定需要移動檔案之目標物件儲存的儲存桶或資料夾的 URI。 此參數為必要參數。 URI 的格式取決於雲端物件儲存服務。如需詳細資訊，請參閱雲端物件儲存 URI 格式。
target_credential_name	用以存取目標雲端物件儲存位置的證明資料名稱。 如果未提供 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;
/

PUT_OBJECT 程序

此程序已超載。程序會以一種形式從自治式 AI 資料庫將檔案複製到雲端物件儲存。另一種形式，此程序會將 BLOB 從自治式 AI 資料庫複製到雲端物件儲存。

語法

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

參數

Parameter - 參數	描述
credential_name	存取雲端物件儲存的證明資料名稱。
object_uri	物件或檔案 URI。URI 的格式視您使用的雲端物件儲存服務而定，如需詳細資訊，請參閱雲端物件儲存 URI 格式。
directory_name	資料庫上的目錄名稱。(請參閱下面的註腳 1)
contents	指定要從自治式 AI 資料庫複製到雲端物件儲存的 BLOB。
file_name	指定目錄中的檔案名稱。
compression	指定用來儲存物件的壓縮。 預設值：NULL

Footnote 1

注意：若要以 ADMIN 以外的使用者執行 DBMS_CLOUD.PUT_OBJECT，您必須將目錄的讀取權限授與該使用者。例如，以 ADMIN 身分執行下列命令，將讀取權限授與 atpc_user：

GRANT READ ON DIRECTORY data_pump_dir TO atpc_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;
/

使用注意事項

視您的雲端物件儲存而定，您傳輸的物件大小限制如下：

雲端物件儲存服務 - 經濟實惠	物件傳輸大小限制
Oracle Cloud Infrastructure Object Storage	50 GB
Amazon S3	5 GB
Azure Blob 儲存	256 MB
Amazon S3 相容	由物件存放區提供者設定。如需詳細資訊，請參閱提供者的文件。

Oracle Cloud Infrastructure 物件存放區不允許在不提供證明資料的情況下，將檔案寫入公用儲存桶 (Oracle Cloud Infrastructure 允許使用者從公用儲存桶下載物件)。因此，您必須提供具備有效證明資料的證明資料名稱，才能使用 PUT_OBJECT 將物件儲存在 Oracle Cloud Infrastructure 公用儲存桶中。

如需詳細資訊，請參閱雲端物件儲存 URI 格式。

SYNC_EXTERNAL_PART_TABLE 程序

此程序可簡化從雲端檔案更新外部分割的表格。每當新增分割區，或從外部分割表格的「物件存放區」來源移除分割區時，執行此程序。

語法

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

參數

Parameter - 參數	描述
table_name	目標表格的名稱。您必須先建立目標表格，才能執行 DBMS_CLOUD.SYNC_EXTERNAL_PART_TABLE。
schema_name	目標表格所在的綱要名稱。預設值為 NULL，表示目標表格與執行程序的使用者位於相同的綱要中。
update_columns	新的檔案可能會對綱要產生變更。支援的更新包括：新資料欄、刪除的資料欄。對現有資料欄的更新，例如資料類型的變更發出錯誤。 預設值：False

VALIDATE_EXTERNAL_PART_TABLE 程序

此程序會驗證外部分割表格的來源檔案、產生日誌資訊，以及將不符合在「自治式 AI 資料庫」之錯誤檔案表格中為外部表格指定之格式選項的資料列儲存起來。超載表單可讓您使用 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);

參數

Parameter - 參數	描述
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 參數的值為止。

VALIDATE_EXTERNAL_TABLE 程序

此程序會驗證外部表格的來源檔案、產生日誌資訊，以及將不符合為外部表格指定之格式選項的資料列儲存在「自治式 AI 資料庫」的錯誤檔案表格中。超載表單可讓您使用 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);

參數

Parameter - 參數	描述
table_name	外部表格的名稱。
operation_id	使用此參數可追蹤載入作業的進度和最終狀態，作為 USER_LOAD_OPERATIONS 視觀表中對應的 ID。
schema_name	外部表格所在的綱要名稱。預設值為 NULL，表示外部表格與執行程序的使用者位於相同的綱要中。
rowcount	要掃描的資料列數目。預設值為 NULL，表示會掃描來源檔案中的所有資料列。
stop_on_error	決定當拒絕資料列時，是否應停止驗證。預設值為 TRUE，表示驗證會在第一個拒絕的資料列停止。將值設為 FALSE 時，會指定驗證不會在第一個拒絕的資料列停止，並驗證所有資料列，直到指定給 rowcount 參數的值為止。 如果外部表格參照 Avro、ORC 或 Parquet 檔案，則驗證會在第一個拒絕的資料列停止。 當外部表格指定 format 參數 type 設為值 avro、orc 或 parquet 時，參數 stop_on_error 的有效值一律為 TRUE。因此，對於參照 Avro、ORC 或 Parquet 檔案的外部表格，表格徽章檔案一律會是空的。

用途注意事項

DBMS_CLOUD.VALIDATE_EXTERNAL_TABLE 可同時使用分割的外部表格和混合分割的表格。這可能會從所有外部分割區讀取資料，直到達到 rowcount 或套用 stop_on_error 為止。您無法控制哪個分割區或部分分割區的讀取順序。

VALIDATE_HYBRID_PART_TABLE 程序

此程序會驗證混合分割表格的來源檔案、產生日誌資訊，以及在「自治式 AI 資料庫」的錯誤檔案表格中，儲存與為混合表格指定格式選項不相符的資料列。超載表單可讓您使用 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);

參數

Parameter - 參數	描述
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 參數的值為止。

相關內容

• 雲端物件儲存 URI 格式

• 格式化參數

• DBMS_CLOUD Avro、ORC 和 Parquet 支援