Pacote DBMS_CLOUD_PIPELINE

O pacote DBMS_CLOUD_PIPELINE permite que você crie pipelines de dados para carregar e exportar dados na nuvem. Este pacote suporta carregamento de dados incremental contínuo de arquivos no armazenamento de objetos no banco de dados. DBMS_CLOUD_PIPELINE também suporta exportação incremental contínua de dados de tabela ou resultados de consulta do banco de dados para o armazenamento de objetos com base em uma coluna de timestamp.

Pré-requisitos

Como desenvolvedor, você pode usar procedimentos DBMS_CLOUD com Autonomous AI Databases implantados na Oracle Public Cloud, Multicloud ou Exadata Cloud@Customer.

Dependendo da opção de implantação, os pré-requisitos a seguir devem ser atendidos para usar os procedimentos DBMS_CLOUD com os provedores de serviços Amazon S3, Azure Blob Storage e Google Cloud Storage.

Uma conectividade de saída deve ter sido configurada usando um gateway NAT, pelo administrador da frota, conforme descrito abaixo:

  • Crie um gateway NAT na VCN (Virtual Cloud Network) em que seus recursos do Autonomous AI Database residem seguindo as instruções em Criar um Gateway NAT na Documentação do Oracle Cloud Infrastructure.

  • Após criar o gateway NAT, adicione uma regra da rota e uma regra da segurança da saída a cada sub-rede (na VCN) em que residem os recursos do Autonomous AI Database para que esses recursos possam usar o gateway para obter a chave pública da sua instância doAzure AD

    1. Vá para a página Detalhes de Sub-rede da sub-rede.

    2. Na guia Informações da Sub-rede, clique no nome da Tabela da Rota da sub-redes para exibir sua página Detalhes da Tabela de Roteamento.

    3. Na tabela de Regras de Rota existentes, verifique se já existe uma regra com as seguintes características:

      • Destino: 0.0.0.0/0

      • Target Type: Gateway NAT

      • Destino: O nome do gateway NAT que você acaba de criar na VCN

      Se essa regra não existir, clique em Adicionar Regras de Roteamento e adicione uma regra de roteamento com essas características.

    4. Retorne à página Detalhes da Subrede da sub-rede.

    5. Na tabela Listas de Segurança da subrede, clique no nome da lista para exibir sua página Detalhes da Lista de Segurança.

    6. No menu lateral, em Recursos, clique em Regras de Saída.

    7. Na tabela de Regras de Saída existentes, verifique se já existe uma regra com as seguintes características:

      • Tipo de Destino:CIDR

      • Destino:0.0.0.0/0

      • Protocolo IP:TCP

      • Faixa de Portas de Origem:443

      • Intervalo de Portas de Destino:Tudo

      Se essa regra não existir, clique em Adicionar Regras de Saída e adicione uma regra de saída com essas características.

As definições de Proxy HTTP em seu ambiente devem permitir que o banco de dados acesse o provedor de serviços em nuvem.

Essas definições são definidas pelo administrador da frota ao criar a infraestrutura do Exadata Cloud@Customer conforme descrito em Usando a Console para Provisionar o Exadata Database Service on Cloud@Customer.

Observação: A configuração de rede, incluindo o Proxy HTTP, só poderá ser editada até que o Exadata Infrastructure esteja no estado Exige Ativação. Uma vez ativado, você não pode editar essas configurações.

A configuração de um Proxy HTTP para uma Infraestrutura do Exadata já provisionada precisa de uma Solicitação de Serviço (SR) no My Oracle Support. Consulte Criar uma Solicitação de Serviço no My Oracle Support para obter detalhes.

Resumo dos Subprogramas DBMS_CLOUD_PIPELINE

Esta tabela resume os subprogramas incluídos no pacote DBMS_CLOUD_PIPELINE.

