DBMS_EXT_TABLE_CACHE 套裝程式

此表格總結列出 DBMS_EXT_TABLE_CACHE 套裝程式中所含的子程式。

子程式	描述
ADD_BY_LIKE 程序	將一或多個符合指定篩選條件的檔案新增至外部表格快取。
ADD_FILE 程序	新增檔案至外部表格快取。
ADD_TABLE 程序	從指定的外部表格新增檔案至外部表格快取。
清除程序	清除外部表格快取。
CREATE_CACHE 程序	建立外部表格快取。
停用程序	停用外部表格快取。
DROP_BY_LIKE 程序	根據指定的篩選，從外部表格快取刪除檔案。
DROP_CACHE 程序	刪除外部表格快取。
DROP_FILE 程序	從外部表格快取中移除指定的外部表格檔案。
啟用程序	啟用先前停用的外部表格快取。
GET_USER_PROPERTY 函數	擷取外部表格快取的快取偏好設定。
RETIRE_FILES 程序	從快取中刪除一或多個超過指定間隔的檔案。
SET_USER_PROPERTY 程序	指定外部表格快取的快取偏好設定。
驗證程序	驗證外部表格快取。

ADD_BY_LIKE 程序

DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE 程序會從「物件存放區」將一或多個指定的檔案載入外部表格快取。

語法

DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE (
      owner        IN VARCHAR2,
      table_name   IN VARCHAR2,
      path_filters IN CLOB,
      esc_char     IN VARCHAR2 DEFAULT NULL,
      force        IN BOOLEAN  DEFAULT FALSE);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。
path_filters	PATH_FILTERS 是用來搜尋檔案 URL 中指定樣式之路徑篩選的 JSON_ARRAY。
esc_char	指定路徑篩選中要使用的遁離字元。如果遁離字元在樣式的 '%' 或 '_' 之前，則會依文字解譯特殊字元，而非特殊樣式比對字元。 此參數為可選參數，此參數的預設值為 NULL。
force	強制在快取中覆寫指定的現有檔案，即使未修改檔案。 此參數為選擇性參數，force 參數的預設值為 FALSE。

範例

BEGIN
  DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE (
    owner        => 'SALES',
    table_name   =>'STORE_SALES',
    path_filters => '["https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/your_namespace/your_bucket/salesdata1.parquet",
                      "https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/your_namespace/your_bucket/salesdata2.parquet"]'
);
END;
/

用途注意事項

依照預設，DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE 程序會在下列情況略過載入檔案：

• 這些檔案先前已快取，但仍可在快取中使用。

• 檔案自上次快取後未被修改。

  不過，即使未修改檔案，您也可以使用 force 參數覆寫快取中的檔案。

ADD_FILE 程序

DBMS_EXT_TABLE_CACHE.ADD_FILE 程序會將指定的檔案載入外部表格快取中。

語法

DBMS_EXT_TABLE_CACHE.ADD_FILE (
      owner        IN VARCHAR2,
      table_name   IN VARCHAR2,
      file_url     IN VARCHAR2,
      force        IN BOOLEAN DEFAULT FALSE);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。
file_url	指定檔案 URL。
force	強制在快取中覆寫指定的現有檔案，即使檔案未修改。 此為選擇性參數，force 參數的預設值為 FALSE。

範例

BEGIN
  DBMS_EXT_TABLE_CACHE.ADD_FILE (
    owner        => 'SALES',
    table_name   => 'STORE_SALES',
    file_url     => 'https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/your_namespace/your_bucket/salesdata.parquet'
);
END;
/

使用注意事項

• 如果指定的檔案存在於快取中且自上次快取檔案後尚未修改，則 DBMS_EXT_TABLE_CACHE.ADD_FILE 程序會略過將檔案載入快取中。

• 即使檔案未修改，您也可以使用 force 參數覆寫快取中的檔案。

ADD_LATEST_FILES 程序

DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES 會將一或多個檔案載入外部表格快取中。檔案會根據 SINCE 引數和目前時戳所決定的時間間隔來載入。

