Sommaire des sous-programmes DBMS_DCAT
Ce tableau répertorie les procédures d'ensemble DBMS_DCAT utilisées pour créer, interroger et supprimer des connexions au catalogue de données.
| Sous-programme | Description |
|---|---|
| Procédure SET_DATA_CATALOG_CREDENTIAL | Définir les données 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 données d'identification utilisées par l'identificateur de connexion unique indiqué pour accéder au magasin d'objets |
| Procédure SET_DATA_CATALOG_CONN | Créer une connexion au catalogue de données indiqué |
| Procédure UNSET_DATA_CATALOG_CONN | Supprimer une connexion existante au catalogue de données |
Procédure SET_DATA_CATALOG_CREDENTIAL
Cette procédure définit les données d'identification d'accès au catalogue de données utilisées par une connexion spécifique au catalogue de données.
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 |
Données d'identification utilisées pour accéder au catalogue de données. |
dcat_con_id |
Identificateur unique de connexion au catalogue de données. Ces données d'identification sont utilisées pour la connexion identifiée par dcat_con_id. La valeur par défaut est Null. |
Ces données d'identification doivent avoir les autorisations Gérer le catalogue de données; voir Politiques de catalogue de données.
Procédure SET_OBJECT_STORE_CREDENTIAL
Cette procédure définit les données d'identification utilisées par l'identificateur de connexion unique indiqué pour accéder au magasin d'objets. La modification des données d'identification d'accès au magasin d'objets modifie toutes les tables synchronisées existantes pour utiliser les nouvelles données 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 |
Données d'identification utilisées par les tables externes pour accéder au magasin d'objets. |
dcat_con_id |
Identificateur unique de connexion au catalogue de données. La valeur par défaut est NULL. |
Procédure SET_DATA_CATALOG_CONN
Cette procédure crée une connexion au catalogue de données indiqué. La connexion est requise pour synchroniser les métadonnées avec le catalogue de données. Une instance de base de données autonome avec intelligence artificielle peut se connecter à plusieurs instances de catalogue de données et prend en charge la connexion aux catalogues de données OCI et aux catalogues de données AWS Glue.
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 Catalogue de données. Si endpoint est spécifié, region est facultatif. Si endpoint et region sont indiqués, endpoint a préséance. La valeur par défaut est NULL. |
endpoint |
Point d'extrémité du catalogue de données. Si region est spécifié, endpoint est facultatif. Si endpoint et region sont indiqués, endpoint a préséance. La valeur par défaut est NULL. |
catalog_id |
Identificateur Oracle Cloud unique (OCID) pour l'instance de catalogue de données. Lors de la connexion à AWS Glue Data Catalogs, catalog_id est facultatif. |
dcat_con_id |
Identificateur unique de connexion au catalogue de données. Cet identificateur est requis lors de la connexion à plusieurs catalogues de données et est facultatif lors de la connexion à un seul catalogue. Il est utilisé pour faire référence à la connexion au catalogue de données lors d'appels ultérieurs ou lors de l'interrogation de vues. Si aucun identificateur n'est indiqué, cette procédure génère un identificateur de connexion NULL. Les restrictions suivantes s'appliquent à dcat_con_id :
|
catalog_type |
Type de catalogue de données à connecter. Valeurs autorisées :
|
token_endpoint |
Point d'extrémité de jeton d'accès pour l'authentification OAuth. La valeur par défaut est NULL. |
Syntaxe
Vous n'avez besoin d'appeler cette procédure qu'une seule fois pour définir la connexion. Dans le cadre du processus de connexion, Autonomous AI Database ajoute des propriétés personnalisées au catalogue de données. Ces propriétés personnalisées sont accessibles aux utilisateurs du catalogue de données 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, les données d'identification doivent être créées et définies. Pour une description du processus de connexion, voir Flux de travail type avec le catalogue de données pour les catalogues de données OCI et Flux de travail d'utilisateur pour l'interrogation avec le catalogue de données AWS Glue pour les catalogues de données AWS Glue.
Exemples
Exemple : Connexion avec un OCID connu
Dans cet exemple, Autonomous AI Database se connecte au catalogue de données dans la région uk-london-1. Le paramètre catalog_id utilise l'identificateur Oracle Cloud (ocid) pour l'instance de catalogue de données. Le type de catalogue de données est déterminé automatiquement : Catalogue de données AWS Glue ou Catalogue de données OCI.
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 IA autonome et un catalogue de données AWS Glue. Après une connexion réussie, l'instance de base de données Autonomous AI Database peut se synchroniser 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 du point d'extrémité de service correspondant pour chaque région. Une instance de base de données d'intelligence artificielle autonome peut être associée à un catalogue de données de colle AWS en appelant l'API DBMS_DCAT.SET_DATA_CATALOG_CONN et en spécifiant le point d'extrémité pour la région où réside le catalogue.
Voir Points d'extrémité et quotas de la colle AWS.
Dans cet exemple, Autonomous AI Database se connecte à un catalogue de données de colle AWS dans la région uk-london-1. Comme il s'agit d'une connexion au catalogue de données AWS Glue, 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 existante au catalogue de données.
Syntaxe
Note : L'appel de cette procédure supprime tous les schémas protégés et toutes les tables externes créés dans le cadre des synchronisations précédentes. Cela n'a aucune incidence sur les métadonnées du catalogue de données.
PROCEDURE DBMS_DCAT.UNSET_DATA_CATALOG_CONN (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Paramètres
| Paramètre | Description |
|---|---|
dcat_con_id |
Identificateur unique de connexion au catalogue de données. La valeur par défaut est nulle. |
Sous-programmes de synchronisation
L'exécution d'une synchronisation, la création et la suppression d'un travail de synchronisation et la suppression de schémas synchronisés peuvent être effectuées avec les procédures répertoriées dans ce tableau.
Note : 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 la bonne exécution des tâches de synchronisation programmées créées avant cette date, vous devez supprimer et recréer les tâches de synchronisation programmées. Voir Procédure DROP_SYNC_JOB et Procédure CREATE_SYNC_JOB.
| Sous-programme | Description |
|---|---|
| Procédure CREATE_SYNC_JOB | Créer un travail de programmateur pour appeler RUN_SYNC périodiquement |
| Procédure DROP_SYNC_JOB | Supprimer une tâche de synchronisation existante pour l'identificateur de connexion unique indiqué |
| Procédure DROP_SYNCED_SCHEMAS | Supprimer tous les schémas synchronisés précédemment pour l'identificateur de connexion unique indiqué |
| 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 tant qu'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, en supprimant et en modifiant des tables externes.
Le paramètre sync_option spécifie l'opération effectuée par la procédure RUN_SYNC : SYNC, DELETE ou REPLACE. L'opération est effectuée sur des entités dans la portée du paramètre synced_objects.
Chaque appel à la procédure RUN_SYNC retourne 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 la valeur log_table correspondante. La vue DBMS_DCAT$SYNC_LOG peut être interrogée pour permettre un accès facile à log_table pour la dernière opération de synchronisation exécutée par l'utilisateur courant. Pour plus de détails, voir Vue DBMS_DCAT$SYNC_LOG.
Note : 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 la bonne exécution des tâches de synchronisation programmées créées avant cette date, vous devez supprimer et recréer les tâches de synchronisation programmées. Voir 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 de colle lorsque les trois éléments suivants s'appliquent :
-
L'entité logique du catalogue de données OCI ou la table de colle 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 des préfixes. Les entités logiques partitionnées dérivées de modèles basés sur une expression rationnelle 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 autre. Les entités logiques basées sur des données partitionnées qui suivent le format de style non ruche 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.
Tenez compte des 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 seau à 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 estPartitionalors que celui 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 des préfixes.
Tenez compte des 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 seau à 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, alors que dans l'exemple 1, ils sont extraits de l'URL (country,yearetmonthrespectivement).
-
Pour un exemple complet de synchronisation de bout en bout d'entités logiques partitionnées, voir Exemple : Scénario de données partitionnées.
Synchronisation incrémentielle des entités logiques partitionnées/tables de grue
Chaque appel à la procédure RUN_SYNC spécifie un jeu d'entités logiques de catalogue de données OCI ou de tables AWS Glue à synchroniser avec la base de données. Lorsqu'une entité logique ou une table de colle est présente dans deux appels RUN_SYNC, le deuxième appel conserve et modifie éventuellement les tables externes existantes. Le tableau suivant indique les modifications d'entité logique ou de table de colle prises en charge lorsque l'entité logique ou la table de colle est partitionnée :
| Modification d'entité logique ou de 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 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 spécifie un jeu d'entités à granularité multiple : ressources de données, dossiers (seaux du magasin d'objets) ou entités logiques. Il contient un Pour AWS Glue Data Catalogs, le document JSON spécifie une liste de tables de granularité multiple : bases de données, tables. Le document spécifie une liste de bases de données. Les utilisateurs peuvent restreindre le jeu de tables à synchroniser en spécifiant des tables individuelles dans une base de données. |
sync_option |
(Facultatif) Il existe trois options :
|
error_semantics |
(Facultatif) Ce paramètre spécifie le comportement de l'erreur. Si elle est réglée à SKIP_ERRORS, la synchronisation tente de continuer malgré les erreurs rencontrées pour les entités individuelles. Si elle est réglée à STOP_ON_ERROR, la procédure échoue lors de la première erreur détectée. La valeur par défaut est SKIP_ERRORS. |
log_level |
(Facultatif) Ce paramètre spécifie les valeurs suivantes pour l'augmentation du niveau des détails 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 des 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 est utilisé pour rechercher l'entrée correspondante dans Note : Une version de |
dcat_con_id |
Ce paramètre est l'identificateur unique de connexion au catalogue de données qui a été spécifié lors de la création de la connexion au catalogue de données. Voir Procédure SET_DATA_CATALOG_CONN. Ce paramètre identifie la connexion utilisée pour la synchronisation et fait partie du nom du schéma dérivé. Voir Mappage de synchronisation pour une description de la façon dont le nom du schéma est dérivé. La valeur par défaut du paramètre est NULL. |
Exemples
Exemple : Synchronisez toutes les entités du catalogue de données OCI.
Dans l'exemple suivant, toutes les entités du catalogue de données sont synchronisées.
EXEC DBMS_DCAT.RUN_SYNC(synced_objects=>'{"asset_list":["*"]}');
Exemple : Paramètre synced_objects pour synchroniser toutes les ressources de données du catalogue de données OCI.
Voici un exemple de paramètre synced_objects pour synchroniser toutes les ressources de données (stockage d'objets) du catalogue de données.
{"asset_list" : ["*"]}
Exemple : Paramètre synced_objects pour synchroniser des ressources de données de catalogue de données OCI spécifiques.
Voici un exemple de paramètre synced_objects pour synchroniser deux ressources de données.
{"asset_list": [
{
"asset_id":"...-9e2e7f78fd5f"
},
{
"asset_id":"...-9e2e7f74523"
}
]}
Exemple : Paramètre synced_objects pour synchroniser des entités de catalogue de données OCI spécifiques dans une ressource de données.
Ce qui suit présente un exemple de paramètre synced_objects pour synchroniser 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 pour synchroniser des dossiers et des entités de catalogue de données OCI spécifiques dans une ressource de données.
Voici un exemple de 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 synchroniser toutes les bases de données du catalogue de données de colle AWS.
Voici un exemple de paramètre synced_objects pour synchroniser toutes les bases de données dans le catalogue de données AWS Glue.
{"database_list":["*"]}
Exemple : Paramètre synced_objects pour synchroniser deux bases de données de catalogue de données de colle AWS.
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 de catalogue de données de colle AWS.
Voici un exemple de paramètre synced_objects pour synchroniser 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 programmateur pour appeler RUN_SYNC périodiquement
Il prend en entrée l'ensemble des objets à synchroniser, la sémantique d'erreur, le niveau de journal et un intervalle de répétition. Voir Procédure RUN_SYNC pour plus de détails sur le fonctionnement de la synchronisation.
Il ne peut y avoir qu'une seule tâche de synchronisation. La procédure CREATE_SYNC_JOB échoue si une autre tâche est déjà spécifiée, sauf si le paramètre force est réglé à TRUE. Si force est réglée à TRUE, la tâche précédente est supprimée.
Si un travail du programmateur tente de s'exécuter alors qu'une autre synchronisation est en cours, le travail du programmateur échoue.
Note : 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 la bonne exécution des tâches de synchronisation programmées créées avant cette date, vous devez supprimer et recréer les tâches de synchronisation programmées. Voir 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 spécifiant les objets à synchroniser, comme décrit dans la procédure RUN_SYNC. Voir Procédure RUN_SYNC. |
error_semantics |
(Facultatif) Comportement de l'erreur, tel que spécifié pour RUN_SYNC. La valeur par défaut est SKIP_ERRORS. |
log_level |
(Facultatif) Niveau de journalisation, tel que spécifié pour RUN_SYNC. La valeur par défaut est INFO. |
repeat_interval |
Intervalle de répétition de la tâche, 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 de détails sur repeat_interval, voir Aperçu de la création de tâches. |
force |
(Facultatif) Si TRUE, les tâches de synchronisation existantes sont d'abord supprimées. Si FALSE, la procédure CREATE_SYNC_JOB échoue si une tâche de synchronisation existe déjà. La valeur par défaut est FALSE. |
grant_read |
(Facultatif) Liste des utilisateurs/rôles auxquels accorder la fonction READ sur les tables externes synchronisées, comme décrit pour la procédure RUN_SYNC. Voir Procédure RUN_SYNC. |
sync_option |
(Facultatif) Comportement par rapport aux entités qui ont déjà été synchronisées au moyen d'une opération RUN_SYNC précédente, comme décrit pour la procédure RUN_SYNC. Voir Procédure RUN_SYNC. |
dcat_con_id |
Ce paramètre est l'identificateur unique de connexion au catalogue de données qui a été spécifié lors de la création de la connexion au catalogue de données. Voir Procédure SET_DATA_CATALOG_CONN. Ce paramètre identifie la connexion utilisée pour la synchronisation et fait partie du nom du schéma dérivé. Voir Mappage de synchronisation pour une description de la façon dont le nom du schéma est dérivé. La valeur par défaut du paramètre est NULL. |
Procédure DROP_SYNC_JOB
Cette procédure supprime une tâche de synchronisation existante pour l'identificateur de connexion unique indiqué.
Syntaxe
PROCEDURE DBMS_DCAT.DROP_SYNC_JOB (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Paramètres
| Paramètre | Description |
|---|---|
dcat_con_id |
Identificateur unique de connexion au catalogue de données. La valeur par défaut est 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 indiqué.
Syntaxe
PROCEDURE DBMS_DCAT.DROP_SYNCED_SCHEMAS (
dcat_con_id IN VARCHAR2 DEFAULT NULL
);
Paramètres
| Paramètre | Description |
|---|---|
dcat_con_id |
Identificateur unique de connexion au catalogue de données. La valeur par défaut est NULL. |