Documentation Oracle Cloud Infrastructure

Package DBMS_EXT_TABLE_CACHE

Le package DBMS_EXT_TABLE_CACHE fournit des routines permettant de configurer et de gérer la mise en cache des données fréquemment consultées à partir de tables externes dans Autonomous Database.

Rubrique parent : Référence de package fourni avec Autonomous Database

Récapitulatif des sous-programmes DBMS_EXT_TABLE_CACHE

Ce tableau récapitule les sous-programmes inclus dans le package DBMS_EXT_TABLE_CACHE.

Sous-programme Description

Procédure ADD_BY_LIKE

Ajoute un ou plusieurs fichiers qui correspondent aux filtres spécifiés dans un cache de table externe.

Procédure ADD_FILE

Ajoute un fichier au cache de table externe.

Procédure ADD_TABLE

Ajoute des fichiers de la table externe indiquée dans un cache de table externe.

Procédure CLEAR

Efface un cache de table externe.

Procédure CREATE_CACHE

Crée un cache de table externe.

Désactiver la procédure

Désactive un cache de table externe.

Procédure DROP_BY_LIKE

Supprimez des fichiers d'un cache de table externe en fonction des filtres spécifiés.

Procédure DROP_CACHE

Supprime un cache de table externe.

Procédure DROP_FILE

Supprime le fichier de table externe indiqué du cache de table externe.

ACTIVER la procédure

Active un cache de table externe précédemment désactivé.

Fonction GET_USER_PROPERTY

Récupère la préférence de mise en cache pour un cache de table externe.

Procédure RETIRE_FILES

Supprime un ou plusieurs fichiers du cache qui sont antérieurs à l'intervalle spécifié.

Procédure SET_USER_PROPERTY

Spécifie la préférence de mise en cache pour un cache de table externe.

Procédure VALIDATE

Valide un cache de table externe.
  • Procédure ADD_BY_LIKE
    La procédure DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE charge un ou plusieurs fichiers spécifiés à partir de la banque d'objets dans le cache de table externe.
  • Procédure ADD_FILE
    La procédure DBMS_EXT_TABLE_CACHE.ADD_FILE charge le fichier indiqué dans le cache de table externe.
  • Procédure ADD_LATEST_FILES
    DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES charge un ou plusieurs fichiers dans le cache de table externe. Les fichiers sont chargés en fonction de l'intervalle de temps déterminé par l'argument SINCE et l'horodatage en cours.
  • Procédure ADD_TABLE
    La procédure DBMS_EXT_TABLE_CACHE.ADD_TABLE charge une table entière ou un certain pourcentage de la table externe dans le cache.
  • Procédure CLEAR
    La procédure DBMS_EXT_TABLE_CACHE.CLEAR supprime tous les fichiers d'un cache de table externe tout en conservant le cache.
  • Procédure CREATE_CACHE
    La procédure DBMS_EXT_TABLE_CACHE.CREATE_CACHE crée un cache de table externe dans une instance Autonomous Database.
  • Procédure DISABLE
    La procédure DBMS_EXT_TABLE_CACHE.DISABLE désactive le cache de table externe indiqué. Le cache est marqué comme désactivé, mais les données qu'il contient sont conservées.
  • Procédure DROP_BY_LIKE
    La procédure DBMS_EXT_TABLE_CACHE.DROP_BY_LIKE supprime un ou plusieurs fichiers du cache de table externe. Les fichiers sont supprimés en fonction des filtres spécifiés.
  • Procédure DROP_CACHE
    La procédure DBMS_EXT_TABLE_CACHE.DROP_CACHE supprime le cache de table externe indiqué. Cette procédure supprime le cache et libère l'espace de stockage associé au cache.
  • Procédure DROP_FILE
    La procédure DBMS_EXT_TABLE_CACHE.DROP_FILE supprime le fichier indiqué d'un cache de table externe.
  • Procédure ENABLE
    La procédure DBMS_EXT_TABLE_CACHE.ENABLE active un cache de table externe précédemment désactivé. Lorsqu'un cache est créé, il est activé par défaut.
  • Fonction GET_USER_PROPERTY
    La fonction renvoie la préférence de mise en cache pour le schéma indiqué et renvoie une valeur Number.
  • Procédure RETIRE_FILES
    L'option DBMS_EXT_TABLE_CACHE.RETIRE_FILES supprime les fichiers du cache qui sont plus anciens que l'intervalle indiqué. Les fichiers sont supprimés en fonction de l'intervalle de temps calculé à l'aide de la valeur du paramètre BEFORE.
  • Procédure SET_USER_PROPERTY
    La procédure DBMS_EXT_TABLE_CACHE.SET_USER_PROPERTY définit la préférence de mise en cache pour un schéma.
  • Procédure VALIDATE
    La procédure DBMS_EXT_TABLE_CACHE.VALIDATE valide le cache de table externe. Une erreur est signalée si la table externe référencée est introuvable dans la base de données.

