Pacote DBMS_DCAT

O pacote DBMS_DCAT fornece funções e procedimentos para ajudar os usuários do Autonomous AI Database a aproveitar o sistema de descoberta de dados e gerenciamento centralizado de metadados do OCI Data Catalog.

O serviço Data Catalog coleta metadados de ativos de armazenamento de objetos de um data lake. O processo de coleta cria entidades lógicas, que podem ser consideradas como tabelas com colunas e tipos de dados associados. Os procedimentos e funções do DBMS_DCAT conectam o Autonomous AI Database ao serviço Data Catalog e sincronizam os ativos com o banco de dados, criando esquemas protegidos e tabelas externas. Em seguida, você pode consultar o armazenamento de objetos usando essas tabelas externas, unindo facilmente dados externos aos dados armazenados no Autonomous AI Database. Isso simplifica drasticamente o processo de gerenciamento; há um único armazenamento de metadados gerenciado centralmente que é compartilhado entre vários serviços da OCI (incluindo Autonomous AI Databases). Há também views de dicionário do Autonomous AI Database que permitem inspecionar o conteúdo do serviço Data Catalog usando SQL e mostrar como essas entidades do serviço Data Catalog são mapeadas para seus esquemas e tabelas do Autonomous AI Database.

Usuários e Atribuições do Serviço Data Catalog

O pacote DBMS_DCAT suporta usuários/esquemas sincronizados, usuários dcat_admin e usuários locais. Os usuários devem ter a atribuição dcat_sync para poder usar este pacote.

Usuários do Data Catalog

• Usuários/esquemas sincronizados

  As tabelas externas sincronizadas são organizadas em esquemas de banco de dados correspondentes às combinações de Ativo de Dados/Bucket ou de acordo com propriedades personalizadas definidas pelo usuário. Os esquemas sincronizados são criados/eliminados automaticamente durante a sincronização do serviço Data Catalog. Eles são criados como nenhum usuário de autenticação sem o privilégio CREATE SESSION. Os esquemas sincronizados também são criados usando a cláusula protegida, de modo que não possam ser alterados por usuários locais (nem mesmo o administrador do PDB) e só possam ser modificados por meio da sincronização.

• Usuário dcat_admin

  O usuário dcat_admin é um usuário do banco de dados local que pode executar uma sincronização e conceder o privilégio READ em tabelas sincronizadas a outros usuários ou atribuições. O usuário é criado como um usuário sem autenticação sem o privilégio CREATE SESSION.

• Usuários Locais

  Os usuários do banco de dados que consultam as tabelas externas devem receber explicitamente privilégios READ nas tabelas externas sincronizadas pelos usuários dcat_admin ou ADMIN. Por padrão, após a conclusão da sincronização, somente os usuários dcat_admin e ADMIN têm acesso às tabelas externas sincronizadas.

Funções do Serviço Data Catalog

• dcat_sync

  A atribuição dcat_sync tem todos os privilégios necessários para usar o pacote DBMS_DCAT. Os usuários devem ter essa função para poder usar a API para navegar no serviço Data Catalog e executar a sincronização.

Credenciais e Políticas de IAM Obrigatórias

Este tópico descreve as credenciais de usuário e as políticas do Oracle Cloud Infrastructure Identity and Access Management (IAM) necessárias para conceder aos usuários do Autonomous AI Database permissão para gerenciar um catálogo de dados e ler no armazenamento de objetos.

Requisitos de Credencial e Política do OCI Data Catalog

• É necessário um objeto de credencial com permissão para gerenciar uma instância do serviço Data Catalog. Objetos de credencial que contêm credenciais de controlador de recursos ou autenticação nativa do OCI são suportados. Objetos de credencial baseados em principais de usuário de token de autenticação não são suportados.

  Para obter informações sobre como gerenciar credenciais, consulte DBMS_CLOUD para Gerenciamento de Acesso.

  Para obter exemplos de autenticação nativa do OCI, consulte Exemplo: Criando um Objeto de Credencial de Autenticação Nativa do OCI e o Autonomous AI Database Agora Suporta o Acesso ao Object Storage com Autenticação Nativa do OCI.

  Para obter exemplos de como usar o controlador de recursos, consulte Exemplo: Usando o Controlador de Recursos do Autonomous AI Database e Acessando Recursos do Oracle Cloud Infrastructure do Seu Autonomous AI Database usando o Controlador de Recursos.

• O privilégio gerenciar o serviço Data Catalog é necessário para que o Autonomous AI Database adicione propriedades personalizadas ao namespace do serviço Data Catalog. Esses privilégios permitem que você substitua nomes de esquemas, nomes de tabelas, nomes de colunas e muito mais.

  Para obter mais informações sobre permissões do serviço Data Catalog, consulte Permissões Necessárias para Cada Operação de API.

• O privilégio de leitura de armazenamento de objetos em buckets é necessário para que o Autonomous AI Database possa consultar arquivos de dados.

  Para obter mais exemplos de políticas do Oracle Object Storage, consulte Exemplos da Política.

Credencial do catálogo de dados do AWS Glue e requisitos de política

As seguintes credenciais e políticas de usuário são necessárias para conceder aos usuários do Autonomous AI Database permissão para acessar Catálogos de Dados de Colagem do AWS (Amazon Web Services) e para ler no armazenamento de objetos S3:

