Package DBMS_CLOUD_PIPELINE

Il pacchetto DBMS_CLOUD_PIPELINE consente di creare pipeline di dati per il caricamento e l'esportazione dei dati nel cloud. Questo package supporta il caricamento incrementale continuo dei dati dei file nell'area di memorizzazione degli oggetti nel database. DBMS_CLOUD_PIPELINE supporta inoltre l'esportazione incrementale continua dei dati delle tabelle o dei risultati delle query dal database all'area di memorizzazione degli oggetti in base a una colonna con indicatore orario.

Prerequisiti

Come sviluppatore, puoi utilizzare le procedure DBMS_CLOUD con i database AI autonomi distribuiti su Oracle Public Cloud, Multicloud o Exadata Cloud@Customer.

A seconda della scelta di distribuzione, è necessario soddisfare i seguenti prerequisiti per utilizzare le procedure DBMS_CLOUD con i provider di servizi Amazon S3, Azure Blob Storage e Google Cloud Storage.

Riepilogo dei sottoprogrammi DBMS_CLOUD_PIPELINE

La tabella riportata di seguito riassume i sottoprogrammi inclusi nel pacchetto DBMS_CLOUD_PIPELINE.

Sottoprogramma Descrizione
Procedura CREATE_PIPELINE Crea una nuova pipeline di dati.
Procedura DROP_PIPELINE Elimina una pipeline di dati esistente.
Procedura RESET_PIPELINE Reimposta lo stato di registrazione di una pipeline di dati. Utilizzare Reimposta pipeline per riavviare la pipeline dallo stato iniziale di caricamento o esportazione dei dati. Facoltativamente, la reimpostazione della pipeline può rimuovere i dati nel database o nell'area di memorizzazione degli oggetti, a seconda del tipo di pipeline.
Procedura RUN_PIPELINE_ONCE Esegue un'esecuzione su richiesta della pipeline nella sessione in primo piano corrente anziché in un job pianificato.
Procedura SET_ATTRIBUTE Imposta gli attributi della pipeline. Esistono due procedure sovraccaricate, una per impostare un singolo attributo e un'altra per impostare più attributi utilizzando un documento JSON di coppie nome/valore attributo.
Procedura START_PIPELINE Avvia la pipeline dati. Quando viene avviata una pipeline, l'operazione della pipeline viene eseguita continuamente in un job pianificato in base all'"intervallo" configurato negli attributi della pipeline.
Procedura STOP_PIPELINE Arresta la pipeline di dati. Quando una pipeline viene arrestata, non viene pianificato alcun job futuro per la pipeline.

Procedura CREATE_PIPELINE

La procedura crea una nuova pipeline di dati.

Sintassi

DBMS_CLOUD_PIPELINE.CREATE_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      pipeline_type        IN   VARCHAR2,
      attributes           IN   CLOB        DEFAULT NULL,
      description          IN   VARCHAR2    DEFAULT NULL
);

Parametri

Parametro Descrizione
pipeline_name

Specifica un nome per la pipeline. Il nome della pipeline deve seguire le regole di denominazione degli identificativi Oracle SQL. Per ulteriori informazioni, vedere Identificatori in Oracle Database Database PL/SQL Language Reference o Oracle Database 26ai Database PL/SQL Language Reference.

Questo parametro è obbligatorio.
pipeline_type

Specifica il tipo di pipeline.

Valori validi: LOAD, EXPORT

Questo parametro è obbligatorio.
attributes

Attributi della pipeline in formato JSON.

Valore predefinito: NULL

Per ulteriori informazioni, vedere Attributi DBMS_CLOUD_PIPELINE.

description

Descrizione per la pipeline.

Valore predefinito: NULL

Procedura DROP_PIPELINE

La procedura elimina una pipeline di dati esistente. Se una pipeline è stata avviata, deve essere arrestata prima di poter essere eliminata.

Sintassi

DBMS_CLOUD_PIPELINE.DROP_PIPELINE(
       pipeline_name        IN   VARCHAR2,
       force                IN   BOOLEAN DEFAULT FALSE
 );

Parametri

Parametro Descrizione
pipeline_name

Specifica un nome pipeline.

Questo parametro è obbligatorio.
force

Eliminare forzatamente una pipeline, anche se è in stato avviato.

Valori validi: TRUE, FALSE

Valore predefinito: FALSE

Nota per l'uso

Procedura RESET_PIPELINE

Reimposta lo stato di registrazione di una pipeline di dati. Utilizzare Reimposta pipeline per riavviare la pipeline dallo stato iniziale di caricamento o esportazione dei dati. Facoltativamente, la reimpostazione della pipeline può rimuovere i dati nel database o nell'area di memorizzazione degli oggetti, a seconda del tipo di pipeline. Per reimpostarla, è necessario che una pipeline di dati sia in stato arrestato.

Sintassi

