DBMS_DCAT 子程式摘要

此表格列出用來建立、查詢及刪除「資料目錄」連線的 DBMS_DCAT 套裝程式程序。

子程式	描述
SET_DATA_CATALOG_CREDENTIAL 程序	設定資料目錄特定連線所使用的資料目錄存取證明資料
SET_OBJECT_STORE_CREDENTIAL 程序	設定指定唯一連線 ID 所使用的證明資料，以存取物件存放區
SET_DATA_CATALOG_CONN 程序	建立指定資料目錄的連線
UNSET_DATA_CATALOG_CONN 程序	移除現有的資料目錄連線

SET_DATA_CATALOG_CREDENTIAL 程序

此程序會設定「資料目錄」特定連線所使用的「資料目錄」存取證明資料。

語法

PROCEDURE DBMS_DCAT.SET_DATA_CATALOG_CREDENTIAL(
    credential_name VARCHAR2(128) DEFAULT NULL,
    dcat_con_id     VARCHAR2 DEFAULT NULL
  );

參數

Parameter - 參數	描述
credential_name	用於存取「資料目錄」的證明資料。
dcat_con_id	唯一的資料目錄連線 ID。此證明資料用於 dcat_con_id 所識別的連線。預設值為 Null。

此證明資料必須具備「管理資料目錄」權限，請參閱資料目錄原則。

SET_OBJECT_STORE_CREDENTIAL 程序

此程序會設定指定唯一連線 ID 用於存取「物件存放區」的證明資料。若變更「物件存放區」存取證明資料，會變更所有現有的同步表格以使用新的證明資料。

語法

PROCEDURE DBMS_DCAT.SET_OBJECT_STORE_CREDENTIAL(
    credential_name  VARCHAR2(128),
    dcat_con_id      IN VARCHAR2 DEFAULT NULL
  );

參數

Parameter - 參數	描述
credential_name	外部表格用來存取「物件存放區」的證明資料。
dcat_con_id	唯一的資料目錄連線 ID。預設值為 NULL。

SET_DATA_CATALOG_CONN 程序

此程序會建立指定之「資料目錄」的連線。必須要有連線，才能將描述資料與「資料目錄」同步。自治式 AI 資料庫執行處理可以連線至多個資料目錄執行處理，並支援連線至 OCI 資料目錄和 AWS Glue 資料目錄。

語法

PROCEDURE DBMS_DCAT.SET_DATA_CATALOG_CONN (
   region         VARCHAR2 DEFAULT NULL,
   endpoint       VARCHAR2 DEFAULT NULL,
   catalog_id     VARCHAR2 DEFAULT NULL,
   dcat_con_id    VARCHAR2 DEFAULT NULL,
   catalog_type   VARCHAR2 DEFAULT NULL,
   token_endpoint VARCHAR2 DEFAULT Null
 );

參數