• É necessário um objeto de credencial com permissão para acessar um Catálogo de Dados do AWS Glue. Para obter informações sobre como gerenciar credenciais, consulte DBMS_CLOUD para Gerenciamento de Acesso.

  Para acessar um catálogo de dados do AWS Glue, os seguintes privilégios são necessários: cola:GetDatabases , cola:GetTables e cola:GetTable.

  Além disso, o privilégio s3:GetBucketLocation é necessário durante a sincronização para gerar urls https resolvíveis que apontam para os objetos S3 subjacentes.

• É necessário um objeto de credencial com permissão para acessar os arquivos armazenados em S3 para que o Autonomous AI Database possa consultar arquivos de dados.

• As credenciais da AWS são suportadas. As credenciais do AWS Amazon Resource Names (ARN) não são suportadas.

Exemplo: Criando um Objeto de Credencial de Autenticação Nativa do OCI

Neste exemplo, criamos uma credencial de autenticação nativa do OCI que pode ser usada ao criar um catálogo de dados ou um objeto de credencial de armazenamento de objetos. Para obter mais detalhes, consulte Procedimento DBMS_DCAT SET_DATA_CATALOG_CREDENTIAL e Procedimento DBMS_DCAT SET_OBJECT_STORE_CREDENTIAL, respectivamente.

Na autenticação nativa do OCI, o procedimento DBMS_CLOUD.CREATE_CREDENTIAL inclui estes parâmetros: credential_name, user_ocid, tenancy_ocid, private_key e fingerprint. Consulte Procedimento DBMS_CLOUD CREATE_CREDENTIAL para obter uma descrição completa desse procedimento.

O credential_name é o nome do objeto da credencial. Os parâmetros user_ocid e tenancy_ocid correspondem aos OCIDs do usuário e da tenancy, respectivamente.