Rubrique parent : Package DBMS_EXT_TABLE_CACHE

Procédure ADD_BY_LIKE

La procédure DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE charge un ou plusieurs fichiers spécifiés à partir de la banque d'objets dans le cache de table externe.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.
path_filters

PATH_FILTERS est un JSON_ARRAY de filtres de chemin utilisés pour rechercher des modèles spécifiés dans des URL de fichier.

esc_char

Spécifie le caractère d'échappement à utiliser dans les filtres de chemin. Si le caractère d'échappement précède "%" ou "_" dans le modèle, le caractère spécial est interprété littéralement et non comme un caractère spécial correspondant au modèle.

Ce paramètre est facultatif et sa valeur par défaut est NULL.

force

Force l'écrasement des fichiers existants spécifiés dans le cache même si les fichiers n'ont pas été modifiés.

Ce paramètre est facultatif et la valeur par défaut du paramètre force est FALSE.

Exemple

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

Remarque sur l'utilisation

  • Par défaut, la procédure DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE ignore le chargement des fichiers dans les cas suivants :

    • Les fichiers étaient précédemment mis en cache et toujours disponibles dans le cache.

    • Les fichiers n'ont pas été modifiés depuis leur dernière mise en cache.

    Cependant, vous pouvez utiliser le paramètre force pour écraser les fichiers dans le cache même si les fichiers n'ont pas été modifiés.

Procédure ADD_FILE

La procédure DBMS_EXT_TABLE_CACHE.ADD_FILE charge le fichier indiqué dans le cache de table externe.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.
file_url

Indique l'URL du fichier.
force

Force l'écrasement des fichiers existants spécifiés dans le cache même si les fichiers n'ont pas été modifiés.

Ce paramètre est facultatif et la valeur par défaut du paramètre force est FALSE.

Exemple

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

Notes d'utilisation

  • La procédure DBMS_EXT_TABLE_CACHE.ADD_FILE ignore le chargement du fichier dans le cache si le fichier indiqué existe dans le cache et n'a pas été modifié depuis le dernier cache du fichier.

  • Vous pouvez utiliser le paramètre force pour écraser le fichier dans le cache, même si le fichier n'a pas été modifié.

Procédure ADD_LATEST_FILES

DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES charge un ou plusieurs fichiers dans le cache de table externe. Les fichiers sont chargés en fonction de l'intervalle de temps déterminé par l'argument SINCE et l'horodatage en cours.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.

since

Le paramètre since accepte une valeur INTERVAL DAY TO SECOND et sert à calculer l'intervalle de temps entre la valeur since et l'horodatage en cours. L'intervalle de temps résultant est ensuite utilisé pour charger les fichiers, en fonction de leur dernière modification.

max_files

Indiquez la valeur max_files pour limiter le nombre de fichiers pouvant être chargés dans le cache de table externe.