語法

DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES (
      owner        IN  VARCHAR2,
      table_name   IN  VARCHAR2,
      since        IN  INTERVAL DAY TO SECOND,
      max_files    IN  NUMBER,
      force        IN  BOOLEAN DEFAULT FALSE);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。
since	since 參數接受 INTERVAL DAY TO SECOND 值，可用來計算 since 值與目前時戳之間的時間間隔。接著會使用產生的時間間隔，根據檔案上次修改的時間來載入檔案。
max_files	指定 max_files 值，以限制可載入至外部表格快取的檔案數目。 此為選擇性參數，未指定時預設為無限制。
force	強制在快取中覆寫指定的現有檔案，即使檔案未修改。 此參數為選擇性參數，此參數的預設值為 FALSE。

範例

BEGIN
  DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES (
    owner        => 'SALES',
    table_name   => 'STORE_SALES',
    since        => INTERVAL '7' DAY,
    max_files    => 5,
    force        => TRUE);
END;
/

用途注意事項

依照預設，DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES 程序會在下列情況略過載入檔案：

• 先前已快取指定的檔案，而且仍可在快取中使用。

• 指定的檔案自上次快取後未被修改。

  不過，即使未修改檔案，您也可以使用 force 參數覆寫快取中的檔案。

ADD_TABLE 程序

DBMS_EXT_TABLE_CACHE.ADD_TABLE 程序會將整個表格或特定百分比的外部表格載入快取中。

語法

DBMS_EXT_TABLE_CACHE.ADD_TABLE (
      owner         IN VARCHAR2,
      table_name    IN VARCHAR2,
      percent_files IN NUMBER DEFAULT NULL,
      force         IN BOOLEAN DEFAULT FALSE);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。
percent_files	指定要快取的表格資料百分比。例如從 1 升級到 100。 依預設，會載入所有檔案。
force	強制在快取中覆寫指定的檔案，即使檔案未修改。 此為選擇性參數，force 的預設值為 FALSE。

範例

BEGIN
  DBMS_EXT_TABLE_CACHE.ADD_TABLE (
    owner         => 'SALES',
    table_name    => 'STORE_SALES',
    percent_files => 50);
END;
/

使用注意事項

• DBMS_EXT_TABLE_CACHE.ADD_TABLE 會嘗試將整個表格或指定的檔案內容百分比快取至快取中。

• percent_files 和 force 參數互斥。

• 依照預設，DBMS_EXT_TABLE_CACHE.ADD_TABLE 程序會在下列情況略過載入檔案：

  • 先前已快取指定的檔案，而且仍可在快取中使用。

  • 指定的檔案自上次快取後未被修改。

  不過，即使檔案未修改，您也可以使用 force 參數覆寫快取中的檔案。

清除程序

DBMS_EXT_TABLE_CACHE.CLEAR 程序會從外部表格快取中移除所有檔案，同時保留快取。

語法

DBMS_EXT_TABLE_CACHE.CLEAR (
      owner         IN VARCHAR2,
      table_name    IN VARCHAR2);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。

範例

BEGIN
  DBMS_EXT_TABLE_CACHE.CLEAR (
    owner         => 'SALES',
    table_name    => 'STORE_SALES');
END;
/

CREATE_CACHE 程序

DBMS_EXT_TABLE_CACHE.CREATE_CACHE 程序會在「自治式 AI 資料庫」執行處理中建立外部表格快取。

語法

DBMS_EXT_TABLE_CACHE.CREATE_CACHE (
      owner            IN    VARCHAR2,
      table_name       IN    VARCHAR2,
      partition_type   IN    VARCHAR2);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格的名稱。
partition_type	下列是 partition_type 參數的有效值： FILE：使用 FILE$PATH 和 FILE$NAME 不顯示的資料欄分割外部表格快取。 PATH：使用 FILE$PATH 不顯示的資料欄分割外部表格快取。 file$path：指定直到物件名稱開頭為止的檔案路徑文字。 file$name：指定物件名稱，包括最後 '/' 後面的所有文字。 請參閱外部表格描述資料資料欄以瞭解詳細資訊。