O parâmetro private_key especifica a chave privada gerada no formato PEM. Não há suporte a chaves privadas criadas com uma frase-senha. Portanto, precisamos nos certificar de gerar uma chave sem frase-senha. Consulte Como Gerar uma Chave de Assinatura de API para obter mais detalhes sobre como criar uma chave privada sem frase-senha. Além disso, a chave privada que fornecemos para esse parâmetro só deve conter a chave em si sem qualquer cabeçalho ou rodapé (por exemplo, '—–BEGIN RSA PRIVATE KEY—–', '–END RSA PRIVATE KEY—–).

O parâmetro fingerprint especifica a impressão digital obtida após o upload da chave pública para a console ou usando os comandos OpenSSL. Consulte Como Fazer Upload da Chave Pública e Como Obter a Impressão Digital da Chave para obter mais detalhes sobre como obter a impressão digital.

Assim que todas as informações necessárias forem reunidas e a chave privada for gerada, estaremos prontos para executar o seguinte procedimento CREATE_CREDENTIAL:

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL (
    credential_name => 'OCI_NATIVE_CRED',
    user_ocid              => 'ocid
1.user.oc1..aaaaaaaatfn77fe3fxux3o5lego7glqjejrzjsqsrs64f4jsjrhbsk5qzndq',
    tenancy_ocid           => 'ocid1.tenancy.oc1..aaaaaaaapwkfqz3upqklvmelbm3j77nn3y7uqmlsod75rea5zmtmbl574ve6a',
    private_key            => 'MIIEogIBAAKCAQEA...t9SH7Zx7a5iV7QZJS5WeFLMUEv+YbYAjnXK+dOnPQtkhOblQwCEY3Hsblj7Xz7o=',
    fingerprint            => '4f:0c:d6:b7:f2:43:3c:08:df:62:e3:b2:27:2e:3c:7a');
END;
/

Depois de criar o objeto de credencial, ele é exibido na tabela dba_credentials:

SELECT owner, credential_name
FROM dba_credentials
WHERE credential_name LIKE '%NATIVE%';

OWNER CREDENTIAL_NAME
----- ---------------
ADMIN OCI_NATIVE_CRED

Exemplo: Usando o Controlador de Recursos do Autonomous AI Database

Neste exemplo, um grupo dinâmico é criado que inclui membros de recursos apropriados, o grupo dinâmico recebe permissão para gerenciar um Catálogo de Dados e, em seguida, o grupo dinâmico recebe permissão para ler no armazenamento de objetos.

1. Crie um grupo dinâmico chamado adb-grp-1. Adicione uma regra de correspondência ao adb-grp-1 que inclua a instância do Autonomous AI Database com o OCID ocid1.autonomousdatabase.oc1.iad.abuwcljr...fjkfe como membro de recurso.

   Regra de correspondência de grupo dinâmico:

   resource.id = 'ocid1.autonomousdatabase.oc1.iad.abuwcljr...fjkfe'

2. Defina uma política que conceda ao grupo dinâmico adb-grp-1 acesso total às instâncias do serviço Data Catalog, no compartimento mycompartment.

   allow dynamic-group adb-grp-1 to manage data-catalog-family in compartment mycompartment

3. Defina uma política que permita ao grupo dinâmico adb-grp-1 ler qualquer bucket no compartimento chamado mycompartment.

   allow dynamic-group adb-grp-1 to read objects in compartment mycompartment

Exemplo: Usando Principais do Usuário

Neste exemplo, user1 é membro do grupo adb-admins. Todos os membros desse grupo recebem permissão para gerenciar todos os catálogos de dados no mycompartment e para ler no armazenamento de objetos no mycompartment.

1. Permita que os usuários que são membros do adb-admins gerenciem todos os catálogos de dados no mycompartment.

   allow group adb-admins to manage data-catalog-family in compartment mycompartment

2. Permita que os usuários que são membros do adb-admins leiam qualquer objeto em qualquer bucket dentro do mycompartment.

   allow group adb-admins to read objects in compartment mycompartment

Resumo de Subprogramas de Gerenciamento de Conexão

Esta tabela lista os procedimentos de pacote DBMS_DCAT usados para criar, consultar e eliminar conexões do serviço Data Catalog.

SET_DATA_CATALOG_CREDENTIAL Procedimento

Este procedimento define a credencial de acesso do serviço Data Catalog usada por uma conexão específica com o serviço Data Catalog.

Sintaxe

PROCEDURE DBMS_DCAT.SET_DATA_CATALOG_CREDENTIAL(
    credential_name VARCHAR2(128) DEFAULT NULL,
    dcat_con_id     VARCHAR2 DEFAULT NULL
  );

Parâmetros

Uso

Essa credencial deve ter permissões Gerenciar Catálogo de Dados; consulte Políticas do Serviço Data Catalog. O padrão é o controlador de recursos; consulte Acessar Recursos da Nuvem Configurando Políticas e Atribuições.

SET_OBJECT_STORE_CREDENTIAL Procedimento

Este procedimento define a credencial usada pelo identificador de conexão exclusivo fornecido para acessar o Armazenamento de Objetos. A alteração da credencial de acesso do Object Store altera todas as tabelas sincronizadas existentes para usar a nova credencial.

Sintaxe

PROCEDURE DBMS_DCAT.SET_OBJECT_STORE_CREDENTIAL(
    credential_name  VARCHAR2(128),
    dcat_con_id      IN VARCHAR2 DEFAULT NULL
  );

Parâmetros

SET_DATA_CATALOG_CONN Procedimento

Este procedimento cria uma conexão com o Catálogo de Dados fornecido. A conexão é necessária para sincronizar metadados com o serviço Data Catalog. Uma instância do Autonomous AI Database pode se conectar a várias instâncias do serviço Data Catalog e oferece suporte à conexão com Catálogos de Dados da OCI, Catálogos de Dados do AWS Glue e Catálogos REST do Apache Iceberg.

Sintaxe

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

Parâmetros

Uso

Você só precisa chamar este procedimento uma vez para definir a conexão. Como parte do processo de conexão, o Autonomous AI Database adiciona propriedades personalizadas ao serviço Data Catalog. Essas propriedades personalizadas são acessíveis aos usuários do serviço Data Catalog e permitem que você substitua nomes padrão (para esquemas, tabelas e colunas) e tipos de dados de coluna.

Antes de criar uma conexão, as credenciais devem ser criadas e definidas. Para obter uma descrição do processo de conexão, consulte Workflow Típico com o Serviço Data Catalog para Catálogos de Dados do OCI e Workflow do Usuário para Consultar com o AWS Glue Data Catalog para Catálogos de Dados do AWS Glue.

Exemplo: Estabelecendo Conexão com um OCID conhecido

Neste exemplo, o Autonomous AI Database está se conectando ao serviço Data Catalog na região uk-london-1. O parâmetro catalog_id usa o Oracle Cloud Identifier (ocid) para a instância do serviço Data Catalog. O tipo de Data Catalog é determinado automaticamente: AWS Glue Data Catalog ou OCI Data Catalog.

BEGIN
  DBMS_DCAT.SET_DATA_CATALOG_CONN(
    region=>'uk-london-1',
    catalog_id=>'ocid1.datacatalog.oc1.uk-london-1...');
END;
/

Exemplo: Conexão com um Catálogo de Dados do AWS Glue

Uma conexão é a associação entre uma instância do Autonomous AI Database e um Catálogo de Dados do AWS Glue. Após uma conexão bem-sucedida, a instância do Autonomous AI Database pode ser sincronizada com o AWS Glue. Cada conta da AWS tem um Catálogo de Dados do AWS Glue por região e cada catálogo pode ser acessado usando o ponto final de serviço correspondente para cada região. Uma instância do Autonomous AI Database pode ser associada a um Catálogo de Dados do AWS Glue chamando a API DBMS_DCAT.SET_DATA_CATALOG_CONN e especificando o ponto final da região em que o catálogo reside.

Consulte Pontos finais e cotas da AWS Glue.

Neste exemplo, o Autonomous AI Database está se conectando a um Catálogo de Dados do AWS Glue na região uk-london-1. Como essa é uma conexão do AWS Glue Data Catalog, o parâmetro catalog_id não é necessário.

BEGIN
  DBMS_DCAT.SET_DATA_CATALOG_CONN(
    region=>'uk-london-1',
    catalog_type=>'AWS_GLUE'
END;
/

Exemplos: Conexão com um catálogo REST do Databricks Unity Iceberg

Neste exemplo, o Autonomous AI Database está se conectando a um catálogo REST do Databricks Unity Iceberg usando um token de acesso pessoal (de longa duração).

DBMS_CLOUD.create_credential('MY_DATABRICKS_CRED','username', '<personal access token>');
DBMS_DCAT.set_data_catalog_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'MY_DATABRICKS_CRED');
DBMS_DCAT.set_object_store_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'SOMECRED');
DBMS_DCAT.set_data_catalog_conn (
  dcat_con_id  => 'ICEBERG_CATALOG',
  catalog_type => 'ICEBERG_UNITY',
  endpoint     => 'https://adb-...azuredatabricks.net/api/2.1/unity-catalog/iceberg/v1/');

