DBMS_CACHE-Package

Das Package DBMS_CACHE vereinfacht das automatische Caching für Lake-Caches in einer autonomen AI-Datenbankinstanz, einschließlich Caches, die für externe Tabellen und für Tabellen erstellt wurden, die über gemountete Kataloge bereitgestellt werden.

Zusammenfassung der DBMS_CACHE-Unterprogramme

In dieser Tabelle werden die Unterprogramme zusammengefasst, die im Package DBMS_CACHE enthalten sind.

Unterprogramm Beschreibung
CLEAR-Verfahren Löscht alle Lake-Caches für einen angegebenen Benutzer.
Prozedur ENABLE_AUTO Aktiviert das automatische Caching global oder für mindestens ein Schema und legt optional GLOBAL_CACHE_SIZE oder GLOBAL_CACHE_PERCENT fest.
Prozedur GET_GLOBAL_PROPERTY Ruft automatische Lake Cache-Eigenschaften ab.
Prozedur GET_USER_PROPERTY Ruft automatische Lake Cache-Eigenschaften für einen angegebenen Benutzer ab.
REFRESH-Verfahren Aktualisiert alle Lake-Caches für einen angegebenen Benutzer.
Prozedur SET_GLOBAL_PROPERTY Gibt die automatische Lake Cache-Voreinstellung für alle Datenbankbenutzer an.
SET_USER_PROPERTY-Prozedur Gibt die automatische Lake Cache-Voreinstellung für einen angegebenen Benutzer an.

CLEAR-Verfahren

Verwenden Sie die Prozedur DBMS_CACHE.CLEAR, um alle Lake-Caches für einen angegebenen Benutzer zu löschen.

Die Prozedur DBMS_CACHE.CLEAR löscht alle Lake-Caches und gibt den Speicherplatz frei, ähnlich wie der Befehl DROP für eine Datenbanktabelle.

Syntax

DBMS_CACHE.CLEAR (
    owner    IN   VARCHAR2
);

Parameter

Parameter Beschreibung
owner Legt den Schemanamen fest.

Beispiel

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

Hinweis zur Verwendung

  • Sie müssen als Benutzer ADMIN angemeldet sein oder über die Berechtigung EXECUTE für das Package DBMS_CACHE verfügen, um einen Cache zu löschen.

Prozedur ENABLE_AUTO

Mit der Prozedur DBMS_CACHE.ENABLE_AUTO können Sie das automatische Caching global oder für mindestens ein Schema aktivieren und optional die globale Cache-Quota festlegen.

Syntax

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

Parameter

Parameter Beschreibung
users Gibt ein JSON-Array im CLOB-Format an, das Schemanamen enthält. Wenn users NULL ist, wird das automatische Caching global für alle Benutzer aktiviert.
global_cache_size Gibt die maximale globale Cache-Quota in Byte für die Datenbank an.
global_cache_pct Gibt die Quota für den globalen Cache als Prozentsatz der maximalen Datenbankgröße an.

Hinweise zur Verwendung

  • Die Prozedur aktiviert das automatische Caching, indem AUTO_CACHE festgelegt wird.

  • Wenn global_cache_size oder global_cache_pct angegeben ist, legt die Prozedur die entsprechende globale Quota-Eigenschaft fest.

  • Wenn weder global_cache_size noch global_cache_pct angegeben ist, setzt die Prozedur GLOBAL_CACHE_PERCENT auf 20.

  • Verwenden Sie DBMS_CACHE.SET_GLOBAL_PROPERTY oder DBMS_CACHE.SET_USER_PROPERTY mit AUTO_CACHE = 0, um das automatische Caching zu deaktivieren.

Beispiele

Beispiel für die globale Aktivierung von automatischem Caching:

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

Beispiel für die Aktivierung des automatischen Caches für ausgewählte Schemas:

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

Prozedur GET_GLOBAL_PROPERTY

