Récapitulatif des sous-programmes DBMS_DCAT
Ce tableau répertorie les procédures de package DBMS_DCAT utilisées pour créer, interroger et supprimer des connexions Data Catalog.
| Sous-programme | Description |
|---|---|
| Procédure SET_DATA_CATALOG_CREDENTIAL | Définir les informations d'identification d'accès au catalogue de données utilisées par une connexion spécifique au catalogue de données |
| Procédure SET_OBJECT_STORE_CREDENTIAL | Définir les informations d'identification utilisées par l'identificateur de connexion unique indiqué pour accéder à la banque d'objets |
| Procédure SET_DATA_CATALOG_CONN | Créer une connexion au catalogue de données indiqué |
| Procédure UNSET_DATA_CATALOG_CONN | Enlever une connexion Data Catalog existante |
SET_DATA_CATALOG_CREDENTIAL - Procédure
Cette procédure définit les informations d'identification d'accès à Data Catalog utilisées par une connexion spécifique à Data Catalog.
Syntaxe
PROCEDURE DBMS_DCAT.SET_DATA_CATALOG_CREDENTIAL(
credential_name VARCHAR2(128) DEFAULT NULL,
dcat_con_id VARCHAR2 DEFAULT NULL
);
Paramètres
| Paramètre | Description |
|---|---|
credential_name |
Informations d'identification utilisées pour accéder au catalogue de données. |
dcat_con_id |
Identificateur de connexion unique du catalogue de données. Ces informations d'identification sont utilisées pour la connexion identifiée par dcat_con_id. Par défaut, la valeur NULL est affectée. |
Ces informations d'identification doivent disposer des droits d'accès Gérer Data Catalog. Reportez-vous à Stratégies Data Catalog.
Procédure SET_OBJECT_STORE_CREDENTIAL
Cette procédure définit les informations d'identification utilisées par l'identificateur de connexion unique donné pour accéder à la banque d'objets. La modification des informations d'identification d'accès à la banque d'objets modifie toutes les tables synchronisées existantes pour utiliser les nouvelles informations d'identification.
Syntaxe
PROCEDURE DBMS_DCAT.SET_OBJECT_STORE_CREDENTIAL(
credential_name VARCHAR2(128),
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Paramètres
| Paramètre | Description |
|---|---|
credential_name |
Informations d'identification utilisées par les tables externes pour accéder à la banque d'objets. |
dcat_con_id |
Identificateur de connexion unique du catalogue de données. Valeur par défaut : NULL. |
Procédure SET_DATA_CATALOG_CONN
Cette procédure crée une connexion au catalogue de données donné. La connexion est requise pour synchroniser les métadonnées avec Data Catalog. Une instance de base de données Autonomous AI peut se connecter à plusieurs instances Data Catalog et prend en charge la connexion à OCI Data Catalogs et AWS Glue Data Catalogs.
Syntaxe
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
);
Paramètres
| Paramètre | Description |
|---|---|
region |
Région Data Catalog. Si endpoint est indiqué, region est facultatif. Si endpoint et region sont fournis, endpoint est prioritaire. La valeur par défaut est NULL. |
endpoint |
Adresse Data Catalog. Si region est indiqué, endpoint est facultatif. Si endpoint et region sont fournis, endpoint est prioritaire. La valeur par défaut est NULL. |
catalog_id |
Identificateur Oracle Cloud (OCID) unique de l'instance Data Catalog. Lors de la connexion à AWS Glue Data Catalogs, catalog_id est facultatif. |
dcat_con_id |
Identificateur de connexion Data Catalog unique. Cet identificateur est requis lors de la connexion à plusieurs catalogues de données et facultatif lors de la connexion à un seul. Il est utilisé pour faire référence à la connexion Data Catalog lors des appels suivants ou lors de l'interrogation des vues. Si aucun identificateur n'est spécifié, cette procédure génère un identificateur de connexion NULL. Pour dcat_con_id, les restrictions suivantes s'appliquent :
|
catalog_type |
Type de catalogue de données à connecter. Valeurs autorisées :
|
token_endpoint |
Adresse de jeton d'accès pour l'authentification OAuth. La valeur par défaut est NULL. |
Utilisation
Vous n'avez besoin d'appeler cette procédure qu'une fois pour définir la connexion. Dans le cadre du processus de connexion, Autonomous AI Database ajoute des propriétés personnalisées à Data Catalog. Ces propriétés personnalisées sont accessibles aux utilisateurs de Data Catalog et vous permettent de remplacer les noms par défaut (pour les schémas, les tables et les colonnes) et les types de données de colonne.
Avant de créer une connexion, vous devez créer et définir des informations d'identification. Pour obtenir une description du processus de connexion, reportez-vous à Workflow standard avec Data Catalog pour les catalogues de données OCI et à Workflow utilisateur pour l'interrogation avec AWS Glue Data Catalog pour les catalogues de données AWS Glue.
Exemples
Exemple : connexion à un OCID connu
Dans cet exemple, la base de données Autonomous AI se connecte à Data Catalog dans la région uk-london-1. Le paramètre catalog_id utilise l'identificateur Oracle Cloud (ocid) pour l'instance Data Catalog. Le type de catalogue de données est déterminé automatiquement : AWS Glue Data Catalog ou OCI Data Catalog.
BEGIN
DBMS_DCAT.SET_DATA_CATALOG_CONN(
region=>'uk-london-1',
catalog_id=>'ocid1.datacatalog.oc1.uk-london-1...');
END;
/
Exemple : connexion à un catalogue de données AWS Glue
Une connexion est l'association entre une instance de base de données Autonomous AI et un catalogue de données AWS Glue. Une fois la connexion établie, l'instance de base de données Autonomous AI peut être synchronisée avec AWS Glue. Chaque compte AWS dispose d'un catalogue de données AWS Glue par région et chaque catalogue est accessible à l'aide de l'adresse de service correspondante pour chaque région. Une instance de base de données Autonomous AI peut être associée à un catalogue de données AWS Glue en appelant l'API DBMS_DCAT.SET_DATA_CATALOG_CONN et en indiquant l'adresse de la région dans laquelle le catalogue réside.
Reportez-vous à Adresses et quotas AWS Glue.
Dans cet exemple, Autonomous AI Database se connecte à un catalogue de données AWS Glue dans la région uk-london-1. Etant donné qu'il s'agit d'une connexion AWS Glue Data Catalog, le paramètre catalog_id n'est pas nécessaire.
BEGIN
DBMS_DCAT.SET_DATA_CATALOG_CONN(
region=>'uk-london-1',
catalog_type=>'AWS_GLUE'
END;
/
Procédure UNSET_DATA_CATALOG_CONN
Cette procédure supprime une connexion Data Catalog existante.
Syntaxe
Remarque : l'appel de cette procédure supprime tous les schémas protégés et toutes les tables externes qui ont été créés dans le cadre de synchronisations précédentes. Elle n'a pas d'impact sur les métadonnées dans Data Catalog.
PROCEDURE DBMS_DCAT.UNSET_DATA_CATALOG_CONN (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Paramètres
| Paramètre | Description |
|---|---|
dcat_con_id |
Identificateur de connexion unique du catalogue de données. La valeur par défaut est NULL. |
Sous-programmes de synchronisation
Vous pouvez exécuter une synchronisation, créer et supprimer un travail de synchronisation et supprimer des schémas synchronisés à l'aide des procédures répertoriées dans ce tableau.
Remarque : le 4 avril 2022, les paramètres sync_option et grant_read ont été ajoutés à la procédure DBMS_DCAT.RUN_SYNC. Pour garantir les performances correctes des travaux de synchronisation planifiés créés avant cette date, vous devez supprimer et recréer les travaux de synchronisation planifiés. Reportez-vous à Procédure DROP_SYNC_JOB et à Procédure CREATE_SYNC_JOB.
| Sous-programme | Description |
|---|---|
| Procédure CREATE_SYNC_JOB | Créer un travail de planificateur pour appeler RUN_SYNC régulièrement |
| Procédure DROP_SYNC_JOB | Supprimer un travail de synchronisation existant pour l'identificateur de connexion unique donné |
| Procédure DROP_SYNCED_SCHEMAS | Supprimer tous les schémas précédemment synchronisés pour l'identificateur de connexion unique donné |
| Procédure RUN_SYNC | Exécuter une opération de synchronisation |
Procédure RUN_SYNC
Cette procédure exécute une opération de synchronisation et constitue le point d'entrée de la synchronisation. En entrée, il prend des listes de ressources, de dossiers et d'entités de catalogue de données sélectionnés et les matérialise en créant, supprimant et modifiant des tables externes.
Le paramètre sync_option indique l'opération exécutée par la procédure RUN_SYNC : SYNC, DELETE ou REPLACE. L'opération est effectuée sur des entités comprises dans la portée du paramètre synced_objects.
Chaque appel de la procédure RUN_SYNC renvoie une valeur operation_id unique qui peut être utilisée pour interroger la vue USER_LOAD_OPERATIONS afin d'obtenir des informations sur le statut de la synchronisation et sur la valeur log_table correspondante. La vue DBMS_DCAT$SYNC_LOG peut être interrogée afin de faciliter l'accès à log_table pour la dernière opération de synchronisation exécutée par l'utilisateur en cours. Pour plus d'informations, reportez-vous à Vue DBMS_DCAT$SYNC_LOG.
Remarque : le 4 avril 2022, les paramètres sync_option et grant_read ont été ajoutés à la procédure DBMS_DCAT.RUN_SYNC. Pour garantir les performances correctes des travaux de synchronisation programmés créés avant cette date, vous devez supprimer et recréer les travaux de synchronisation programmés. Reportez-vous à Procédure DROP_SYNC_JOB et à Procédure CREATE_SYNC_JOB.
Synchronisation des entités logiques partitionnées ou des tables de colle
La procédure RUN_SYNC crée une table externe partitionnée pour chaque entité logique ou table Glue lorsque les trois éléments suivants s'appliquent :
-
L'entité logique ou la table Glue du catalogue de données OCI comporte un ou plusieurs attributs partitionnés.
-
Pour les catalogues de données OCI, l'entité logique est dérivée d'un modèle de nom de fichier basé sur un préfixe. Les entités logiques partitionnées dérivées de modèles basés sur des expressions régulières ne sont pas prises en charge.
-
Pour les catalogues de données OCI, l'entité logique est basée sur des données partitionnées qui suivent le format de dossier de type ruche ou non ruche. Les entités logiques basées sur des données partitionnées qui suivent le format de style non Beehive utilisant des noms d'objet ne sont pas prises en charge.
-
Exemple 1. Entités logiques basées sur des objets collectés qui suivent le format de partitionnement de style Hive avec des modèles de nom de fichier basés sur des préfixes.
Considérez les objets suivants :
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 collecte du bucket à l'aide d'un modèle de nom de fichier avec le préfixe de dossier de début
cluster1/db1.dbgénère une entité logique nomméeSALESavec trois attributs de partition :country,yearetmonth. Le type des attributs partitionnés estPartition, tandis que le type des attributs non partitionnés estPrimitive. -
Exemple 2. Entités logiques basées sur des objets collectés qui suivent le format de partitionnement de style non Hive avec des modèles de nom de fichier basés sur un préfixe.
Considérez les objets suivants :
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 collecte du bucket à l'aide d'un modèle de nom de fichier avec le préfixe de dossier de début
cluster2/db2.dbgénère une entité logique nomméeSALESavec trois attributs de partition :name0, name1 etname2. La seule différence entre l'entité logique générée et l'exemple 1 est que les noms des attributs partitionnés sont générés automatiquement, tandis que dans l'exemple 1, ils sont extraits de l'URL (country,yearetmonthrespectivement).
-
Pour obtenir un exemple complet de synchronisation d'entités logiques partitionnées de bout en bout, reportez-vous à Exemple : scénario de données partitionnées.
Synchronisation incrémentielle des entités logiques partitionnées/tables Glue
Chaque appel de la procédure RUN_SYNC indique un ensemble d'entités logiques du catalogue de données OCI ou de tables AWS Glue à synchroniser avec la base de données. Lorsqu'une entité logique ou une table Glue est présente dans deux appels RUN_SYNC, le deuxième appel conserve et modifie éventuellement les tables externes existantes. Le tableau suivant indique quelles modifications d'entité logique ou de table Glue sont prises en charge lorsque l'entité logique ou la table Glue est partitionnée :
| Modification d'une entité logique ou d'une table de colle | Action |
|---|---|
| Ajout, suppression ou mise à jour d'une partition | Toutes les partitions de la table partitionnée externe sont mises à jour, qu'une modification ait été détectée ou non par le catalogue de données. |
| Ajout d'un attribut partitionné | L'ajout d'une colonne partitionnée à une table partitionnée externe n'est pas pris en charge. Une exception est générée. |
| Suppression d'un attribut de partition | La suppression d'une colonne partitionnée à partir d'une table partitionnée externe n'est pas prise en charge. Une exception est générée. |
| Modification du nom d'un attribut partitionné | Le changement de nom d'une colonne partitionnée dans une table partitionnée externe n'est pas pris en charge. Une exception est générée. |
Syntaxe
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
);
Paramètres
| Paramètre | Description |
|---|---|
synced_objects |
Ce paramètre est un document JSON qui spécifie les objets de catalogue de données à synchroniser. Pour les catalogues de données OCI, le document JSON indique un ensemble d'entités de granularité multiple : ressources de données, dossiers (buckets Object Store) ou entités logiques. Il contient un élément Pour AWS Glue Data Catalogs, le document JSON indique une liste de tables de granularité multiple : bases de données, tables. Le document indique la liste des bases de données. Les utilisateurs peuvent restreindre l'ensemble de tables à synchroniser en indiquant des tables individuelles dans une base de données. |
sync_option |
(Facultatif) Trois options sont disponibles :
|
error_semantics |
(Facultatif) Ce paramètre indique le comportement de l'erreur. Si elle est définie sur SKIP_ERRORS, la synchronisation tente de continuer malgré les erreurs rencontrées pour des entités individuelles. Si elle est définie sur STOP_ON_ERROR, la procédure échoue lors de la première erreur rencontrée. La valeur par défaut est SKIP_ERRORS. |
log_level |
(Facultatif) Ce paramètre spécifie les valeurs suivantes pour augmenter le niveau de détail de journalisation : (OFF, FATAL, ERROR, WARN, INFO, DEBUG, TRACE, ALL). La valeur par défaut est INFO. |
grant_read |
(Facultatif) Ce paramètre est une liste d'utilisateurs/rôles auxquels des privilèges READ sont automatiquement accordés sur toutes les tables externes traitées par cet appel de RUN_SYNC. Tous les utilisateurs/rôles de la liste grant_read disposent de privilèges READ sur toutes les tables externes nouvelles ou existantes qui correspondent aux entités spécifiées par le paramètre synced_objects. La procédure RUN_SYNC conserve les privilèges déjà accordés sur les tables externes synchronisées. |
operation_id |
(Facultatif) Ce paramètre permet de rechercher l'entrée correspondante dans Remarque : une version de |
dcat_con_id |
Ce paramètre est l'identificateur de connexion de catalogue de données unique qui a été spécifié lors de la création de la connexion au catalogue de données. Reportez-vous à Procédure SET_DATA_CATALOG_CONN. Ce paramètre identifie la connexion utilisée pour la synchronisation et devient une partie du nom du schéma dérivé. Pour obtenir une description de la façon dont le nom de schéma est dérivé, reportez-vous à Mappage de synchronisation. La valeur par défaut du paramètre est NULL. |
Exemples
Exemple : Synchronisez toutes les entités OCI Data Catalog.
Dans l'exemple suivant, toutes les entités Data Catalog sont synchronisées.
EXEC DBMS_DCAT.RUN_SYNC(synced_objects=>'{"asset_list":["*"]}');
Exemple : paramètre synced_objects pour la synchronisation de toutes les ressources de données OCI Data Catalog.
Voici un exemple de paramètre synced_objects pour la synchronisation de toutes les ressources de données (Object Storage) dans Data Catalog.
{"asset_list" : ["*"]}
Exemple : paramètre synced_objects pour la synchronisation de ressources de données OCI Data Catalog spécifiques.
Voici un exemple de paramètre synced_objects pour la synchronisation de deux ressources de données.
{"asset_list": [
{
"asset_id":"...-9e2e7f78fd5f"
},
{
"asset_id":"...-9e2e7f74523"
}
]}
Exemple : paramètre synced_objects pour synchroniser des entités OCI Data Catalog spécifiques au sein d'une ressource de données.
L'exemple suivant illustre un paramètre synced_objects pour la synchronisation de deux entités au sein de la ressource de données.
{"asset_list": [
{
"asset_id":"...-9e2e7f78fd5f",
"folder_list":[
"f1",
"f2"
]
}
]}
Exemple : paramètre synced_objects permettant de synchroniser des entités et des dossiers OCI Data Catalog spécifiques au sein d'une ressource de données.
L'exemple suivant illustre un paramètre synced_objects pour synchroniser deux dossiers et deux entités au sein de la ressource de données.
{"asset_list":[
{
"asset_id":"...-9e2e7f78fd5f",
"entity_list": [
"entity1",
"entity2"
],
"folder_list": [
"f1",
"f2"
]
}
]}
Exemple : paramètre synced_objects pour la synchronisation de toutes les bases de données AWS Glue Data Catalog.
Voici un exemple de paramètre synced_objects pour la synchronisation de toutes les bases de données dans AWS Glue Data Catalog.
{"database_list":["*"]}
Exemple : paramètre synced_objects pour la synchronisation de deux bases de données AWS Glue Data Catalog.
Voici un exemple de paramètre synced_objects pour la synchronisation de deux bases de données AWS Glue Data Catalog.
{"database_list":[
{"database":"tpcdscsv"},
{"database":"tpcdsparquet"} ]}
Exemple : paramètre synced_objects pour la synchronisation de trois bases de données AWS Glue Data Catalog.
Voici un exemple de paramètre synced_objects pour la synchronisation de trois tables à partir d'une base de données AWS Glue Data Catalog.
{"database_list":[
{"database":"tpcdsparquet",
"table_list": [ "tpcdsparquet_customer",
"tpcdsparquet_item",
"tpcdsparquet_web_sales" ] } ]}
Procédure CREATE_SYNC_JOB
Cette procédure crée un travail de planificateur pour appeler RUN_SYNC régulièrement
Il prend en entrée l'ensemble des objets à synchroniser, la sémantique des erreurs, le niveau de journalisation et un intervalle de répétition. Pour plus d'informations sur le fonctionnement de la synchronisation, reportez-vous à Procédure RUN_SYNC.
Il ne peut y avoir qu'un seul travail de synchronisation. La procédure CREATE_SYNC_JOB échoue si un autre travail est déjà indiqué, sauf si le paramètre force est défini sur TRUE. Si force est définie sur TRUE, le travail précédent est supprimé.
Si un travail de planificateur tente de s'exécuter alors qu'une autre synchronisation est en cours, le travail de planificateur échoue.
Remarque : le 4 avril 2022, les paramètres sync_option et grant_read ont été ajoutés à la procédure DBMS_DCAT.RUN_SYNC. Pour garantir les performances correctes des travaux de synchronisation planifiés créés avant cette date, vous devez supprimer et recréer les travaux de synchronisation planifiés. Reportez-vous à Procédure DROP_SYNC_JOB et à Procédure CREATE_SYNC_JOB.
Syntaxe
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
);
Paramètres
| Paramètre | Description |
|---|---|
synced_objects |
Objet JSON indiquant les objets à synchroniser, comme décrit dans la procédure RUN_SYNC. Reportez-vous à Procédure RUN_SYNC. |
error_semantics |
(Facultatif) Comportement en cas d'erreur, comme indiqué pour RUN_SYNC. La valeur par défaut est SKIP_ERRORS. |
log_level |
(Facultatif) Niveau de journalisation, comme indiqué pour RUN_SYNC. La valeur par défaut est INFO. |
repeat_interval |
Intervalle de répétition du travail, avec la même sémantique que le paramètre d'intervalle de répétition de la procédure DBMS_SCHEDULER.CREATE_JOB. Pour plus d'informations sur repeat_interval, reportez-vous à Présentation de la création de travaux. |
force |
(Facultatif) Si TRUE, les travaux de synchronisation existants sont d'abord supprimés. Si FALSE, la procédure CREATE_SYNC_JOB échoue si un travail de synchronisation existe déjà. La valeur par défaut est FALSE. |
grant_read |
(Facultatif) Liste des utilisateurs/rôles auxquels l'accès en lecture est accordé sur les tables externes synchronisées, comme décrit pour la procédure RUN_SYNC. Reportez-vous à Procédure RUN_SYNC. |
sync_option |
(Facultatif) Comportement concernant les entités qui ont déjà été synchronisées via une opération RUN_SYNC précédente, comme décrit pour la procédure RUN_SYNC. Reportez-vous à Procédure RUN_SYNC. |
dcat_con_id |
Ce paramètre est l'identificateur de connexion unique Data Catalog indiqué lors de la création de la connexion à Data Catalog. Reportez-vous à Procédure SET_DATA_CATALOG_CONN. Ce paramètre identifie la connexion utilisée pour la synchronisation et devient une partie du nom du schéma dérivé. Pour obtenir une description de la façon dont le nom de schéma est dérivé, reportez-vous à Mappage de synchronisation. La valeur par défaut du paramètre est NULL. |
Procédure DROP_SYNC_JOB
Cette procédure supprime un travail de synchronisation existant pour l'identificateur de connexion unique donné.
Syntaxe
PROCEDURE DBMS_DCAT.DROP_SYNC_JOB (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Paramètres
| Paramètre | Description |
|---|---|
dcat_con_id |
Identificateur de connexion unique du catalogue de données. Valeur par défaut : NULL. |
Procédure DROP_SYNCED_SCHEMAS
Cette procédure supprime tous les schémas précédemment synchronisés pour l'identificateur de connexion unique donné.
Syntaxe
PROCEDURE DBMS_DCAT.DROP_SYNCED_SCHEMAS (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Paramètres
| Paramètre | Description |
|---|---|
dcat_con_id |
Identificateur de connexion unique du catalogue de données. Valeur par défaut : NULL. |