Neste exemplo, o Autonomous AI Database está se conectando a um catálogo REST do Databricks Unity Iceberg com um controlador de serviços usando OAuth.

DBMS_CLOUD.create_credential('MY_DATABRICKS_SP_CRED','<client id for the service principal>', '<client secret for the service principal>');
DBMS_DCAT.set_data_catalog_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'MY_DATABRICKS_SP_CRED');
DBMS_DCAT.set_object_store_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'MY_OS_CRED');
DBMS_DCAT.set_data_catalog_conn (
  dcat_con_id    => 'ICEBERG_CATALOG',
  catalog_type   => 'ICEBERG_UNITY',
  endpoint       => 'https://adb-...azuredatabricks.net/api/2.1/unity-catalog/iceberg/v1',
  token_endpoint => 'https://adb-...azuredatabricks.net/oidc/v1/token');

Exemplo: Conexão com um catálogo REST do Apache Polaris Iceberg

Neste exemplo, o Autonomous AI Database está se conectando a um catálogo REST do Apache Polaris Iceberg usando OAuth.

DBMS_CLOUD.create_credential('MY_POLARIS_CRED','<client id>', '<client secret>');
DBMS_DCAT.set_data_catalog_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'MY_POLARIS_CRED');
DBMS_DCAT.set_object_store_credential(dcat_con_id=>'ICEBERG_CATALOG',credential_name=>'SOMECRED');
DBMS_DCAT.set_data_catalog_conn (
  dcat_con_id    => 'ICEBERG_CATALOG',
  catalog_type   => 'ICEBERG_POLARIS',
  endpoint       => 'https://dev-iceberg.subnet...vcn...oraclevcn.com/api/catalog/v1/quickstart_catalog',
  token_endpoint => 'https://dev-iceberg.subnet...vcn...oraclevcn.com/api/catalog/v1/oauth/tokens');

UNSET_DATA_CATALOG_CONN Procedimento

Este procedimento remove uma conexão existente do serviço Data Catalog.

Sintaxe

Observação

Observação: A chamada desse procedimento elimina todos os esquemas protegidos e tabelas externas que foram criados como parte das sincronizações anteriores. Ela não afeta os metadados no serviço Data Catalog.

PROCEDURE DBMS_DCAT.UNSET_DATA_CATALOG_CONN (
    dcat_con_id IN VARCHAR2 DEFAULT NULL
);

Parâmetros

Resumo dos Subprogramas de Sincronização

A execução de uma sincronização, a criação e a eliminação de um job de sincronização e a eliminação de esquemas sincronizados podem ser executadas com os procedimentos listados nesta tabela.

Observação

Observação: Em 4 de abril de 2022, os parâmetros sync_option e grant_read foram adicionados ao procedimento DBMS_DCAT.RUN_SYNC. Para garantir o desempenho correto dos jobs de sincronização programados criados antes dessa data, você precisa eliminar e recriar os jobs de sincronização programados. Consulte Procedimento DBMS_DCAT.DROP_SYNC_JOB e Procedimento DBMS_DCAT.CREATE_SYNC_JOB.

RUN_SYNC Procedimento

Este procedimento executa uma operação de sincronização e é o ponto de entrada para a sincronização. Como entrada, ele pega listas de ativos, pastas e entidades do catálogo de dados selecionados e materializa-os criando, eliminando e alterando tabelas externas.

O parâmetro sync_option especifica qual operação o procedimento RUN_SYNC executa: SYNC, DELETE ou REPLACE. A operação é executada em entidades dentro do escopo do parâmetro synced_objects.

Cada chamada para o procedimento RUN_SYNC retorna um operation_id exclusivo que pode ser usado para consultar a view USER_LOAD_OPERATIONS para obter informações sobre o status da sincronização e o log_table correspondente. A view DBMS_DCAT$SYNC_LOG pode ser consultada para facilitar o acesso à log_table para a última operação de sincronização executada pelo usuário atual. Para obter mais detalhes, consulte View DBMS_DCAT$SYNC_LOG e Monitoramento e Solução de Problemas de Cargas.

Observação

Observação: Em 4 de abril de 2022, os parâmetros sync_option e grant_read foram adicionados ao procedimento RUN_SYNC. Para garantir o desempenho correto dos jobs de sincronização programados criados antes dessa data, você precisa eliminar e recriar os jobs de sincronização programados. Consulte Procedimento DBMS_DCAT.DROP_SYNC_JOB e Procedimento DBMS_DCAT.CREATE_SYNC_JOB.

Sincronizando Entidades Lógicas Particionadas ou Tabelas de Cola

O procedimento RUN_SYNC cria uma tabela externa particionada para cada entidade lógica ou tabela de Colagem quando as três seguintes situações se aplicam:

1. A entidade lógica ou tabela de Colagem do catálogo de dados do OCI tem um ou mais atributos particionados.

2. Para catálogos de dados do OCI, a entidade lógica é derivada de um padrão de nome de arquivo baseado em prefixo. Não há suporte para entidades lógicas particionadas derivadas de padrões baseados em regex.

