物件和檔案的 DBMS

必備條件

身為開發人員，您可以將 DBMS_CLOUD 程序與部署在 Oracle Public Cloud 、多重雲端或 Exadata Cloud@Customer 上的 Autonomous Database 搭配使用。

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

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

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

請依照 Oracle Cloud Infrastructure 文件中建立 NAT 閘道的指示，在 Autonomous Database 資源所在的虛擬雲端網路 (VCN) 中建立 NAT 閘道。
建立 NAT 閘道之後，請在 Autonomous Database 資源所在的每個子網路新增路由規則和傳出安全規則 (在 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 代理主機)。啟用之後，您就無法編輯這些設定值。

在 My Oracle Support 中設定已啟動設定之 Exadata 基礎架構的 HTTP 代理主機時，必須要有服務要求 (SR)。請參閱在 My Oracle Support 中建立服務要求瞭解詳細資訊。

物件和檔案的 DBMS_CLOUD 子程式

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

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

COPY_COLLECTION 程序

此程序會從雲端物件儲存或從目錄將資料載入至 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 中的 REGEXP_LIKE 條件或 Oracle Database 23ai SQL Language Reference ，瞭解 `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 資料格式之外，Autonomous Database 也支援其他格式。如需 Autonomous Database 支援的格式引數清單，請參閱格式參數。
`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;
/

COPY_DATA 程序

此程序會從雲端中的檔案或目錄中的檔案，將資料載入至現有的 Autonomous 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);

參數

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 中的 REGEXP_LIKE 條件或 Oracle Database 23ai SQL Language Reference ，瞭解 `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 23ai Utilities 中的 field_list 。當 `format` 參數 `type` 選項值為 `json` 時，將忽略此參數。如需使用 `field_list` 的範例，請參閱 CREATE_EXTERNAL_TABLE 程序。
`format`	描述來源格式、日誌和錯誤檔案的選項。如需選項清單及如何指定值，請參閱格式參數。如需 Avro、ORC 或 Parquet 檔案格式選項，請參閱 DBMS_CLOUD Avro、ORC 或 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        => '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;
/

COPY_DATA Avro、ORC 或 Parquet 檔案的程序

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

與文字檔類似，資料會從來源 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 中的 REGEXP_LIKE 條件或 Oracle Database 23ai SQL Language Reference ，瞭解 `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 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 程序

此程序會對雲端中的檔案或目錄中的檔案建立外部分割表格。這可讓您對來自 Autonomous 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);

參數

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 中的 REGEXP_LIKE 條件或 Oracle Database 23ai SQL Language Reference ，瞭解 `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 23ai 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)"}]'` 如果資料檔為非結構化且 `partition_columns` 指定了 `type` 子子句，則會忽略 `type` 子句。對於不是以 hive 格式為基礎的物件名稱，`partition_columns` 指定之資料欄的順序必須與在 `file_uri_list` 參數中指定之檔案路徑的物件名稱中顯示的順序相同。若要查看描述來源檔案格式的所有 `format` 參數選項，請參閱雲端物件儲存 URI 格式。

使用注意事項

您無法同時使用 partitioning_clause 和 file_uri_list 參數呼叫此程序。
指定 column_list 參數是結構化資料檔 (包括 Avro、Parquet 或 ORC 資料檔) 的選擇性參數。如果未指定 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"。在此情況下，您必須修改來源檔案以使用相同的記錄分隔符號，或僅指定使用相同記錄分隔符號的來源檔案。

請參閱雲端物件儲存 URI 格式，瞭解 recorddelmiter 格式選項的相關資訊。
您以 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;
/

CREATE_EXTERNAL_TABLE 程序

此程序會對雲端中的檔案或目錄中的檔案建立外部表格。這可讓您對來自 Autonomous Database 的外部資料執行查詢。

語法

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

參數

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 中的 REGEXP_LIKE 條件或 Oracle Database 23ai SQL Language Reference ，瞭解 `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 23ai Utilities 中的 field_definitions 子句底下的 ORACLE_LOADER 存取驅動程式 field_list。
`format`	描述來源檔案格式的選項。如需選項清單及如何指定值，請參閱格式參數。如需 Avro、ORC 或 Parquet 格式檔案，請參閱 CREATE_EXTERNAL_TABLE Avro、ORC 或 Parquet 檔案的程序。

使用注意事項

程序 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 格式選項的相關資訊，請參閱格式參數。

範例

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

CREATE_EXTERNAL_TABLE Avro、ORC 或 Parquet 檔案的程序

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

這可讓您對來自 Autonomous 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);

參數

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 中的 REGEXP_LIKE 條件或 Oracle Database 23ai SQL Language Reference ，瞭解 `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 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')