Parameter - 參數	描述
region	「資料目錄」區域。如果已指定 endpoint，則 region 為選擇性。如果同時提供 endpoint 和 region，則會優先使用 endpoint。預設值為 NULL。
endpoint	資料目錄端點。如果已指定 region，則 endpoint 為選擇性。如果同時提供 endpoint 和 region，則會優先使用 endpoint。預設值為 NULL。
catalog_id	資料目錄執行處理的唯一 Oracle Cloud ID (OCID)。連線至 AWS Glue Data Catalogs 時，catalog_id 為選擇性項目。
dcat_con_id	唯一的資料目錄連線 ID。連線至多個資料目錄時必須要有此 ID，若只連線到一個資料目錄，則為選擇性 ID。它用於在後續呼叫或查詢檢視時，參照「資料目錄」連線。如果未指定 ID，此程序會產生 NULL 連線 ID。適用於 dcat_con_id 的限制如下： 它在自治式 AI 資料庫執行處理內必須是唯一的。 必須以字母為開頭。 它可能包含英數字元、底線 (_)、貨幣符號 ($) 及井號 (#)。 長度必須至少為 16 個字元。
catalog_type	要連線的資料目錄類型。允許的值為： OCI_DCAT - OCI 資料目錄 AWS_GLUE - AWS Glue 資料目錄 NULL - 會自動從提供的區域或端點偵測目錄類型。
token_endpoint	OAuth 認證的存取權杖端點。預設值為 NULL。

使用情況

您只需要呼叫此程序一次即可設定連線。自治式 AI 資料庫會在連線過程中新增自訂特性至資料目錄。「資料目錄」使用者可以存取這些自訂特性，並允許您覆寫預設名稱 (綱要、表格和資料欄) 和資料欄資料類型。

建立連線之前，必須先建立並設定證明資料。如需連線處理作業的描述，請參閱 OCI 資料目錄的一般工作流程與資料目錄和 AWS Glue 資料目錄的使用 AWS Glue 資料目錄查詢的使用者工作流程。

範例

範例：使用已知的 OCID 連線

在此範例中，Autonomous AI Database 正在連線至 uk-london-1 區域中的資料目錄。catalog_id 參數使用 Oracle Cloud ID (ocid) 作為「資料目錄」執行處理。資料目錄的類型會自動決定：AWS Glue 資料目錄或 OCI 資料目錄。

BEGIN
  DBMS_DCAT.SET_DATA_CATALOG_CONN(
    region=>'uk-london-1',
    catalog_id=>'ocid1.datacatalog.oc1.uk-london-1...');
END;
/

範例：連線至 AWS Glue 資料目錄

連線是自治式 AI 資料庫執行處理與 AWS Glue 資料目錄之間的關聯。成功連線之後，自治式 AI 資料庫執行處理便能夠與 AWS Glue 同步。每個 AWS 帳戶每個區域都有一個 AWS Glue 資料目錄，每個目錄都可以使用每個區域的對應服務端點進行存取。自治式 AI 資料庫執行處理可以透過呼叫 API DBMS_DCAT.SET_DATA_CATALOG_CONN 並指定目錄所在區域的端點，與 AWS Glue 資料目錄建立關聯。

請參閱 AWS Glue 端點與配額。

在此範例中，Autonomous AI Database 正在連線至 uk-london-1 區域中的 AWS Glue 資料目錄。因為這是 AWS Glue Data Catalog 連線，所以不需要 catalog_id 參數。

BEGIN
  DBMS_DCAT.SET_DATA_CATALOG_CONN(
    region=>'uk-london-1',
    catalog_type=>'AWS_GLUE'
END;
/

UNSET_DATA_CATALOG_CONN 程序

此程序會移除現有的資料目錄連線。

語法

注意：呼叫此程序會刪除在先前同步化中建立的所有受保護綱要和外部表格。它不會影響資料目錄中的描述資料。

PROCEDURE DBMS_DCAT.UNSET_DATA_CATALOG_CONN (
    dcat_con_id IN VARCHAR2 DEFAULT NULL
);

參數

Parameter - 參數	描述
dcat_con_id	唯一的資料目錄連線 ID。預設值為 Null。

同步化子程式

執行同步化、建立及刪除同步化工作，以及刪除同步化綱要，都可以使用本表格中所列的程序來執行。

注意：在 2022 年 4 月 4 日，sync_option 和 grant_read 參數已新增至 DBMS_DCAT.RUN_SYNC 程序。若要確保排定同步工作在該日期之前建立的效能正確，您必須刪除並重新建立排定的同步工作。請參閱 DROP_SYNC_JOB Procedure 和 CREATE_SYNC_JOB Procedure 。

子程式	描述
CREATE_SYNC_JOB 程序	建立定期呼叫 RUN_SYNC 的排程器工作
DROP_SYNC_JOB 程序	刪除指定之唯一連線 ID 的現有同步工作
DROP_SYNCED_SCHEMAS 程序	刪除指定之唯一連線 ID 的所有先前同步綱要
RUN_SYNC 程序	執行同步化作業

RUN_SYNC 程序

此程序會執行同步化作業，而且是同步化的進入點。輸入時，它會取得選取的資料目錄資產、資料夾和個體清單，並透過建立、刪除及更改外部表格來具體化這些物件。

sync_option 參數指定 RUN_SYNC 程序執行的作業：SYNC、DELETE 或 REPLACE。在 synced_objects 參數範圍內對實體執行作業。

每個對 RUN_SYNC 程序的呼叫都會傳回唯一的 operation_id，可用來查詢 USER_LOAD_OPERATIONS 視觀表，以取得同步狀態和對應 log_table 的相關資訊。您可以查詢 DBMS_DCAT$SYNC_LOG 視觀表，以便輕鬆存取目前使用者執行之上次同步作業的 log_table。如需進一步的詳細資訊，請參閱 DBMS_DCAT$SYNC_LOG View 。

注意：在 2022 年 4 月 4 日，sync_option 和 grant_read 參數已新增至 DBMS_DCAT.RUN_SYNC 程序。若要確保排定同步工作在該日期之前建立的效能正確，您必須刪除並重新建立排定的同步工作。請參閱 DROP_SYNC_JOB 程序和 CREATE_SYNC_JOB 程序。

同步分割的邏輯實體或 Glue 表格

RUN_SYNC 程序會在下列三個條件全部適用時，為每個邏輯實體或 Glue 表格建立一個分割的外部表格：

1. OCI 資料目錄邏輯實體或 Glue 表格有一或多個分割的屬性。

2. 對於 OCI 資料目錄，邏輯實體衍生自前置碼型檔案名稱樣式。不支援從正規表示式型樣式衍生的分割邏輯實體。

3. 對於 OCI 資料目錄，邏輯實體是根據 hive 樣式或非 hive 資料夾格式之後的分割資料。不支援以使用物件名稱之非階層式格式的分割資料為基礎的邏輯實體。

   • 範例 1。以 Hive 樣式分割格式與前置碼型檔案名稱樣式為依據的收集物件為基礎的邏輯實體。

     請參考下列物件：

     Bucket: MYBUCKET
     cluster1/db1.db/sales/country=USA/year=2020/month=01/sales1.csv
     cluster1/db1.db/sales/country=USA/year=2020/month=01/sales2.csv
     cluster1/db1.db/sales/country=USA/year=2020/month=02/sales1.csv
     

     使用開始資料夾前置碼為 cluster1/db1.db 的檔案名稱樣式收集儲存桶時，會產生一個名為 SALES 的邏輯實體，其中包含三個分割區屬性：country、year 和 month。分割屬性的類型為 Partition，非分割屬性的類型則為 Primitive。

   • 範例 2。依循非 Hive 樣式分割格式與前置碼型檔案名稱樣式之收集物件的邏輯實體。

     請參考下列物件：

     Bucket: MYBUCKET
     cluster2/db2.db/sales/USA/2020/01/sales1.csv
     cluster2/db2.db/sales/USA/2020/01/sales2.csv
     cluster2/db2.db/sales/USA/2020/02/sales1.csv
     

     使用開始資料夾前置碼為 cluster2/db2.db 的檔案名稱樣式收集儲存桶時，會產生名為 SALES 的邏輯實體，並包含三個分割區屬性：name0、name1 和 name2。與範例 1 相比，所產生邏輯實體之間的唯一差異是自動產生分割屬性的名稱，而在範例 1 中，它們是分別從 URL 擷取 (country、year 和 month)。

如需同步分割邏輯實體的完整端對端範例，請參閱範例：分割的資料案例。

分割的邏輯實體 / 標示表格的增量同步化

每個對 RUN_SYNC 程序的呼叫都會指定一組要與資料庫同步的 OCI 資料目錄邏輯實體或 AWS Glue 表格。當兩個 RUN_SYNC 呼叫中有邏輯實體或 Glue 表格時，第二個呼叫會保留並可能變更現有的外部表格。下表顯示分割邏輯實體或 Glue 表格時，支援哪些邏輯實體或 Glue 表格變更：

邏輯實體或 Glue 表格變更	動作
新增、移除或更新分割區	無論資料目錄是否偵測到變更，外部分割表格的所有分割區都會更新。
新增分割的屬性	不支援新增分割的資料欄至外部分割表格。已產生例外。
刪除分割區屬性	不支援從外部分割表格刪除分割的資料欄。已產生例外。
重新命名分割的屬性	不支援在外部分割表格中重新命名分割的資料欄。已產生例外。

語法

PROCEDURE DBMS_DCAT.RUN_SYNC (
    synced_objects   IN  CLOB,
    sync_option      IN VARCHAR2 DEFAULT 'SYNC',
    error_semantics  IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
    log_level        IN VARCHAR2 DEFAULT 'INFO',
    grant_read       IN VARCHAR2 DEFAULT NULL,
    dcat_con_id      IN VARCHAR2 DEFAULT NULL
 );

PROCEDURE DBMS_DCAT.RUN_SYNC (
    synced_objects   IN  CLOB,
    sync_option      IN VARCHAR2 DEFAULT 'SYNC',
    error_semantics  IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
    log_level        IN VARCHAR2 DEFAULT 'INFO',
    grant_read       IN VARCHAR2 DEFAULT NULL,
    operation_id     OUT NOCOPY NUMBER,
    dcat_con_id      IN VARCHAR2 DEFAULT NULL
 );

參數

Parameter - 參數	描述
synced_objects	此參數是指定要同步之資料目錄物件的 JSON 文件。 對於 OCI 資料目錄，JSON 文件會指定多個資料點的一組實體：資料資產、資料夾 (物件存放區儲存桶) 或邏輯實體。它包含的 asset_list 是資產物件的陣列，或包含單一 "*" 字串的陣列，代表目錄中「同步所有 (物件存放區) 資料資產」。 對於 AWS Glue Data Catalogs，JSON 文件會指定多個精細度的表格清單：資料庫、表格。文件會指定資料庫清單。使用者可以指定資料庫內的個別表格，限制要同步的表格集。
sync_option	(選擇性) 有三個選項： SYNC (預設) - 此選項可確保資料目錄中 synced_objects 範圍內的內容在「自治式 AI 資料庫」中呈現。如果自上次同步作業之後，邏輯實體或 Glue 表格已自資料目錄中刪除，則會在自治式 AI 資料庫中刪除。在 synced_objects 範圍執行以下作業： 新增新資料目錄實體的表格 移除已刪除資料目錄實體的表格 更新現有表格的特性 (例如名稱、資料欄以及資料類型) DELETE - 刪除 synced_objects 範圍內的表格。 REPLACE - 以 synced_objects 範圍內的物件取代所有目前同步的物件。
error_semantics	(選擇性) 此參數指定錯誤行為。如果設為 SKIP_ERRORS，則同步會嘗試繼續，儘管個別實體發生錯誤。如果設定為 STOP_ON_ERROR，則程序會在第一次遇到的錯誤時失敗。預設值為 SKIP_ERRORS。
log_level	(選擇性) 此參數在增加記錄日誌詳細資訊層次中指定下列值：(OFF、FATAL、ERROR、WARN、INFO、DEBUG、TRACE、ALL)。預設值為 INFO。
grant_read	(選擇性) 此參數是使用者 / 角色清單，這些使用者 / 角色會自動授與此呼叫 RUN_SYNC 所處理之所有外部表格的 READ 權限。grant_read 清單中的所有使用者 / 角色都會被授予對應 synced_objects 參數所指定實體之所有新外部或現有外部表格的 READ 權限。RUN_SYNC 程序會保留已授予同步之外部表格的權限。
operation_id	(選用) 此參數用於在 USER_LOAD_OPERATIONS 中尋找同步的對應項目，並決定日誌表格的名稱。 注意：提供未傳回 operation_id 的 RUN_SYNC 版本，讓使用者可以查詢 USER_LOAD_OPERATIONS 以取得最新的同步。
dcat_con_id	此參數是建立資料目錄連線時所指定的唯一資料目錄連線 ID。請參閱 SET_DATA_CATALOG_CONN Procedure 。此參數會識別用於同步化的連線，並成為衍生綱要名稱的一部分。如需如何導出結構名稱的描述，請參閱同步對應。參數預設值為 NULL。

範例

範例：同步所有 OCI 資料目錄實體。

在下列範例中，會同步化所有「資料目錄」實體。

EXEC DBMS_DCAT.RUN_SYNC(synced_objects=>'{"asset_list":["*"]}');

範例：synced_objects 參數，用於同步所有 OCI 資料目錄資料資產。

以下為同步「資料目錄」中所有 (物件儲存) 資料資產的範例 synced_objects 參數。

{"asset_list" : ["*"]}

範例：synced_objects 參數，用於同步特定 OCI 資料目錄資料資產。

以下為同步兩個資料資產的範例 synced_objects 參數。

{"asset_list": [
        {
            "asset_id":"...-9e2e7f78fd5f"
        },
        {
            "asset_id":"...-9e2e7f74523"
        }
    ]}

範例：用於同步資料資產內特定 OCI 資料目錄實體的 synced_objects 參數。

以下顯示用於同步資料資產內兩個實體的範例 synced_objects 參數。

{"asset_list": [
        {
            "asset_id":"...-9e2e7f78fd5f",
            "folder_list":[
                "f1",
                "f2"
           ]
        }
    ]}

範例：同步資料資產內特定 OCI 資料目錄資料夾和實體的 synced_objects 參數。

以下顯示同步資料資產內兩個資料夾和兩個實體的範例 synced_objects 參數。

{"asset_list":[
        {
            "asset_id":"...-9e2e7f78fd5f",
            "entity_list": [
                "entity1",
                "entity2"
            ],
             "folder_list": [
                "f1",
                "f2"
            ]
        }
    ]}

範例：synced_objects 同步所有 AWS Glue 資料目錄資料庫的參數。

以下顯示用於同步 AWS Glue 資料目錄中所有資料庫的範例 synced_objects 參數。

{"database_list":["*"]}

範例：synced_objects 同步兩個 AWS Glue 資料目錄資料庫的參數。

以下顯示同步兩個 AWS Glue 資料目錄資料庫的範例 synced_objects 參數。

{"database_list":[
    {"database":"tpcdscsv"},
    {"database":"tpcdsparquet"} ]}

範例：synced_objects 用於同步三個 AWS Glue 資料目錄資料庫的參數。

以下顯示從 AWS Glue Data Catalog 資料庫同步三個表格的範例 synced_objects 參數。

{"database_list":[
 {"database":"tpcdsparquet",
     "table_list": [ "tpcdsparquet_customer",
                     "tpcdsparquet_item",
                     "tpcdsparquet_web_sales" ] } ]}

CREATE_SYNC_JOB 程序

此程序會建立定期呼叫 RUN_SYNC 的排程器工作

它需要輸入要同步的物件集、錯誤語意、日誌層次以及重複間隔。請參閱 RUN_SYNC 程序，以取得同步運作方式的進一步詳細資訊。

只能有單一同步工作。如果已指定其他工作，則 CREATE_SYNC_JOB 程序會失敗，除非強制參數設為 TRUE。如果強制設為 TRUE，則會刪除上一個工作。

如果排程器工作嘗試在其他同步進行時執行，排程器工作就會失敗。

注意：在 2022 年 4 月 4 日，sync_option 和 grant_read 參數已新增至 DBMS_DCAT.RUN_SYNC 程序。若要確保排定同步工作在該日期之前建立的效能正確，您必須刪除並重新建立排定的同步工作。請參閱 DROP_SYNC_JOB 程序和 CREATE_SYNC_JOB 程序。

語法

PROCEDURE DBMS_DCAT.CREATE_SYNC_JOB (
    synced_objects   IN CLOB,
    error_semantics  IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
    log_level        IN VARCHAR2 DEFAULT 'INFO',
    repeat_interval  IN VARCHAR2,
    force            IN VARCHAR2 DEFAULT 'FALSE',
    grant_read       IN VARCHAR2 DEFAULT NULL,
    sync_option      IN VARCHAR2 DEFAULT 'SYNC',
    dcat_con_id      IN VARCHAR2 DEFAULT NULL
);

參數

Parameter - 參數	描述
synced_objects	指定要同步之物件的 JSON 物件，如 RUN_SYNC 程序中所述。請參閱 RUN_SYNC Procedure 。
error_semantics	(選擇性) 錯誤行為，如為 RUN_SYNC 所指定。預設值為 SKIP_ERRORS。
log_level	(選擇性) 記錄日誌層次，如 RUN_SYNC 所指定。預設為 INFO。
repeat_interval	工作的重複間隔，其語意與 DBMS_SCHEDULER.CREATE_JOB 程序的重複間隔參數相同。如需 repeat_interval 的詳細資訊，請參閱建立工作簡介。
force	(選擇性) 如果是 TRUE，則會先刪除現有的同步工作。如果是 FALSE，如果同步工作已經存在，CREATE_SYNC_JOB 程序就會失敗。預設值為 FALSE。
grant_read	(選擇性) 要在同步的外部表格上授與 READ 之使用者 / 角色的清單，如程序 RUN_SYNC 所述。請參閱 RUN_SYNC Procedure 。
sync_option	(選擇性) 已透過先前的 RUN_SYNC 作業同步之實體的相關行為，如程序 RUN_SYNC 所述。請參閱 RUN_SYNC Procedure 。
dcat_con_id	此參數是建立「資料目錄」連線時指定的唯一「資料目錄」連線 ID。請參閱 SET_DATA_CATALOG_CONN Procedure 。此參數會識別用於同步化的連線，並成為衍生綱要名稱的一部分。如需如何導出結構名稱的描述，請參閱同步對應。參數預設值為 NULL。

DROP_SYNC_JOB 程序

此程序會刪除指定之唯一連線 ID 的現有同步工作。

語法

PROCEDURE DBMS_DCAT.DROP_SYNC_JOB (
    dcat_con_id IN VARCHAR2 DEFAULT NULL
  );

參數

Parameter - 參數	描述
dcat_con_id	唯一的資料目錄連線 ID。預設值為 NULL。

DROP_SYNCED_SCHEMAS 程序

此程序會刪除指定之唯一連線 ID 的所有先前同步綱要。

語法

PROCEDURE DBMS_DCAT.DROP_SYNCED_SCHEMAS (
    dcat_con_id IN VARCHAR2 DEFAULT NULL
  );

參數

Parameter - 參數	描述
dcat_con_id	唯一的資料目錄連線 ID。預設值為 NULL。