Catalogue de données Oracle AI

Oracle AI Data Catalog (AICAT) est un service de catalogue REST Iceberg géré par Oracle. Le service de catalogue est conçu pour gérer efficacement les tables Iceberg. Il fournit des API pour la gestion des opérations CRUD sur les tables, la gestion des métadonnées et la gestion des transactions.

AICAT fonctionne dans Oracle Autonomous AI Database et est disponible pour toutes les bases de données de cette location. Le service de catalogue utilise le schéma de base de données locataire pour stocker les métadonnées des tables.

• Type de stockage pris en charge
  
• Démarrage rapide
  
• Activation de l'accès aux sources de données privées à partir d'une base de données d'IA autonome
  La base de données d'IA autonome à partir de laquelle vous accédez à AICAT doit être configurée pour utiliser une adresse privée afin de pouvoir communiquer avec des sources de base de données privées. Sinon, lorsque vous essayez de créer et de tester une telle connexion, vous risquez d'obtenir une erreur "échec de connexion".

Vous devez créer ou sélectionner une instance de base de données Autonomous AI existante sur laquelle Oracle AI Data Catalog sera exécuté. Cette instance de base de données sera utilisée comme référentiel de métadonnées de catalogue.

Pour activer Oracle AI Data Catalog (AICAT) sur une instance Autonomous AI Database Serverless, vous devez définir la balise OCI ADB$TOOLS sur AI_CAT. Vous pouvez ensuite vous connecter au service de catalogue à l'aide de l'URL de service générée.

Prenez note des points suivants :

• La définition de la balise OCI AI_CAT sur une instance ADB-S active le service AI Data Catalog pour cette base de données.
• Le service prend en charge jusqu'à 32 ECPU dans la version initiale. La consommation d'ECPU est facturée au tarif standard de la base de données Autonomous AI lorsque les ressources de calcul du service de catalogue sont actives et en cours d'utilisation. Pour plus d'informations sur la facturation des ECPU pour les machines virtuelles et les ressources de calcul supplémentaires, reportez-vous à Informations de facturation sur le modèle de calcul d'ECPU.
• Le service AICAT est configuré avec un délai d'inactivité par défaut de 2 heures (120 minutes). Cette configuration permet de garder le service facilement disponible et réactif pour les modèles d'utilisation normaux tout en évitant la facturation inutile lorsque le service est inactif. Cela garantit également que lorsque le service reste inactif au-delà du délai d'inactivité configuré, les ressources de calcul associées sont automatiquement arrêtées et ne sont plus facturées.
• Si le service AICAT a expiré, toute demande ultérieure au service déclenche automatiquement un redémarrage du service de catalogue. Dans la plupart des cas, le service devient disponible en 30 secondes environ.

Vous pouvez activer AICAT sur les types de base de données Lakehouse et Autonomous Transaction Processing (ATP). Oracle recommande d'utiliser des bases de données ATP car les opérations de catalogue telles que la gestion des métadonnées, les appels d'API, les vérifications d'autorisation et les mises à jour de catalogue seraient mieux optimisées à l'aide de ATP.

Pour activer AICAT et obtenir l'URL de l'instance :

1. Connectez-vous à OCI et accédez à l'instance Autonomous AI Database Serverless que vous avez sélectionnée comme référentiel de métadonnées de catalogue.
2. Accédez à Balises.
3. Définissez la balise suivante :
   • Nom de clé de balise : ADB$TOOLS
   • Valeur de balise : AI_CAT

   Cela active AICAT pour l'instance Autonomous AI Database Serverless.

4. Pour obtenir l'adresse, accédez à ADBS dans OCI et sélectionnez l'onglet Configuration des outils. Modifiez l'URL affichée au format <database name>/catalog.

   Par exemple, remplacez https://test1234.adb.us-phoenix-1.oraclecloudapps.com/ords/apex par https://test1234.adb.us-phoenix-1.oraclecloudapps.com/catalog.

