Documentação do Oracle Cloud Infrastructure

Pacote DBMS_EXT_TABLE_CACHE

O pacote DBMS_EXT_TABLE_CACHE fornece rotinas para configurar e gerenciar o armazenamento em cache de dados acessados com frequência de tabelas externas no Autonomous AI Database.

Tópico principal: Referência de Pacote Fornecida pelo Autonomous AI Database

Resumo dos Subprogramas DBMS_EXT_TABLE_CACHE

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

Subprograma Descrição

ADD_BY_LIKE Procedimento

Adiciona um ou mais arquivos que correspondem aos filtros especificados em um cache de tabela externa.

ADD_FILE Procedimento

Adiciona um arquivo ao cache de tabela externa.

ADD_LATEST_FILES Procedimento

Preenche um ou mais arquivos com base no intervalo de tempo especificado pelo argumento SINCE e o timestamp atual.

ADD_TABLE Procedimento

Adiciona arquivos da tabela externa especificada em um cache de tabela externa.

Procedimento CLEAR

Limpa um cache de tabela externa.

CREATE_CACHE Procedimento

Cria um cache de tabela externa.

Desabilitar procedimento

Desativa um cache de tabela externa.

DROP_BY_LIKE Procedimento

Elimine arquivos de um cache de tabela externa com base nos filtros especificados.

DROP_CACHE Procedimento

Elimina um cache de tabela externa.

DROP_FILE Procedimento

Remove o arquivo de tabela externa especificado do cache de tabela externa.

Ativar procedimento

Ativa um cache de tabela externa desativado anteriormente.

Função GET_USER_PROPERTY

Recupera a preferência de armazenamento em cache para um cache de tabela externa.

RETIRE_FILES Procedimento

Exclui um ou mais arquivos do cache que são mais antigos que o intervalo especificado.

SET_USER_PROPERTY Procedimento

Especifica a preferência de armazenamento em cache para um cache de tabela externa.

Procedimento VALIDATE

Valida um cache de tabela externa.
  • Procedimento ADD_BY_LIKE
    O procedimento DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE carrega um ou mais arquivos especificados do Object Store no cache da tabela externa.
  • Procedimento ADD_FILE
    O procedimento DBMS_EXT_TABLE_CACHE.ADD_FILE carrega o arquivo especificado no cache da tabela externa.
  • Procedimento ADD_LATEST_FILES
    O DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES preenche um ou mais arquivos no cache da tabela externa. Os arquivos são preenchidos com base no intervalo de tempo determinado pelo argumento SINCE e pelo timestamp atual.
  • Procedimento ADD_TABLE
    O procedimento DBMS_EXT_TABLE_CACHE.ADD_TABLE carrega uma tabela inteira ou uma determinada porcentagem da tabela externa no cache.
  • Procedimento CLEAR
    O procedimento DBMS_EXT_TABLE_CACHE.CLEAR remove todos os arquivos de um cache de tabela externa enquanto mantém o cache.
  • Procedimento CREATE_CACHE
    O procedimento DBMS_EXT_TABLE_CACHE.CREATE_CACHE cria um cache de tabela externa em uma instância do Autonomous AI Database.
  • Procedimento DISABLE
    O procedimento DBMS_EXT_TABLE_CACHE.DISABLE desativa o cache de tabela externa especificado. O cache é sinalizado como desativado; no entanto, os dados dentro do cache são mantidos.
  • Procedimento DROP_BY_LIKE
    O procedimento DBMS_EXT_TABLE_CACHE.DROP_BY_LIKE elimina um ou mais arquivos do cache da tabela externa. Os arquivos são eliminados com base nos filtros especificados.
  • Procedimento DROP_CACHE
    O procedimento DBMS_EXT_TABLE_CACHE.DROP_CACHE elimina o cache de tabela externa especificado. Este procedimento elimina o cache e libera o espaço de armazenamento associado ao cache.
  • Procedimento DROP_FILE
    O procedimento DBMS_EXT_TABLE_CACHE.DROP_FILE elimina o arquivo especificado de um cache de tabela externa.
  • Procedimento HABILITAR
    O procedimento DBMS_EXT_TABLE_CACHE.ENABLE ativa um cache de tabela externa desativado anteriormente. Quando um cache é criado, ele é ativado por padrão.
  • Função GET_USER_PROPERTY
    A função retorna a preferência de armazenamento em cache para o esquema especificado e retorna um Number.
  • Procedimento RETIRE_FILES
    O DBMS_EXT_TABLE_CACHE.RETIRE_FILES elimina arquivos do cache que são anteriores ao intervalo especificado. Os arquivos são excluídos com base no intervalo de tempo calculado usando o valor do parâmetro BEFORE.
  • Procedimento SET_USER_PROPERTY
    O procedimento DBMS_EXT_TABLE_CACHE.SET_USER_PROPERTY define a preferência de armazenamento em cache para um esquema.
  • Procedimento de VALIDAÇÃO
    O procedimento DBMS_EXT_TABLE_CACHE.VALIDATE valida o cache da tabela externa. Um erro será reportado se a tabela externa referenciada não for encontrada no banco de dados.

