Documentação do Oracle Cloud Infrastructure

Pacote DBMS_CACHE

O pacote DBMS_CACHE facilita o armazenamento automático em cache para Lake Caches em uma instância do Autonomous AI Database, incluindo caches criados para tabelas externas e para tabelas expostas por meio de catálogos montados.

Resumo dos Subprogramas DBMS_CACHE

Esta tabela resume os subprogramas incluídos no pacote DBMS_CACHE.

Subprograma Descrição
Procedimento CLEAR Limpa todos os Caches do Lake para um usuário especificado.
Procedimento ENABLE_AUTO Ativa o armazenamento automático em cache globalmente ou para um ou mais esquemas e, opcionalmente, define GLOBAL_CACHE_SIZE ou GLOBAL_CACHE_PERCENT.
Procedimento GET_GLOBAL_PROPERTY Recupera propriedades automáticas do Lake Cache.
Procedimento GET_USER_PROPERTY Recupera propriedades automáticas do Lake Cache para um usuário especificado.
REFRESH Procedimento Atualiza todos os Caches do Lake para um usuário especificado.
Procedimento SET_GLOBAL_PROPERTY Especifica a preferência automática do Lake Cache para todos os usuários do banco de dados.
Procedimento SET_USER_PROPERTY Especifica a preferência automática do Lake Cache para um usuário especificado.

Procedimento CLEAR

Use o procedimento DBMS_CACHE.CLEAR para eliminar todos os Caches do Lake para um usuário especificado.

O procedimento DBMS_CACHE.CLEAR elimina todos os Caches do Lake e libera o espaço de armazenamento, semelhante ao modo como o comando DROP funciona em uma tabela de banco de dados.

Sintaxe

DBMS_CACHE.CLEAR (
    owner    IN   VARCHAR2
);

Parâmetros

Parâmetro Descrição
owner Especifica o nome do esquema.

Exemplo

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

Observação do Uso

  • Você deve estar conectado como usuário ADMIN ou ter o privilégio EXECUTE no pacote DBMS_CACHE para limpar um cache.

Procedimento ENABLE_AUTO

Use o procedimento DBMS_CACHE.ENABLE_AUTO para ativar o armazenamento automático em cache globalmente ou para um ou mais esquemas e, opcionalmente, definir a cota de cache global.

Sintaxe

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

Parâmetros

Parâmetro Descrição
users Especifica um array JSON no formato CLOB que contém nomes de esquema. Se users for NULL, o armazenamento automático em cache será ativado globalmente para todos os usuários.
global_cache_size Especifica a cota máxima do cache global, em bytes, para o banco de dados.
global_cache_pct Especifica a cota de cache global como uma porcentagem do tamanho máximo do banco de dados.

Observações de Uso

  • O procedimento ativa o armazenamento automático em cache definindo AUTO_CACHE.

  • Se global_cache_size ou global_cache_pct for fornecido, o procedimento definirá a propriedade de cota global correspondente.

  • Se nem global_cache_size nem global_cache_pct forem fornecidos, o procedimento definirá GLOBAL_CACHE_PERCENT como 20.

  • Use DBMS_CACHE.SET_GLOBAL_PROPERTY ou DBMS_CACHE.SET_USER_PROPERTY com AUTO_CACHE = 0 para desativar o armazenamento automático em cache.

Exemplos

Exemplo para ativar o armazenamento automático em cache globalmente:

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

Exemplo para ativar o armazenamento automático em cache para esquemas selecionados:

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

GET_GLOBAL_PROPERTY Procedimento

O procedimento DBMS_CACHE.GET_GLOBAL_PROPERTY recupera as preferências automáticas do Lake Cache para todos os usuários do banco de dados. Este procedimento é sobrecarregado.

Sintaxe

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

Parâmetros

Parâmetro Descrição
property_name

Especifica o nome da propriedade.