Un écran de démarrage apparaît et répertorie les étapes à suivre pour commencer à utiliser AICAT, ainsi que des liens vers les rubriques d'aide.

Pour enregistrer du stockage, utilisez la procédure ORACLE_AI_DATA_CATALOG.REGISTER_STORAGE_<VENDOR>() PL/SQL.

L'appelant doit être un utilisateur ADMIN ou un utilisateur auquel le rôle PDB_DBA est affecté. Pour plus d'informations sur l'octroi de rôles et l'ajout ou la mise à jour de privilèges pour un utilisateur, reportez-vous à Gestion des rôles et des privilèges utilisateur sur une base de données Autonomous AI.

Oracle AI Data Catalog prend en charge les fournisseurs de stockage suivants :

• Compatibilité entre Oracle Cloud Infrastructure et S3
• Stockage Azure (ADLS et BLOB)
• ZFS Storage

Pour mettre à jour les informations d'identification de stockage, reportez-vous à Mise à jour des informations d'identification de stockage. Pour annuler l'enregistrement des informations d'identification de stockage, reportez-vous à Annulation de l'enregistrement des informations d'identification de stockage.

begin
   oracle_ai_data_catalog.register_storage_oci(
   p_warehouse => 's3://<bucket>',
   p_endpoint => 'https://<namespace>.compat.objectstorage.<region>.oci.customer-oci.com',
   p_region     => '<region>',
   p_access_key => '<access-key-id>',
   p_secret_key => '<secret-key-id>'
   );
end;
/

begin oracle_ai_data_catalog.register_storage_azure(
    p_warehouse            => 'abfss://<container>',
    p_endpoint             => 'https://<account>.dfs.core.windows.net',
    p_storage_account_name => '<storage_account_name>',
    p_storage_account_key  => '<storage_account_key>'
);
end;
/

begin oracle_ai_data_catalog.register_storage_azure(
    p_warehouse            => 'abfss://<container>',
    p_endpoint             => 'https://<account>.blob.core.windows.net',
    p_storage_account_name => '<storage_account_name>',
    p_storage_account_key  => '<storage_account_key>'
);
end;
/

begin
   oracle_ai_data_catalog.register_storage_zfs(
   p_warehouse  => 's3a://icebergs3/iceberg_warehouse_s3/',
   p_endpoint   => 'https://<account>.us.oracle.com',
   p_accesskey => '<access-key-id>',
   p_secret_key => '<secret-key-id>'
   );
end;
/

• Mettre à jour les informations d'identification de stockage
  
• Annulation de l'enregistrement des informations d'identification de stockage
  

AICAT prend en charge l'enregistrement des tables Apache Iceberg existantes qui sont stockées dans Object Storage. Une fois enregistrés, les métadonnées et les définitions de table Iceberg deviennent détectables et accessibles via l'AICAT.

Avant d'enregistrer les tables Iceberg dans AICAT, assurez-vous que :

• AICAT est déjà activé sur une instance sans serveur Autonomous Database. Reportez-vous à Activation d'Oracle AI Data Catalog.
• Vous êtes connecté à l'instance Autonomous Database Serverless en tant qu'utilisateur ADMIN ou utilisateur doté du rôle PDB_DBA ou AICAT_USER.
• Vous avez enregistré votre stockage auprès d'AICAT. Reportez-vous à Inscription des informations d'identification de stockage.
• Le bucket Object Storage contient des métadonnées et des données de table Iceberg valides dans le format correct.

  Par exemple,

  Bucket/Warehouse: N-Warehouse
  -NAMESPACE 
    -TABLE_NAME_NAMESPACE
      - data
        - parquet files.
      - metadata
        - json files

  Ici:

  • NAMESPACE représente l'espace de noms/le schéma Iceberg.
  • TABLE_NAME_NAMESPACE représente la table Iceberg
  • data contient les fichiers de données de la table (généralement Parquet).
  • metadata contient les métadonnées Iceberg et les fichiers JSON d'instantané requis pour la gestion des tables et l'interrogation.