範例

BEGIN
    DBMS_EXT_TABLE_CACHE.CREATE_CACHE (
      owner          => 'SALES',
      table_name     => 'STORE_SALES',
      partition_type => 'FILE');
END;
/

用途注意事項

DBMS_EXT_TABLE_CACHE.CREATE_CACHE 會在「自治式 AI 資料庫」執行處理中建立外部表格快取。建立快取類似於在資料庫綱要中建立表格。

停用程序

DBMS_EXT_TABLE_CACHE.DISABLE 程序會停用指定的外部表格快取。快取會標示為停用；不過，會保留快取內的資料。

語法

DBMS_EXT_TABLE_CACHE.DISABLE (
      owner        IN VARCHAR2,
      table_name   IN VARCHAR2
);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。

範例

BEGIN
    DBMS_EXT_TABLE_CACHE.DISABLE (
      owner          => 'SALES',
      table_name     => 'STORE_SALES');
END;
/

用途注意事項

DBMS_EXT_TABLE_CACHE.DISABLE 不會刪除外部表格快取中的任何資料。而是會將快取標示為 DISABLED ，這表示最佳化處理程式無法使用快取進行查詢重新寫入。

DROP_BY_LIKE 程序

DBMS_EXT_TABLE_CACHE.DROP_BY_LIKE 程序會從外部表格快取中刪除一或多個檔案。檔案會根據指定的篩選刪除。

語法

DBMS_EXT_TABLE_CACHE.DROP_BY_LIKE (
      owner        IN VARCHAR2,
      table_name   IN VARCHAR2,
      path_filters IN CLOB,
      esc_char     IN VARCHAR2 DEFAULT NULL);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。
path_filters	PATH_FILTERS 是用來搜尋檔案 URL 中指定樣式之路徑篩選的 JSON_ARRAY。
esc_char	指定路徑篩選中要使用的遁離字元。如果遁離字元在樣式的 '%' 或 '_' 之前，則會依文字解譯特殊字元，而非特殊樣式比對字元。 此參數為選用參數，此參數的預設值為 NULL。

範例

BEGIN
  DBMS_EXT_TABLE_CACHE.DROP_BY_LIKE (
    owner        => 'SALES',
    table_name   => 'STORE_SALES',
    path_filters => '["https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/your_namespace/your_bucket/salesdata1.parquet",
                      "https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/your_namespace/your_bucket/salesdata2.parquet"]'
);
END;
/

DROP_CACHE 程序

DBMS_EXT_TABLE_CACHE.DROP_CACHE 程序會刪除指定的外部表格快取。此程序會刪除快取，並釋出與快取關聯的儲存體空間。

語法

DBMS_EXT_TABLE_CACHE.DROP_CACHE (
      owner            IN    VARCHAR2,
      table_name       IN    VARCHAR2
);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。

範例

BEGIN
    DBMS_EXT_TABLE_CACHE.DROP_CACHE (
      owner          => 'SALES',
      table_name     => 'STORE_SALES');
END;
/

用途注意事項

刪除快取會從資料說明中移除其描述資料，並刪除其所有快取的資料。

DROP_FILE 程序

DBMS_EXT_TABLE_CACHE.DROP_FILE 程序會從外部表格快取刪除指定的檔案。

語法

DBMS_EXT_TABLE_CACHE.DROP_FILE (
      owner        IN VARCHAR2,
      table_name   IN VARCHAR2,
      file_url     IN VARCHAR2);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。
file_url	指定檔案 URL。

範例

BEGIN
  DBMS_EXT_TABLE_CACHE.DROP_FILE (
    owner        => 'SALES',
    table_name   => 'STORE_SALES',
    file_url     => 'https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/your_namespace/your_bucket/salesdata.parquet'
);
END;
/

啟用程序

DBMS_EXT_TABLE_CACHE.ENABLE 程序會啟用先前停用的外部表格快取。建立快取時，預設為啟用快取。

語法

