Catálogo de Dados do Oracle AI

O AICAT (Oracle AI Data Catalog) é um serviço de catálogo REST Iceberg gerenciado pela Oracle. O serviço de catálogo é projetado para gerenciar tabelas Iceberg de forma eficiente. Ele fornece APIs para lidar com operações CRUD em tabelas, gerenciar metadados e tratar transações.

A AICAT funciona no Oracle Autonomous AI Database e está disponível para todos os bancos de dados dentro dessa tenancy. O serviço de catálogo usa o esquema do banco de dados do tenant para armazenar os metadados das tabelas.

• Tipos de Armazenamento Suportados
  
• Início Rápido
  
• Ativar Acesso a Origens de Dados Privadas do Autonomous AI Database
  O Autonomous AI Database no qual você está acessando o AICAT deve ser configurado para usar um ponto final privado para poder se comunicar com origens de banco de dados privadas. Caso contrário, quando você tentar criar e testar essa conexão, poderá obter um erro de "falha ao conectar".

Você precisa criar ou selecionar uma instância existente do Autonomous AI Database na qual o Oracle AI Data Catalog será executado. Esta instância de banco de dados será usada como repositório de metadados do catálogo.

Para ativar o Oracle AI Data Catalog (AICAT) em uma instância do Autonomous AI Database Serverless, você precisa definir a tag OCI ADB$TOOLS como AI_CAT. Em seguida, você pode se conectar ao serviço de catálogo usando o URL de serviço gerado.

Observe o seguinte:

• A definição da tag do OCI AI_CAT em uma instância do ADB-S ativa o serviço AI Data Catalog para esse banco de dados.
• O serviço suporta até 32 ECPUs na versão inicial. O consumo de ECPU é cobrado na taxa padrão do Autonomous AI Database quando os recursos de computação do serviço de catálogo estão ativos e em uso. Consulte Informações de Faturamento do Modelo de Computação de ECPU para obter informações sobre faturamento de ECPU para VMs e recursos de computação adicionais.
• O serviço AICAT é configurado com um tempo limite de inatividade padrão de 2 horas (120 minutos). Esta configuração mantém o serviço prontamente disponível e responsivo para padrões de uso normais, evitando o faturamento desnecessário quando o serviço está ocioso. Isso também garante que, quando o serviço permanecer inativo após o período de tempo limite de inatividade configurado, os recursos de computação associados serão automaticamente interrompidos e não serão mais cobrados.
• Se o serviço AICAT tiver expirado, qualquer solicitação subsequente ao serviço acionará automaticamente uma reinicialização do serviço de catálogo. Na maioria dos casos, o serviço fica disponível em aproximadamente 30 segundos.

Você pode ativar os tipos de banco de dados AICAT on Lakehouse e Autonomous Transaction Processing (ATP). A Oracle recomenda que você use bancos de dados ATP porque operações de catálogo, como gerenciamento de metadados, chamadas de API, verificações de autorização e atualizações de catálogo, seriam melhor otimizadas usando ATP.

Para ativar o AICAT e obter o URL da instância:

1. Faça log-in no OCI e vá para a instância do Autonomous AI Database Serverless que você selecionou como repositório de metadados do catálogo.
2. Navegue até Tags.
3. Defina a seguinte tag:
   • Nome da Chave de Tag: ADB$TOOLS
   • Valor da Tag: AI_CAT

   Isso ativa o AICAT para a instância do Autonomous AI Database Serverless.

4. Para obter o ponto final, vá para ADBS no OCI e selecione a guia Configuração das ferramentas. Edite o URL exibido no formato <database name>/catalog.

   Por exemplo, altere https://test1234.adb.us-phoenix-1.oraclecloudapps.com/ords/apex para https://test1234.adb.us-phoenix-1.oraclecloudapps.com/catalog.

Uma tela inicial é exibida e lista as etapas que você precisa seguir para começar a usar o AICAT, juntamente com links para os tópicos da ajuda.

Para registrar o armazenamento, use o procedimento ORACLE_AI_DATA_CATALOG.REGISTER_STORAGE_<VENDOR>() PL/SQL.

Observe que o chamador deve ser um usuário ADMIN ou um usuário com a atribuição PDB_DBA designada. Consulte Gerenciar Atribuições e Privilégios do Usuário no Autonomous AI Database para obter mais informações sobre como conceder atribuições e adicionar ou atualizar privilégios de um usuário.

O Oracle AI Data Catalog suporta os seguintes provedores de armazenamento:

• Oracle Cloud Infrastructure com compatibilidade com S3
• Armazenamento do Azure (ADLS e BLOB)
• ZFS Storage

Para atualizar as credenciais de armazenamento, consulte Atualizar Credenciais de Armazenamento. Se quiser cancelar o registro das credenciais de armazenamento, consulte Cancelar Registro de Credenciais de Armazenamento.

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

• Atualizar Credenciais de Armazenamento
  