• Vous disposez de droits d'accès au bucket et aux objets.

Pour enregistrer vos tables Iceberg existantes avec AICAT :

1. Connectez-vous à votre instance AICAT à l'aide de vos informations d'identification d'authentification de base de données.

   Utilisez la commande suivante pour générer un jeton d'accès :

   TOKEN=$(curl -k -s --location '<URI>/v1/auth/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=client_credentials' \
   --data-urlencode 'client_id=<dbUser>' \
   --data-urlencode 'client_secret=<dbPwd>' \
   --data-urlencode 'scope=PRINCIPAL_ROLE:ALL' | jq -r '.access_token')
   

   Ici,

   • <URI> est l'URL du serveur de catalogue.
   • <dbUser> est le nom utilisateur de votre base de données.
   • <dbPwd> est le mot de passe de votre base de données.

   Si la valeur de jeton renvoie la valeur null, réexécutez la demande à l'aide de l'option -v pour une sortie détaillée afin de résoudre les problèmes d'authentification ou de connectivité.

   Exemple :

   curl -v -k --location '<URI>/v1/auth/token'

2. Déterminez l'emplacement du fichier de métadonnées Iceberg pour la table que vous souhaitez enregistrer dans le catalogue. Vous pouvez obtenir l'emplacement des métadonnées de l'une des manières suivantes :
   • Chargez les métadonnées de la table à partir d'un serveur de catalogue précédent.
   • Parcourez manuellement l'entrepôt ou le bucket Object Storage et identifiez le fichier JSON de métadonnées Iceberg en cours.
   Par exemple :

   Namespace           : SILVER
   Table               : COMPETITOR_PRICING_SILVER
   Metadata Location   : s3://0A-Warehouse/SILVER/COMPETITOR_PRICING_SILVER/metadata/00002-f2662b11-3268-4792-90f9-b8f4b851d629.metadata.json

   Le fichier JSON de métadonnées contient les informations de définition de table Iceberg, de schéma, d'instantanés, de manifestes et d'état de table requises pour l'enregistrement du catalogue.

   Pour créer l'espace de noms SILVER s'il n'existe pas déjà, utilisez la commande suivante :

   curl -k --location '<URI>/v1/namespaces' \
   --header "Authorization: Bearer $TOKEN" \
   --header 'Content-Type: application/json' \
   --data '{"namespace": ["SILVER"], "properties": {}}'

3. Pour enregistrer la table, exécutez la commande suivante :

   curl -k --location '<URI>/v1/namespaces/SILVER/register' \
   --header 'Content-Type: application/json' \
   --header "Authorization: Bearer $TOKEN" \
   --data '{
       "name":"COMPETITOR_PRICING_SILVER",
       "metadata-location": "s3://0A-Warehouse/SILVER/COMPETITOR_PRICING_SILVER/metadata/00002-f2662b11-3268-4792-90f9-b8f4b851d629.metadata.json",
       "overwrite": false
   }'

4. Pour charger la nouvelle table enregistrée, exécutez la commande suivante :

   curl -k --location '<URI>/v1/namespaces/SILVER/tables/COMPETITOR_PRICING_SILVER' \
   --header "Authorization: Bearer $TOKEN" \
   --header 'Content-Type: application/json'

5. De même, enregistrez d'autres tables.

Pour autoriser un utilisateur de base de données à accéder au service AICAT (reportez-vous à Choix de la base de données du référentiel de catalogue), il doit s'agir d'un utilisateur ADMIN ou vous devez autoriser l'utilisateur avec le rôle AICAT_USER ou PDB_DBA.

Vous pouvez authentifier les utilisateurs à l'aide d'un appel d'API de jeton avec des informations d'identification utilisateur. Pour obtenir le jeton d'accès, envoyez la demande suivante :

POST https://public_lb_host/catalog/v1/auth/token

Exemple de paramètre de demande utilisant cURL :