Estes são os valores válidos para property_name:

  • AUTO_CACHE: Ativa ou desativa o armazenamento automático em cache no escopo do banco de dados. Os valores numéricos são 1 e 0. O valor padrão é 0.

  • BEHAVIOR: Controla o comportamento de carregamento automático do cache. Os valores da string são AUTO, AGGRESSIVE e COOPERATIVE. O valor padrão é AUTO.

  • GLOBAL_CACHE_SIZE: Especifica a cota de cache global, em bytes, para o banco de dados. Um valor de -1 indica uma cota ilimitada. -1 significa cota ilimitada.

  • GLOBAL_CACHE_PERCENT: Especifica a cota de cache global como uma porcentagem do tamanho máximo do banco de dados.

  • MAX_CACHE_SIZE: Especifica o tamanho máximo padrão do cache em bytes para esquemas sem uma substituição no nível do usuário.

  • MAX_CACHE_PERCENT: Especifica o tamanho máximo padrão do cache como uma porcentagem da base de cota aplicável para esquemas sem uma substituição no nível do usuário.

  • MAX_REFRESH_WINDOW: Especifica a janela de tempo máxima, em segundos, permitida para atualizar caches de lake.

  • AUTO_REFRESH_MODE: Especifica o escopo no qual a atualização é executada para caches AUTO.
property_value_num Recupera um valor NUMBER para o nome de propriedade especificado.
property_value_str Recupera um valor STRING para o nome de propriedade especificado.

Exemplo

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

Observações de Uso

  • Você deve estar conectado como usuário ADMIN ou ter o privilégio EXECUTE no pacote DBMS_CACHE para executar este procedimento.

  • GLOBAL_CACHE_SIZE e GLOBAL_CACHE_PERCENT definem cota apenas. Eles não ativam o armazenamento automático em cache. Use AUTO_CACHE ou DBMS_CACHE.ENABLE_AUTO para ativar o armazenamento automático em cache.

  • Se GLOBAL_CACHE_SIZE e GLOBAL_CACHE_PERCENT forem definidos, o valor maior será usado. Se nenhuma propriedade de cota global for definida explicitamente, o padrão de GLOBAL_CACHE_PERCENT será 20.

  • Se MAX_CACHE_SIZE e MAX_CACHE_PERCENT forem definidos, o valor maior será usado. Se nenhuma propriedade de cota padrão for definida explicitamente, o padrão de MAX_CACHE_PERCENT será 20.

SET_GLOBAL_PROPERTY Procedimento

Use DBMS_CACHE.SET_GLOBAL_PROPERTY para definir propriedades globais de armazenamento automático em cache para o banco de dados. Este procedimento é sobrecarregado.

AUTO_CACHE ativa ou desativa o armazenamento automático em cache no escopo do banco de dados. GLOBAL_CACHE_SIZE e GLOBAL_CACHE_PERCENT definem a cota de cache global para todos os caches de tabelas externas. MAX_CACHE_SIZE e MAX_CACHE_PERCENT definem preferências de cota no nível do esquema padrão para esquemas que não têm uma substituição no nível do usuário. A definição de GLOBAL_CACHE_SIZE, GLOBAL_CACHE_PERCENT, MAX_CACHE_SIZE ou MAX_CACHE_PERCENT não permite, por si só, o armazenamento automático em cache.

Sintaxe

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

Parâmetros

Parâmetro Descrição
property_name

Especifica o nome da propriedade.

Estes são os valores válidos para property_name:

  • AUTO_CACHE: Ativa ou desativa o armazenamento automático em cache no escopo do banco de dados. Os valores numéricos válidos são 1 e 0. O valor padrão é 0.

  • BEHAVIOR: Controla o comportamento de carregamento automático do cache. Os valores da string são AUTO, AGGRESSIVE e COOPERATIVE. O valor padrão é AUTO.

  • GLOBAL_CACHE_SIZE: Especifica a cota do cache global em toda a instância em bytes. -1 significa cota ilimitada.

  • GLOBAL_CACHE_PERCENT: Especifica a cota do cache global em toda a instância como uma porcentagem do tamanho máximo do banco de dados.

  • MAX_CACHE_SIZE: Especifica o tamanho máximo padrão do cache em bytes para esquemas sem uma substituição no nível do usuário.

  • MAX_CACHE_PERCENT: Especifica o tamanho máximo padrão do cache como uma porcentagem da base de cota aplicável para esquemas sem uma substituição no nível do usuário.

  • MAX_REFRESH_WINDOW: Especifica a janela de tempo máxima, em segundos, permitida para atualizar caches de tabelas externas.

  • AUTO_REFRESH_MODE: Especifica o escopo no qual a atualização é executada para caches AUTO.
