Catálogo de datos de Oracle AI

Oracle AI Data Catalog (AICAT) es un servicio de catálogo REST de Iceberg gestionado por Oracle. El servicio de catálogo está diseñado para gestionar mesas Iceberg de manera eficiente. Proporciona API para manejar operaciones CRUD en tablas, gestionar metadatos y manejar transacciones.

AICAT funciona dentro de Oracle Autonomous AI Database y está disponible para todas las bases de datos de ese arrendamiento. El servicio de catálogo utiliza el esquema de base de datos de inquilino para almacenar los metadatos de las tablas.

• Tipos de almacenamiento admitidos
  
• Inicio rápido
  
• Activar acceso a orígenes de datos privados desde una base de datos de IA autónoma
  La base de datos de IA autónoma desde la que accede a AICAT debe estar configurada para utilizar un punto final privado para poder comunicarse con orígenes de base de datos privados. De lo contrario, al intentar crear y probar una conexión de este tipo, es posible que aparezca el error "failed to connect".

Debe crear o seleccionar una instancia de base de datos de IA autónoma existente en la que se ejecutará Oracle AI Data Catalog. Esta instancia de base de datos se utilizará como repositorio de metadatos del catálogo.

Para activar Oracle AI Data Catalog (AICAT) en una instancia autónoma de AI Database sin servidor, debe definir la etiqueta OCI ADB$TOOLS en AI_CAT. A continuación, puede conectarse al servicio de catálogo mediante la URL de servicio generada.

Tenga en cuenta lo siguiente:

• La configuración de la etiqueta de OCI AI_CAT en una instancia de ADB-S permite el servicio AI Data Catalog para esa base de datos.
• El servicio admite hasta 32 ECPU en la versión inicial. El consumo de ECPU se factura al ratio estándar de base de datos de IA autónoma cuando los recursos informáticos del servicio de catálogo están activos y en uso. Consulte Información de facturación del modelo de recursos informáticos de ECPU para obtener información sobre la facturación de ECPU para máquinas virtuales y recursos informáticos adicionales.
• El servicio AICAT se configura con un tiempo de espera inactivo predeterminado de 2 horas (120 minutos). Esta configuración mantiene el servicio disponible y receptivo para los patrones de uso normales, al tiempo que evita la facturación innecesaria cuando el servicio está inactivo. Esto también garantiza que cuando el servicio permanezca inactivo más allá del período de tiempo de espera inactivo configurado, los recursos informáticos asociados se detengan automáticamente y ya no se facturen.
• Si el servicio AICAT ha sufrido un timeout, cualquier solicitud posterior al servicio activa automáticamente un reinicio del servicio de catálogo. En la mayoría de los casos, el servicio está disponible en aproximadamente 30 segundos.

Puede activar AICAT en los tipos de base de datos Lakehouse y Autonomous Transaction Processing (ATP). Oracle recomienda utilizar bases de datos ATP porque las operaciones de catálogo, como la gestión de metadatos, las llamadas de API, las comprobaciones de autorización y las actualizaciones de catálogo, se optimizarían mejor mediante ATP.

Para activar AICAT y obtener la URL de la instancia:

1. Conéctese a OCI y vaya a la instancia de Autonomous AI Database Serverless que ha seleccionado como repositorio de metadatos del catálogo.
2. Vaya a Etiquetas.
3. Defina la siguiente etiqueta:
   • Nombre de clave de etiqueta: ADB$TOOLS
   • Valor de etiqueta: AI_CAT

   Esto permite AICAT para la instancia de Autonomous AI Database Serverless.

4. Para obtener el punto final, vaya a ADBS en OCI y seleccione el separador Configuración de herramientas. Edite la URL mostrada con el formato <database name>/catalog.

   Por ejemplo, cambie https://test1234.adb.us-phoenix-1.oraclecloudapps.com/ords/apex a https://test1234.adb.us-phoenix-1.oraclecloudapps.com/catalog.

Aparece una pantalla de presentación que muestra los pasos que debe seguir para comenzar a utilizar AICAT junto con enlaces a los temas de ayuda.

Para registrar el almacenamiento, utilice el procedimiento ORACLE_AI_DATA_CATALOG.REGISTER_STORAGE_<VENDOR>() de PL/SQL.

Tenga en cuenta que el invocador debe ser un usuario ADMIN o un usuario con el rol PDB_DBA asignado. Consulte Gestión de roles y privilegios de usuario en la base de datos de IA autónoma para obtener más información sobre cómo otorgar roles y agregar o actualizar privilegios para un usuario.

Oracle AI Data Catalog soporta los siguientes proveedores de almacenamiento:

• Compatibilidad de Oracle Cloud Infrastructure con S3
• Almacenamiento de Azure (ADLS y BLOB)
• ZFS Storage

Para actualizar las credenciales de almacenamiento, consulte Actualización de credenciales de almacenamiento. Si desea anular el registro de las credenciales de almacenamiento, consulte Anular Registro de Credenciales de Almacenamiento.

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

