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.

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