Die Prozedur DBMS_CACHE.GET_GLOBAL_PROPERTY ruft die automatischen Lake Cache-Voreinstellungen für alle Benutzer in der Datenbank ab. Diese Prozedur ist überladen.

Syntax

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

Parameter

Parameter Beschreibung
property_name

Gibt den Namen der Eigenschaft an.

Folgende gültige Werte sind für property_name verfügbar:

  • AUTO_CACHE: Aktiviert oder deaktiviert das automatische Caching im Datenbankgeltungsbereich. Die numerischen Werte sind 1 und 0. Der Standardwert ist 0.

  • BEHAVIOR: Steuert das Verhalten beim automatischen Laden des Cache. Die Zeichenfolgenwerte sind AUTO, AGGRESSIVE und COOPERATIVE. Der Standardwert ist AUTO.

  • GLOBAL_CACHE_SIZE: Gibt die globale Cache-Quota in Byte für die Datenbank an. Der Wert -1 gibt eine unbegrenzte Quota an. -1 bedeutet eine unbegrenzte Quota.

  • GLOBAL_CACHE_PERCENT: Gibt die Quota für den globalen Cache als Prozentsatz der maximalen Datenbankgröße an.

  • MAX_CACHE_SIZE: Gibt die maximale Standardcachegröße in Byte für Schemas ohne Überschreibung auf Benutzerebene an.

  • MAX_CACHE_PERCENT: Gibt die maximale Standardcachegröße als Prozentsatz der anwendbaren Quota-Basis für Schemas ohne Überschreibung auf Benutzerebene an.

  • MAX_REFRESH_WINDOW: Gibt das maximale Zeitfenster in Sekunden an, das zum Aktualisieren von Lake-Caches zulässig ist.

  • AUTO_REFRESH_MODE: Gibt den Geltungsbereich an, in dem die Aktualisierung für AUTO-Caches ausgeführt wird.

property_value_num Ruft einen NUMBER-Wert für den angegebenen Eigenschaftsnamen ab.
property_value_str Ruft einen STRING-Wert für den angegebenen Eigenschaftsnamen ab.

Beispiel

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

Hinweise zur Verwendung

  • Sie müssen als Benutzer ADMIN angemeldet sein oder über die Berechtigung EXECUTE für das Package DBMS_CACHE verfügen, um diese Prozedur ausführen zu können.

  • GLOBAL_CACHE_SIZE und GLOBAL_CACHE_PERCENT definieren nur Quota. Sie aktivieren kein automatisches Caching. Verwenden Sie AUTO_CACHE oder DBMS_CACHE.ENABLE_AUTO, um das automatische Caching zu aktivieren.

  • Wenn sowohl GLOBAL_CACHE_SIZE als auch GLOBAL_CACHE_PERCENT festgelegt sind, wird der größere Wert verwendet. Wenn keine globale Quota-Eigenschaft explizit festgelegt ist, lautet der Standardwert für GLOBAL_CACHE_PERCENT 20.

  • Wenn sowohl MAX_CACHE_SIZE als auch MAX_CACHE_PERCENT festgelegt sind, wird der größere Wert verwendet. Wenn keine der Standard-Quota-Eigenschaften explizit festgelegt ist, lautet der Standardwert für MAX_CACHE_PERCENT 20.

Prozedur SET_GLOBAL_PROPERTY

Verwenden Sie DBMS_CACHE.SET_GLOBAL_PROPERTY, um globale automatische Caching-Eigenschaften für die Datenbank festzulegen. Diese Prozedur ist überladen.