3. Para catálogos de dados do OCI, a entidade lógica se baseia em dados particionados que seguem o formato de pasta hive-style ou não-hive. Não há suporte para entidades lógicas baseadas em dados particionados que seguem o formato de estilo não-hive usando nomes de objeto.

   • Exemplo 1. Entidades lógicas baseadas em objetos coletados que seguem o formato de particionamento de estilo do Hive com padrões de nome de arquivo baseados em prefixo.

     Considere os seguintes objetos:

     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.csv

     A coleta do bucket usando um padrão de nome de arquivo com um prefixo de pasta inicial cluster1/db1.db gera uma entidade lógica chamada SALES com três atributos de partição: country, year e month. O tipo de atributos particionados é Partition, enquanto o tipo de atributos não particionados é Primitive.

   • Exemplo 2. Entidades lógicas baseadas em objetos coletados que seguem o formato de particionamento de estilo não Hive com padrões de nome de arquivo baseados em prefixo.

     Considere os seguintes objetos:

     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.csv

     A coleta do bucket usando um padrão de nome de arquivo com um prefixo de pasta inicial cluster2/db2.db gera uma entidade lógica chamada SALES com três atributos de partição: name0, name1 e name2. A única diferença entre a entidade lógica gerada em comparação com o Exemplo 1 é que os nomes dos atributos particionados são gerados automaticamente, enquanto no Exemplo 1 eles são extraídos do URL (country, year e month, respectivamente).

Para obter um exemplo completo de sincronização de entidades lógicas particionadas, consulte Exemplo: Um Cenário de Dados Particionado.

Sincronização Incremental de Entidades Lógicas Particionadas/Tabelas de Cola

Cada chamada ao procedimento RUN_SYNC especifica um conjunto de entidades lógicas do catálogo de dados do OCI ou tabelas do AWS Glue a serem sincronizadas com o banco de dados. Quando uma entidade lógica ou uma tabela de cola está presente em duas chamadas RUN_SYNC, a segunda chamada preserva e possivelmente altera as tabelas externas existentes. A tabela a seguir mostra quais alterações de entidade lógica ou tabela de colagem são suportadas quando a entidade lógica ou tabela de colagem é particionada:

Sintaxe

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

Parâmetros

Exemplo: Sincronizar todas as entidades do OCI Data Catalog

No exemplo a seguir, todas as entidades do serviço Data Catalog são sincronizadas.

EXEC DBMS_DCAT.RUN_SYNC(synced_objects=>'{"asset_list":["*"]}');

Exemplo: parâmetro synced_objects para sincronizar todos os ativos de dados do OCI Data Catalog

Veja a seguir um exemplo de parâmetro synced_objects para sincronizar todos os ativos de dados (Object Storage) no serviço Data Catalog.

{"asset_list" : ["*"]}

Exemplo: parâmetro synced_objects para sincronizar ativos de dados específicos do OCI Data Catalog

Veja a seguir um exemplo de parâmetro synced_objects para sincronizar dois ativos de dados.

{"asset_list": [
        {
            "asset_id":"...-9e2e7f78fd5f"
        },
        {
            "asset_id":"...-9e2e7f74523"
        }
    ]}

Exemplo: parâmetro synced_objects para sincronizar entidades específicas do OCI Data Catalog em um ativo de dados

O exemplo a seguir mostra um parâmetro synced_objects para sincronizar duas entidades dentro do ativo de dados.

{"asset_list": [
        {
            "asset_id":"...-9e2e7f78fd5f",
            "folder_list":[
                "f1",
                "f2"
           ]
        }
    ]}

Exemplo: parâmetro synced_objects para sincronizar pastas e entidades específicas do OCI Data Catalog em um ativo de dados

O exemplo a seguir mostra um parâmetro synced_objects para sincronizar duas pastas e duas entidades dentro do ativo de dados.

{"asset_list":[
        {
            "asset_id":"...-9e2e7f78fd5f",
            "entity_list": [
                "entity1",
                "entity2"
            ],
             "folder_list": [
                "f1",
                "f2"
            ]
        }
    ]}

Exemplo: Parâmetro synced_objects para Sincronizar Todos os Bancos de Dados do AWS Glue Data Catalog

O exemplo a seguir mostra um parâmetro synced_objects para sincronizar todos os bancos de dados no AWS Glue Data Catalog.

{"database_list":["*"]}

Exemplo: Parâmetro synced_objects para Sincronizar Dois Bancos de Dados do AWS Glue Data Catalog

O exemplo a seguir mostra um parâmetro synced_objects para sincronizar dois bancos de dados do AWS Glue Data Catalog.

{"database_list":[
    {"database":"tpcdscsv"},
    {"database":"tpcdsparquet"} ]}

Exemplo: Parâmetro synced_objects para Sincronizar Três Bancos de Dados do AWS Glue Data Catalog

O exemplo a seguir mostra um parâmetro synced_objects para sincronizar três tabelas de um banco de dados do AWS Glue Data Catalog.

{"database_list":[
 {"database":"tpcdsparquet",
     "table_list": [ "tpcdsparquet_customer",
                     "tpcdsparquet_item",
                     "tpcdsparquet_web_sales" ] } ]}

Exemplo: Chame o DBMS_DCAT.run_sync para sincronizar todos os namespaces em um catálogo do Iceberg

Para um catálogo Iceberg, esta chamada de amostra sincroniza todos os namespaces:

