Pacchetto DBMS_EXT_TABLE_CACHE

La tabella riportata di seguito riepiloga i sottoprogrammi inclusi nel pacchetto DBMS_EXT_TABLE_CACHE.

Sottoprogramma Descrizione

Procedura ADD_BY_LIKE

Aggiunge uno o più file corrispondenti ai filtri specificati in una cache di tabelle esterne.

Procedura ADD_FILE

Aggiunge un file nella cache delle tabelle esterne.

Procedura ADD_TABLE

Aggiunge i file della tabella esterna specificata in una cache di tabella esterna.

Procedura CLEAR

Cancella una cache di tabella esterna.

Procedura CREATE_CACHE

Crea una cache tabella esterna.

Procedura DISABLE

Disabilita una cache tabella esterna.

Procedura DROP_BY_LIKE

Rilasciare i file da una cache tabella esterna in base ai filtri specificati.

Procedura DROP_CACHE

Elimina una cache tabella esterna.

Procedura DROP_FILE

Rimuove il file tabella esterno specificato dalla cache tabella esterna.

Procedura ENABLE

Abilita una cache tabella esterna precedentemente disabilitata.

Funzione GET_USER_PROPERTY

Recupera la preferenza di inserimento nella cache per una cache tabella esterna.

Procedura RETIRE_FILES

Elimina dalla cache uno o più file precedenti all'intervallo specificato.

Procedura SET_USER_PROPERTY

Specifica la preferenza di inserimento nella cache per una cache tabella esterna.

Procedura VALIDATE

Convalida una cache di tabella esterna.

Argomenti correlati

Procedura ADD_BY_LIKE

La procedura DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE carica uno o più file specificati dall'area di memorizzazione degli oggetti nella cache delle tabelle esterne.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.
path_filters

PATH_FILTERS è un JSON_ARRAY di filtri di percorso utilizzati per cercare pattern specificati negli URL dei file.

esc_char

Specifica il carattere di escape da utilizzare nei filtri del percorso. Se il carattere di escape precede il carattere '%' o '_' nel pattern, il carattere speciale viene interpretato letteralmente e non come un carattere speciale corrispondente al pattern.

Questo parametro è facoltativo e il valore predefinito per questo parametro è NULL.

force

Forza la sovrascrittura dei file esistenti specificati nella cache anche se i file non sono stati modificati.

Questo parametro è facoltativo e il valore predefinito per il parametro force è FALSE.

Esempio

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

Nota per l'uso

  • Per impostazione predefinita, la procedura DBMS_EXT_TABLE_CACHE.ADD_BY_LIKE ignora il caricamento dei file quando:

    • I file sono stati precedentemente inseriti nella cache e sono ancora disponibili nella cache.

    • I file non sono stati modificati dall'ultimo inserimento nella cache.

    Tuttavia, è possibile utilizzare il parametro force per sovrascrivere i file nella cache anche se i file non sono stati modificati.

Procedura ADD_FILE

La procedura DBMS_EXT_TABLE_CACHE.ADD_FILE carica il file specificato nella cache delle tabelle esterne.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.
file_url

Specifica l'URL del file.
force

Forza la sovrascrittura dei file esistenti specificati nella cache anche se i file non sono stati modificati.

Questo parametro è facoltativo e il valore predefinito per il parametro force è FALSE.

Esempio

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

Note sull'uso

  • La procedura DBMS_EXT_TABLE_CACHE.ADD_FILE salta il caricamento del file nella cache se il file specificato esiste nella cache e non è stato modificato dall'ultima volta che il file è stato inserito nella cache.

  • È possibile utilizzare il parametro force per sovrascrivere il file nella cache anche se il file non è stato modificato.

Procedura ADD_LATEST_FILES

DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES carica uno o più file nella cache delle tabelle esterne. I file vengono caricati in base all'intervallo di tempo determinato dall'argomento SINCE e dall'indicatore orario corrente.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.

since

Il parametro since accetta un valore INTERVAL DAY TO SECOND e viene utilizzato per calcolare l'intervallo di tempo tra il valore since e l'indicatore orario corrente. L'intervallo di tempo risultante viene quindi utilizzato per caricare i file in base all'ora dell'ultima modifica.

