Pacchetto 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 indicatore orario.

Argomenti correlati

Prerequisiti

Come sviluppatore, puoi utilizzare le procedure DBMS_CLOUD con Autonomous Database distribuite 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.

Una connettività in uscita deve essere stata configurata mediante un gateway NAT dall'amministratore della flotta, come descritto di seguito.
  • Crea un gateway NAT nella rete cloud virtuale (VCN) in cui risiedono le tue risorse di Autonomous Database seguendo le istruzioni riportate in Crea un gateway NAT nella documentazione di Oracle Cloud Infrastructure.
  • Dopo aver creato il gateway NAT, aggiungere una regola di instradamento e una regola di sicurezza di uscita a ogni subnet (nella VCN) in cui risiedono le risorse di Autonomous Database in modo che queste risorse possano utilizzare il gateway per ottenere una chiave pubblica dall'istanza di Azure AD:
    1. Andare alla pagina Dettagli subnet per la subnet.
    2. Nella scheda Informazioni subnet, fare clic sul nome della tabella di instradamento della subnet per visualizzare la relativa pagina Dettagli tabella di instradamento.
    3. Nella tabella delle regole di instradamento esistenti, verificare se esiste già una regola con le seguenti caratteristiche:
      • Data: 0.0.0.0/0
      • Tipo di destinazione: gateway NAT
      • Destinazione: il nome del gateway NAT appena creato nella VCN

      Se la regola non esiste, fare clic su Aggiungi regole di instradamento e aggiungere una regola di instradamento con queste caratteristiche.

    4. Tornare alla pagina Dettagli subnet per la subnet.
    5. Nella tabella Elenchi di sicurezza della subnet, fare clic sul nome della lista di sicurezza della subnet per visualizzare la relativa pagina Dettagli lista di sicurezza.
    6. Nel menu laterale, in Risorse, fare clic su Regole di uscita.
    7. Nella tabella delle regole di uscita esistenti, verificare se esiste già una regola con le seguenti caratteristiche:
      • Tipo di destinazione: CIDR
      • Data: 0.0.0.0/0
      • Protocollo IP: TCP
      • Intervallo porte di origine: 443
      • Intervallo di porte di destinazione: tutte

      Se una regola di questo tipo non esiste, fare clic su Aggiungi regole di uscita e aggiungere una regola di uscita con queste caratteristiche.

Le impostazioni del proxy HTTP nell'ambiente devono consentire al database di accedere al provider di servizi cloud.

Queste impostazioni vengono definite dall'amministratore della flotta durante la creazione dell'infrastruttura Exadata Cloud@Customer, come descritto in Uso della console per eseguire il provisioning di Exadata Database Service su Cloud@Customer.

Nota

La configurazione di rete, incluso il proxy HTTP, può essere modificata solo fino a quando lo stato dell'infrastruttura Exadata non è Richiede attivazione. Una volta attivato, non è possibile modificare tali impostazioni.

L'impostazione di un proxy HTTP per un'infrastruttura Exadata già fornita richiede una richiesta di servizio (SR) in My Oracle Support. Per informazioni dettagliate, vedere Create a Service Request in My Oracle Support.

Riepilogo dei sottoprogrammi DBMS_CLOUD_PIPELINE

La tabella seguente contiene un riepilogo dei sottoprogrammi inclusi nel pacchetto DBMS_CLOUD_PIPELINE.

Sottoprogramma Descrizione

CREATE_PIPELINE Procedura

Crea una nuova pipeline di dati.

DROP_PIPELINE Procedura

Elimina una pipeline di dati esistente.

RESET_PIPELINE Procedura

Reimposta lo stato di tracciamento di una pipeline di dati. Utilizzare Reimposta pipeline per riavviare la pipeline dallo stato iniziale di caricamento o esportazione dei dati. Se si desidera, è possibile reimpostare la pipeline per rimuovere i dati nel database o nell'area di memorizzazione degli oggetti, a seconda del tipo di pipeline.

RUN_PIPELINE_ONCE Procedura

Esegue un'esecuzione su richiesta della pipeline nella sessione in primo piano corrente, anziché un job pianificato.

SET_ATTRIBUTE Procedura

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

START_PIPELINE Procedura

Avvia la pipeline dati. Quando viene avviata una pipeline, l'operazione della pipeline viene eseguita in modo continuo in un job pianificato in base all'"intervallo" configurato negli attributi della pipeline.

STOP_PIPELINE Procedura

Arresta la pipeline dati. Quando una pipeline viene arrestata, non viene pianificato alcun job futuro per la pipeline.

CREATE_PIPELINE Procedura

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 23ai 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 DBMS_CLOUD_PIPELINE Attributi.

description

Descrizione della pipeline.

Valore predefinito: NULL

DROP_PIPELINE Procedura

La procedura elimina una pipeline di dati esistente. Se una pipeline è stata avviata, è necessario arrestarla prima di poterla eliminare.

Sintassi

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

Parametri

Parametro Descrizione

pipeline_name

Specifica un nome di pipeline.

Questo parametro è obbligatorio.

force

Eliminazione forzata di una pipeline, anche se è in stato avviato.

Valori validi: TRUE, FALSE

Valore predefinito: FALSE