Avro、ORC 或 Parquet 資料欄名稱對應至 Oracle 資料欄名稱

請參閱 DBMS_CLOUD Package Avro，ORC，and 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 的格式取決於雲端物件儲存體服務。如需詳細資訊，請參閱 DBMS_CLOUD Package File Cloud Object Storage URI Formats 。
`index_name`	指定要在位於 `location_uri` 位置之檔案上建立的索引名稱。此為必要參數。
`format`	指定其他組態選項。選項會指定為 JSON 字串。支援的格式選項包括： `refresh_rate`：指定重新整理區域索引的頻率 (分鐘)。新的檔案上傳與刪除會導致索引重新整理。預設值為 5 分鐘。 `binary_files`：指定要編製索引之檔案的內容是否為二進位檔案。例如，PDF、MS-Word，預設值為 `FALSE`。 `stop_words`：指定當您建立索引時，可以提供停止字詞清單。 `stop_words` 值表示它是停止字詞清單或停止字詞表格。提供 JSON 陣列時，會將停用字參數視為清單，否則停用字參數會被視為表格名稱，其資料欄 "`STOP_WORDS`" 會用於讀取停用字清單。您可以使用下列方法指定停用字： 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 程序

此程序會建立混合分割表格。這可讓您使用雲端中的資料庫物件和檔案，或目錄中的資料庫物件和檔案，對來自 Autonomous 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);

參數

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 中的 REGEXP_LIKE 條件或 Oracle Database 23ai SQL Language Reference ，瞭解 `REGEXP_LIKE` 條件的詳細資訊。
`column_list`	外部表格之資料欄名稱和資料類型的逗號分隔清單。
`field_list`	識別來源檔案中的欄位及其資料類型。預設值為 NULL，表示欄位及其資料類型是由 column_list 參數所決定。此引數的語法與一般 Oracle 外部表格中的 `field_list` 子句相同。如需詳細資訊，請參閱 Oracle Database 19c Utilities 或 Oracle Database 23ai 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 - 參數描述

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

type

指定要刪除的作業類型。您可以在 user_load_operations 表格的 TYPE 資料欄中找到類型值。

如果未指定 type，則會刪除所有資料列。

使用備註

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

DELETE_FILE 程序

此程序會從 Autonomous Database 上指定的目錄移除指定的檔案。

語法

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

參數

Parameter - 參數	描述
`directory_name`	Autonomous Database 執行處理的目錄名稱。
`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 - 參數描述

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

index_name

指定要刪除的索引名稱。

索引名稱必須與建立索引時提供的名稱相符。

此為必要參數。

範例

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

EXPORT_DATA 程序

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

根據 format type 參數，程序會將檔案匯出至 Cloud 或目錄位置，作為 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。請參閱 Oracle Database 19c SQL Language Reference 中的 JSON_OBJECT 或 Oracle Database 23ai SQL Language Reference 中的 JSON_OBJECT_T Object Type ，以及 Oracle Database 19c PL/SQL Packages and Types Reference 或 Oracle Database 23ai PL/SQL Packages and Types Reference ，瞭解詳細資訊。舉例而言： `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，您可能會有多個輸出檔案，視資料庫服務和 Autonomous Database 執行處理的 ECPU 數目而定 (如果您的資料庫使用 OCPU，則為 OCPU)。

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

CSV、JSON 或 XML 的預設輸出檔案區塊大小為 10MB。您可以使用 format 參數 maxfilesize 選項來變更此值。如需詳細資訊，請參閱 EXPORT_DATA 的 DBMS_CLOUD 套件格式選項。
對於 Parquet 輸出，每個產生的檔案小於 128MB，可能會產生多個輸出檔案。不過，如果結果資料少於 128MB，則視資料庫服務和 Autonomous Database 執行處理的 ECPU 數目而定，您可能會有多個輸出檔案 (如果資料庫使用 OCPU，則為 OCPU)。

如需詳細資訊，請參閱文字輸出的檔案命名 (CSV、JSON、Parquet 或 XML) 。
parquet 輸出格式只能與專用 Exadata 基礎架構上 Autonomous Database 的中高資料庫服務搭配使用。

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 Database 。此函數表單會從雲端物件儲存讀取物件，並將 BLOB 傳回至 Autonomous 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 是儲存桶名稱。請參閱瞭解 Object Storage 命名空間瞭解詳細資訊。

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。

範例

