Package DBMS_CACHE

Le package DBMS_CACHE facilite la mise en cache automatique des caches de lac dans une instance de base de données Autonomous AI, y compris les caches créés pour les tables externes et pour les tables exposées via des catalogues montés.

Récapitulatif des sous-programmes DBMS_CACHE

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

Procédure CLEAR

Utilisez la procédure DBMS_CACHE.CLEAR pour supprimer tous les caches de lac d'un utilisateur donné.

La procédure DBMS_CACHE.CLEAR supprime tous les caches de lac et libère l'espace de stockage, comme la commande DROP fonctionne sur une table de base de données.

Syntaxe

DBMS_CACHE.CLEAR (
    owner    IN   VARCHAR2
);

Paramètres

Exemple

BEGIN
 DBMS_CACHE.CLEAR (
    owner => 'SALES');
END;
/

Remarque sur l'utilisation

• Vous devez être connecté en tant qu'utilisateur ADMIN ou disposer du privilège EXECUTE sur le package DBMS_CACHE pour vider un cache.

Procédure ENABLE_AUTO

Utilisez la procédure DBMS_CACHE.ENABLE_AUTO pour activer la mise en cache automatique de manière globale ou pour un ou plusieurs schémas, et définissez éventuellement le quota global de cache.

Syntaxe

DBMS_CACHE.ENABLE_AUTO (
    users             IN   CLOB   DEFAULT NULL,
    global_cache_size IN   NUMBER DEFAULT NULL,
    global_cache_pct  IN   NUMBER DEFAULT NULL
);

Paramètres

Notes d'utilisation

• La procédure active la mise en cache automatique en définissant AUTO_CACHE.

• Si global_cache_size ou global_cache_pct est fourni, la procédure définit la propriété de quota global correspondante.

• Si ni global_cache_size ni global_cache_pct n'est fourni, la procédure définit GLOBAL_CACHE_PERCENT sur 20.

• Utilisez DBMS_CACHE.SET_GLOBAL_PROPERTY ou DBMS_CACHE.SET_USER_PROPERTY avec AUTO_CACHE = 0 pour désactiver la mise en cache automatique.

Exemples

Exemple d'activation de la mise en cache automatique de manière globale :

BEGIN
  DBMS_CACHE.ENABLE_AUTO(
    users            => NULL,
    global_cache_pct => 20);
END;
/

Exemple d'activation de la mise en cache automatique pour les schémas sélectionnés :

DECLARE
  l_users CLOB := '["HR","SALES"]';
BEGIN
  DBMS_CACHE.ENABLE_AUTO(
    users             => l_users,
    global_cache_size => 21474836480);
END;
/

Procédure GET_GLOBAL_PROPERTY

La procédure DBMS_CACHE.GET_GLOBAL_PROPERTY extrait les préférences automatiques de cache de lac pour tous les utilisateurs de la base de données. Cette procédure est surchargée.

Syntaxe

DBMS_CACHE.GET_GLOBAL_PROPERTY (
    property_name       IN   VARCHAR2,
    property_value_num  OUT  NUMBER);

DBMS_CACHE.GET_GLOBAL_PROPERTY (
    property_name       IN   VARCHAR2,
    property_value_str  OUT  VARCHAR2);

Paramètres

Exemple

SET SERVEROUTPUT ON;
DECLARE
  l_auto_cache NUMBER;
BEGIN
  DBMS_CACHE.GET_GLOBAL_PROPERTY(
    property_name      => 'AUTO_CACHE',
    property_value_num => l_auto_cache);
  DBMS_OUTPUT.PUT_LINE('AUTO_CACHE=' || l_auto_cache);
END;
/

Notes d'utilisation

• Vous devez être connecté en tant qu'utilisateur ADMIN ou disposer du privilège EXECUTE sur le package DBMS_CACHE pour exécuter cette procédure.

• GLOBAL_CACHE_SIZE et GLOBAL_CACHE_PERCENT définissent un quota uniquement. Ils n'activent pas la mise en cache automatique. Utilisez AUTO_CACHE ou DBMS_CACHE.ENABLE_AUTO pour activer la mise en cache automatique.

• Si GLOBAL_CACHE_SIZE et GLOBAL_CACHE_PERCENT sont définis, la valeur la plus élevée est utilisée. Si aucune propriété de quota global n'est explicitement définie, GLOBAL_CACHE_PERCENT prend par défaut la valeur 20.

• Si MAX_CACHE_SIZE et MAX_CACHE_PERCENT sont définis, la valeur la plus élevée est utilisée. Si aucune propriété de quota par défaut n'est explicitement définie, MAX_CACHE_PERCENT prend par défaut la valeur 20.

Procédure SET_GLOBAL_PROPERTY

