DBMS_EXT_TABLE_CACHEパッケージ

DBMS_EXT_TABLE_CACHEパッケージは、外部表からAutonomous Databaseへの頻繁にアクセスされるデータのキャッシュを構成および管理するためのルーチンを提供します。

DBMS_EXT_TABLE_CACHEサブプログラムの要約

この表は、DBMS_EXT_TABLE_CACHEパッケージに含まれるサブプログラムの概要を示しています。

サブプログラム 説明

ADD_BY_LIKEプロシージャ

指定されたフィルタに一致する1つ以上のファイルを外部表キャッシュに追加します。

ADD_FILEプロシージャ

外部表キャッシュにファイルを追加します。

ADD_TABLEプロシージャ

指定された外部表から外部表キャッシュにファイルを追加します。

CLEARプロシージャ

外部表キャッシュをクリアします。

CREATE_CACHEプロシージャ

外部表キャッシュを作成します。

DISABLEプロシージャ

外部表キャッシュを無効にします。

DROP_BY_LIKEプロシージャ

指定されたフィルタに基づいて、外部表キャッシュからファイルをドロップします。

DROP_CACHEプロシージャ

外部表キャッシュを削除します。

DROP_FILEプロシージャ

外部表キャッシュから指定された外部表ファイルを削除します。

ENABLEプロシージャ

以前に無効にした外部表キャッシュを有効にします。

GET_USER_PROPERTYファンクション

外部表キャッシュのキャッシュ・プリファレンスを取得します。

RETIRE_FILESプロシージャ

指定された間隔より古い1つ以上のファイルをキャッシュから削除します。

SET_USER_PROPERTYプロシージャ

外部表キャッシュのキャッシュ・プリファレンスを指定します。

VALIDATEプロシージャ

外部表キャッシュを検証します。

ADD_BY_LIKEプロシージャ

DBMS_EXT_TABLE_CACHE.ADD_BY_LIKEプロシージャは、指定した1つ以上のファイルをオブジェクト・ストアから外部表キャッシュにロードします。

構文

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

パラメータ

パラメータ 説明

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

パラメータ

パラメータ 説明

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は、1つ以上のファイルを外部表キャッシュにロードします。ファイルは、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);

パラメータ

パラメータ 説明

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

パラメータ

パラメータ 説明

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パラメータを使用すると、ファイルが変更されていない場合でも、キャッシュ内のファイルを上書きできます。

CLEARプロシージャ

DBMS_EXT_TABLE_CACHE.CLEARプロシージャは、キャッシュを保持しながら外部表キャッシュからすべてのファイルを削除します。

構文

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

パラメータ

パラメータ 説明

owner

スキーマ名を指定します。

table_name

外部表名を指定します。

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

CREATE_CACHEプロシージャ

DBMS_EXT_TABLE_CACHE.CREATE_CACHEプロシージャは、Autonomous Databaseインスタンスに外部表キャッシュを作成します。

構文

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

パラメータ

パラメータ 説明

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は、Autonomous Databaseインスタンスに外部表キャッシュを作成します。キャッシュの作成は、データベース・スキーマでの表の作成に似ています。

DISABLEプロシージャ

DBMS_EXT_TABLE_CACHE.DISABLEプロシージャは、指定された外部表キャッシュを無効にします。キャッシュには無効のフラグが付けられますが、キャッシュ内のデータは保持されます。

構文

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

パラメータ

パラメータ 説明

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プロシージャは、外部表キャッシュから1つ以上のファイルを削除します。ファイルは、指定されたフィルタに基づいて削除されます。

構文

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

パラメータ

パラメータ 説明

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

パラメータ

パラメータ 説明

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

パラメータ

パラメータ 説明

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

ENABLEプロシージャ

DBMS_EXT_TABLE_CACHE.ENABLEプロシージャは、以前に無効にした外部表キャッシュを有効にします。キャッシュが作成されると、キャッシュはデフォルトで有効になります。

構文

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

パラメータ

パラメータ 説明

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;

パラメータ

パラメータ 説明

property_name

プロパティ名を指定します。

property_nameの有効な値は次のとおりです。
  • MAX_CACHE_PERCENT

  • MAX_CACHE_SIZE

owner

スキーマ名を指定します。

戻り値

戻り値 説明

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

パラメータ

パラメータ 説明

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

パラメータ

パラメータ 説明

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

VALIDATEプロシージャ

DBMS_EXT_TABLE_CACHE.VALIDATEプロシージャは、外部表キャッシュを検証します。参照される外部表がデータベースで見つからない場合は、エラーが報告されます。

構文

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

パラメータ

パラメータ 説明

owner

スキーマ名を指定します。

table_name

外部表名を指定します。

raise_errors

外部表キャッシュが無効とマークされた場合にレポートします。

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