DBMS_DCAT.run_sync(
  dcat_con_id     => 'MY_ICEBERG_CON',
  synced_objects  => '{"namespace_list" : ["*"]}',
  sync_option     => 'SYNC',
  error_semantics => 'STOP_ON_ERROR,
  log_level       => 'DEBUG',
  grant_read      => 'DB_USER');

Exemplo: Chame o DBMS_DCAT.run_sync para sincronizar todas as tabelas em um namespace Iceberg e algumas tabelas em outro namespace Iceberg

Para um catálogo Iceberg, esta chamada de amostra sincroniza todas as tabelas no namespace warehouse e três tabelas do namespace ["bigdata","tpcdsparquet"]:

DBMS_DCAT.run_sync(
  dcat_con_id     => 'MY_ICEBERG_CON',
  synced_objects  => '{"namespace_list": [
                          { "namespace": ["warehouse"] },
                          { "namespace": ["bigdata", "tpcdsparquet"],
                                "table_list": [ "tpcdsparquet_customer",
                                                "tpcdsparquet_item",
                                                "tpcdsparquet_web_sales" ] } ]}',
  sync_option     => 'SYNC',
  error_semantics => 'STOP_ON_ERROR,
  log_level       => 'DEBUG',
  grant_read      => 'DB_USER');

CREATE_SYNC_JOB Procedimento

Este procedimento cria um job do scheduler para chamar RUN_SYNC periodicamente.

Ele utiliza como entrada o conjunto de objetos a serem sincronizados, a semântica de erro, o nível de log e um intervalo de repetição. Consulte Procedimento DBMS_DCAT RUN_SYNC para obter mais detalhes sobre como a sincronização funciona.

Só pode haver um único job de sincronização. O procedimento CREATE_SYNC_JOB falhará se outro job já estiver especificado, a menos que o parâmetro de imposição seja definido como TRUE. Se a imposição for definida como TRUE, o job anterior será eliminado.

Se um job do scheduler tentar ser executado enquanto outra sincronização estiver em andamento, o job do scheduler falhará.

Observação

Observação: Em 4 de abril de 2022, os parâmetros sync_option e grant_read foram adicionados ao procedimento RUN_SYNC. Para garantir o desempenho correto dos jobs de sincronização programados criados antes dessa data, você precisa eliminar e recriar os jobs de sincronização programados. Consulte Procedimento DBMS_DCAT.DROP_SYNC_JOB e Procedimento DBMS_DCAT.CREATE_SYNC_JOB.

Sintaxe

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

Parâmetros

DROP_SYNC_JOB Procedimento

Este procedimento elimina um job de sincronização existente para o identificador de conexão exclusivo fornecido.

Sintaxe

PROCEDURE DBMS_DCAT.DROP_SYNC_JOB (
    dcat_con_id IN VARCHAR2 DEFAULT NULL
  );

Parâmetros

DROP_SYNCED_SCHEMAS Procedimento

Este procedimento elimina todos os esquemas sincronizados anteriormente para o identificador de conexão exclusivo fornecido.

Sintaxe

PROCEDURE DBMS_DCAT.DROP_SYNCED_SCHEMAS (
    dcat_con_id IN VARCHAR2 DEFAULT NULL
  );

Parâmetros

Início Rápido

Esta seção descreve o processo de configuração de credenciais e conexões seguras da nuvem para que o Oracle Data Catalog sincronize e acesse metadados das origens de dados da nuvem do OCI e do AWS Glue no banco de dados.

OCI

O procedimento a seguir configura as credenciais de autenticação do OCI, configura a conexão do Oracle Data Catalog para usar essas credenciais e inicia uma operação de sincronização de metadados para tornar os metadados do catálogo de dados na nuvem acessíveis no ambiente do banco de dados por meio de tabelas externas para consulta e consumo.

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'OCI_NATIVE_CRED',
    user_ocid       => 'ocid1.user....',
    tenancy_ocid    => 'ocid1.tenancy....',
    private_key     => '...PEM_WITHOUT_HEADERS...',
    fingerprint     => '4f:0c:d6:...:7a'
  );
END;
/

BEGIN
  DBMS_DCAT.SET_DATA_CATALOG_CONN(region => 'us-ashburn-1');
  DBMS_DCAT.SET_DATA_CATALOG_CREDENTIAL(dcat_con_id => NULL, credential_name => 'OCI_NATIVE_CRED');
  DBMS_DCAT.SET_OBJECT_STORE_CREDENTIAL(dcat_con_id => NULL, credential_name => 'OCI_NATIVE_CRED');
END;
/

DECLARE
  op NUMBER;
BEGIN
  DBMS_DCAT.RUN_SYNC(
    synced_objects  => q'{"asset_list":["*"]}',
    sync_option     => 'SYNC',
    error_semantics => 'STOP_ON_ERROR',
    log_level       => 'INFO',
    grant_read      => 'DATA_CONSUMERS',
    operation_id    => op
  );
END;
/

AWS Glue

O procedimento a seguir prepara o Oracle Database para se conectar e autenticar com segurança com os serviços da AWS usando credenciais, configurar a conexão do catálogo de dados com o catálogo do AWS Glue e importar metadados selecionados do AWS Glue para a Oracle para uso em seu ambiente.

BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'AWS_CRED',
    username        => '<aws_access_key_id>',
    password        => '<aws_secret_access_key>');
END;
/