AUTO_CACHE aktiviert oder deaktiviert das automatische Caching im Datenbankgeltungsbereich. GLOBAL_CACHE_SIZE und GLOBAL_CACHE_PERCENT definieren die globale Cache-Quota für alle externen Tabellencaches. MAX_CACHE_SIZE und MAX_CACHE_PERCENT definieren Standardvoreinstellungen für Quota auf Schemaebene für Schemas, die keine Überschreibung auf Benutzerebene aufweisen. Wenn Sie GLOBAL_CACHE_SIZE, GLOBAL_CACHE_PERCENT, MAX_CACHE_SIZE oder MAX_CACHE_PERCENT festlegen, wird das automatische Caching allein nicht aktiviert.

Syntax

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

Parameter

Parameter Beschreibung
property_name

Gibt den Namen der Eigenschaft an.

Folgende gültige Werte sind für property_name verfügbar:

  • AUTO_CACHE: Aktiviert oder deaktiviert das automatische Caching im Datenbankgeltungsbereich. Gültige numerische Werte sind 1 und 0. Der Standardwert ist 0.

  • BEHAVIOR: Steuert das Verhalten beim automatischen Laden des Cache. Die Zeichenfolgenwerte sind AUTO, AGGRESSIVE und COOPERATIVE. Der Standardwert ist AUTO.

  • GLOBAL_CACHE_SIZE: Gibt die instanzweite globale Cache-Quota in Byte an. -1 bedeutet unbegrenzte Quota.

  • GLOBAL_CACHE_PERCENT: Gibt die instanzweite globale Cache-Quota als Prozentsatz der maximalen Datenbankgröße an.

  • MAX_CACHE_SIZE: Gibt die maximale Standardcachegröße in Byte für Schemas ohne Überschreibung auf Benutzerebene an.

  • MAX_CACHE_PERCENT: Gibt die maximale Standardcachegröße als Prozentsatz der anwendbaren Quota-Basis für Schemas ohne Überschreibung auf Benutzerebene an.

  • MAX_REFRESH_WINDOW: Gibt das maximale Zeitfenster in Sekunden an, das zum Aktualisieren externer Tabellencaches zulässig ist.

  • AUTO_REFRESH_MODE: Gibt den Geltungsbereich an, in dem die Aktualisierung für AUTO-Caches ausgeführt wird.

property_value_num Stellt einen NUMBER-Wert für den angegebenen Eigenschaftsnamen bereit.
property_value_str Stellt einen STRING-Wert für den angegebenen Eigenschaftsnamen bereit.

Beispiele

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

Hinweise zur Verwendung

  • Sie müssen als Benutzer ADMIN angemeldet sein oder über die Berechtigung EXECUTE für das Package DBMS_CACHE verfügen, um diese Prozedur ausführen zu können.

  • Wenn sowohl GLOBAL_CACHE_SIZE als auch GLOBAL_CACHE_PERCENT festgelegt sind, wird der größere Wert verwendet.

  • Wenn keine globale Quota-Eigenschaft explizit festgelegt ist, lautet der Standardwert für GLOBAL_CACHE_PERCENT 20.

  • Wenn sowohl MAX_CACHE_SIZE als auch MAX_CACHE_PERCENT festgelegt sind, wird der größere Wert verwendet.

  • Wenn keine der Standard-Quota-Eigenschaften explizit festgelegt ist, lautet der Standardwert für MAX_CACHE_PERCENT 20.

  • Wenn MAX_CACHE_SIZE größer als GLOBAL_CACHE_SIZE festgelegt ist, löst die Datenbank einen Fehler aus.

  • Manuelle Caches und AUTO-Caches belegen denselben Quota-Pool.

  • Die Eigenschaft MAX_REFRESH_WINDOW gibt in Sekunden an, wie lange maximal Lake-Caches aktualisiert werden dürfen. Wenn die Aktualisierung den angegebenen Grenzwert überschreitet, wird die Cacheaktualisierung normal beendet, und alle verbleibenden zulässigen Caches werden für den nächsten Aktualisierungszyklus in die Queue gestellt.

  • Wenn Sie Caches mit der Prozedur DBMS_CACHE.REFRESH aktualisieren, hat der Prozedurparameter Vorrang vor der Eigenschaft AUTO_REFRESH_MODE.

    Weitere Informationen finden Sie unter Prozedur REFRESH.