max_files

Specificare il valore max_files per limitare il numero di file che è possibile caricare nella cache delle tabelle esterne.

Questo parametro è facoltativo e il valore predefinito è illimitato se non specificato.

force

Forza la sovrascrittura dei file esistenti specificati nella cache anche se i file non sono stati modificati.

Questo parametro è facoltativo e il valore predefinito di questo parametro è FALSE.

Esempio

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

Nota per l'uso

  • Per impostazione predefinita, la procedura DBMS_EXT_TABLE_CACHE.ADD_LATEST_FILES ignora il caricamento dei file quando:

    • I file specificati sono stati precedentemente inseriti nella cache e sono ancora disponibili nella cache.

    • I file specificati non sono stati modificati dall'ultimo inserimento nella cache.

    Tuttavia, è possibile utilizzare il parametro force per sovrascrivere i file nella cache anche se i file non sono stati modificati.

Procedura ADD_TABLE

La procedura DBMS_EXT_TABLE_CACHE.ADD_TABLE carica nella cache un'intera tabella o una determinata percentuale della tabella esterna.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.

percent_files

Specifica la percentuale di dati della tabella da inserire nella cache. Ad esempio, da 1 a 100.

Per impostazione predefinita, tutti i file vengono caricati.

force

Forza la sovrascrittura dei file specificati nella cache anche se i file non sono stati modificati.

Questo parametro è facoltativo e il valore predefinito per force è FALSE.

Esempio

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

Note sull'uso

  • DBMS_EXT_TABLE_CACHE.ADD_TABLE tenta di inserire nella cache l'intera tabella o una percentuale specificata del contenuto del file.

  • I parametri percent_files e force si escludono a vicenda.

  • Per impostazione predefinita, la procedura DBMS_EXT_TABLE_CACHE.ADD_TABLE ignora il caricamento dei file quando:

    • I file specificati sono stati precedentemente inseriti nella cache e sono ancora disponibili nella cache.

    • I file specificati non sono stati modificati dall'ultimo inserimento nella cache.

    Tuttavia, è possibile utilizzare il parametro force per sovrascrivere i file nella cache anche se i file non sono stati modificati.

Procedura CLEAR

La procedura DBMS_EXT_TABLE_CACHE.CLEAR rimuove tutti i file da una cache di tabelle esterne conservando la cache.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.

Esempio

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

Procedura CREATE_CACHE

La procedura DBMS_EXT_TABLE_CACHE.CREATE_CACHE crea una cache di tabella esterna in un'istanza di Autonomous AI Database.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.

partition_type
Di seguito sono riportati i valori validi per il parametro partition_type.

  • FILE: esegue il partizionamento della cache delle tabelle esterne utilizzando le colonne invisibili FILE$PATH e FILE$NAME.

  • PATH: esegue il partizionamento della cache delle tabelle esterne utilizzando la colonna invisibile FILE$PATH.

file$path: specifica il testo del percorso del file fino all'inizio del nome dell'oggetto.

file$name: specifica il nome dell'oggetto, incluso tutto il testo che segue il '/' finale.

Per ulteriori informazioni, vedere Colonne metadati tabella esterna.

Esempio

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

Nota per l'uso

  • DBMS_EXT_TABLE_CACHE.CREATE_CACHE crea la cache delle tabelle esterne in un'istanza di Autonomous AI Database. La creazione di una cache è simile alla creazione di una tabella nello schema di database.

Procedura DISABLE

La procedura DBMS_EXT_TABLE_CACHE.DISABLE disabilita la cache delle tabelle esterne specificata. La cache è contrassegnata come disabilitata; tuttavia, i dati all'interno della cache vengono conservati.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.

Esempio

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

Nota per l'uso

  • DBMS_EXT_TABLE_CACHE.DISABLE non elimina alcun dato dalla cache delle tabelle esterne. Contrassegna invece la cache come DISABLED, il che significa che l'ottimizzatore non può utilizzare la cache per la riscrittura delle query.

Procedura DROP_BY_LIKE