Subprograma Descrição
Procedimento CREATE_PIPELINE Cria um novo pipeline de dados.
Procedimento DROP_PIPELINE Elimina um pipeline de dados existente.
Procedimento RESET_PIPELINE Redefine o estado de rastreamento de um pipeline de dados. Use o pipeline de redefinição para reiniciar o pipeline do estado inicial do carregamento ou da exportação de dados. Opcionalmente, a redefinição do pipeline pode expurgar dados no banco de dados ou no armazenamento de objetos, dependendo do tipo de pipeline.
Procedimento RUN_PIPELINE_ONCE Executa uma execução sob demanda do pipeline na sessão em primeiro plano atual, em vez de um job programado.
Procedimento SET_ATTRIBUTE Define atributos de pipeline. Há dois procedimentos sobrecarregados, um para definir um único atributo e outro para definir vários atributos usando um documento JSON de pares de nome/valor de atributo
Procedimento START_PIPELINE Inicia o pipeline de dados. Quando um pipeline é iniciado, a operação do pipeline será executada continuamente em um job programado de acordo com o "intervalo" configurado nos atributos do pipeline.
Procedimento STOP_PIPELINE Interrompe o pipeline de dados. Quando um pipeline é interrompido, nenhum job futuro é programado para o pipeline.

Procedimento CREATE_PIPELINE

O procedimento cria um novo pipeline de dados.

Sintaxe

DBMS_CLOUD_PIPELINE.CREATE_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      pipeline_type        IN   VARCHAR2,
      attributes           IN   CLOB        DEFAULT NULL,
      description          IN   VARCHAR2    DEFAULT NULL
);

Parâmetros

Parâmetro Descrição
pipeline_name

Especifica um nome para o pipeline. O nome do pipeline deve seguir as regras de nomenclatura dos identificadores Oracle SQL. Consulte Identificadores na Referência de Linguagem PL/SQL do Oracle Database Database ou Referência de Linguagem PL/SQL do Oracle Database 26ai Database para obter mais informações.

Este parâmetro é obrigatório.
pipeline_type

Especifica o tipo de pipeline.

Valores válidos: LOAD, EXPORT

Este parâmetro é obrigatório.
attributes

Atributos de pipeline no formato JSON.

Valor padrão: NULL

Consulte Atributos DBMS_CLOUD_PIPELINE para obter mais informações.

description

Descrição do pipeline.

Valor padrão: NULL

Procedimento DROP_PIPELINE

O procedimento elimina um pipeline de dados existente. Se um pipeline tiver sido iniciado, ele deverá ser interrompido antes de ser eliminado.

Sintaxe

DBMS_CLOUD_PIPELINE.DROP_PIPELINE(
       pipeline_name        IN   VARCHAR2,
       force                IN   BOOLEAN DEFAULT FALSE
 );

Parâmetros

Parâmetro Descrição
pipeline_name

Especifica um nome de pipeline.

Este parâmetro é obrigatório.
force

Elimine à força um pipeline, mesmo que ele esteja no estado iniciado.

Valores válidos: TRUE, FALSE

Valor padrão: FALSE

Observações de Uso

Procedimento RESET_PIPELINE

Redefine o estado de rastreamento de um pipeline de dados. Use o pipeline de redefinição para reiniciar o pipeline do estado inicial do carregamento ou da exportação de dados. Opcionalmente, a redefinição do pipeline pode expurgar dados no banco de dados ou no armazenamento de objetos, dependendo do tipo de pipeline. Um pipeline de dados deve estar no estado interrompido para redefini-lo.

Sintaxe

DBMS_CLOUD_PIPELINE.RESET_PIPELINE(
       pipeline_name        IN   VARCHAR2,
       purge_data           IN   BOOLEAN DEFAULT FALSE
 );

Parâmetros

Parâmetro Descrição
pipeline_name

Especifica um nome para o pipeline.

Este parâmetro é obrigatório.
purge_data

Os dados de expurgação se aplicam a um pipeline de carga ou a um pipeline de exportação:

  • Para um pipeline de carga, quando TRUE, trunca os dados na tabela do banco de dados.

  • Para um pipeline de exportação, quando TRUE, exclua os arquivos no local do armazenamento de objetos.

Valores válidos: TRUE, FALSE

Valor padrão: FALSE

Observações sobre Uso

Procedimento RUN_PIPELINE_ONCE

Este procedimento executa uma execução sob demanda do pipeline na sessão em primeiro plano atual, em vez de uma execução em um job programado. Use DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCE para testar um pipeline antes de iniciar o pipeline como um job contínuo.

Sintaxe

DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCE(
       pipeline_name  IN  VARCHAR2
);

Parâmetros

Parâmetro Descrição
pipeline_name

Especifica um nome para o pipeline a ser executado.

Este parâmetro é obrigatório.

Observações sobre Uso

Procedimento SET_ATTRIBUTE

Este procedimento define atributos de pipeline. Há dois procedimentos sobrecarregados, um para definir um único atributo e outro para definir vários atributos usando um documento JSON de pares de nome/valor de atributo.

Sintaxe

PROCEDURE DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE(
      pipeline_name        IN   VARCHAR2,
      attribute_name       IN   VARCHAR2,
      attribute_value      IN   CLOB
);

PROCEDURE DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE(
      pipeline_name        IN   VARCHAR2,
      attributes           IN   CLOB
);

Parâmetros

Parâmetro Descrição
pipeline_name

Especifica um nome para o pipeline para definir atributos.

Este parâmetro é obrigatório.
attribute_name

Especifica o nome do atributo a ser definido.

Consulte Atributos DBMS_CLOUD_PIPELINE para obter mais informações.

attribute_value

Especifica o valor do atributo de pipeline a ser definido.

Consulte Atributos DBMS_CLOUD_PIPELINE para obter mais informações.

attributes

Especifica um documento JSON contendo nomes e valores de atributo.

Consulte Atributos DBMS_CLOUD_PIPELINE para obter mais informações.

Observações de Uso

Quando você usa DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE para definir vários atributos com o parâmetro attributes, todos os atributos existentes são excluídos e substituídos pelos atributos especificados do documento JSON.

Procedimento START_PIPELINE

O procedimento inicia o pipeline de dados. Quando um pipeline é iniciado, a operação do pipeline é executada continuamente em um job programado de acordo com o interval configurado com os atributos do pipeline.

Sintaxe

DBMS_CLOUD_PIPELINE.START_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      start_date           IN   TIMESTAMP WITH TIME ZONE DEFAULT NULL
);

Parâmetros

Parâmetro Descrição
pipeline_name

Especifica um nome para o pipeline.

Este parâmetro é obrigatório.
start_date

Especifica a data inicial do job do pipeline.

Valor padrão: NULL

Observações sobre Uso

Procedimento STOP_PIPELINE

O procedimento interrompe o pipeline de dados. Quando um pipeline é interrompido, nenhum job futuro é programado para o pipeline.

Sintaxe

DBMS_CLOUD_PIPELINE.STOP_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      force                IN   BOOLEAN  DEFAULTFALSE
);

Parâmetros

Parâmetro Descrição
pipeline_name

Especifica um nome para o pipeline.

Este parâmetro é obrigatório.
force

Se o parâmetro de imposição for informado como TRUE, ele encerrará todos os jobs em execução do pipeline.

Valores válidos: TRUE, FALSE

Valor padrão: FALSE

Atributos DBMS_CLOUD_PIPELINE

Os atributos ajudam a controlar e configurar o comportamento de um pipeline de dados.

Atributos

Observação: conforme indicado na coluna Tipo de Pipeline, dependendo do tipo de pipeline LOAD ou EXPORT, um pipeline suporta outro conjunto de atributos.

Nome do Atributo Descrição Tipo de Pipeline Modificável Após o Início do Pipeline
credential_name

O nome da credencial para acessar o Cloud Object Storage de origem.

Valor padrão: NULL.

Se você não fornecer uma credential_name, a credential_name será definida como NULL.

LOAD, EXPORT Sim
field_list

Identifica os campos nos arquivos de origem e seus tipos de dados. A sintaxe desse argumento é a mesma da cláusula field_list nas tabelas externas regulares do sistema Oracle. Para obter mais informações, consulte field_list em Oracle Database 19c Utilities ou Oracle Database 26ai Utilities.

Valor padrão: NULL

O valor padrão especifica os campos e seus tipos de dados são determinados pelas colunas na tabela especificada no atributo table_name.

LOAD Sim
format

As opções que descrevem o formato do tipo de pipeline.

O Datapump format não é suportado para um pipeline de exportação.

Esse atributo é obrigatório para os pipelines LOAD e EXPORT.

LOAD, EXPORT Sim
interval