DBMS_CLOUD_PIPELINE.RESET_PIPELINE(
       pipeline_name        IN   VARCHAR2,
       purge_data           IN   BOOLEAN DEFAULT FALSE
 );

Parametri

Parametro Descrizione
pipeline_name

Specifica un nome per la pipeline.

Questo parametro è obbligatorio.
purge_data

I dati di rimozione sono validi per una pipeline di caricamento o di esportazione:

  • Per una pipeline di caricamento, quando TRUE, tronca i dati nella tabella del database.

  • Per una pipeline di esportazione, quando si utilizza TRUE, eliminare i file nella posizione dell'area di memorizzazione degli oggetti.

Valori validi: TRUE, FALSE

Valore predefinito: FALSE

Note sull'uso

Procedura RUN_PIPELINE_ONCE

Questa procedura esegue un'esecuzione su richiesta della pipeline nella sessione in primo piano corrente, invece di un'esecuzione in un job pianificato. Utilizzare DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCE per eseguire il test di una pipeline prima di avviare la pipeline come job continuo.

Sintassi

DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCE(
       pipeline_name  IN  VARCHAR2
);

Parametri

Parametro Descrizione
pipeline_name

Specifica un nome per l'esecuzione della pipeline.

Questo parametro è obbligatorio.

Note sull'uso

Procedura SET_ATTRIBUTE

Questa procedura imposta gli attributi della pipeline. Esistono due procedure sovraccaricate, una per impostare un singolo attributo e un'altra per impostare più attributi utilizzando un documento JSON di coppie nome/valore attributo.

Sintassi

PROCEDURE DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE(
      pipeline_name        IN   VARCHAR2,
      attribute_name       IN   VARCHAR2,
      attribute_value      IN   CLOB
);

PROCEDURE DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE(
      pipeline_name        IN   VARCHAR2,
      attributes           IN   CLOB
);

Parametri

Parametro Descrizione
pipeline_name

Specifica un nome per la pipeline di impostazione degli attributi.

Questo parametro è obbligatorio.
attribute_name

Specifica il nome attributo per l'attributo da impostare.

Per ulteriori informazioni, vedere Attributi DBMS_CLOUD_PIPELINE.

attribute_value

Specifica il valore dell'attributo pipeline da impostare.

Per ulteriori informazioni, vedere Attributi DBMS_CLOUD_PIPELINE.

attributes

Specifica un documento JSON contenente i nomi e i valori degli attributi.

Per ulteriori informazioni, vedere Attributi DBMS_CLOUD_PIPELINE.

Nota per l'uso

Quando si utilizza DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE per impostare più attributi con il parametro attributes, tutti gli attributi esistenti vengono eliminati e sovrascritti con gli attributi specificati dal documento JSON.

Procedura START_PIPELINE

La procedura avvia la pipeline di dati. Quando viene avviata una pipeline, l'operazione della pipeline viene eseguita in modo continuo in un job pianificato in base all'indirizzo interval configurato con gli attributi della pipeline.

Sintassi

DBMS_CLOUD_PIPELINE.START_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      start_date           IN   TIMESTAMP WITH TIME ZONE DEFAULT NULL
);

Parametri

Parametro Descrizione
pipeline_name

Specifica un nome per la pipeline.

Questo parametro è obbligatorio.
start_date

Specifica la data di inizio per il job pipeline.

Valore predefinito: NULL

Note sull'uso

Procedura STOP_PIPELINE

La procedura arresta la pipeline di dati. Quando una pipeline viene arrestata, non viene pianificato alcun job futuro per la pipeline.

Sintassi

DBMS_CLOUD_PIPELINE.STOP_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      force                IN   BOOLEAN  DEFAULTFALSE
);

Parametri

Parametro Descrizione
pipeline_name

Specifica un nome per la pipeline.

Questo parametro è obbligatorio.
force

Se il parametro force viene passato come TRUE, interromperà qualsiasi job in esecuzione per la pipeline.

Valori validi: TRUE, FALSE

Valore predefinito: FALSE

Attributi DBMS_CLOUD_PIPELINE

Gli attributi consentono di controllare e configurare il funzionamento di una pipeline di dati.

Attributi

Nota: come indicato nella colonna Tipo di pipeline, a seconda del tipo di pipeline LOAD o EXPORT, una pipeline supporta un set di attributi diverso.

Nome attributo Descrizione Tipo di pipeline Modificabile dopo l'avvio della pipeline
credential_name

Nome della credenziale per accedere allo storage degli oggetti cloud di origine.

Valore predefinito: NULL.

Se non si specifica un valore credential_name, credential_name viene impostato su NULL.

LOAD, EXPORT Sì
field_list

Identifica i campi nei file di origine e i relativi tipi di dati. La sintassi di questo argomento è la stessa della clausola field_list nelle normali tabelle esterne Oracle. Per ulteriori informazioni, vedere elenco_campi in Oracle Database 19c Utilities o Oracle Database 26ai Utilities.

