Pacote DBMS_EXT_TABLE_CACHE

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

Subprograma	Descrição
Procedimento ADD_BY_LIKE	Adiciona um ou mais arquivos que correspondem aos filtros especificados em um cache de tabela externa.
Procedimento ADD_FILE	Adiciona um arquivo ao cache de tabela externa.
Procedimento ADD_TABLE	Adiciona arquivos da tabela externa especificada em um cache de tabela externa.
Procedimento CLEAR	Limpa um cache de tabela externa.
Procedimento CREATE_CACHE	Cria um cache de tabela externa.
Desabilitar procedimento	Desativa um cache de tabela externa.
Procedimento DROP_BY_LIKE	Elimine arquivos de um cache de tabela externa com base nos filtros especificados.
Procedimento DROP_CACHE	Elimina um cache de tabela externa.
Procedimento DROP_FILE	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.
Procedimento RETIRE_FILES	Exclui um ou mais arquivos do cache que são mais antigos que o intervalo especificado.
Procedimento SET_USER_PROPERTY	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 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ções de 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.

Procedimento ADD_FILE

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 sobre 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.

Procedimento ADD_LATEST_FILES

O DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES carrega um ou mais arquivos no cache de tabela externa. Os arquivos são carregados 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. Em seguida, o intervalo de tempo resultante é usado para carregar 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 carregados 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ções de Uso

Por padrão, o procedimento DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES 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 ADD_TABLE

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

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.

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

Estes sã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ções de 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ções de 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.

Procedimento DROP_BY_LIKE

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

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.

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ções de Uso

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

Procedimento DROP_FILE

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

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.

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

Procedimento RETIRE_FILES

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

Procedimento SET_USER_PROPERTY

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

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.

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

Conteúdo Relacionado

Melhorar o Desempenho da Consulta com Cache de Tabela Externa