O intervalo de tempo em minutos entre execuções consecutivas do job de pipeline programado.

Valor padrão: 15 minutos

 LOAD, EXPORT Sim
key_column

Um timestamp ou coluna de data no table ou query especificado para exportar dados mais recentes continuamente para o armazenamento de objetos. O último timestamp ou data de execução é rastreado pelo pipeline de Exportação e comparado com o valor no key_column para identificar novos dados para exportação para o armazenamento de objetos.

Valor padrão: NULO

Se key_column não for especificado para um pipeline de exportação, todo o conteúdo do table ou do query será submetido a upload para o armazenamento de objetos em cada execução do job do pipeline.

EXPORT No
location

Este parâmetro especifica URI ou diretórios de arquivo de origem e arquivos de origem. Você pode usar curingas nos nomes dos arquivos.

Este parâmetro é obrigatório.

URIs de arquivo de origem na nuvem

Você pode especificar um URI de arquivo de origem para bucket ou subpasta. Você pode usar curingas para especificar subpastas ou padrões de nome de arquivo. O caractere "\*" pode ser usado como caractere curinga para vários caracteres, e o caractere "?" pode ser usado como caractere curinga para um único caractere.

Exemplo usando curingas:

location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv

O formato dos URIs depende do serviço do Cloud Object Storage que você estiver usando. Para obter detalhes, consulte Formatos do Cloud Object Storage URI.

Diretório

Você pode especificar um diretório e um nome de arquivo. O formato para especificar um diretório é 'MY_DIR:filename.ext'. Por padrão, o nome do diretório MY_DIR é um objeto de banco de dados e não faz distinção entre maiúsculas e minúsculas. O arquivo faz distinção entre maiúsculas e minúsculas.

Você só pode usar curingas para especificar nomes de arquivo em um diretório. O caractere "*" pode ser usado como caractere curinga para vários caracteres e o caractere "?" pode ser usado como caractere curinga para um único caractere.

Por exemplo: 'MY_DIR:*" ou 'MY_DIR:test?'

Use aspas duplas para especificar um nome de diretório com distinção entre maiúsculas e minúsculas.

Por exemplo: '"my_dir1":*, "my_dir2":Test?'

Para incluir um caractere de aspas, use duas aspas.

Por exemplo: 'MY_DIR:''filename.ext'. Isso especifica que o nome do arquivo começa com uma aspa (').

   
priority

Especifica um valor de string que determina o número de operações paralelas executadas para o pipeline.

  • Em um pipeline de carregamento, ele determina o número de arquivos carregados em paralelo.

  • Em um pipeline de exportação, ele determina o grau de paralelismo para extrair dados do banco de dados.

Uma operação com prioridade mais alta consome mais recursos de banco de dados e é concluída mais cedo.

Valores válidos:

  • HIGH: Determina o número de arquivos paralelos tratados usando a contagem de ECPUs do banco de dados (contagem de OCPUs se o banco de dados usar OCPUs).
  • MEDIUM: Determina o número de processos simultâneos usando o limite de simultaneidade para o serviço Medium. O valor padrão é 4.
  • LOW: Execute o job do pipeline em ordem serial.

Valor padrão: MEDIUM

O número máximo de operações simultâneas de arquivos é limitado a 64.

 LOAD, EXPORT Sim
query

Especifica uma instrução SELECT para que somente os dados necessários sejam exportados. A consulta determina o conteúdo dos arquivos exportados como arquivos de texto (CSV, JSON, Parquet ou XML) ou arquivos de dump.

Por exemplo:

SELECT warehouse_id, quantity FROM inventories;

Valor padrão: NULL

Para um pipeline de exportação, table_name ou query é obrigatório.

EXPORT No
table_name

Especifica o nome da tabela de destino para carregar ou exportar dados.

Para um pipeline de carga, o table_name é obrigatório.

Para um pipeline de exportação, table_name ou query é obrigatório.

LOAD, EXPORT No
table_owner

O nome do esquema no qual a tabela de destino reside para carregar ou exportar dados.

Valor padrão: NULL

Com um valor NULL, a tabela do alvo está no mesmo esquema que o usuário que está executando o procedimento.

LOAD, EXPORT No

Conteúdo Relacionado