Valore predefinito: NULL

Il valore predefinito specifica i campi e i relativi tipi di dati sono determinati dalle colonne della tabella specificata nell'attributo table_name.

LOAD Sì
format

Opzioni che descrivono il formato per il tipo di pipeline.

Datapump format non supportato per una pipeline di esportazione.

Questo attributo è obbligatorio per entrambe le pipeline LOAD e EXPORT.

LOAD, EXPORT Sì
interval

Intervallo di tempo in minuti tra le esecuzioni consecutive del job pipeline pianificato.

Valore predefinito: 15 minuti

 LOAD, EXPORT Sì
key_column

Colonna indicatore orario o data nel file table o query specificato per l'esportazione continua dei dati più recenti nell'area di memorizzazione degli oggetti. L'indicatore orario o la data dell'ultima esecuzione viene tracciato dalla pipeline di esportazione e confrontato con il valore in key_column per identificare i nuovi dati da esportare nell'area di memorizzazione degli oggetti.

Valore predefinito: NULL

Se key_column non viene specificato per una pipeline di esportazione, l'intero contenuto di table o query viene caricato nell'area di memorizzazione degli oggetti in ogni esecuzione del job della pipeline.

EXPORT N.
location

Questo parametro specifica l'URI o le directory del file di origine e i file di origine. Nei nomi dei file è possibile utilizzare caratteri jolly.

Questo parametro è obbligatorio.

URI file di origine cloud

È possibile specificare un URI del file di origine per il bucket o la sottocartella. È possibile utilizzare i caratteri jolly per specificare le sottocartelle o i pattern dei nomi file. Il carattere "\*" può essere utilizzato come caratteri jolly per più caratteri, mentre il carattere "?" può essere utilizzato come caratteri jolly per un singolo carattere.

Esempio con caratteri jolly:

location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv

Il formato degli URI dipende dal servizio di storage degli oggetti cloud in uso. Per i dettagli, vedere Formati URI di storage degli oggetti cloud.

Directory

È possibile specificare una directory e un nome file. Il formato per specificare una directory è 'MY_DIR:filename.ext'. Per impostazione predefinita, il nome della directory MY_DIR è un oggetto di database e non fa distinzione tra maiuscole e minuscole. Nel nome del file viene fatta distinzione tra maiuscole e minuscole.

È possibile utilizzare solo caratteri jolly per specificare i nomi dei file in una directory. Il carattere "*" può essere utilizzato come caratteri jolly per più caratteri, mentre il carattere "?" può essere utilizzato come caratteri jolly per un singolo carattere.

Ad esempio: 'MY_DIR:*" o 'MY_DIR:test?'

Usare le virgolette doppie per specificare un nome di directory con distinzione tra maiuscole e minuscole.

Ad esempio: '"my_dir1":*, "my_dir2":Test?'

Per includere una virgoletta, utilizzare due virgolette.

Ad esempio: 'MY_DIR:''filename.ext'. Specifica che il nome file inizia con una virgoletta (').

   
priority

Specifica un valore stringa che determina il numero di operazioni parallele eseguite per la pipeline.

  • In una pipeline di caricamento, determina il numero di file caricati in parallelo.

  • In una pipeline di esportazione, determina il grado di parallelismo per il recupero dei dati dal database.

Un'operazione con priorità più alta consuma più risorse del database e viene completata prima.

Valori validi:

  • HIGH: determina il numero di file paralleli gestiti utilizzando il conteggio ECPU del database (conteggio OCPU se il database utilizza le OCPU).
  • MEDIUM: determina il numero di processi simultanei che utilizzano il limite di concorrenza per il servizio Medium. Il valore predefinito è 4.
  • LOW: esegue il job di pipeline in ordine seriale.

Valore predefinito: MEDIUM

Il numero massimo di operazioni file concorrenti è limitato a 64.

 LOAD, EXPORT Sì
query

Specifica un'istruzione SELECT in modo che vengano esportati solo i dati richiesti. La query determina il contenuto dei file esportati come file di testo (CSV, JSON, Parquet o XML) o file di dump.

Ad esempio:

SELECT warehouse_id, quantity FROM inventories;

Valore predefinito: NULL

Per una pipeline di esportazione, table_name o query è obbligatorio.

EXPORT N.
table_name

Specifica il nome della tabella di destinazione per il caricamento o l'esportazione dei dati.

Per una pipeline di caricamento table_name è obbligatorio.

Per una pipeline di esportazione, table_name o query è obbligatorio.

LOAD, EXPORT N.
table_owner

Nome dello schema in cui risiede la tabella di destinazione per il caricamento o l'esportazione dei dati.

Valore predefinito: NULL

Con un valore NULL, la tabella di destinazione si trova nello stesso schema dell'utente che esegue la procedura.

LOAD, EXPORT N.

Contenuto correlato