Utilisez DBMS_CACHE.SET_GLOBAL_PROPERTY pour définir les propriétés globales de mise en cache automatique de la base de données. Cette procédure est surchargée.

AUTO_CACHE active ou désactive la mise en cache automatique au niveau de la portée de la base de données. GLOBAL_CACHE_SIZE et GLOBAL_CACHE_PERCENT définissent le quota global de cache pour tous les caches de table externes. MAX_CACHE_SIZE et MAX_CACHE_PERCENT définissent des préférences de quota de niveau schéma par défaut pour les schémas qui n'ont pas de remplacement de niveau utilisateur. La définition de GLOBAL_CACHE_SIZE, GLOBAL_CACHE_PERCENT, MAX_CACHE_SIZE ou MAX_CACHE_PERCENT n'active pas en soi la mise en cache automatique.

Syntaxe

DBMS_CACHE.SET_GLOBAL_PROPERTY (
    property_name      IN   VARCHAR2,
    property_value_num IN   NUMBER);

DBMS_CACHE.SET_GLOBAL_PROPERTY (
    property_name      IN   VARCHAR2,
    property_value_str IN   VARCHAR2);

Paramètres

Exemples

BEGIN
  DBMS_CACHE.SET_GLOBAL_PROPERTY(
    property_name      => 'AUTO_CACHE',
    property_value_num => 1);
END;
/

BEGIN
  DBMS_CACHE.SET_GLOBAL_PROPERTY(
    property_name      => 'GLOBAL_CACHE_PERCENT',
    property_value_num => 20);
END;
/

BEGIN
  DBMS_CACHE.SET_GLOBAL_PROPERTY(
    property_name      => 'MAX_CACHE_PERCENT',
    property_value_num => 25);
END;
/

BEGIN
  DBMS_CACHE.SET_GLOBAL_PROPERTY(
    property_name      => 'BEHAVIOR',
    property_value_str => 'COOPERATIVE');
END;
/

BEGIN
  DBMS_CACHE.SET_GLOBAL_PROPERTY(
    property_name      => 'AUTO_REFRESH_MODE',
    property_value_str => 'NEW');
END;
/

BEGIN
  DBMS_CACHE.SET_GLOBAL_PROPERTY(
    property_name      => 'MAX_REFRESH_WINDOW',
    property_value_num => 20);
END;
/

Notes d'utilisation

• Vous devez être connecté en tant qu'utilisateur ADMIN ou disposer du privilège EXECUTE sur le package DBMS_CACHE pour exécuter cette procédure.

• Si GLOBAL_CACHE_SIZE et GLOBAL_CACHE_PERCENT sont définis, la valeur la plus élevée est utilisée.

• Si aucune propriété de quota global n'est explicitement définie, GLOBAL_CACHE_PERCENT prend par défaut la valeur 20.

• Si MAX_CACHE_SIZE et MAX_CACHE_PERCENT sont définis, la valeur la plus élevée est utilisée.

• Si aucune propriété de quota par défaut n'est explicitement définie, MAX_CACHE_PERCENT prend par défaut la valeur 20.

• Si la valeur MAX_CACHE_SIZE est supérieure à GLOBAL_CACHE_SIZE, la base de données génère une erreur.

• Les caches manuels et les caches AUTO utilisent le même pool de quotas.

• La propriété MAX_REFRESH_WINDOW indique, en secondes, la durée maximale autorisée pour l'actualisation des caches de lac. Si l'actualisation dépasse la limite spécifiée, l'actualisation du cache se ferme normalement et tous les caches admissibles restants sont mis en file d'attente pour le cycle d'actualisation suivant.

• Lorsque vous actualisez les caches à l'aide de la procédure DBMS_CACHE.REFRESH, le paramètre de procédure est prioritaire sur la propriété AUTO_REFRESH_MODE.

  Pour plus d'informations, reportez-vous à Procédure REFRESH.

Procédure REFRESH

Utilisez la procédure DBMS_CACHE.REFRESH pour actualiser tous les caches de lac AUTO pour un utilisateur donné.

Syntaxe

DBMS_CACHE.REFRESH (
      owner          IN VARCHAR2,
      refresh_type   IN VARCHAR2 DEFAULT ALL
);

Paramètres

Exemple

BEGIN
    DBMS_CACHE.REFRESH (
      owner          => 'SALES',
      refresh_type   => 'CURRENT');
END;
/

Notes d'utilisation

• Vous devez être connecté en tant qu'utilisateur ADMIN ou disposer du privilège EXECUTE sur le package DBMS_CACHE pour exécuter cette procédure.

• Si vous n'indiquez pas de valeur pour le paramètre refresh_type, Oracle effectue une actualisation en fonction de la valeur auto_refresh_mode. La valeur par défaut de auto_refresh_mode est ALL.

