Data Catalog Oracle AI

Oracle AI Data Catalog (AICAT) è un servizio di catalogo REST Iceberg gestito da Oracle. Il servizio catalogo è progettato per gestire i tavoli Iceberg in modo efficiente. Fornisce API per la gestione delle operazioni CRUD sulle tabelle, la gestione dei metadati e la gestione delle transazioni.

AICAT funziona all'interno di Oracle Autonomous AI Database ed è disponibile per tutti i database all'interno di tale tenancy. Il servizio catalogo utilizza lo schema di database tenant per memorizzare i metadati delle tabelle.

• Tipi di storage supportati
  
• Avvio rapido
  
• Abilitare l'accesso alle origini dati private da Autonomous AI Database
  L'Autonomous AI Database da cui si accede a AICAT deve essere configurato per utilizzare un endpoint privato per poter comunicare con le origini di database privati. Altrimenti, quando si tenta di creare e testare una connessione di questo tipo, potrebbe verificarsi un errore di "connessione non riuscita".

È necessario creare o selezionare un'istanza di Autonomous AI Database esistente su cui verrà eseguito Oracle AI Data Catalog. Questa istanza di database verrà utilizzata come repository di metadati del catalogo.

Per abilitare Oracle AI Data Catalog (AICAT) su un'istanza Autonomous AI Database Serverless, è necessario impostare la tag OCI ADB$TOOLS su AI_CAT. È quindi possibile connettersi al servizio catalogo utilizzando l'URL del servizio generato.

Tenere presente quanto riportato di seguito.

• L'impostazione della tag OCI AI_CAT su un'istanza ADB-S abilita il servizio AI Data Catalog per tale database.
• Il servizio supporta un massimo di 32 ECPU nella release iniziale. Il consumo di ECPU viene fatturato alla tariffa standard di Autonomous AI Database quando le risorse di computazione del servizio catalogo sono attive e in uso. Vedere Informazioni sulla fatturazione del modello di computazione ECPU per informazioni sulla fatturazione ECPU per VM e risorse di computazione aggiuntive.
• Il servizio AICAT è configurato con un timeout di inattività predefinito di 2 ore (120 minuti). Questa configurazione mantiene il servizio prontamente disponibile e reattivo per i normali pattern di utilizzo evitando la fatturazione non necessaria quando il servizio è inattivo. Ciò garantisce inoltre che, quando il servizio rimane inattivo oltre il periodo di timeout inattività configurato, le risorse di computazione associate vengano arrestate automaticamente e non vengano più fatturate.
• Se si è verificato il timeout del servizio AICAT, qualsiasi richiesta successiva al servizio attiva automaticamente un riavvio del servizio catalogo. Nella maggior parte dei casi, il servizio diventa disponibile entro circa 30 secondi.

Puoi abilitare AICAT nei tipi di database Lakehouse e Autonomous Transaction Processing (ATP). Oracle consiglia di utilizzare i database ATP perché le operazioni del catalogo, ad esempio la gestione dei metadati, le chiamate API, i controlli di autorizzazione e gli aggiornamenti del catalogo, sarebbero ottimizzate meglio utilizzando ATP.

Per abilitare AICAT e ottenere l'URL dell'istanza:

1. Eseguire il login a OCI e andare all'istanza Autonomous AI Database Serverless selezionata come repository di metadati del catalogo.
2. Passare a Tag.
3. Imposta il seguente tag:
   • Nome chiave tag: ADB$TOOLS
   • Valore tag: AI_CAT

   Ciò abilita AICAT per l'istanza Autonomous AI Database Serverless.

4. Per ottenere l'endpoint, andare a ADBS in OCI e selezionare la scheda Configurazione strumenti. Modificare l'URL visualizzato nel formato <database name>/catalog.

   Ad esempio, modificare https://test1234.adb.us-phoenix-1.oraclecloudapps.com/ords/apex in https://test1234.adb.us-phoenix-1.oraclecloudapps.com/catalog.

Viene visualizzata una schermata iniziale che elenca i passi da eseguire per iniziare a utilizzare AICAT insieme ai collegamenti agli argomenti della Guida.

Per registrare lo storage, utilizzare la procedura ORACLE_AI_DATA_CATALOG.REGISTER_STORAGE_<VENDOR>() PL/SQL.

Tenere presente che il chiamante deve essere un utente ADMIN o un utente al quale è assegnato il ruolo PDB_DBA. Per ulteriori informazioni sulla concessione di ruoli e l'aggiunta o l'aggiornamento dei privilegi per un utente, vedere Gestisci ruoli e privilegi utente in Autonomous AI Database.

Oracle AI Data Catalog supporta i seguenti provider di storage:

• Oracle Cloud Infrastructure con compatibilità S3
• Storage di Azure (ADLS e BLOB)
• ZFS Storage

Per aggiornare le credenziali di storage, vedere Aggiorna credenziali di storage. Se si desidera annullare la registrazione delle credenziali di storage, vedere Annulla registrazione credenziali di storage.

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;
/