REFRESH-Verfahren

Verwenden Sie die Prozedur DBMS_CACHE.REFRESH, um alle AUTO-Lake-Caches für einen angegebenen Benutzer zu aktualisieren.

Syntax

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

Parameter

Parameter Beschreibung
owner Legt den Schemanamen fest.
refresh_type

Gibt die Aktualisierungsoption an.

Folgende gültige refresh_type-Werte sind verfügbar:

  • ALL: Alle vorhandenen AUTO-Caches für das angegebene Schema werden aktualisiert, und bei Bedarf werden neue Caches für den angegebenen Benutzer erstellt. Dies ist das Standardverhalten.

  • CURRENT: Es werden nur vorhandene Caches aktualisiert. Für den angegebenen Benutzer werden keine neuen Caches hinzugefügt.

  • NEW: Für den angegebenen Benutzer werden nur neue Caches erstellt.

Dieser Parameter ist optional und standardmäßig ALL.

Beispiel

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

Hinweise zur Verwendung

  • Sie müssen als Benutzer ADMIN angemeldet sein oder über die Berechtigung EXECUTE für das Package DBMS_CACHE verfügen, um diese Prozedur ausführen zu können.

  • Wenn Sie keinen Wert für den Parameter refresh_type angeben, führt Oracle eine Aktualisierung basierend auf dem Wert auto_refresh_mode durch. Der Standardwert für auto_refresh_mode ist ALL.

  • Wenn die Eigenschaft MAX_REFRESH_WINDOW festgelegt ist, versucht Oracle, eine Aktualisierung im angegebenen Fenster durchzuführen. Wenn die Aktualisierung den angegebenen Grenzwert überschreitet, wird die Cacheaktualisierung normal beendet, und alle verbleibenden zulässigen Caches werden für den nächsten Aktualisierungszyklus in die Queue gestellt.

  • Alle AUTO-Caches in der Datenbank werden mit einem Räumungsalgorithmus verwaltet, der dem LRU (Least Recently Used) ähnelt. Unter Speicherplatzdruck werden Caches, auf die zuletzt zugegriffen wurde, während des Aktualisierungsprozesses automatisch gelöscht, um den Speicherplatz freizugeben.

Prozedur GET_USER_PROPERTY

Verwenden Sie die Prozedur DBMS_CACHE.GET_USER_PROPERTY, um automatische Caching-Eigenschaften für einen Benutzer abzurufen.

Syntax

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

Parameter

Parameter Beschreibung
property_name

Gibt den Namen der Eigenschaft an.

Folgende gültige Werte sind für property_name verfügbar:

  • AUTO_CACHE: Aktiviert oder deaktiviert das automatische Caching für das angegebene Schema. Gültige numerische Werte sind 1 und 0.

  • MAX_CACHE_SIZE: Gibt die maximale Cachegröße auf Schemaebene in Byte an.

  • MAX_CACHE_PERCENT: Gibt die maximale Cachegröße auf Schemaebene als Prozentsatz der anwendbaren Quota-Basis an.

  • AUTO_REFRESH_MODE: Gibt den Geltungsbereich an, in dem die Aktualisierung für AUTO-Caches ausgeführt wird.

owner Legt den Schemanamen fest. Dieser Parameter ist optional und standardmäßig das aktuelle Schema.
property_value_str Ruft einen STRING-Wert für den angegebenen Eigenschaftsnamen ab.
property_value_num Ruft einen NUMBER-Wert für den angegebenen Eigenschaftsnamen ab.

Beispiel

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