Tópico principal: Pacote DBMS_EXT_TABLE_CACHE

ADD_BY_LIKE Procedimento

O procedimento DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE carrega um ou mais arquivos especificados do Object Store no cache de tabela externa.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.
path_filters

PATH_FILTERS é um JSON_ARRAY de filtros de caminho usados para procurar padrões especificados em URLs de arquivo.

esc_char

Especifica o caractere de escape a ser usado nos filtros de caminho. Se o caractere de escape preceder o '%' ou o '_' no padrão, o caractere especial será interpretado literalmente, e não como um caractere de correspondência de padrão especial.

Esse parâmetro é opcional e o valor padrão desse parâmetro é NULL.

force

Força os arquivos existentes especificados a serem substituídos no cache, mesmo que os arquivos não tenham sido modificados.

Esse parâmetro é opcional e o valor padrão do parâmetro force é FALSE.

Exemplo

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

Observação do Uso

  • Por padrão, o procedimento DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE ignora o carregamento dos arquivos quando:

    • Os arquivos foram armazenados em cache anteriormente e ainda estão disponíveis no cache.

    • Os arquivos não foram modificados desde que foram armazenados em cache pela última vez.

    No entanto, você pode usar o parâmetro force para substituir os arquivos no cache, mesmo que os arquivos não tenham sido modificados.

ADD_FILE Procedimento

O procedimento DBMS_EXT_TABLE_CACHE.ADD_FILE carrega o arquivo especificado no cache da tabela externa.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.
file_url

Especifica o URL do arquivo.
force

Força os arquivos existentes especificados a serem substituídos no cache, mesmo que os arquivos não tenham sido modificados.

Esse parâmetro é opcional e o valor padrão para o parâmetro force é FALSE.

Exemplo

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

Observações de Uso

  • O procedimento DBMS_EXT_TABLE_CACHE.ADD_FILE ignora o carregamento do arquivo no cache se o arquivo especificado existir no cache e não tiver sido modificado desde que o arquivo foi armazenado no cache pela última vez.

  • Você pode usar o parâmetro force para substituir o arquivo no cache, mesmo que o arquivo não tenha sido modificado.

ADD_LATEST_FILES Procedimento

O DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES preenche um ou mais arquivos no cache de tabela externa. Os arquivos são preenchidos com base no intervalo de tempo determinado pelo argumento SINCE e pelo timestamp atual.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.

since

O parâmetro since aceita um valor INTERVAL DAY TO SECOND e é usado para calcular o intervalo de tempo entre o valor since e o timestamp atual. O intervalo de tempo resultante é usado para preencher os arquivos, com base no horário da última modificação.