這是一個管線函數，會傳回每個檔案的列。例如，使用下列查詢來使用此函數：

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

LIST_OBJECTS 函數

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

語法

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

參數

Parameter - 參數	描述
`credential_name`	存取雲端物件儲存的證明資料名稱。
`location_uri`	物件或檔案 URI。URI 的格式取決於您使用的雲端物件儲存體服務，如需詳細資訊，請參閱雲端物件儲存體 URI 格式。

使用注意事項

視物件存放區的功能而定，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 是儲存桶名稱。請參閱瞭解 Object Storage 命名空間瞭解詳細資訊。

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 的格式取決於雲端物件儲存體服務。如需詳細資訊，請參閱雲端物件儲存 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 程序

此程序已超載。其中一種方式就是將檔案從 Autonomous Database 複製到雲端物件儲存。另一方面，該程序會將 BLOB 從 Autonomous Database 複製到雲端物件儲存。

語法

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`	Autonomous Database 上目錄的名稱。 ^{註腳 1}
`contents`	指定要從 Autonomous Database 複製到雲端物件儲存的 `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 - 參數描述

Parameter - 參數	描述
`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

VALIDATE_EXTERNAL_PART_TABLE 程序

此程序會驗證外部分割表格的來源檔案、產生日誌資訊，並將不符合為外部表格指定之格式選項的資料列儲存在 Autonomous 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);

參數

Parameter - 參數	描述
`table_name`	外部表格的名稱。
`operation_id`	使用此參數來追蹤載入作業的進度和最終狀態，作為 `USER_LOAD_OPERATIONS` 視觀表中的對應 ID。
`partition_name`	如果已定義，則只會驗證特定分割區。如果未指定，請依序讀取所有分割區，直到達到 `rowcount` 為止。
`subpartition_name`	如果已定義，則只會驗證特定子分割區。若未指定，請依序讀取所有外部分割區或子分割區，直到達到 `rowcount` 為止。
`schema_name`	外部表格所在的綱要名稱。預設值為空值，表示外部表格與執行程序的使用者位於相同的綱要中。
`rowcount`	要掃描的資料列數目。預設值為 NULL，表示已掃描來源檔案中的所有資料列。
`partition_key_validation`	僅供內部使用。請勿使用此參數。
`stop_on_error`	決定當資料列被拒絕時是否應停止驗證。預設值為 `TRUE`，表示驗證會在第一個拒絕的資料列停止。將值設為 `FALSE` 時，會指定驗證不會在第一個拒絕的資料列停止，並驗證直到為 `rowcount` 參數指定之值為止的所有資料列。

VALIDATE_EXTERNAL_TABLE 程序

此程序會驗證外部表格的來源檔案、產生日誌資訊，並將不符合為外部表格指定之格式選項的資料列儲存在 Autonomous 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);

參數

Parameter - 參數	描述
`table_name`	外部表格的名稱。
`operation_id`	使用此參數來追蹤載入作業的進度和最終狀態，作為 `USER_LOAD_OPERATIONS` 視觀表中的對應 ID。
`schema_name`	外部表格所在的綱要名稱。預設值為空值，表示外部表格與執行程序的使用者位於相同的綱要中。
`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 程序

此程序會驗證混合分割表格的來源檔案、產生日誌資訊，並將不符合為混合表格指定之格式選項的資料列儲存在 Autonomous 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);

參數

Parameter - 參數	描述
`table_name`	外部表格的名稱。
`operation_id`	使用此參數來追蹤載入作業的進度和最終狀態，作為 `USER_LOAD_OPERATIONS` 視觀表中的對應 ID。
`partition_name`	如果已定義，則只會驗證特定分割區。如果未指定，請依序讀取所有外部分割區，直到達到 `rowcount` 為止。
`subpartition_name`	如果已定義，則只會驗證特定子分割區。若未指定，請依序讀取所有外部分割區或子分割區，直到達到 `rowcount` 為止。
`schema_name`	外部表格所在的綱要名稱。預設值為空值，表示外部表格與執行程序的使用者位於相同的綱要中。
`rowcount`	要掃描的資料列數目。預設值為 NULL，表示已掃描來源檔案中的所有資料列。
`partition_key_validation`	僅供內部使用。請勿使用此參數。
`stop_on_error`	決定當資料列被拒絕時是否應停止驗證。預設值為 `TRUE`，表示驗證會在第一個拒絕的資料列停止。將值設為 `FALSE` 時，會指定驗證不會在第一個拒絕的資料列停止，並驗證直到為 `rowcount` 參數指定之值為止的所有資料列。