curl -k -s --location '<URI>/catalog/v1/auth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<dbUser>' \
--data-urlencode 'client_secret=<dbPwd>' \
--data-urlencode 'scope=PRINCIPAL_ROLE:ALL' | jq -r '.access_token'

Lorsque le jeton expire, vous recevez une réponse 401. Utilisez la même adresse pour obtenir un nouveau jeton.

Voici un exemple de jeton de réponse :

{
    "access_token": "<token>",
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "token_type": "bearer",
    "expires_in": 3600
}

Utilisez le jeton obtenu comme jeton Bearer dans l'en-tête d'autorisation :

Authorization: Bearer <your_token>

Pour plus d'informations sur chaque adresse REST d'API de catalogue, reportez-vous à API REST pour Oracle AI Data Catalog.

Le catalogue REST Iceberg d'AICAT est le catalogue Iceberg REST par défaut intégré à AICAT. Il est conçu pour gérer efficacement les tables Iceberg en fournissant des API REST pour les opérations de cycle de vie des tables, notamment la création, la lecture, la mise à jour et la suppression (CRUD), ainsi que la gestion des métadonnées et la gestion des transactions. Le catalogue REST Iceberg d'AICAT suit la spécification d'API standard du catalogue REST Iceberg d'Apache. Vous devez être un utilisateur ADMIN ou un utilisateur disposant du rôle PDB_DBA ou AICAT_USER.

Pour plus d'informations sur chaque adresse REST d'API de catalogue, reportez-vous à API REST pour Oracle AI Data Catalog.

AICAT s'intègre à plusieurs moteurs de requête pour demander et extraire des informations. Vous pouvez utiliser AICAT avec des moteurs de requête tels qu'Apache Spark, ajouter des tables externes sur des tables AICAT, monter AICAT sur le catalogue de SGBD, et créer des tables Apache Iceberg à l'aide d'Oracle Data Transforms.

En cas de problème, enregistrez une demande d'assistance sur le support Oracle Cloud ou contactez votre représentant du support.

-- setup ACL Rules --
-- for XT to communicate to ai catalog instance
-- for XT to communicate to object storage bucket, OCI in this example.

BEGIN
dbms_network_acl_admin.append_host_ace(
host => '*.oraclecloudapps.com',
lower_port => 443,
upper_port => 443,
ace => xs$ace_type(
privilege_list => xs$name_list('http', 'http_proxy'),
principal_name =>  'ADMIN',
principal_type => xs_acl.ptype_db));

dbms_network_acl_admin.append_host_ace(
host => '*.oci.customer-oci.com',
lower_port => 443,
upper_port => 443,
ace => xs$ace_type(
privilege_list => xs$name_list('http', 'http_proxy'),
principal_name =>  'ADMIN',
principal_type => xs_acl.ptype_db));
END;
/

-- create storage and catalog access credentials --
begin
dbms_cloud.create_credential(
  credential_name => '<catalogAuthCreds>',
  username        => '<dbUserName>',
  password        => '<dbUserPwd>'
);
end;
/

begin
  dbms_cloud.create_credential(
    credential_name => '<storageCredentialName>',
    username        => '<s3accessKey>',
    password        => '<s3secretKey>'
  );
end;
/


-- XT Creation with AI Cat Syntax --
-- <catalogURI> eg: https://<dbIdentifierString>.adb.<region>.oraclecloudapps.com/catalog
-- <authUri> eg: https://<dbIdentifierString>.adb.<region>.oraclecloudapps.com/catalog/v1/auth/token

begin
dbms_cloud.create_external_table(
  table_name      => '<extTableName>',
  credential_name => '<storageCredentialName>',
  format          => '{
    "access_protocol": {
      "protocol_type": "iceberg",
      "protocol_config": {
        "iceberg_catalog_type": "oracle_ai_data_catalog",
        "rest_catalog_endpoint":"<catalogURI>",
        "rest_authentication": {
          "rest_auth_cred": "<catalogAuthCreds>",
          "rest_auth_endpoint":"<authUri>"
        },
        "table_path": ["<namespaceName>", "<tableName>"]
      }
    }
  }'
);
end;
/