Ce paramètre est facultatif et est défini par défaut sur illimité lorsqu'il n'est pas spécifié.

force

Force l'écrasement des fichiers existants spécifiés dans le cache même si les fichiers n'ont pas été modifiés.

Ce paramètre est facultatif et sa valeur par défaut est FALSE.

Exemple

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

Remarque sur l'utilisation

  • Par défaut, la procédure DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES ignore le chargement des fichiers dans les cas suivants :

    • Les fichiers spécifiés étaient précédemment mis en cache et toujours disponibles dans le cache.

    • Les fichiers spécifiés n'ont pas été modifiés depuis leur dernier cache.

    Cependant, vous pouvez utiliser le paramètre force pour écraser les fichiers dans le cache même si les fichiers n'ont pas été modifiés.

Procédure ADD_TABLE

La procédure DBMS_EXT_TABLE_CACHE.ADD_TABLE charge une table entière ou un certain pourcentage de la table externe dans le cache.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.

percent_files

Indique le pourcentage des données de table à mettre en cache. Par exemple de la 1 à la 100.

Par défaut, tous les fichiers sont chargés.

force

Force l'écrasement des fichiers spécifiés dans le cache même s'ils n'ont pas été modifiés.

Ce paramètre est facultatif et la valeur par défaut pour force est FALSE.

Exemple

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

Notes d'utilisation

  • DBMS_EXT_TABLE_CACHE.ADD_TABLE tente de mettre en cache la table entière ou un pourcentage spécifié du contenu du fichier dans le cache.

  • Les paramètres percent_files et force s'excluent mutuellement.

  • Par défaut, la procédure DBMS_EXT_TABLE_CACHE.ADD_TABLE ignore le chargement des fichiers dans les cas suivants :

    • Les fichiers spécifiés étaient précédemment mis en cache et toujours disponibles dans le cache.

    • Les fichiers spécifiés n'ont pas été modifiés depuis leur dernier cache.

    Cependant, vous pouvez utiliser le paramètre force pour écraser les fichiers dans le cache même si les fichiers n'ont pas été modifiés.

Procédure CLEAR

La procédure DBMS_EXT_TABLE_CACHE.CLEAR supprime tous les fichiers d'un cache de table externe tout en conservant le cache.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.

Exemple

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

Procédure CREATE_CACHE

La procédure DBMS_EXT_TABLE_CACHE.CREATE_CACHE crée un cache de table externe dans une instance Autonomous Database.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Spécifie le nom de la table externe.

partition_type
Les valeurs valides pour le paramètre partition_type sont les suivantes :

  • FILE : partitionne le cache de table externe à l'aide des colonnes invisibles FILE$PATH et FILE$NAME.

  • PATH : partitionne le cache de table externe à l'aide de la colonne invisible FILE$PATH.

file$path : indique le texte du chemin du fichier jusqu'au début du nom de l'objet.

file$name : indique le nom de l'objet, y compris tout le texte qui suit le texte final "/".

Pour plus d'informations, reportez-vous à Colonnes de métadonnées de table externe.

Exemple

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

Remarque sur l'utilisation

  • DBMS_EXT_TABLE_CACHE.CREATE_CACHE crée le cache de table externe dans une instance Autonomous Database. La création d'un cache est similaire à la création d'une table dans le schéma de base de données.

Désactiver la procédure

La procédure DBMS_EXT_TABLE_CACHE.DISABLE désactive le cache de table externe indiqué. Le cache est marqué comme désactivé, mais les données qu'il contient sont conservées.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.

Exemple

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

Remarque sur l'utilisation

  • DBMS_EXT_TABLE_CACHE.DISABLE ne supprime aucune donnée du cache de table externe. Au lieu de cela, il marque le cache comme DISABLED, ce qui signifie que l'optimiseur ne peut pas utiliser le cache pour les réécritures de requête.

Procédure DROP_BY_LIKE