max_files

Especifique o valor max_files para limitar o número de arquivos que podem ser preenchidos no cache de tabela externa.

Esse parâmetro é opcional e assume ilimitado como padrão quando não especificado.

force

Força os arquivos existentes especificados a serem substituídos no cache, mesmo que os arquivos não tenham sido modificados.

Este parâmetro é opcional e o valor padrão para este parâmetro é FALSE.

Exemplo

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

Observação do Uso

  • Por padrão, o procedimento DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES ignora o preenchimento dos arquivos quando:

    • Os arquivos especificados foram armazenados em cache anteriormente e ainda estão disponíveis no cache.

    • Os arquivos especificados não foram modificados desde que foram armazenados em cache pela última vez.

    No entanto, você pode usar o parâmetro force para substituir os arquivos no cache, mesmo que os arquivos não tenham sido modificados.

ADD_TABLE Procedimento

O procedimento DBMS_EXT_TABLE_CACHE.ADD_TABLE carrega uma tabela inteira ou uma determinada porcentagem da tabela externa no cache.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.

percent_files

Especifica a porcentagem dos dados de tabela a serem armazenados em cache. Por exemplo, 1 a 100.

Por padrão, todos os arquivos são carregados.

force

Força os arquivos especificados a serem substituídos no cache, mesmo que os arquivos não tenham sido modificados.

Esse parâmetro é opcional e o valor padrão para force é FALSE.

Exemplo

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

Observações de Uso

  • O DBMS_EXT_TABLE_CACHE.ADD_TABLE tenta armazenar em cache toda a tabela ou uma porcentagem especificada do conteúdo do arquivo no cache.

  • Os parâmetros percent_files e force são mutuamente exclusivos.

  • Por padrão, o procedimento DBMS_EXT_TABLE_CACHE.ADD_TABLE ignora o carregamento dos arquivos quando:

    • Os arquivos especificados foram armazenados em cache anteriormente e ainda estão disponíveis no cache.

    • Os arquivos especificados não foram modificados desde que foram armazenados em cache pela última vez.

    No entanto, você pode usar o parâmetro force para substituir os arquivos no cache, mesmo que os arquivos não tenham sido modificados.

Procedimento CLEAR

O procedimento DBMS_EXT_TABLE_CACHE.CLEAR remove todos os arquivos de um cache de tabela externa enquanto mantém o cache.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.

Exemplo

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

CREATE_CACHE Procedimento

O procedimento DBMS_EXT_TABLE_CACHE.CREATE_CACHE cria um cache de tabela externa em uma instância do Autonomous AI Database.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome da tabela externa.

partition_type
A seguir estão os valores válidos para o parâmetro partition_type:

  • FILE: faz a partição do cache da tabela externa usando as colunas invisíveis FILE$PATH e FILE$NAME.

  • PATH: faz a partição do cache da tabela externa usando a coluna invisível FILE$PATH.

file$path: Especifica o texto do caminho do arquivo até o início do nome do objeto.

file$name: Especifica o nome do objeto, incluindo todo o texto que segue o '/' final.

Consulte Colunas de Metadados da Tabela Externa para obter mais informações.

Exemplo

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

Observação do Uso

  • DBMS_EXT_TABLE_CACHE.CREATE_CACHE cria o cache de tabela externa em uma instância do Autonomous AI Database. Criar um cache é semelhante a criar uma tabela no esquema do banco de dados.

Desabilitar procedimento

O procedimento DBMS_EXT_TABLE_CACHE.DISABLE desativa o cache de tabela externa especificado. O cache é sinalizado como desativado; no entanto, os dados dentro do cache são mantidos.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.

Exemplo

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

Observação do Uso

  • DBMS_EXT_TABLE_CACHE.DISABLE não exclui dados do cache de tabela externa. Em vez disso, ele marca o cache como DISABLED, o que significa que o otimizador não pode usar o cache para regravações de consulta.

