Riepilogo dei sottoprogrammi DBMS_DCAT
In questa tabella sono elencate le procedure del package DBMS_DCAT utilizzate per creare, eseguire query ed eliminare le connessioni al Data Catalog.
| Sottoprogramma | Descrizione |
|---|---|
| SET_DATA_CATALOG_CREDENTIAL Procedura | Impostare la credenziale di accesso al Data Catalog utilizzata da una connessione specifica al Data Catalog |
| Procedura SET_OBJECT_STORE_CREDENTIAL | Imposta la credenziale utilizzata dall'identificativo di connessione univoco specificato per accedere all'area di memorizzazione degli oggetti |
| Procedura SET_DATA_CATALOG_CONN | Creare una connessione al Data Catalog specificato |
| Procedura UNSET_DATA_CATALOG_CONN | Rimuovere una connessione Data Catalog esistente |
SET_DATA_CATALOG_CREDENTIAL Procedura
Questa procedura imposta le credenziali di accesso al Data Catalog utilizzate da una connessione specifica al Data Catalog.
Sintassi
PROCEDURE DBMS_DCAT.SET_DATA_CATALOG_CREDENTIAL(
credential_name VARCHAR2(128) DEFAULT NULL,
dcat_con_id VARCHAR2 DEFAULT NULL
);
Parametri
| Parametro | Descrizione |
|---|---|
credential_name |
Credenziale utilizzata per accedere al Data Catalog. |
dcat_con_id |
Identificativo di connessione Data Catalog univoco. Questa credenziale viene utilizzata per la connessione identificata da dcat_con_id. L'impostazione predefinita è Null. |
Questa credenziale deve disporre delle autorizzazioni Gestisci Data Catalog; vedere Criteri Data Catalog.
Procedura SET_OBJECT_STORE_CREDENTIAL
Questa procedura imposta la credenziale utilizzata dall'identificativo di connessione univoco specificato per accedere all'area di memorizzazione degli oggetti. La modifica delle credenziali di accesso all'area di memorizzazione degli oggetti modifica tutte le tabelle sincronizzate esistenti per utilizzare la nuova credenziale.
Sintassi
PROCEDURE DBMS_DCAT.SET_OBJECT_STORE_CREDENTIAL(
credential_name VARCHAR2(128),
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parametri
| Parametro | Descrizione |
|---|---|
credential_name |
Credenziale utilizzata dalle tabelle esterne per accedere all'area di memorizzazione degli oggetti. |
dcat_con_id |
Identificativo di connessione Data Catalog univoco. Il valore predefinito è NULL. |
Procedura SET_DATA_CATALOG_CONN
Questa procedura crea una connessione al Data Catalog specificato. La connessione è necessaria per sincronizzare i metadati con Data Catalog. Un'istanza di Autonomous AI Database può connettersi a più istanze di Data Catalog e supporta la connessione a OCI Data Catalog e AWS Glue Data Catalogs.
Sintassi
PROCEDURE DBMS_DCAT.SET_DATA_CATALOG_CONN (
region VARCHAR2 DEFAULT NULL,
endpoint VARCHAR2 DEFAULT NULL,
catalog_id VARCHAR2 DEFAULT NULL,
dcat_con_id VARCHAR2 DEFAULT NULL,
catalog_type VARCHAR2 DEFAULT NULL,
token_endpoint VARCHAR2 DEFAULT Null
);
Parametri
| Parametro | Descrizione |
|---|---|
region |
Area Data Catalog. Se si specifica endpoint, region è facoltativo. Se vengono specificati sia endpoint che region, il valore endpoint ha la precedenza. Il valore predefinito è NULL. |
endpoint |
Endpoint Data Catalog. Se si specifica region, endpoint è facoltativo. Se vengono specificati sia endpoint che region, il valore endpoint ha la precedenza. Il valore predefinito è NULL. |
catalog_id |
L'OCID (Oracle Cloud Identifier) univoco per l'istanza di Data Catalog. Quando ci si connette ad AWS Glue Data Catalogs, catalog_id è facoltativo. |
dcat_con_id |
Identificativo di connessione Data Catalog univoco. Questo identificativo è obbligatorio quando si esegue la connessione a più Data Catalog ed è facoltativo quando si esegue la connessione a uno solo. Viene utilizzato per fare riferimento alla connessione Data Catalog nelle chiamate successive o durante l'esecuzione di query sulle viste. Se non viene specificato alcun identificativo, questa procedura genera un identificativo di connessione NULL. Per dcat_con_id sono previste le limitazioni riportate di seguito:
|
catalog_type |
Tipo di Data Catalog da connettere. Valori consentiti:
|
token_endpoint |
Endpoint del token di accesso per l'autenticazione OAuth. Il valore predefinito è NULL. |
Utilizzo
È necessario chiamare questa procedura solo una volta per impostare la connessione. Nell'ambito del processo di connessione, Autonomous AI Database aggiunge proprietà personalizzate a Data Catalog. Queste proprietà personalizzate sono accessibili agli utenti di Data Catalog e consentono di sostituire i nomi predefiniti (per schemi, tabelle e colonne) e i tipi di dati delle colonne.
Prima di creare una connessione, è necessario creare e impostare le credenziali. Per una descrizione del processo di connessione, vedere Workflow tipico con Data Catalog per OCI Data Catalog e Workflow utente per l'esecuzione di query con AWS Glue Data Catalog per AWS Glue Data Catalogs.
Esempi
Esempio: connessione a un OCID noto
In questo esempio, Autonomous AI Database si sta connettendo a Data Catalog nell'area uk-london-1. Il parametro catalog_id utilizza l'identificativo Oracle Cloud (ocid) per l'istanza di Data Catalog. Il tipo di Data Catalog viene determinato automaticamente: AWS Glue Data Catalog o OCI Data Catalog.
BEGIN
DBMS_DCAT.SET_DATA_CATALOG_CONN(
region=>'uk-london-1',
catalog_id=>'ocid1.datacatalog.oc1.uk-london-1...');
END;
/
Esempio: connessione a un AWS Glue Data Catalog
Una connessione è l'associazione tra un'istanza di Autonomous AI Database e un AWS Glue Data Catalog. Dopo una connessione riuscita, l'istanza di Autonomous AI Database è in grado di sincronizzarsi con AWS Glue. Ogni account AWS dispone di un AWS Glue Data Catalog per regione e è possibile accedere a ogni catalogo utilizzando l'endpoint del servizio corrispondente per ogni regione. Un'istanza di Autonomous AI Database può essere associata a un AWS Glue Data Catalog richiamando l'API DBMS_DCAT.SET_DATA_CATALOG_CONN e specificando l'endpoint per l'area in cui risiede il catalogo.
Vedere Endpoint e quote AWS Glue.
In questo esempio, Autonomous AI Database si sta connettendo a un AWS Glue Data Catalog nell'area uk-london-1. Poiché si tratta di una connessione AWS Glue Data Catalog, il parametro catalog_id non è necessario.
BEGIN
DBMS_DCAT.SET_DATA_CATALOG_CONN(
region=>'uk-london-1',
catalog_type=>'AWS_GLUE'
END;
/
Procedura UNSET_DATA_CATALOG_CONN
Questa procedura rimuove una connessione al Data Catalog esistente.
Sintassi
Nota: se si richiama questa procedura, vengono eliminati tutti gli schemi protetti e le tabelle esterne creati nell'ambito delle sincronizzazioni precedenti. Non influisce sui metadati in Data Catalog.
PROCEDURE DBMS_DCAT.UNSET_DATA_CATALOG_CONN (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parametri
| Parametro | Descrizione |
|---|---|
dcat_con_id |
Identificativo di connessione Data Catalog univoco. L'impostazione predefinita è Null. |
Sottoprogrammi di sincronizzazione
È possibile eseguire una sincronizzazione, la creazione e l'eliminazione di un job di sincronizzazione e di schemi sincronizzati con le procedure elencate in questa tabella.
Nota: il 4 aprile 2022, i parametri sync_option e grant_read sono stati aggiunti alla procedura DBMS_DCAT.RUN_SYNC. Per garantire le prestazioni corrette dei job di sincronizzazione schedulati creati prima di tale data, è necessario eliminare e ricreare i job di sincronizzazione schedulati. Vedere Procedura DROP_SYNC_JOB e Procedura CREATE_SYNC_JOB.
| Sottoprogramma | Descrizione |
|---|---|
| Procedura CREATE_SYNC_JOB | Creare un job scheduler per richiamare periodicamente RUN_SYNC |
| Procedura DROP_SYNC_JOB | Elimina un job di sincronizzazione esistente per l'identificativo di connessione univoco specificato |
| Procedura DROP_SYNCED_SCHEMAS | Elimina tutti gli schemi sincronizzati in precedenza per l'identificativo di connessione univoco specificato |
| Procedura RUN_SYNC | Eseguire un'operazione di sincronizzazione |
Procedura RUN_SYNC
Questa procedura esegue un'operazione di sincronizzazione ed è il punto di accesso alla sincronizzazione. Come input, acquisisce elenchi di asset, cartelle ed entità di Data Catalog selezionati e li materializza creando, eliminando e modificando tabelle esterne.
Il parametro sync_option specifica l'operazione eseguita dalla procedura RUN_SYNC: SYNC, DELETE o REPLACE. L'operazione viene eseguita su entità incluse nell'ambito del parametro synced_objects.
Ogni chiamata alla procedura RUN_SYNC restituisce un operation_id univoco che può essere utilizzato per eseguire una query sulla vista USER_LOAD_OPERATIONS per ottenere informazioni sullo stato della sincronizzazione e sul corrispondente log_table. È possibile eseguire query sulla vista DBMS_DCAT$SYNC_LOG per accedere facilmente a log_table per l'ultima operazione di sincronizzazione eseguita dall'utente corrente. Per ulteriori dettagli, vedere Vista DBMS_DCAT$SYNC_LOG.
Nota: il 4 aprile 2022, i parametri sync_option e grant_read sono stati aggiunti alla procedura DBMS_DCAT.RUN_SYNC. Per garantire le prestazioni corrette dei job di sincronizzazione schedulati creati prima di tale data, è necessario eliminare e ricreare i job di sincronizzazione schedulati. Vedere Procedura DROP_SYNC_JOB e Procedura CREATE_SYNC_JOB.
Sincronizzazione delle entità logiche partizionate o delle tabelle di colla
La procedura RUN_SYNC crea una tabella esterna partizionata per ogni entità logica o tabella Glue quando si applicano tutte e tre le condizioni riportate di seguito.
-
L'entità logica o la tabella Colla di OCI Data Catalog dispone di uno o più attributi partizionati.
-
Per i Data Catalog OCI, l'entità logica deriva da un pattern di nomi file basato su prefissi. Le entità logiche partizionate derivate da pattern basati su espressioni regolari non sono supportate.
-
Per i Data Catalog OCI, l'entità logica si basa su dati partizionati che seguono il formato della cartella hive-style o non Beehive. Le entità logiche basate su dati partizionati che seguono il formato di stile non Beehive utilizzando i nomi oggetto non sono supportate.
-
Esempio 1. Entità logiche basate su oggetti raccolti che seguono il formato di partizionamento di stile Hive con pattern di nomi file basati su prefissi.
Considerare gli oggetti riportati di seguito.
Bucket: MYBUCKET cluster1/db1.db/sales/country=USA/year=2020/month=01/sales1.csv cluster1/db1.db/sales/country=USA/year=2020/month=01/sales2.csv cluster1/db1.db/sales/country=USA/year=2020/month=02/sales1.csvLa raccolta del bucket mediante un pattern di nomi file con un prefisso di cartella iniziale
cluster1/db1.dbgenera un'entità logica denominataSALEScon tre attributi di partizione:country,yearemonth. Il tipo per gli attributi partizionati èPartitionmentre il tipo per gli attributi non partizionati èPrimitive. -
Esempio 2. Entità logiche basate su oggetti raccolti che seguono il formato di partizionamento in stile non Hive con pattern di nomi file basati su prefissi.
Considerare gli oggetti riportati di seguito.
Bucket: MYBUCKET cluster2/db2.db/sales/USA/2020/01/sales1.csv cluster2/db2.db/sales/USA/2020/01/sales2.csv cluster2/db2.db/sales/USA/2020/02/sales1.csvLa raccolta del bucket mediante un pattern di nomi file con un prefisso di cartella iniziale
cluster2/db2.dbgenera un'entità logica denominataSALEScon tre attributi di partizione:name0, name1 ename2. L'unica differenza tra l'entità logica generata rispetto all'esempio 1 è che i nomi degli attributi partizionati vengono generati automaticamente, mentre nell'esempio 1 vengono estratti dall'URL (rispettivamentecountry,yearemonth).
-
Per un esempio completo di sincronizzazione delle entità logiche partizionate, vedere Esempio: scenario di dati partizionati.
Sincronizzazione incrementale di entità logiche partizionate/tabelle Glue
Ogni chiamata alla procedura RUN_SYNC specifica un set di entità logiche del Data Catalog OCI o tabelle AWS Glue da sincronizzare con il database. Quando un'entità logica o una tabella Colla è presente in due chiamate RUN_SYNC, la seconda chiamata conserva ed eventualmente altera le tabelle esterne esistenti. La tabella riportata di seguito mostra quali modifiche all'entità logica o alla tabella Colla sono supportate quando l'entità logica o la tabella Colla è partizionata.
| Modifica entità logica o tabella colla | Azione |
|---|---|
| Aggiunta, rimozione o aggiornamento di una partizione | Tutte le partizioni della tabella partizionata esterna vengono aggiornate, indipendentemente dal fatto che sia stata rilevata una modifica dal Data Catalog. |
| Aggiunta di un attributo partizionato | L'aggiunta di una colonna partizionata a una tabella partizionata esterna non è supportata. Viene generata un'eccezione. |
| Eliminazione di un attributo di partizione | L'eliminazione di una colonna partizionata da una tabella partizionata esterna non è supportata. Viene generata un'eccezione. |
| Ridenominazione di un attributo partizionato | La ridenominazione di una colonna partizionata in una tabella partizionata esterna non è supportata. Eccezione generata. |
Sintassi
PROCEDURE DBMS_DCAT.RUN_SYNC (
synced_objects IN CLOB,
sync_option IN VARCHAR2 DEFAULT 'SYNC',
error_semantics IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
log_level IN VARCHAR2 DEFAULT 'INFO',
grant_read IN VARCHAR2 DEFAULT NULL,
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
PROCEDURE DBMS_DCAT.RUN_SYNC (
synced_objects IN CLOB,
sync_option IN VARCHAR2 DEFAULT 'SYNC',
error_semantics IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
log_level IN VARCHAR2 DEFAULT 'INFO',
grant_read IN VARCHAR2 DEFAULT NULL,
operation_id OUT NOCOPY NUMBER,
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parametri
| Parametro | Descrizione |
|---|---|
synced_objects |
Questo parametro è un documento JSON che specifica gli oggetti Data Catalog da sincronizzare. Per i Data Catalog OCI, il documento JSON specifica un set di entità con più granularità: asset di dati, cartelle (bucket dell'area di memorizzazione degli oggetti) o entità logiche. Contiene un Per AWS Glue Data Catalogs, il documento JSON specifica un elenco di tabelle in più granularità: database, tabelle. Il documento specifica una lista di database. Gli utenti possono limitare il set di tabelle da sincronizzare specificando singole tabelle all'interno di un database. |
sync_option |
(Opzionale) Sono disponibili tre opzioni:
|
error_semantics |
(Facoltativo) Questo parametro specifica il funzionamento dell'errore. Se impostato su SKIP_ERRORS, la sincronizzazione tenta di continuare nonostante gli errori rilevati per le singole entità. Se impostato su STOP_ON_ERROR, la procedura non riesce al primo errore rilevato. L'impostazione predefinita è SKIP_ERRORS. |
log_level |
(Facoltativo) Questo parametro specifica i seguenti valori nell'aumento del livello dei dettagli di log: (OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL). L'impostazione predefinita è INFO. |
grant_read |
(Facoltativo) Questo parametro è un elenco di utenti/ruoli ai quali vengono concessi automaticamente i privilegi READ su tutte le tabelle esterne elaborate da questo richiamo di RUN_SYNC. A tutti gli utenti/ruoli della lista grant_read vengono assegnati privilegi READ su tutte le tabelle esterne nuove o già esistenti che corrispondono alle entità specificate dal parametro synced_objects. La procedura RUN_SYNC conserva i privilegi già concessi sulle tabelle esterne sincronizzate. |
operation_id |
(Facoltativo) Questo parametro viene utilizzato per trovare la voce corrispondente in Nota: è disponibile una versione di |
dcat_con_id |
Questo parametro è l'identificativo di connessione di Data Catalog univoco specificato al momento della creazione della connessione al Data Catalog. Vedere la procedura SET_DATA_CATALOG_CONN. Questo parametro identifica la connessione utilizzata per la sincronizzazione e diventa parte del nome dello schema derivato. Vedere Mapping sincronizzazione per una descrizione delle modalità di derivazione del nome dello schema. Il valore predefinito del parametro è NULL. |
Esempi
Esempio: sincronizza tutte le entità di OCI Data Catalog.
Nell'esempio seguente vengono sincronizzate tutte le entità di Data Catalog.
EXEC DBMS_DCAT.RUN_SYNC(synced_objects=>'{"asset_list":["*"]}');
Esempio: parametro synced_objects per la sincronizzazione di tutti gli asset dati di OCI Data Catalog.
Di seguito è riportato un parametro synced_objects di esempio per la sincronizzazione di tutti gli asset dati (storage degli oggetti) nel Data Catalog.
{"asset_list" : ["*"]}
Esempio: parametro synced_objects per la sincronizzazione di asset dati OCI Data Catalog specifici.
Di seguito è riportato un parametro synced_objects di esempio per la sincronizzazione di due asset dati.
{"asset_list": [
{
"asset_id":"...-9e2e7f78fd5f"
},
{
"asset_id":"...-9e2e7f74523"
}
]}
Esempio: parametro synced_objects per la sincronizzazione di entità OCI Data Catalog specifiche all'interno di un asset dati.
Di seguito è riportato un parametro synced_objects di esempio per la sincronizzazione di due entità all'interno dell'asset dati.
{"asset_list": [
{
"asset_id":"...-9e2e7f78fd5f",
"folder_list":[
"f1",
"f2"
]
}
]}
Esempio: parametro synced_objects per la sincronizzazione di cartelle ed entità OCI Data Catalog specifiche all'interno di un asset dati.
Di seguito è riportato un parametro synced_objects di esempio per la sincronizzazione di due cartelle e due entità all'interno dell'asset dati.
{"asset_list":[
{
"asset_id":"...-9e2e7f78fd5f",
"entity_list": [
"entity1",
"entity2"
],
"folder_list": [
"f1",
"f2"
]
}
]}
Esempio: parametro synced_objects per la sincronizzazione di tutti i database AWS Glue Data Catalog.
Di seguito è riportato un parametro synced_objects di esempio per la sincronizzazione di tutti i database in AWS Glue Data Catalog.
{"database_list":["*"]}
Esempio: parametro synced_objects per la sincronizzazione di due database AWS Glue Data Catalog.
Di seguito è riportato un parametro synced_objects di esempio per la sincronizzazione di due database AWS Glue Data Catalog.
{"database_list":[
{"database":"tpcdscsv"},
{"database":"tpcdsparquet"} ]}
Esempio: parametro synced_objects per la sincronizzazione di tre database AWS Glue Data Catalog.
Di seguito è riportato un parametro synced_objects di esempio per la sincronizzazione di tre tabelle da un database AWS Glue Data Catalog.
{"database_list":[
{"database":"tpcdsparquet",
"table_list": [ "tpcdsparquet_customer",
"tpcdsparquet_item",
"tpcdsparquet_web_sales" ] } ]}
Procedura CREATE_SYNC_JOB
Questa procedura crea un job scheduler per richiamare periodicamente RUN_SYNC
Richiede come input il set di oggetti da sincronizzare, la semantica degli errori, il livello di log e un intervallo di ripetizione. Per ulteriori informazioni sul funzionamento della sincronizzazione, vedere Procedura RUN_SYNC.
Può esistere un solo job di sincronizzazione. La procedura CREATE_SYNC_JOB non riesce se è già stato specificato un altro job, a meno che il parametro force non sia impostato su TRUE. Se la forzatura è impostata su TRUE, il job precedente viene eliminato.
Se un job scheduler tenta di essere eseguito mentre è in corso un'altra sincronizzazione, il job scheduler non riesce.
Nota: il 4 aprile 2022, i parametri sync_option e grant_read sono stati aggiunti alla procedura DBMS_DCAT.RUN_SYNC. Per garantire le prestazioni corrette dei job di sincronizzazione schedulati creati prima di tale data, è necessario eliminare e ricreare i job di sincronizzazione schedulati. Vedere Procedura DROP_SYNC_JOB e Procedura CREATE_SYNC_JOB.
Sintassi
PROCEDURE DBMS_DCAT.CREATE_SYNC_JOB (
synced_objects IN CLOB,
error_semantics IN VARCHAR2 DEFAULT 'SKIP_ERRORS',
log_level IN VARCHAR2 DEFAULT 'INFO',
repeat_interval IN VARCHAR2,
force IN VARCHAR2 DEFAULT 'FALSE',
grant_read IN VARCHAR2 DEFAULT NULL,
sync_option IN VARCHAR2 DEFAULT 'SYNC',
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parametri
| Parametro | Descrizione |
|---|---|
synced_objects |
Oggetto JSON che specifica gli oggetti da sincronizzare, come descritto nella procedura RUN_SYNC. Vedere RUN_SYNC Procedure. |
error_semantics |
(Facoltativo) Funzionamento dell'errore, come specificato per RUN_SYNC. L'impostazione predefinita è SKIP_ERRORS. |
log_level |
(Facoltativo) Livello di registrazione, come specificato per RUN_SYNC. L'impostazione predefinita è INFO. |
repeat_interval |
Ripetere l'intervallo per il job, con la stessa semantica del parametro intervallo di ripetizione della procedura DBMS_SCHEDULER.CREATE_JOB. Per informazioni dettagliate su repeat_interval, vedere Panoramica sulla creazione di job. |
force |
(Facoltativo) Se TRUE, i job di sincronizzazione esistenti vengono eliminati per primi. Se FALSE, la procedura CREATE_SYNC_JOB non riesce se esiste già un job di sincronizzazione. L'impostazione predefinita è FALSE. |
grant_read |
(Facoltativo) Elenco di utenti/ruoli a cui concedere READ sulle tabelle esterne sincronizzate, come descritto per la procedura RUN_SYNC. Vedere RUN_SYNC Procedure. |
sync_option |
(Facoltativo) Comportamento relativo alle entità già sincronizzate tramite una precedente operazione RUN_SYNC, come descritto per la procedura RUN_SYNC. Vedere RUN_SYNC Procedure. |
dcat_con_id |
Questo parametro è l'identificativo di connessione Data Catalog univoco specificato al momento della creazione della connessione a Data Catalog. Vedere Procedura SET_DATA_CATALOG_CONN. Questo parametro identifica la connessione utilizzata per la sincronizzazione e diventa parte del nome dello schema derivato. Vedere Mapping sincronizzazione per una descrizione delle modalità di derivazione del nome dello schema. Il valore predefinito del parametro è NULL. |
Procedura DROP_SYNC_JOB
Questa procedura elimina un job di sincronizzazione esistente per l'identificativo di connessione univoco specificato.
Sintassi
PROCEDURE DBMS_DCAT.DROP_SYNC_JOB (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parametri
| Parametro | Descrizione |
|---|---|
dcat_con_id |
Identificativo di connessione Data Catalog univoco. Il valore predefinito è NULL. |
Procedura DROP_SYNCED_SCHEMAS
Questa procedura elimina tutti gli schemi sincronizzati in precedenza per l'identificativo di connessione univoco specificato.
Sintassi
PROCEDURE DBMS_DCAT.DROP_SYNCED_SCHEMAS (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Parametri
| Parametro | Descrizione |
|---|---|
dcat_con_id |
Identificativo di connessione Data Catalog univoco. Il valore predefinito è NULL. |