DBMS_EXT_TABLE_CACHE.ENABLE (
    owner         IN    VARCHAR2,
    table_name    IN    VARCHAR2
);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。

範例

BEGIN
  DBMS_EXT_TABLE_CACHE.ENABLE (
    owner        => 'SALES',
    table_name   => 'STORE_SALES'
 );
END;
/

GET_USER_PROPERTY 函數

此函數會傳回指定綱要的快取偏好設定，並傳回 Number。

語法

DBMS_EXT_TABLE_CACHE.GET_USER_PROPERTY (
    property_name   IN   VARCHAR2,
    owner           IN   VARCHAR2 DEFAULT NULL);

RETURN NUMBER;

參數

Parameter - 參數	描述
property_name	指定特性名稱。 下列是 property_name 的有效值： MAX_CACHE_PERCENT MAX_CACHE_SIZE
owner	指定綱要名稱。

傳回值

傳回值	描述
數字中的 MAX_CACHE_SIZE 或 MAX_CACHE_SIZE 值。	根據 property_name 參數，傳回的數字是 MAX_CACHE_SIZE 或 MAX_CACHE_SIZE 值。

範例

SET SERVEROUTPUT ON
    DECLARE
    max_cache_sz NUMBER,
    BEGIN
    max_cache_sz := DBMS_EXT_TABLE_CACHE.GET_USER_PROPERTY (
        property_name       => 'MAX_CACHE_SIZE',
        owner               => 'SALES');
END;
/

RETIRE_FILES 程序

DBMS_EXT_TABLE_CACHE.RETIRE_FILES 會從快取中刪除超過指定間隔的檔案。檔案會根據使用 BEFORE 參數值計算的時間間隔刪除。

語法

DBMS_EXT_TABLE_CACHE.RETIRE_FILES (
    owner        IN VARCHAR2,
    table_name   IN VARCHAR2,
    before       IN INTERVAL DAY TO SECOND
);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。
before	before 參數接受 INTERVAL DAY TO SECOND 值，可用來計算 before 值與目前時戳之間的時間間隔。接著會使用產生的時間間隔來刪除快取中的檔案。

範例

BEGIN
 DBMS_EXT_TABLE_CACHE.RETIRE_FILES (
    owner        => 'SALES',
    table_name   => 'STORE_SALES',
    before       => INTERVAL '30' DAY);
END;
/

SET_USER_PROPERTY 程序

DBMS_EXT_TABLE_CACHE.SET_USER_PROPERTY 程序會設定綱要的快取偏好設定。

語法

DBMS_EXT_TABLE_CACHE.SET_USER_PROPERTY (
    property_name    IN    VARCHAR2,
    property_value   IN    NUMBER,
    owner            IN    VARCHAR2 DEFAULT NULL);

參數

Parameter - 參數	描述
property_name	指定特性名稱。 下列是 property_name 的有效值： MAX_CACHE_PERCENT MAX_CACHE_SIZE
property_value	指定特性值。
owner	指定綱要名稱。

範例

BEGIN
    DBMS_EXT_TABLE_CACHE.SET_USER_PROPERTY (
    property_name  => 'MAX_CACHE_PERCENT',
    property_value => 100,
    owner          => 'SALES');
END;
/

驗證程序

DBMS_EXT_TABLE_CACHE.VALIDATE 程序會驗證外部表格快取。如果在資料庫中找不到參照的外部表格，則會報告錯誤。

語法

DBMS_EXT_TABLE_CACHE.VALIDATE (
      owner            IN    VARCHAR2,
      table_name       IN    VARCHAR2,
      raise_errors     IN    BOOLEAN DEFAULT TRUE);

參數

Parameter - 參數	描述
owner	指定綱要名稱。
table_name	指定外部表格名稱。
raise_errors	外部表格快取標示為無效的報表。

範例

BEGIN
  DBMS_EXT_TABLE_CACHE.VALIDATE (
    owner         => 'SALES',
    table_name    => 'STORE_SALES',
    raise_errors  => TRUE);
END;
/

相關內容

使用外部表格快取改善查詢效能