BEGIN
  DBMS_DCAT.SET_DATA_CATALOG_CONN(region => 'eu-west-2', catalog_type => 'AWS_GLUE');
  DBMS_DCAT.SET_DATA_CATALOG_CREDENTIAL(dcat_con_id => NULL, credential_name => 'AWS_CRED');
  DBMS_DCAT.SET_OBJECT_STORE_CREDENTIAL(dcat_con_id => NULL, credential_name => 'AWS_CRED');
END;
/

BEGIN
  DBMS_DCAT.RUN_SYNC(
    synced_objects => q'{
      "database_list":[
        {"database":"tpcdsparquet",
         "table_list":["customer","item","web_sales"]}
      ]}',
    grant_read => 'DATA_CONSUMERS'
  );
END;
/

Resumo de Views do Serviço Data Catalog

A integração do serviço Data Catalog com o Autonomous AI Database fornece várias tabelas e views.

Estas tabelas e views ajudam a compreender:

• Ativos disponíveis do serviço Data Catalog. Obtenha informações sobre qualquer tipo de ativo do serviço Data Catalog - incluindo bancos de dados, armazenamentos de objetos e muito mais.

• Informações sobre os ativos e as entidades do serviço Data Catalog Object Storage que foram sincronizados com o Autonomous AI Database. Isso inclui detalhes sobre como os itens do serviço Data Catalog (ativos, pastas e entidades) são mapeados para objetos do Autonomous AI Database (ou seja, esquemas e tabelas externas).

• Execuções de sincronização de metadados. Verifique os detalhes sobre jobs de sincronização, incluindo quaisquer problemas que possam ter ocorrido durante a sincronização.

Esta tabela lista as tabelas e as views fornecidas pelo pacote DBMS_DCAT.

ALL_CLOUD_CATALOG_DATABASES Exibição

Use a view ALL_CLOUD_CATALOG_DATABASES para exibir informações sobre ativos de dados do OCI Data Catalog e bancos de dados do AWS Glue Data Catalog.

Data stored in S3 (N. California)

Data stored in S3 (N. California)

{ "catalog-id": "ocid1.datacatalog.oc1.ap-mumbai-1.amaaa...", "description": null, "display-name": "OBJECT_STORE_AT_ASHBURN", "external-key": "https://swiftobjectstorage.us-ashburn-1....", "key": "bc95181c-3ac3-4959-9e5f-4e460d3fb82a", "lifecycle-state": "ACTIVE", "time-created": "2022-09-26T22:56:01.395000+00:00", "type-key": "3ea65bc5-f60d-477a-a591-f063665339f9", "uri": "/dcat/20190325/dataAssets/bc95181c-3ac3-4959-9e5f-4e460d3fb82a" }

{ "Name": "dbmsdcatpoc", "Parameters": { "somekey": "somevalue" }, "CreateTime": "2022-06-15T09:45:35+01:00", "CreateTableDefaultPermissions": [ { "Principal": { "DataLakePrincipalIdentifier": "IAM_ALLOWED_PRINCIPALS" }, "Permissions": [ "ALL" ] } ], "CatalogId": "579294766787" }

ALL_CLOUD_CATALOG_TABLES Exibição

O View ALL_CLOUD_CATALOG_TABLES é usado para exibir informações sobre entidades de dados para Catálogos de Dados do OCI e tabelas do AWS Glue Data Catalogs.

{  "business-name": null, "data-asset-key": "bc95181c-3ac3-4959-9e5f-...", "description": null, "display-name": "bikes_trips", "external-key": "LE: https://swiftobjectstorage.us-ashburn-1.oraclecloud.com/v1/..._trips", "folder-key": "9c4b542d-d6eb-4b83-bf59-...", "folder-name": "hive", "is-logical": true, "is-partition": false, "key": "fde30a69-a07c-478a-ab62-...", "lifecycle-state": "ACTIVE", "object-storage-url": "https://objectstorage.us-ashburn-1.oraclecloud.com/n/...", "path": "OBJECT_STORE_AT_ASHBURN/hive/hive", "pattern-key": "db21b3f1-1508-4045-aa80-...", "properties": { "default": { "CONTENT-LENGTH": "4310321", "LAST-MODIFIED": "Fri, 9 Oct 2020 20:16:52 UTC", "archivedPECount": "0", "dataEntityExpression": "{logicalEntity:[^/]+}.db/{logicalEntity:[^/]+}/.*", "harvestedFile": "bikes.db/trips/p_start_month=2019-09/000000_0", "patternName": "bikes_trips" }, "harvestProps": { "characterset": "UTF8", "compression": "none", "type": "PARQUET" } }, "realized-expression": "bikes.db/trips/.*", "time-created": "2022-09-26T22:56:35.063000+00:00", "time-updated": "2022-09-26T22:56:35.063000+00:00", "type-key": "6753c3af-7f88-44b9-be52-1d57bef462fb", "updated-by-id": "ocid1.user.oc1..r5l3tov7a", "uri": "/dcat/20190325/dataAssets/bc95181c-3ac3-4959-9e5f-..." }