Nota per l'uso

  • Per eliminare una pipeline in stato avviato, impostare il parametro force su TRUE.

RESET_PIPELINE Procedura

Reimposta lo stato di tracciamento di una pipeline di dati. Utilizzare Reimposta pipeline per riavviare la pipeline dallo stato iniziale di caricamento o esportazione dei dati. Se si desidera, è possibile reimpostare la pipeline per rimuovere i dati nel database o nell'area di memorizzazione degli oggetti, a seconda del tipo di pipeline. Per reimpostarla, è necessario che una pipeline 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 TRUE, eliminare i file nella posizione dell'area di memorizzazione degli oggetti.

Valori validi: TRUE, FALSE

Valore predefinito: FALSE

Note sull'uso

  • Per reimpostarla, è necessario che una pipeline dati sia in stato arrestato. Per ulteriori informazioni, vedere STOP_PIPELINE Procedura.

  • Per una pipeline di caricamento, la reimpostazione della pipeline cancella il record dei file caricati dalla pipeline. Quando si chiama START_PIPELINE o RUN_PIPELINE_ONCE dopo aver reimpostato una pipeline di caricamento, la pipeline ripete il caricamento dei dati e include tutti i file presenti nella posizione dell'area di memorizzazione degli oggetti.

    Quando purge_data è impostato su TRUE, DBMS_CLOUD_PIPELINE.RESET_PIPELINE effettua le operazioni riportate di seguito.

    • Tronca i dati nella tabella di database della pipeline specificata con l'attributo table_name.

    • Elimina la tabella degli stati della pipeline, la tabella dei file errati della pipeline e la tabella degli errori (se esistenti).

  • Per una pipeline di esportazione, la reimpostazione della pipeline cancella gli ultimi dati registrati nella tabella del database. Quando si chiama START_PIPELINE o RUN_PIPELINE_ONCE dopo aver reimpostato una pipeline di esportazione, la pipeline ripete l'esportazione dei dati dalla tabella o dalla query.

    Quando purge_data è impostato su TRUE, DBMS_CLOUD_PIPELINE.RESET_PIPELINE elimina i file esistenti nella posizione dell'area di memorizzazione degli oggetti specificata con l'attributo location.

RUN_PIPELINE_ONCE Procedura

Questa procedura esegue un'esecuzione su richiesta della pipeline nella sessione in primo piano corrente, anziché 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 la pipeline da eseguire.

Questo parametro è obbligatorio.

Note sull'uso

  • Dopo aver eseguito un test di una pipeline, è possibile reimpostare lo stato della pipeline utilizzando DBMS_CLOUD_PIPELINE.RESET_PIPELINE. Ciò consente di reimpostare lo stato della pipeline prima di avviare la pipeline in un job pianificato.

  • Se una pipeline si trova nello stato avviato, non può essere eseguita nella sessione in primo piano.

SET_ATTRIBUTE Procedura

Questa procedura imposta gli attributi della pipeline. Esistono due procedure sovraccaricate, una per impostare un singolo attributo e l'altra per impostare più attributi utilizzando un documento JSON con 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 per l'impostazione degli attributi.

Questo parametro è obbligatorio.

attribute_name

Specifica il nome attributo per l'attributo da impostare.

Per ulteriori informazioni, vedere DBMS_CLOUD_PIPELINE Attributi.

attribute_value

Specifica il valore per l'attributo pipeline da impostare.

Per ulteriori informazioni, vedere DBMS_CLOUD_PIPELINE Attributi.

attributes

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

Per ulteriori informazioni, vedere DBMS_CLOUD_PIPELINE Attributi.

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.

START_PIPELINE Procedura

La procedura avvia la pipeline di dati. Quando viene avviata una pipeline, l'operazione viene eseguita in modo continuo in un job pianificato in base all'elemento 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

  • Per impostazione predefinita, un job della pipeline viene avviato immediatamente non appena la pipeline viene avviata. Per avviare un job pipeline in un secondo momento, specificare una data o un indicatore orario validi utilizzando il parametro start_date.

  • Per informazioni sulla pipeline interval e sugli altri attributi della pipeline, vedere DBMS_CLOUD_PIPELINE Attributi.

STOP_PIPELINE Procedura

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à tutti i job in esecuzione per la pipeline.

Valori validi: TRUE, FALSE

Valore predefinito: FALSE

DBMS_CLOUD_PIPELINE Attributi

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

Attributi

Nota

Come indicato nella colonna Tipo 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, visita il sito Web all'indirizzo field_list in Oracle Database 19c Utilities o Oracle Database 23ai Utilities.

Valore predefinito: NULL

Il valore predefinito specifica che 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.

Data Pump format non supportato per una pipeline di esportazione.

Questo attributo è obbligatorio sia per le pipeline LOAD che per quelle 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 data o indicatore orario nell'table o query specificato per l'esportazione continua di dati più recenti nell'area di memorizzazione degli oggetti. La data o l'indicatore orario 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, 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, 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 una priorità più alta consuma più risorse di 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 OCPU).
  • MEDIUM: determina il numero di processi simultanei utilizzando il limite di concorrenza per il servizio di medie dimensioni. Il valore predefinito è 4.
  • LOW: esegue il job 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, è obbligatorio specificare table_name o query.

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, è obbligatorio specificare table_name o query.

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.