Pacote DBMS_CLOUD_PIPELINE

O pacote DBMS_CLOUD_PIPELINE permite criar 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.

Tópicos Relacionados

Pré-requisitos

Como desenvolvedor, você pode usar procedimentos DBMS_CLOUD com Autonomous Databases implantados no 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 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 Rede Virtual na Nuvem (VCN) em que seus recursos do Autonomous 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 de roteamento e uma regra de segurança de saída a cada sub-rede (na VCN) na qual os recursos do Autonomous Database residem para que esses recursos possam usar o gateway para obter uma chave pública da sua instância do Azure AD:
    1. Vá para a página Detalhes da Sub-rede da sub-rede.
    2. Na guia Informações da Sub-rede, clique no nome da Tabela de Rota da sub-rede para exibir sua respectiva página Detalhes da Tabela de Rota.
    3. Na tabela de Regras de Roteamento existentes, verifique se já existe uma regra com as seguintes características:
      • Destino: 0.0.0.0/0
      • Tipo de Destino: Gateway NAT
      • Alvo: O nome do gateway NAT recém-criado na VCN

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

    4. Retorne à página Detalhes da Sub-rede da sub-rede.
    5. Na tabela Listas de Segurança da sub-rede, clique no nome da lista de segurança da sub-rede para exibir a 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
      • Faixa de Portas de Destino: Todas

      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. Depois de ativado, você não poderá 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 de 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 redefinir pipeline para reiniciar o pipeline a partir do estado inicial da carga de dados ou exportação. 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 de 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 for 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 SQL da Oracle. Consulte Identificadores em Referência de Linguagem PL/SQL do Oracle Database Database ou Referência de Linguagem PL/SQL do Oracle Database 23ai Database para obter mais informações.

Esse parâmetro é obrigatório.

pipeline_type

Especifica o tipo de pipeline.

Valores válidos: LOAD, EXPORT

Esse parâmetro é obrigatório.

attributes

Atributos de pipeline no formato JSON.

Valor padrão: NULL

Consulte DBMS_CLOUD_PIPELINE Atributos 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 para poder 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.

Esse 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

  • Para eliminar um pipeline que está no estado iniciado, defina o parâmetro force como TRUE.

Procedimento RESET_PIPELINE

Redefine o estado de rastreamento de um pipeline de dados. Use redefinir pipeline para reiniciar o pipeline a partir do estado inicial da carga de dados ou exportação. 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.

Esse parâmetro é obrigatório.

purge_data

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

  • Para um pipeline de carga, quando TRUE, trunque os dados na tabela de 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

  • Um pipeline de dados deve estar no estado interrompido para redefini-lo. Consulte STOP_PIPELINE Procedimento para obter mais informações.

  • Para um pipeline de carga, a redefinição do pipeline limpa o registro dos arquivos que estão sendo carregados pelo pipeline. Quando você chama START_PIPELINE ou RUN_PIPELINE_ONCE após redefinir um pipeline de carga, o pipeline repete a carga de dados e inclui todos os arquivos presentes no local de armazenamento de objetos.

    Quando purge_data é definido como TRUE, DBMS_CLOUD_PIPELINE.RESET_PIPELINE faz o seguinte:

    • Trunca os dados na tabela de banco de dados do pipeline especificada com o atributo table_name.

    • Elimina a tabela de status do pipeline, a tabela de arquivos inválidos e a tabela de erros do pipeline (se existirem).

  • Para um pipeline de exportação, a redefinição do pipeline limpa os últimos dados rastreados na tabela do banco de dados. Quando você chama START_PIPELINE ou RUN_PIPELINE_ONCE após redefinir um pipeline de exportação, o pipeline repete a exportação de dados da tabela ou da consulta.

    Quando purge_data é definido como TRUE, DBMS_CLOUD_PIPELINE.RESET_PIPELINE exclui arquivos existentes no local de armazenamento de objetos especificado com o atributo location.

Procedimento RUN_PIPELINE_ONCE

Este procedimento executa uma execução sob demanda do pipeline na sessão de 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.

Esse parâmetro é obrigatório.

Observações sobre Uso

  • Depois de executar uma execução de teste de um pipeline, você poderá redefinir o estado do pipeline usando DBMS_CLOUD_PIPELINE.RESET_PIPELINE. Isso permite redefinir o estado do pipeline antes de iniciar o pipeline em um job programado.

  • Se um pipeline estiver no estado iniciado, ele não poderá ser executado na sessão em primeiro plano.

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 definir atributos.

Esse parâmetro é obrigatório.

attribute_name

Especifica o nome do atributo a ser definido.

Consulte DBMS_CLOUD_PIPELINE Atributos para obter mais informações.

attribute_value

Especifica o valor do atributo do pipeline a ser definido.

Consulte DBMS_CLOUD_PIPELINE Atributos para obter mais informações.

attributes

Especifica um documento JSON contendo nomes e valores de atributos.

Consulte DBMS_CLOUD_PIPELINE Atributos 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 de pipeline é executada continuamente em um job programado de acordo com o interval configurado com os atributos de 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.

Esse parâmetro é obrigatório.

start_date

Especifica a data inicial do job de pipeline.

Valor padrão: NULL

Observações sobre Uso

  • Por padrão, um job de pipeline começa imediatamente, assim que o pipeline é iniciado. Para iniciar um job de pipeline posteriormente, especifique uma data ou um timestamp válido usando o parâmetro start_date.

  • Consulte Atributos DBMS_CLOUD_PIPELINE para obter informações sobre o pipeline interval e outros atributos de pipeline.

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.

Esse parâmetro é obrigatório.

force

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

Valores válidos: TRUE, FALSE

Valor padrão: FALSE

DBMS_CLOUD_PIPELINE Atributos

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 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 um credential_name, credential_name será definido 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 23ai 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

Uma coluna de timestamp ou 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 em 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 de table ou query será submetido a upload para o armazenamento de objetos em cada execução de job de 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 carga, 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 seu banco de dados usar OCPUs).
  • MEDIUM: Determina o número de processos simultâneos usando o limite de simultaneidade para o serviço Médio. 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 de arquivo simultâneas é limitado a 64.

 LOAD, EXPORT Sim
query

Especifica uma instrução SELECT para que apenas 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, 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 em que a tabela de destino reside para carregar ou exportar dados.

Valor padrão: NULL

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

LOAD, EXPORT No