DROP_BY_LIKE Procedimento

O procedimento DBMS_EXT_TABLE_CACHE.DROP_BY_LIKE elimina um ou mais arquivos do cache de tabela externa. Os arquivos são eliminados com base nos filtros especificados.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.
path_filters

PATH_FILTERS é um JSON_ARRAY de filtros de caminho usados para procurar padrões especificados em URLs de arquivo.

esc_char

Especifica o caractere de escape a ser usado nos filtros de caminho. Se o caractere de escape preceder o '%' ou o '_' no padrão, o caractere especial será interpretado literalmente, e não como um caractere de correspondência de padrão especial.

Esse parâmetro é opcional e o valor padrão desse parâmetro é NULL.

Exemplo

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 Procedimento

O procedimento DBMS_EXT_TABLE_CACHE.DROP_CACHE elimina o cache de tabela externa especificado. Este procedimento elimina o cache e libera o espaço de armazenamento associado ao cache.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.

Exemplo

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

Observação do Uso

  • A eliminação de um cache remove seus metadados do dicionário de dados e exclui todos os dados armazenados no cache.

DROP_FILE Procedimento

O procedimento DBMS_EXT_TABLE_CACHE.DROP_FILE elimina o arquivo especificado de um cache de tabela externa.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.

file_url

Especifica o URL do arquivo.

Exemplo

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

Ativar procedimento

O procedimento DBMS_EXT_TABLE_CACHE.ENABLE ativa um cache de tabela externa desativado anteriormente. Quando um cache é criado, ele é ativado por padrão.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.

Exemplo

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

Função GET_USER_PROPERTY

A função retorna a preferência de armazenamento em cache para o esquema especificado e retorna um Number.

Sintaxe


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

RETURN NUMBER;

Parâmetros

Parâmetro Descrição

property_name

Especifica o nome da propriedade.

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

  • MAX_CACHE_PERCENT

  • MAX_CACHE_SIZE

owner

Especifica o nome do esquema.

Valores de Retorno

Valor de Retorno Descrição

O valor MAX_CACHE_SIZE ou MAX_CACHE_SIZE em Número.

Dependendo do parâmetro property_name, o número retornado é o valor MAX_CACHE_SIZE ou MAX_CACHE_SIZE.

Exemplo

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 Procedimento

O DBMS_EXT_TABLE_CACHE.RETIRE_FILES elimina arquivos do cache que são mais antigos que o intervalo especificado. Os arquivos são excluídos com base no intervalo de tempo calculado usando o valor do parâmetro BEFORE.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.

before

O parâmetro before aceita um valor INTERVAL DAY TO SECOND e é usado para calcular o intervalo de tempo entre o valor before e o timestamp atual. O intervalo de tempo resultante é então usado para excluir os arquivos do cache.

Exemplo

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

SET_USER_PROPERTY Procedimento

O procedimento DBMS_EXT_TABLE_CACHE.SET_USER_PROPERTY define a preferência de armazenamento em cache para um esquema.

Sintaxe

DBMS_EXT_TABLE_CACHE.SET_USER_PROPERTY (         
    property_name    IN    VARCHAR2,         
    property_value   IN    NUMBER,                   
    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:

  • MAX_CACHE_PERCENT

  • MAX_CACHE_SIZE

property_value

Especifica o valor da propriedade.

owner

Especifica o nome do esquema.

Exemplo

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

Procedimento VALIDATE

O procedimento DBMS_EXT_TABLE_CACHE.VALIDATE valida o cache da tabela externa. Um erro será reportado se a tabela externa referenciada não for encontrada no banco de dados.

Sintaxe

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

Parâmetros

Parâmetro Descrição

owner

Especifica o nome do esquema.

table_name

Especifica o nome de tabela externa.

raise_errors

Informa quando um cache de tabela externa é marcado como inválido.

Exemplo

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