{ "Name": "bikes_trips", "DatabaseName": "dbmsdcatpoc", "Owner": "owner", "CreateTime": "2022-06-23T13:24:20+01:00", "UpdateTime": "2022-06-23T13:24:20+01:00", "LastAccessTime": "2022-06-23T13:24:20+01:00", "Retention": 0, "StorageDescriptor": { "Columns": [ { "Name": "trip_duration", "Type": "int" }, { "Name": "start_month", "Type": "string" }, ... ], "Location": "s3://dbmsdcatpoc/hive/bikes.db/trips/", "InputFormat": "org.apache.hadoop.hive.ql.io.parquet.MapredParquetInputFormat", "OutputFormat": "org.apache.hadoop.hive.ql.io.parquet.MapredParquetOutputFormat", "Compressed": false, "NumberOfBuckets": -1, "SerdeInfo": { "SerializationLibrary": "org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe", "Parameters": { "serialization.format": "1" } }, "BucketColumns": [], "SortColumns": [], "Parameters": { "CrawlerSchemaDeserializerVersion": "1.0", "CrawlerSchemaSerializerVersion": "1.0", "UPDATED_BY_CRAWLER": "crawler-bikes", "averageRecordSize": "86", "classification": "parquet", "compressionType": "none", "objectCount": "12", "recordCount": "404947", "sizeKey": "35312159", "typeOfData": "file" }, "StoredAsSubDirectories": false }, "PartitionKeys": [ { "Name": "p_start_month", "Type": "string" } ], "TableType": "EXTERNAL_TABLE", "Parameters": { "CrawlerSchemaDeserializerVersion": "1.0", "CrawlerSchemaSerializerVersion": "1.0", "UPDATED_BY_CRAWLER": "crawler-bikes", "averageRecordSize": "86", "classification": "parquet", "compressionType": "none", "objectCount": "12", "recordCount": "404947", "sizeKey": "35312159", "typeOfData": "file" }, "CreatedBy": "arn:aws:sts::579294766787:assumed-role/AWSGlueServiceRole-dbmsdcat/AWS-Crawler", "IsRegisteredWithLakeFormation": false, "CatalogId": "579294766787", "VersionId": "0" }

ALL_DCAT_ASSETS Exibição

Os ativos do serviço Data Catalog que este banco de dados está autorizado a acessar.

ALL_DCAT_ATTRIBUTES Exibição

Os atributos do serviço Data Catalog que este banco de dados está autorizado a acessar.

ALL_DCAT_CONNECTIONS Exibição

Uma view que contém informações sobre os catálogos de dados conectados a esta instância.

ALL_DCAT_ENTITIES Exibição

As entidades lógicas do serviço Data Catalog que este banco de dados está autorizado a acessar.

ALL_DCAT_FOLDERS Exibição

Metadados para os buckets do serviço Object Storage que contêm os arquivos de dados das Entidades Lógicas.

ALL_DCAT_GLOBAL_ACCESSIBLE_CATALOGS Exibição

Esta view lista todos os catálogos acessíveis em todas as regiões, juntamente com o nível de privilégios de acesso para cada catálogo.

ALL_DCAT_LOCAL_ACCESSIBLE_CATALOGS Exibição

Esta exibição lista todos os catálogos acessíveis na região atual, juntamente com o nível de privilégios de acesso para cada catálogo.

ALL_GLUE_DATABASES Exibição

Os bancos de dados do AWS Glue Data Catalog que a credencial do catálogo de dados está autorizada a acessar.

ALL_GLUE_TABLES Exibição

Esta exibição mostra todas as tabelas do AWS Glue Data Catalog que a credencial do catálogo de dados está autorizada a acessar.

DCAT_ATTRIBUTES Exibição

Lista o mapeamento de atributos de entidade lógica para colunas de tabela externa.

DCAT_ENTITIES Exibição

Descreve o mapeamento de entidades lógicas para tabelas externas.

Visualização DBMS_DCAT$SYNC_LOG

A view DBMS_DCAT$SYNC_LOG fornece acesso fácil à tabela de logs para a última operação de sincronização executada pelo usuário atual.

Cada chamada para o procedimento RUN_SYNC é registrada em uma nova tabela de log, apontada pelo campo LOGFILE_TABLE de USER_LOAD_OPERATIONS. As tabelas de log são eliminadas automaticamente após 2 dias, e os usuários podem limpar todos os logs de sincronização usando o Procedimento DELETE_ALL_OPERATIONS em que o tipo é DCAT_SYNC.

A view DBMS_DCAT$SYNC_LOG identifica automaticamente a tabela de log mais recente. O esquema da view DBMS_DCAT$SYNC_LOG é descrito abaixo e as permissões de acesso são idênticas às das tabelas de log individuais. Por padrão, o READ é concedido à atribuição dbms_dcat e ao usuário ADMIN.

As tabelas de log têm o seguinte formato:

Dicas de Diagnóstico e Solução de Problemas

Esta seção fornece dicas de solução de problemas para problemas comuns:

• Verifique se todas as atribuições e privilégios necessários estão atribuídos corretamente.
• Verifique novamente se os URLs da região e do armazenamento de objetos correspondem à implantação real.
• Certifique-se de que as permissões GRANT READ tenham sido concedidas explicitamente aos usuários ou atribuições relevantes.
• Para diagnosticar problemas de sincronização, revise a tabela DBMS_DCAT$SYNC_LOG para obter mensagens de erro detalhadas e o status da operação.

Observação

Observação: O USER_LOAD_OPERATIONS.LOGFILE_TABLE pode ser encontrado consultando o dicionário de dados ou usando as views do Oracle Data Catalog que rastreiam logs de operação de carregamento.