property_value_num Fornece um valor NUMBER para o nome de propriedade especificado.
property_value_str Fornece um valor STRING para o nome de propriedade especificado.

Exemplos

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

Observações de Uso

  • Você deve estar conectado como usuário ADMIN ou ter o privilégio EXECUTE no pacote DBMS_CACHE para executar este procedimento.

  • Se GLOBAL_CACHE_SIZE e GLOBAL_CACHE_PERCENT forem definidos, o valor maior será usado.

  • Se nenhuma propriedade de cota global for definida explicitamente, o padrão de GLOBAL_CACHE_PERCENT será 20.

  • Se MAX_CACHE_SIZE e MAX_CACHE_PERCENT forem definidos, o valor maior será usado.

  • Se nenhuma propriedade de cota padrão for definida explicitamente, o padrão de MAX_CACHE_PERCENT será 20.

  • Se MAX_CACHE_SIZE for definido como maior que GLOBAL_CACHE_SIZE, o banco de dados gerará um erro.

  • Caches manuais e caches AUTO consomem o mesmo pool de cotas.

  • A propriedade MAX_REFRESH_WINDOW especifica, em segundos, o tempo máximo permitido para atualizar os Caches do Lake. Se a atualização exceder o limite especificado, a atualização de cache será encerrada normalmente e quaisquer caches elegíveis restantes serão enfileirados para o próximo ciclo de atualização.

  • Quando você atualiza caches usando o procedimento DBMS_CACHE.REFRESH, o parâmetro de procedimento tem precedência sobre a propriedade AUTO_REFRESH_MODE.

    Consulte Procedimento REFRESH para obter mais informações.

REFRESH Procedimento

Use o procedimento DBMS_CACHE.REFRESH para atualizar todos os Caches do Lake AUTO para um usuário especificado.

Sintaxe

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

Parâmetros

Parâmetro Descrição
owner Especifica o nome do esquema.
refresh_type

Especifica a opção de atualização.

Estes são os valores válidos de refresh_type:

  • ALL: Todos os caches AUTO existentes para o esquema especificado são atualizados e, se necessário, novos caches são criados para o usuário especificado. Esse é o valor padrão.

  • CURRENT: somente os caches existentes são atualizados, nenhum novo caches é adicionado para o usuário especificado.

  • NEW: somente novos caches são criados para o usuário especificado.

Esse parâmetro é opcional e tem como padrão ALL.

Exemplo

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

Observações de Uso

  • Você deve estar conectado como usuário ADMIN ou ter o privilégio EXECUTE no pacote DBMS_CACHE para executar este procedimento.

  • Se você não especificar um valor para o parâmetro refresh_type, a Oracle executará a atualização com base no valor auto_refresh_mode. O valor padrão para auto_refresh_mode é ALL.

  • Quando a propriedade MAX_REFRESH_WINDOW é definida, o sistema Oracle tenta executar a atualização na janela especificada. Se a atualização exceder o limite especificado, a atualização de cache será encerrada normalmente e quaisquer caches elegíveis restantes serão enfileirados para o próximo ciclo de atualização.

  • Todos os caches AUTO no banco de dados são gerenciados usando um algoritmo de remoção semelhante ao LRU (Menos Usado Recentemente). Quando sob pressão de espaço, os caches que foram acessados menos recentemente são automaticamente eliminados durante o processo de atualização para liberar o espaço de armazenamento.

GET_USER_PROPERTY Procedimento

Use o procedimento DBMS_CACHE.GET_USER_PROPERTY para recuperar propriedades de armazenamento automático em cache para um usuário.

Sintaxe

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

Parâmetros

Parâmetro Descrição
property_name

Especifica o nome da propriedade.