La procedura DBMS_EXT_TABLE_CACHE.DROP_BY_LIKE elimina uno o più file dalla cache delle tabelle esterne. I file vengono eliminati in base ai filtri specificati.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.
path_filters

PATH_FILTERS è un JSON_ARRAY di filtri di percorso utilizzati per cercare pattern specificati negli URL dei file.

esc_char

Specifica il carattere di escape da utilizzare nei filtri del percorso. Se il carattere di escape precede il carattere '%' o '_' nel pattern, il carattere speciale viene interpretato letteralmente e non come un carattere speciale corrispondente al pattern.

Questo parametro è facoltativo e il valore predefinito per questo parametro è NULL.

Esempio

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

Procedura DROP_CACHE

La procedura DBMS_EXT_TABLE_CACHE.DROP_CACHE elimina la cache delle tabelle esterne specificata. Questa procedura elimina la cache e rilascia lo spazio di memorizzazione associato alla cache.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.

Esempio

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

Nota per l'uso

  • L'eliminazione di una cache comporta la rimozione dei metadati dal dizionario dati e l'eliminazione di tutti i dati inseriti nella cache.

Procedura DROP_FILE

La procedura DBMS_EXT_TABLE_CACHE.DROP_FILE elimina il file specificato da una cache di tabelle esterne.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.

file_url

Specifica l'URL del file.

Esempio

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

Procedura ENABLE

La procedura DBMS_EXT_TABLE_CACHE.ENABLE abilita una cache di tabelle esterne precedentemente disabilitata. Quando viene creata, la cache viene abilitata per impostazione predefinita.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.

Esempio

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

Funzione GET_USER_PROPERTY

La funzione restituisce la preferenza di inserimento nella cache per lo schema specificato e restituisce un valore Number.

Sintassi


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

RETURN NUMBER;

Parametri

Parametro Descrizione

property_name

Specifica il nome della proprietà.

I valori validi per property_name sono riportati di seguito.

  • MAX_CACHE_PERCENT

  • MAX_CACHE_SIZE

owner

Specifica il nome dello schema.

Valori restituiti

Valore restituito Descrizione

Numero del valore MAX_CACHE_SIZE o MAX_CACHE_SIZE.

A seconda del parametro property_name, il numero restituito è il valore MAX_CACHE_SIZE o MAX_CACHE_SIZE.

Esempio

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

Procedura RETIRE_FILES

DBMS_EXT_TABLE_CACHE.RETIRE_FILES elimina dalla cache i file precedenti all'intervallo specificato. I file vengono eliminati in base all'intervallo di tempo calcolato utilizzando il valore del parametro BEFORE.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.

before

Il parametro before accetta un valore INTERVAL DAY TO SECOND e viene utilizzato per calcolare l'intervallo di tempo tra il valore before e l'indicatore orario corrente. L'intervallo di tempo risultante viene quindi utilizzato per eliminare i file dalla cache.

Esempio

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

Procedura SET_USER_PROPERTY

La procedura DBMS_EXT_TABLE_CACHE.SET_USER_PROPERTY imposta la preferenza di inserimento nella cache per uno schema.

Sintassi

DBMS_EXT_TABLE_CACHE.SET_USER_PROPERTY (         
    property_name    IN    VARCHAR2,         
    property_value   IN    NUMBER,                   
    owner            IN    VARCHAR2 DEFAULT NULL);

Parametri

Parametro Descrizione

property_name

Specifica il nome della proprietà.

I valori validi per property_name sono riportati di seguito.

  • MAX_CACHE_PERCENT

  • MAX_CACHE_SIZE

property_value

Specifica il valore della proprietà.

owner

Specifica il nome dello schema.

Esempio

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

Procedura VALIDATE

La procedura DBMS_EXT_TABLE_CACHE.VALIDATE convalida la cache delle tabelle esterne. Si è verificato un errore se la tabella esterna di riferimento non è stata trovata nel database.

Sintassi

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

Parametri

Parametro Descrizione

owner

Specifica il nome dello schema.

table_name

Specifica il nome della tabella esterna.

raise_errors

Segnala quando una cache di tabella esterna è contrassegnata come non valida.

Esempio

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