select * from <extTableName>;

-- setup ACL Rules --
-- for XT to communicate to ai catalog instance
-- for XT to communicate to object storage bucket, OCI in this example.

BEGIN
dbms_network_acl_admin.append_host_ace(
host => '*.oraclecloudapps.com',
lower_port => 443,
upper_port => 443,
ace => xs$ace_type(
privilege_list => xs$name_list('http', 'http_proxy'),
principal_name =>  'ADMIN',
principal_type => xs_acl.ptype_db));

dbms_network_acl_admin.append_host_ace(
host => '*.oci.customer-oci.com',
lower_port => 443,
upper_port => 443,
ace => xs$ace_type(
privilege_list => xs$name_list('http', 'http_proxy'),
principal_name =>  'ADMIN',
principal_type => xs_acl.ptype_db));
END;
/

-- create bearer token and catalog access credentials --
-- <authUri> eg: https://<dbIdentifierString>.adb.<region>.oraclecloudapps.com/catalog/v1/auth/token
BEGIN
    DBMS_SHARE.CREATE_BEARER_TOKEN_CREDENTIAL(
        CREDENTIAL_NAME => '<bearerTokenCredName>',
        BEARER_TOKEN    => 'BEARER_TOKEN',
        TOKEN_ENDPOINT  => '<authUri>',
        CLIENT_ID       => '<dbUserName>',
        CLIENT_SECRET   => '<dbUserPwd>',
        TOKEN_SCOPE     => 'PRINCIPAL_ROLE:ALL'
    );
END;
/

begin
  dbms_cloud.create_credential(
    credential_name => '<storageCredentialName>',
    username        => '<s3accessKey>',
    password        => '<s3secretKey>'
  );
end;
/


-- XT Creation with AI Cat Syntax --
-- <catalogURIForIceberg> eg: https://<dbIdentifierString>.adb.<region>.oraclecloudapps.com/catalog/v1
-- <authUri> eg: https://<dbIdentifierString>.adb.<region>.oraclecloudapps.com/catalog/v1/auth/token

-- DBMS_CATALOG with AI CAT --
BEGIN
dbms_catalog.mount_iceberg(
catalog_name             => '<catalogName>',
endpoint                 => '<catalogURIforIceberg>',
catalog_credential       => '<bearerTokenCredentialName>',
data_storage_credential  => '<storageCredentialName>',
catalog_type             => 'ICEBERG_ORACLE');
END;
/

-- sample queries once catalog is mounted
-- show mounted catalogs
SELECT c.catalog_name AS mounted_catalog_name, c.catalog_type AS mounted_catalog_type
FROM user_mounted_catalogs c
ORDER BY c.catalog_name;

-- show schemas
select schema_name from dbms_catalog.get_schemas('<catalogName>');

-- show tables
select table_name from dbms_catalog.get_tables('<catalogName>', '<schemaName>');

-- query existing tables
select FIRST_NAME, LAST_NAME from "<schemaName>"."<tableName>"@<catalogName> where rownum < 10;

-- create new table
CREATE ICEBERG TABLE  "<schemaName>"."<tableName>"
(   type  STRING,
    address   STRING
)
WITHIN CATALOG "<catalogName>"
STORAGE LOCATION "s3://<ociBucketNameUsedInStep#2>/<schemaName>/<tableName>/";

-- insert into table;
create table TESTLOCAL (type varchar2(10), address varchar2(10));
insert into TESTLOCAL values ('Alan', 'Matthews');
commit;

-- insert into iceberg table via ai catalog from local table
INSERT INTO "<schemaName>"."<tableName>"@<catalogName> select * from TESTLOCAL;

-- query the table in ai cat
select * from "<schemaName>"."<tableName>"@<catalogName>;

select DBMS_CATALOG.GENERATE_TABLE_SELECT('<catalogName>', '"<schemaName>"', '"<tableName>"') from dual;