La procédure DBMS_EXT_TABLE_CACHE.DROP_BY_LIKE supprime un ou plusieurs fichiers du cache de table externe. Les fichiers sont supprimés en fonction des filtres spécifiés.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.
path_filters

PATH_FILTERS est un JSON_ARRAY de filtres de chemin utilisés pour rechercher des modèles spécifiés dans des URL de fichier.

esc_char

Spécifie le caractère d'échappement à utiliser dans les filtres de chemin. Si le caractère d'échappement précède "%" ou "_" dans le modèle, le caractère spécial est interprété littéralement et non comme un caractère spécial correspondant au modèle.

Ce paramètre est facultatif et sa valeur par défaut est NULL.

Exemple

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

Procédure DROP_CACHE

La procédure DBMS_EXT_TABLE_CACHE.DROP_CACHE supprime le cache de table externe indiqué. Cette procédure supprime le cache et libère l'espace de stockage associé au cache.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.

Exemple

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

Remarque sur l'utilisation

  • La suppression d'un cache enlève ses métadonnées du dictionnaire de données et supprime toutes ses données en cache.

Procédure DROP_FILE

La procédure DBMS_EXT_TABLE_CACHE.DROP_FILE supprime le fichier indiqué d'un cache de table externe.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.

file_url

Indique l'URL du fichier.

Exemple

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

ACTIVER la procédure

La procédure DBMS_EXT_TABLE_CACHE.ENABLE active un cache de table externe précédemment désactivé. Lorsqu'un cache est créé, il est activé par défaut.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.

Exemple

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

Fonction GET_USER_PROPERTY

La fonction renvoie la préférence de mise en cache pour le schéma indiqué et renvoie une valeur Number.

Syntaxe


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

RETURN NUMBER;

Paramètres

Paramètre Description

property_name

Indique le nom de propriété.

Les valeurs valides pour property_name sont les suivantes :

  • MAX_CACHE_PERCENT

  • MAX_CACHE_SIZE

owner

Indique le nom du schéma.

Valeurs renvoyées

Valeur de retour Description

Valeur MAX_CACHE_SIZE ou MAX_CACHE_SIZE dans le champ Nombre.

Selon le paramètre property_name, le nombre renvoyé est la valeur MAX_CACHE_SIZE ou MAX_CACHE_SIZE.

Exemple

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

Procédure RETIRE_FILES

DBMS_EXT_TABLE_CACHE.RETIRE_FILES supprime les fichiers du cache qui sont plus anciens que l'intervalle indiqué. Les fichiers sont supprimés en fonction de l'intervalle de temps calculé à l'aide de la valeur du paramètre BEFORE.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.

before

Le paramètre before accepte une valeur INTERVAL DAY TO SECOND et sert à calculer l'intervalle de temps entre la valeur before et l'horodatage en cours. L'intervalle de temps qui en résulte est ensuite utilisé pour supprimer les fichiers du cache.

Exemple

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

Procédure SET_USER_PROPERTY

La procédure DBMS_EXT_TABLE_CACHE.SET_USER_PROPERTY définit la préférence de mise en cache pour un schéma.

Syntaxe

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

Paramètres

Paramètre Description

property_name

Indique le nom de propriété.

Les valeurs valides pour property_name sont les suivantes :

  • MAX_CACHE_PERCENT

  • MAX_CACHE_SIZE

property_value

Spécifie la valeur de propriété.

owner

Indique le nom du schéma.

Exemple

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

Procédure VALIDATE

La procédure DBMS_EXT_TABLE_CACHE.VALIDATE valide le cache de table externe. Une erreur est signalée si la table externe référencée est introuvable dans la base de données.

Syntaxe

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

Paramètres

Paramètre Description

owner

Indique le nom du schéma.

table_name

Indique le nom de la table externe.

raise_errors

Signale lorsqu'un cache de table externe est marqué comme non valide.

Exemple

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