Estes são os valores válidos para property_name:

  • AUTO_CACHE: Ativa ou desativa o armazenamento automático em cache para o esquema especificado. Os valores numéricos válidos são 1 e 0.

  • MAX_CACHE_SIZE: Especifica o tamanho máximo do cache no nível do esquema em bytes.

  • MAX_CACHE_PERCENT: Especifica o tamanho máximo do cache no nível do esquema como uma porcentagem da base de cota aplicável.

  • AUTO_REFRESH_MODE: Especifica o escopo no qual a atualização é executada para caches AUTO.
owner Especifica o nome do esquema. Esse parâmetro é opcional e assume como padrão o esquema atual.
property_value_str Recupera um valor STRING para o nome de propriedade especificado.
property_value_num Recupera um valor NUMBER para o nome de propriedade especificado.

Exemplo

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

Observações de Uso

  • Você deve estar conectado como usuário ADMIN ou ter o privilégio EXECUTE no pacote DBMS_CACHE para executar este procedimento.

  • MAX_CACHE_SIZE e MAX_CACHE_PERCENT são controles de cota no nível do esquema. Eles não permitem o armazenamento automático em cache por si mesmos. Use AUTO_CACHE para ativar ou desativar o armazenamento automático em cache do esquema especificado.

  • Se MAX_CACHE_SIZE e MAX_CACHE_PERCENT forem definidos, o valor maior será usado. Se nenhuma propriedade de cota no nível do esquema for definida explicitamente, o padrão de MAX_CACHE_PERCENT será 20.

SET_USER_PROPERTY Procedimento

Use DBMS_CACHE.SET_USER_PROPERTY para definir propriedades de armazenamento automático em cache para um esquema especificado. Use AUTO_CACHE para ativar ou desativar o armazenamento automático em cache para o esquema. Use MAX_CACHE_SIZE e MAX_CACHE_PERCENT para definir preferências de cota no nível do esquema dentro do modelo de cota global.

Sintaxe

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

Parâmetros

Parâmetro Descrição
property_name

Especifica o nome da propriedade.

Estes são os valores válidos para property_name:

  • AUTO_CACHE: Ativa ou desativa o armazenamento automático em cache para o esquema especificado. Os valores numéricos válidos são 1 e 0.

  • MAX_CACHE_SIZE: Especifica o tamanho máximo do cache no nível do esquema em bytes.

  • MAX_CACHE_PERCENT: Especifica o tamanho máximo do cache no nível do esquema como uma porcentagem da base de cota aplicável.

  • AUTO_REFRESH_MODE: Especifica o escopo no qual a atualização é executada para caches AUTO.

    Estes são os valores válidos para AUTO_REFRESH_MODE:

    • ALL: Todos os caches AUTO existentes no esquema são atualizados e, se necessário, novos caches são criados. Esse é o valor padrão.

    • CURRENT: Somente os caches AUTO existentes são atualizados. Nenhum cache novo foi adicionado.

    • NEW: Somente novos caches AUTO são criados.
property_value_num Fornece um valor NUMBER para o nome de propriedade especificado.
property_value_str Fornece um valor STRING para o nome de propriedade especificado.
owner Especifica o nome do esquema. Esse parâmetro é opcional e assume como padrão o esquema atual.

Exemplos

Exemplo para ativar o armazenamento automático em cache para um esquema:

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

Exemplo para definir uma cota de cache no nível do esquema:

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

Observações de Uso

  • Você deve estar conectado como usuário ADMIN ou ter o privilégio EXECUTE no pacote DBMS_CACHE para executar este procedimento.

  • As definições no nível do usuário substituem as definições globais.

  • MAX_CACHE_SIZE e MAX_CACHE_PERCENT não ativam o armazenamento automático em cache por si só.

  • Se MAX_CACHE_SIZE e MAX_CACHE_PERCENT forem definidos, o valor maior será usado.

  • Se nenhuma propriedade de cota no nível do esquema for definida explicitamente, o padrão de MAX_CACHE_PERCENT será 20.

  • Se MAX_CACHE_SIZE for definido como maior que GLOBAL_CACHE_SIZE, o banco de dados gerará um erro.

  • A política manual sempre substitui o comportamento automático.