• Lorsque la propriété MAX_REFRESH_WINDOW est définie, Oracle tente d'effectuer une actualisation dans la fenêtre indiquée. Si l'actualisation dépasse la limite spécifiée, l'actualisation du cache se ferme normalement et tous les caches admissibles restants sont mis en file d'attente pour le cycle d'actualisation suivant.

• Tous les caches AUTO de la base de données sont gérés à l'aide d'un algorithme d'expulsion similaire à LRU (Least Recent Used). Lorsque l'espace est insuffisant, les caches auxquels vous avez accédé le plus récemment sont automatiquement supprimés au cours du processus d'actualisation pour libérer l'espace de stockage.

Procédure GET_USER_PROPERTY

Utilisez la procédure DBMS_CACHE.GET_USER_PROPERTY pour extraire les propriétés de mise en cache automatique d'un utilisateur.

Syntaxe

DBMS_CACHE.GET_USER_PROPERTY (
    property_name      IN   VARCHAR2,
    owner              IN   VARCHAR2 DEFAULT NULL,
    property_value_str OUT  VARCHAR2);

DBMS_CACHE.GET_USER_PROPERTY (
    property_name      IN   VARCHAR2,
    owner              IN   VARCHAR2 DEFAULT NULL,
    property_value_num OUT  NUMBER);

Paramètres

Exemple

SET SERVEROUTPUT ON;
DECLARE
  l_auto_cache NUMBER;
BEGIN
  DBMS_CACHE.GET_USER_PROPERTY(
    property_name      => 'AUTO_CACHE',
    owner              => 'HR',
    property_value_num => l_auto_cache);
  DBMS_OUTPUT.PUT_LINE('AUTO_CACHE=' || l_auto_cache);
END;
/

Notes d'utilisation

• Vous devez être connecté en tant qu'utilisateur ADMIN ou disposer du privilège EXECUTE sur le package DBMS_CACHE pour exécuter cette procédure.

• MAX_CACHE_SIZE et MAX_CACHE_PERCENT sont des contrôles de quota au niveau du schéma. Ils ne permettent pas la mise en cache automatique par eux-mêmes. Utilisez AUTO_CACHE pour activer ou désactiver la mise en cache automatique pour le schéma indiqué.

• Si MAX_CACHE_SIZE et MAX_CACHE_PERCENT sont définis, la valeur la plus élevée est utilisée. Si aucune propriété de quota de niveau schéma n'est explicitement définie, MAX_CACHE_PERCENT prend par défaut la valeur 20.

Procédure SET_USER_PROPERTY

Utilisez DBMS_CACHE.SET_USER_PROPERTY pour définir les propriétés de mise en cache automatique d'un schéma indiqué. Utilisez AUTO_CACHE pour activer ou désactiver la mise en cache automatique pour le schéma. Utilisez MAX_CACHE_SIZE et MAX_CACHE_PERCENT pour définir les préférences de quota au niveau du schéma dans le modèle de quota global.

Syntaxe

DBMS_CACHE.SET_USER_PROPERTY (
    property_name       IN   VARCHAR2,
    property_value_num  IN   NUMBER,
    owner               IN   VARCHAR2 DEFAULT NULL);

DBMS_CACHE.SET_USER_PROPERTY (
    property_name       IN   VARCHAR2,
    property_value_str  IN   VARCHAR2,
    owner               IN   VARCHAR2 DEFAULT NULL
);

Paramètres

Exemples

Exemple d'activation de la mise en cache automatique pour un schéma :

BEGIN
  DBMS_CACHE.SET_USER_PROPERTY(
    property_name      => 'AUTO_CACHE',
    property_value_num => 1,
    owner              => 'SALES');
END;
/

Exemple de définition d'un quota de cache au niveau schéma :

BEGIN
  DBMS_CACHE.SET_USER_PROPERTY(
    property_name      => 'MAX_CACHE_SIZE',
    property_value_num => 5368709120,
    owner              => 'SALES');
END;
/

Notes d'utilisation

• Vous devez être connecté en tant qu'utilisateur ADMIN ou disposer du privilège EXECUTE sur le package DBMS_CACHE pour exécuter cette procédure.

• Les paramètres au niveau de l'utilisateur remplacent les paramètres globaux.

• MAX_CACHE_SIZE et MAX_CACHE_PERCENT n'activent pas la mise en cache automatique par eux-mêmes.

• Si MAX_CACHE_SIZE et MAX_CACHE_PERCENT sont définis, la valeur la plus élevée est utilisée.

• Si aucune propriété de quota de niveau schéma n'est explicitement définie, MAX_CACHE_PERCENT prend par défaut la valeur 20.

• Si la valeur MAX_CACHE_SIZE est supérieure à GLOBAL_CACHE_SIZE, la base de données génère une erreur.

• La stratégie manuelle remplace toujours le comportement automatique.