• Aggiorna credenziali storage
  
• Annulla registrazione credenziali di storage
  

AICAT supporta la registrazione delle tabelle Apache Iceberg esistenti memorizzate nello storage degli oggetti. Una volta registrati, i metadati della tabella Iceberg e le definizioni delle tabelle diventano individuabili e accessibili tramite AICAT.

Prima di registrare le tabelle Iceberg in AICAT, assicurarsi che:

• AICAT è già abilitato in un'istanza serverless di Autonomous Database. Vedere Abilita Oracle AI Data Catalog.
• Si è connessi all'istanza serverless di Autonomous Database come utente ADMIN o utente con il ruolo PDB_DBA o AICAT_USER.
• Hai registrato il tuo storage con AICAT. Vedere Registra credenziali di storage.
• Il bucket di storage degli oggetti contiene dati e metadati della tabella Iceberg validi nel formato corretto.

  Ad esempio:

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

  Qui:

  • NAMESPACE rappresenta lo spazio di nomi/schema Iceberg.
  • TABLE_NAME_NAMESPACE rappresenta la tavola Iceberg
  • data contiene i file di dati della tabella (in genere Parquet)
  • metadata contiene i metadati Iceberg e i file JSON snapshot necessari per la gestione delle tabelle e l'esecuzione di query
• Si dispone delle autorizzazioni di accesso al bucket e agli oggetti.

Per registrare le tabelle Iceberg esistenti con AICAT:

1. Connettersi all'istanza AICAT utilizzando le credenziali di autenticazione del database.

   Utilizzare il comando seguente per generare un token di accesso:

   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')
   

   Qui,

   • <URI> è l'URL del server catalogo.
   • <dbUser> è il nome utente del database.
   • <dbPwd> è la password del database.

   Se il valore del token restituisce null, eseguire di nuovo la richiesta utilizzando l'opzione -v per l'output descrittivo per risolvere i problemi di autenticazione o connettività.

   Esempio:

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

2. Determinare la posizione del file di metadati Iceberg per la tabella che si desidera registrare nel catalogo. È possibile ottenere la posizione dei metadati in uno dei modi riportati di seguito.
   • Caricare i metadati della tabella da un server catalogo precedente.
   • Sfoglia manualmente il bucket del warehouse o dello storage degli oggetti e identifica il file JSON dei metadati Iceberg corrente.
   Ad esempio:

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

   Il file JSON dei metadati contiene le informazioni sulla definizione della tabella Iceberg, lo schema, gli snapshot, i file manifesto e lo stato della tabella necessarie per la registrazione del catalogo.

   Per creare lo spazio di nomi SILVER se non esiste già, utilizzare il comando seguente:

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

3. Per registrare la tabella, eseguire il comando seguente:

   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. Per caricare la tabella appena registrata, eseguire il comando seguente:

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

5. Analogamente, registrare altre tabelle.

Per consentire a un utente del database di accedere al servizio AICAT (vedere Scegli database repository catalogo), l'utente deve essere un utente ADMIN oppure è necessario autorizzare l'utente con il ruolo AICAT_USER o PDB_DBA.

È possibile autenticare gli utenti utilizzando una chiamata API token con credenziali utente. Per ottenere il token di accesso, inviare la richiesta seguente:

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

Parametro di richiesta di esempio che utilizza 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'

Alla scadenza del token, si riceverà una risposta 401. Utilizzare lo stesso endpoint per ottenere un nuovo token.

Di seguito è riportato un token di risposta di esempio.

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

Utilizzare il token ottenuto come token Bearer nell'intestazione di autorizzazione:

Authorization: Bearer <your_token>

Per informazioni dettagliate su ciascun endpoint REST API catalogo, vedere API REST per Oracle AI Data Catalog.

Il catalogo REST Iceberg AICAT è il catalogo Iceberg predefinito basato su REST incorporato in AICAT. È progettato per gestire in modo efficiente le tabelle Iceberg fornendo API REST per le operazioni del ciclo di vita delle tabelle, tra cui creazione, lettura, aggiornamento ed eliminazione (CRUD), nonché la gestione dei metadati e delle transazioni. Il catalogo REST AICAT Iceberg segue la specifica API standard del catalogo REST Apache Iceberg. È necessario essere un utente ADMIN o un utente a cui è stato concesso il ruolo PDB_DBA o AICAT_USER.

Per informazioni dettagliate su ciascun endpoint REST API catalogo, vedere API REST per Oracle AI Data Catalog.

AICAT si integra con più motori di query per richiedere e recuperare informazioni. Puoi usare AICAT con motori di query come Apache Spark, aggiungere tabelle esterne su tabelle AICAT, montare AICAT sul catalogo DBMS e creare tabelle Apache Iceberg utilizzando Oracle Data Transforms.

In caso di problemi, inoltrare una richiesta di assistenza al Supporto Oracle Cloud o contattare il rappresentante dell'assistenza.

-- 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;