Hinweise zur Verwendung

  • Sie müssen als Benutzer ADMIN angemeldet sein oder über die Berechtigung EXECUTE für das Package DBMS_CACHE verfügen, um diese Prozedur ausführen zu können.

  • MAX_CACHE_SIZE und MAX_CACHE_PERCENT sind Quota-Steuerelemente auf Schemaebene. Sie aktivieren das automatische Caching nicht selbst. Mit AUTO_CACHE können Sie das automatische Caching für das angegebene Schema aktivieren oder deaktivieren.

  • Wenn sowohl MAX_CACHE_SIZE als auch MAX_CACHE_PERCENT festgelegt sind, wird der größere Wert verwendet. Wenn keine Quota-Eigenschaft auf Schemaebene explizit festgelegt ist, lautet der Standardwert für MAX_CACHE_PERCENT 20.

Prozedur SET_USER_PROPERTY

Verwenden Sie DBMS_CACHE.SET_USER_PROPERTY, um Eigenschaften für das automatische Caching für ein angegebenes Schema festzulegen. Verwenden Sie AUTO_CACHE, um das automatische Caching für das Schema zu aktivieren oder zu deaktivieren. Verwenden Sie MAX_CACHE_SIZE und MAX_CACHE_PERCENT, um Quota-Voreinstellungen auf Schemaebene im globalen Quota-Modell festzulegen.

Syntax

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

Parameter

Parameter Beschreibung
property_name

Gibt den Namen der Eigenschaft an.

Folgende gültige Werte sind für property_name verfügbar:

  • AUTO_CACHE: Aktiviert oder deaktiviert das automatische Caching für das angegebene Schema. Gültige numerische Werte sind 1 und 0.

  • MAX_CACHE_SIZE: Gibt die maximale Cachegröße auf Schemaebene in Byte an.

  • MAX_CACHE_PERCENT: Gibt die maximale Cachegröße auf Schemaebene als Prozentsatz der anwendbaren Quota-Basis an.

  • AUTO_REFRESH_MODE: Gibt den Geltungsbereich an, in dem die Aktualisierung für AUTO-Caches ausgeführt wird.

    Folgende gültige Werte sind für AUTO_REFRESH_MODE verfügbar:

    • ALL: Alle vorhandenen AUTO-Caches im Schema werden aktualisiert, und bei Bedarf werden neue Caches erstellt. Dies ist das Standardverhalten.

    • CURRENT: Nur vorhandene AUTO-Caches werden aktualisiert. Es werden keine neuen Caches hinzugefügt.

    • NEW: Es werden nur neue AUTO-Caches erstellt.

property_value_num Stellt einen NUMBER-Wert für den angegebenen Eigenschaftsnamen bereit.
property_value_str Stellt einen STRING-Wert für den angegebenen Eigenschaftsnamen bereit.
owner Legt den Schemanamen fest. Dieser Parameter ist optional und standardmäßig das aktuelle Schema.

Beispiele

Beispiel für die Aktivierung von automatischem Caching für ein Schema:

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

Beispiel zum Festlegen einer Cache-Quota auf Schemaebene:

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

Hinweise zur Verwendung

  • Sie müssen als Benutzer ADMIN angemeldet sein oder über die Berechtigung EXECUTE für das Package DBMS_CACHE verfügen, um diese Prozedur ausführen zu können.

  • Einstellungen auf Benutzerebene überschreiben globale Einstellungen.

  • MAX_CACHE_SIZE und MAX_CACHE_PERCENT aktivieren das automatische Caching nicht selbst.

  • Wenn sowohl MAX_CACHE_SIZE als auch MAX_CACHE_PERCENT festgelegt sind, wird der größere Wert verwendet.

  • Wenn keine Quota-Eigenschaft auf Schemaebene explizit festgelegt ist, lautet der Standardwert für MAX_CACHE_PERCENT 20.

  • Wenn MAX_CACHE_SIZE größer als GLOBAL_CACHE_SIZE festgelegt ist, löst die Datenbank einen Fehler aus.

  • Manuelle Policys setzen automatisches Verhalten immer außer Kraft.