• Cancelar o Registro de Credenciais de Armazenamento
  

O AICAT suporta o registro de tabelas existentes do Apache Iceberg que são armazenadas no Object Storage. Uma vez registrados, os metadados da tabela Iceberg e as definições da tabela se tornam detectáveis e acessíveis por meio da AICAT.

Antes de registrar as tabelas Iceberg no AICAT, certifique-se de que:

• O AICAT já está ativado em uma instância sem Servidor do Autonomous Database. Consulte Ativar o Oracle AI Data Catalog.
• Você está conectado à instância sem Servidor do Autonomous Database como o usuário ADMIN ou um usuário com a atribuição PDB_DBA ou AICAT_USER.
• Você registrou seu armazenamento na AICAT. Consulte Registrar Credenciais de Armazenamento.
• O bucket do Object Storage contém dados e metadados válidos da tabela Iceberg no formato correto.

  Por exemplo,

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

  Aqui:

  • NAMESPACE representa o namespace/esquema do Iceberg.
  • TABLE_NAME_NAMESPACE representa a tabela Iceberg
  • data contém os arquivos de dados da tabela (geralmente Parquet)
  • metadata contém metadados Iceberg e arquivos JSON de snapshot necessários para gerenciamento e consulta de tabelas
• Você tem permissões de acesso ao bucket e aos objetos.

Para registrar suas tabelas Iceberg existentes na AICAT:

1. Conecte-se à sua instância AICAT usando suas credenciais de autenticação do banco de dados.

   Use o seguinte comando para gerar um token de acesso:

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

   Aqui,

   • <URI> é o URL do servidor do Catálogo.
   • <dbUser> é seu nome de usuário do banco de dados.
   • <dbPwd> é a senha do seu banco de dados.

   Se o valor do token retornar como null, execute novamente a solicitação usando a opção -v para obter uma saída detalhada para ajudar a diagnosticar e solucionar problemas de autenticação ou conectividade.

   Exemplo:

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

2. Determine a localização do arquivo de metadados Iceberg para a tabela que você deseja registrar no catálogo. Você pode obter a localização dos metadados de uma das seguintes maneiras:
   • Carregue os metadados da tabela de um servidor de catálogo anterior.
   • Navegue manualmente pelo bucket do warehouse ou Object Storage e identifique o arquivo JSON de metadados do Iceberg atual.
   Por exemplo:

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

   O arquivo JSON de metadados contém a definição da tabela Iceberg, o esquema, os snapshots, os manifestos e as informações de estado da tabela necessárias para o registro do catálogo.

   Para criar o namespace SILVER se ele ainda não existir, use o seguinte comando:

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

3. Para registrar a tabela, execute o seguinte 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 carregar a tabela recém-registrada, execute o seguinte comando:

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

5. Da mesma forma, registre outras tabelas.

Para permitir que um usuário do banco de dados acesse o serviço AICAT (consulte Escolher Banco de Dados do Repositório de Catálogos), o usuário deve ser um usuário ADMIN ou você precisa autorizar o usuário com a atribuição AICAT_USER ou PDB_DBA.

Você pode autenticar usuários usando uma chamada de API de token com credenciais de usuário. Para obter o token de acesso, envie a seguinte solicitação:

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

Exemplo de parâmetro de solicitação usando 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'

Quando o token expirar, você receberá uma resposta 401. Use o mesmo ponto final para obter um novo token.

Veja um exemplo de token de resposta:

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

Use o token obtido como seu token Bearer no cabeçalho Authorization:

Authorization: Bearer <your_token>

Consulte API REST para o Oracle AI Data Catalog para obter informações detalhadas sobre cada ponto final REST da API do catálogo.

O Catálogo REST AICAT Iceberg é o catálogo Iceberg baseado em REST padrão incorporado no AICAT. Ele foi projetado para gerenciar com eficiência tabelas Iceberg, fornecendo APIs REST para operações de ciclo de vida de tabelas, incluindo criar, ler, atualizar e excluir (CRUD), juntamente com gerenciamento de metadados e tratamento de transações. O Catálogo REST do AICAT Iceberg segue a especificação padrão da API do Catálogo REST do Apache Iceberg. Você deve ser um usuário ADMIN ou como um usuário que tenha a atribuição PDB_DBA ou AICAT_USER.

Consulte API REST para o Oracle AI Data Catalog para obter informações detalhadas sobre cada ponto final REST da API do catálogo.

AICAT integra-se com vários mecanismos de consulta para solicitar e recuperar informações. Você pode usar o AICAT com mecanismos de consulta como o Apache Spark, adicionar tabelas externas em tabelas do AICAT, montar o AICAT no catálogo do DBMS e criar tabelas do Apache Iceberg usando o Oracle Data Transforms.

Se você encontrar algum problema, registre uma solicitação em Suporte do Oracle Cloud ou entre em contato com o representante de suporte.

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