• Actualizar credenciales de almacenamiento
  
• Anulación del registro de credenciales de almacenamiento
  

AICAT soporta el registro de tablas Apache Iceberg existentes que se almacenan en Object Storage. Una vez registrados, los metadatos y las definiciones de tabla de Iceberg se pueden descubrir y acceder a través de AICAT.

Antes de registrar las mesas Iceberg en AICAT, asegúrese de que:

• AICAT ya está activado en una instancia sin servidor de Autonomous Database. Consulte Activación de Oracle AI Data Catalog.
• Está conectado a la instancia sin servidor de Autonomous Database como usuario ADMIN o un usuario con el rol PDB_DBA o AICAT_USER.
• Ha registrado su almacenamiento en AICAT. Consulte Registro de credenciales de almacenamiento.
• El cubo de Object Storage contiene datos y metadatos válidos de la tabla Iceberg en el formato correcto.

  Por ejemplo,

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

  aquí:

  • NAMESPACE representa el espacio de nombres/esquema de Iceberg.
  • TABLE_NAME_NAMESPACE representa la mesa Iceberg
  • data contiene los archivos de datos de la tabla (normalmente Parquet)
  • metadata contiene metadatos de Iceberg y archivos JSON de instantánea necesarios para la gestión y consulta de tablas
• Tiene permisos de acceso al cubo y a los objetos.

Para registrar sus mesas Iceberg existentes con AICAT:

1. Conéctese a la instancia de AICAT con las credenciales de autenticación de la base de datos.

   Utilice el siguiente comando para generar un token de acceso:

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

   Aquí,

   • <URI> es la URL del servidor de catálogos.
   • <dbUser> es el nombre de usuario de la base de datos.
   • <dbPwd> es la contraseña de la base de datos.

   Si el valor de token se devuelve como null, vuelva a ejecutar la solicitud mediante la opción -v para obtener una salida detallada que ayude a solucionar problemas de autenticación o conectividad.

   Ejemplo:

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

2. Determine la ubicación del archivo de metadatos de Iceberg para la tabla que desea registrar en el catálogo. Puede obtener la ubicación de metadatos de una de las siguientes maneras:
   • Cargue los metadatos de tabla de un servidor de catálogos anterior.
   • Examine manualmente el almacén o el cubo de Object Storage e identifique el archivo JSON de metadatos actuales de Iceberg.
   Por ejemplo:

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

   El archivo JSON de metadatos contiene la definición de tabla Iceberg, el esquema, las instantáneas, los manifiestos y la información de estado de tabla necesaria para el registro del catálogo.

   Para crear el espacio de nombres SILVER si aún no existe, utilice el siguiente comando:

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

3. Para registrar la tabla, ejecute el siguiente comando:

   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. Para cargar la tabla recién registrada, ejecute el siguiente comando:

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

5. Del mismo modo, registrar otras tablas.

Para permitir que un usuario de base de datos acceda al servicio AICAT (consulte Seleccionar base de datos de repositorio de catálogo), el usuario debe ser un usuario ADMIN o debe autorizar al usuario con el rol AICAT_USER o PDB_DBA.

Puede autenticar usuarios mediante una llamada de API de token con credenciales de usuario. Para obtener el token de acceso, envíe la siguiente solicitud:

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

Ejemplo de parámetro de solicitud mediante 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'

Cuando el token caduque, recibirá una respuesta 401. Utilice el mismo punto final para obtener un nuevo token.

A continuación, se muestra un token de respuesta de ejemplo:

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

Utilice el token obtenido como token de portador en la cabecera de autorización:

Authorization: Bearer <your_token>

Consulte API de REST para Oracle AI Data Catalog para obtener información detallada sobre cada punto final de REST de API de catálogo.

El catálogo REST de Iceberg de AICAT es el catálogo de Iceberg basado en REST por defecto integrado en AICAT. Está diseñado para gestionar de forma eficaz tablas Iceberg proporcionando API de REST para operaciones de ciclo de vida de tablas, incluidas la creación, lectura, actualización y supresión (CRUD), junto con la gestión de metadatos y el manejo de transacciones. El catálogo REST de AICAT Iceberg sigue la especificación estándar de API de catálogo REST de Apache Iceberg. Debe ser un usuario ADMIN o un usuario que tenga otorgado el rol PDB_DBA o AICAT_USER.

Consulte API de REST para Oracle AI Data Catalog para obtener información detallada sobre cada punto final de REST de API de catálogo.

AICAT se integra con varios motores de consulta para solicitar y recuperar información. Puede utilizar AICAT con motores de consulta como Apache Spark, agregar tablas externas a través de tablas AICAT, montar AICAT en el catálogo de DBMS, así como crear tablas de Apache Iceberg con Oracle Data Transforms.

Si tiene algún problema, presente una solicitud del servicio en Oracle Cloud Support o comuníquese con su representante de soporte.

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