Ir para o conteúdo

Atividade de Upsert de Banco de Dados

Introdução

Uma atividade de Upsert de Banco de Dados, utilizando sua conexão de Banco de Dados, atualiza dados existentes e insere novos dados em um banco de dados configurado, sendo destinada a ser usada como um alvo para consumir dados em uma operação.

A atividade de Upsert é utilizada para atualizar registros que já existem e criar aqueles que não existem. Se, em vez disso, você deseja apenas inserir novos registros, utilize uma atividade de Inserir em Banco de Dados, ou se você deseja atualizar registros existentes, utilize uma atividade de Atualizar em Banco de Dados.

Criar uma Atividade de Upsert de Banco de Dados

Uma instância de uma atividade de Upsert de Banco de Dados é criada a partir de uma conexão de Banco de Dados usando seu tipo de atividade Upsert.

Para criar uma instância de uma atividade, arraste o tipo de atividade para a tela de design ou copie o tipo de atividade e cole-o na tela de design. Para detalhes, veja Criar uma instância de atividade ou ferramenta em Reutilização de Componentes.

Uma atividade de Upsert de Banco de Dados existente pode ser editada a partir destes locais:

Configurar uma Atividade de Upsert de Banco de Dados

Siga estas etapas para configurar uma atividade de Upsert de Banco de Dados:

Upsert de objeto único

Siga estas etapas se o upsert do banco de dados for para um único objeto e você não precisar criar nenhuma junção com outros objetos. Se precisar juntar múltiplos objetos, consulte em vez disso Upsert de múltiplos objetos.

Etapa 1: Insira um nome e selecione um objeto

  • Nome: Insira um nome para identificar a atividade do Banco de Dados. O nome deve ser exclusivo para cada atividade de Upsert do Banco de Dados e não deve conter barras (/) ou dois pontos (:).

  • Forneça a referência dos nomes das tabelas: Esta seção exibe as tabelas disponíveis no endpoint do Banco de Dados usando quaisquer filtros aplicados, após usar o ícone de atualização para o carregamento inicial dos objetos. Se houver um grande número de objetos no banco de dados, recomenda-se filtrar os objetos usando Visualizar ou Pesquisar antes de atualizar.

    • Visualizar: Use o menu suspenso para filtrar a lista de objetos exibidos para um dos "Tabelas, Visualizações", "Tabelas", "Visualizações", ou "Tabelas do Sistema". Por padrão, a visualização "Tabelas, Visualizações" é mostrada.

    • Pesquisar: Insira o valor de qualquer coluna na caixa de pesquisa para filtrar a lista de objetos. A pesquisa não diferencia maiúsculas de minúsculas. A lista de objetos pode ser filtrada automaticamente ou pode ser necessário atualizar a lista, dependendo se os objetos já foram recuperados:

      • Se estiver pesquisando em objetos que já foram recuperados do banco de dados e já aparecem na lista, quaisquer termos de pesquisa digitados na caixa de pesquisa filtram automaticamente a lista.

  • Se estiver pesquisando em objetos que ainda não foram recuperados, por exemplo, ao tentar limitar o número de objetos recuperados para bancos de dados com um grande número de objetos, use o ícone de atualização ao lado da caixa de pesquisa para buscar os objetos do banco de dados usando o filtro.

    !!! note "Nota"
    Para bancos de dados que não suportam pesquisa em objetos, como o Microsoft Access, nenhum resultado é retornado.

  • Atualizar: Clique no ícone de atualização para carregar ou recarregar tabelas do endpoint do Banco de Dados. Isso deve ser usado para o carregamento inicial de quaisquer objetos. Além disso, pode ser útil se você adicionou recentemente objetos ao banco de dados ou se você tem critérios de pesquisa adicionais que deseja aplicar antes de recuperar objetos do banco de dados.

  • Permitir truncamento de campos de caracteres para evitar erros de comprimento de campo: Selecione esta caixa de seleção para permitir que os campos sejam truncados conforme necessário se o campo de destino for menor que o campo de origem. Ela não está selecionada por padrão para novas atividades criadas após o lançamento do Harmony 11.39. Quando esta caixa de seleção é deixada desmarcada e dados excessivos passam, um status de operação Erro é relatado. Se a caixa de seleção estiver marcada, um status de Sucesso com Informação é relatado em vez disso, e os logs de operação dirão que Um ou mais valores foram truncados ao inserir e/ou atualizar o campo.

  • Incluir o esquema/proprietário nos nomes das tabelas: Selecione esta caixa de seleção para incluir o esquema nos nomes das tabelas. Isso pode ser útil se você usar o mesmo nome de tabela em vários esquemas (como para desenvolvimento e produção) para permitir que você veja e selecione a tabela no esquema correto.

  • Fornecer a referência dos nomes das tabelas: A lista de objetos é exibida em uma coluna à esquerda. Clique em um único objeto para adicioná-lo à tabela à direita. Se você estiver atualizando ou inserindo em múltiplos objetos que precisam ser unidos, consulte Inserção em Múltiplos Objetos.

    !!! tip "Dica"
    Se a lista não for preenchida com objetos disponíveis mesmo após aplicar um filtro, a [conexão com o banco de dados](/pt/integration-studio/design/connectors/database/database-connection) pode não ter sido bem-sucedida. Certifique-se de que você está conectado reabrindo a conexão e testando novamente as credenciais.
    • Tabela de objetos selecionados: O objeto selecionado é exibido em uma tabela à direita. As colunas desta tabela não são relevantes para Upserts de objeto único ou upserts e não podem ser editadas.

  • Salvar e Sair: Se habilitado, clique para salvar a configuração para esta etapa e fechar a configuração da atividade.

  • Próximo: Clique para armazenar temporariamente a configuração para esta etapa e continuar para a próxima etapa. A configuração não será salva até que você clique no botão Concluído na última etapa.

  • Descartar Alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em qualquer etapa. Uma mensagem pede que você confirme que deseja descartar as alterações.

Etapa 2: Selecionar chaves de upsert

  • Selecionar chaves: Selecione as caixas de seleção de quaisquer campos que você deseja usar como chaves de Upsert. Você também pode selecionar um objeto inteiro para selecionar todos os seus campos de uma vez. A(s) chave(s) de Upsert são o(s) campo(s) usados para identificar quais registros existentes precisam ser Upsertados. Quaisquer campos que forem selecionados para serem usados como chaves de Upsert são listados à direita.

  • Voltar: Clique para armazenar temporariamente a configuração para esta etapa e retornar à etapa anterior.

  • Próximo: Clique para armazenar temporariamente a configuração para esta etapa e continuar para a próxima etapa. A configuração não será salva até que você clique no botão Concluído na última etapa.

  • Descartar Alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em qualquer etapa. Uma mensagem pede que você confirme que deseja descartar as alterações.

Etapa 3: Revisar o esquema de dados

  • Esquema de Dados: O esquema de dados de destino é exibido. Se a operação usar uma transformação, os esquemas de dados serão exibidos novamente mais tarde durante o processo de mapeamento de transformação, onde você pode mapear para campos de destino usando objetos de origem, scripts, variáveis, valores personalizados e mais.

    Nota

    Os dados são transferidos conforme fornecidos. Se houver discrepâncias no comprimento dos dados entre os campos de origem e destino, você pode usar Funções de String para ajustar os dados.

    Nota

    Para atualizar um esquema de dados em uma atividade existente, você deve avançar por cada etapa de configuração da atividade novamente, fazendo pelo menos uma alteração (como adicionar e remover um caractere do final do nome da atividade) para forçar uma atualização do esquema.

  • Voltar: Clique para armazenar temporariamente a configuração desta etapa e retornar à etapa anterior.

  • Concluído: Clique para salvar a configuração de todas as etapas e fechar a configuração da atividade.

  • Descartar Alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em qualquer etapa. Uma mensagem solicita que você confirme que deseja descartar as alterações.

Upsert de múltiplos objetos

Siga estas etapas se o upsert do banco de dados ou upsert for para múltiplos objetos e você precisar criar junções entre eles. Para upsert ou upsert apenas para um único objeto, sem junções, consulte Upsert de objeto único.

Etapa 1: Insira um nome e selecione objetos

  • Nome: Insira um nome para identificar a atividade do Banco de Dados. O nome deve ser exclusivo para cada atividade de Upsert do Banco de Dados e não deve conter barras (/) ou dois-pontos (:).

  • Forneça a referência dos nomes das tabelas: Esta seção exibe as tabelas disponíveis no endpoint do Banco de Dados usando quaisquer filtros aplicados, após usar o ícone de atualizar para o carregamento inicial dos objetos. Se houver um grande número de objetos no banco de dados, é recomendável filtrar os objetos usando Visualizar ou Pesquisar antes de atualizar.

  • Visualizar: Use o menu suspenso para filtrar a lista de objetos exibidos para um dos "Tabelas, Visualizações", "Tabelas", "Visualizações", ou "Tabelas do Sistema". Por padrão, a visualização "Tabelas, Visualizações" é exibida.

  • Pesquisar: Insira o valor de qualquer coluna na caixa de pesquisa para filtrar a lista de objetos. A pesquisa não diferencia maiúsculas de minúsculas. A lista de objetos pode ser filtrada automaticamente ou pode ser necessário atualizar a lista, dependendo se os objetos já foram recuperados:

    • Se a pesquisa for em objetos que já foram recuperados do banco de dados e já aparecem na lista, qualquer termo de pesquisa digitado na caixa de pesquisa filtra automaticamente a lista.

    • Se a pesquisa for em objetos que ainda não foram recuperados, por exemplo, ao tentar limitar o número de objetos recuperados para bancos de dados com um grande número de objetos, use o ícone de atualizar ao lado da caixa de pesquisa para buscar os objetos do banco de dados usando o filtro.

    Nota

    Para bancos de dados que não suportam pesquisa em objetos, como o Microsoft Access, nenhum resultado é retornado.

  • Atualizar: Clique no ícone de atualizar para carregar ou recarregar tabelas do endpoint do Banco de Dados. Isso deve ser usado para o carregamento inicial de quaisquer objetos. Além disso, pode ser útil se você adicionou recentemente objetos ao banco de dados ou se você tem critérios de pesquisa adicionais que deseja aplicar antes de recuperar objetos do banco de dados.

  • Permitir truncamento de campos de caracteres para evitar erros de comprimento de campo: Selecione esta caixa de seleção para permitir que os campos sejam truncados conforme necessário se o campo de destino for menor que o campo de origem. Ela está desmarcada por padrão. Quando esta caixa de seleção é deixada desmarcada e dados excessivos passam, um status de Erro é exibido. Se a caixa de seleção estiver marcada, um status de Sucesso com Informação é exibido em vez disso, e os logs de operação dirão que Um ou mais valores foram truncados ao inserir e/ou atualizar o campo.

  • Incluir o esquema/proprietário nos nomes das tabelas: Selecione esta caixa de seleção para incluir o esquema nos nomes das tabelas. Isso pode ser útil se você usar o mesmo nome de tabela em vários esquemas (como para desenvolvimento e produção) para permitir que você veja e selecione a tabela no esquema correto.

  • Fornecer a referência dos nomes das tabelas: A lista de objetos é exibida em uma coluna à esquerda. Clique nos objetos um de cada vez para adicioná-los à tabela à direita. Qualquer combinação de tabelas, visualizações e/ou tabelas de sistema pode ser selecionada. Se você precisar fazer um Upsert de um único objeto sem junções, consulte em vez disso Upsert de objeto único.

    !!! tip "Dica"
    Se a lista não for preenchida com objetos disponíveis mesmo após aplicar um filtro, a [Conexão com o banco de dados](/pt/integration-studio/design/connectors/database/database-connection) pode não ter sido bem-sucedida. Certifique-se de que você está conectado reabrindo a conexão e testando novamente as credenciais.

  • Tabela de objetos selecionados: Os objetos selecionados são exibidos em uma tabela à direita. Cada coluna é detalhada abaixo:

    • Tabela: O nome do objeto selecionado, uma tabela, visualização ou tabela de sistema.

      Nota

      Nomes de tabelas com caracteres especiais, como +, não são suportados com esta atividade.

    • Pai: Em cada objeto filho que está sendo unido, use o menu suspenso para selecionar o nome do objeto que deve ser o pai. Isso é necessário para garantir a integridade transacional de um objeto, bem como para derivar a(s) chave(s) de link para um objeto filho.

    • Tipo de Junção: Em cada objeto filho que está sendo unido, um menu suspenso fica disponível após você ter atribuído Chaves de Link (coberto a seguir). Use o menu suspenso para definir o tipo de relacionamento entre os objetos selecionados:

      • Um ou Mais: Este tipo de junção requer que cada registro pai tenha pelo menos 1 registro filho e possivelmente mais registros filhos.

      • Apenas Um: Este tipo de junção requer que cada registro pai tenha 1 e apenas 1 registro filho.

        • Zero ou Mais: Este tipo de junção permite que cada registro pai tenha 0 ou mais registros filhos.

        • Zero ou Um: Este tipo de junção permite que cada registro pai tenha 0 registros filhos ou apenas 1 registro filho.

      • Chaves de Link: Em cada objeto filho que está sendo unido, uma vez que um objeto é selecionado como Pai, um link vermelho Atribuir aparece dentro deste campo. Clique em Atribuir para abrir uma janela separada onde você atribui as chaves de link.

        • Objeto pai: O objeto pai e a lista de campos são exibidos na coluna da esquerda. Quaisquer campos usados como chaves primárias dentro do banco de dados são indicados por um ícone de chave . Se você tiver um grande número de campos, pode usar a caixa de pesquisa para filtrar os campos pelo nome.

        • Objeto filho: O objeto filho e a lista de campos são exibidos na coluna da direita. Se você tiver um grande número de campos, pode usar a caixa de pesquisa para filtrar os campos pelo nome.

        • Atribuir chave(s) de link: Para atribuir um campo como uma chave de link, arraste um campo do objeto pai à esquerda para um campo dentro do objeto filho à direita, ou vice-versa. Para atribuir várias chaves de link, repita este processo.

        • Desatribuir chave(s) de link: Para desatribuir chaves de link, clique em qualquer campo que já tenha sido vinculado. Os campos vinculados ficam desmarcados.

        • Começar de novo: Para limpar todas as chaves de link atribuídas, clique em Começar de novo localizado abaixo da lista de pais à esquerda.

        • Concluir: Clique em Concluir para salvar as chaves de link atribuídas e fechar a janela. Sob Chaves de Link, você deve agora ver o número de chaves de link atribuídas, que você pode clicar para reabrir a janela de atribuição de chaves de link. Além disso, o dropdown Tipo de Junção se torna disponível para você definir o tipo de relacionamento (cardinalidade) entre os objetos selecionados.

      • Remover: Para remover um objeto selecionado da tabela, passe o mouse sobre a coluna mais à direita e clique no ícone de remover .

  • Salvar & Sair: Se habilitado, clique para salvar a configuração para esta etapa e fechar a configuração da atividade.

  • Próximo: Clique para armazenar temporariamente a configuração desta etapa e continuar para a próxima etapa. A configuração não será salva até que você clique no botão Concluído na última etapa.

  • Descartar Alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em qualquer etapa. Uma mensagem pede para você confirmar que deseja descartar as alterações.

Etapa 2: Selecionar chaves de upsert

  • Selecionar chaves: Selecione as caixas de seleção de quaisquer campos que você deseja usar como chaves de Upsert. Você também pode selecionar um objeto inteiro para selecionar todos os seus campos de uma vez. A(s) chave(s) de Upsert são o(s) campo(s) usados para identificar quais registros existentes precisam ser Upsertados. Quaisquer campos que forem selecionados para serem usados como chaves de Upsert são listados à direita.

  • Voltar: Clique para armazenar temporariamente a configuração desta etapa e retornar à etapa anterior.

  • Próximo: Clique para armazenar temporariamente a configuração desta etapa e continuar para a próxima etapa. A configuração não será salva até que você clique no botão Concluído na última etapa.

  • Descartar Alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em qualquer etapa. Uma mensagem pede para você confirmar que deseja descartar as alterações.

Etapa 3: Revisar o esquema de dados

  • Esquema de Dados: O esquema de dados de destino é exibido. Se a operação usar uma transformação, os esquemas de dados serão exibidos novamente mais tarde durante o processo de mapeamento de transformação, onde você pode mapear para campos de destino usando objetos de origem, scripts, variáveis, valores personalizados e mais.

    Nota

    Para atualizar um esquema de dados em uma atividade existente, você deve avançar por cada etapa de configuração da atividade novamente, fazendo pelo menos uma alteração (como adicionar e remover um caractere do final do nome da atividade) para forçar uma atualização do esquema.

  • Voltar: Clique para armazenar temporariamente a configuração desta etapa e retornar à etapa anterior.

  • Finalizado: Clique para salvar a configuração de todas as etapas e fechar a configuração da atividade.

  • Descartar Alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em qualquer etapa. Uma mensagem solicita que você confirme que deseja descartar as alterações.

Próximas etapas

Após configurar uma atividade de Upsert de Banco de Dados, você pode usá-la dentro de uma operação ou script, conforme descrito abaixo.

Completar a operação

Após configurar uma atividade de Upsert de Banco de Dados, complete a configuração da operação adicionando e configurando outras atividades ou ferramentas como etapas da operação. Você também pode configurar as definições da operação, que incluem a capacidade de encadear operações que estão no mesmo ou em diferentes fluxos de trabalho.

As ações do menu para uma atividade estão acessíveis a partir do painel do projeto e da tela de design. Para detalhes, veja o menu de ações da atividade em Conceitos básicos do conector.

Atividades de Upsert de Banco de Dados podem ser usadas como um alvo com esses padrões de operação:

Outros padrões não são válidos usando atividades de Upsert de Banco de Dados. Veja os padrões de validação na página de Validade da operação.

Dentro de uma transformação, se usar a opção de espelhar um esquema fornecida por uma atividade de Banco de Dados usando uma única tabela (sem junções), o esquema espelhado resultante é criado automaticamente com um nó adicional chamado row. Quando os campos dentro deste nó adicional são mapeados, o nó se torna um nó de loop para permitir que todos os registros sejam percorridos (veja Nódulos de loop sob Estruturas de dados).

Além disso, ao juntar tabelas de banco de dados, observe que os valores dos campos unidos de uma tabela filha são definidos como os valores dos campos unidos da tabela pai. Os campos unidos de uma tabela filha não podem ser mapeados.

Quando estiver pronto, implante e execute a operação e valide o comportamento verificando os logs da operação.

Use atividades de banco de dados em scripts

Atividades de Upsert de banco de dados também podem ser referenciadas em um script para uso com funções de script que utilizam um target de banco de dados como parâmetro, incluindo estas:

  • DBLoad
  • DBWrite

Para mais detalhes sobre como referenciar atividades em scripts, veja Endpoints em Jitterbit Script.

Além disso, você pode ser capaz de usar funções adicionais de banco de dados na transformação. Por exemplo, ao mapear para um target de banco de dados, se você tiver um target de múltiplas tabelas com relacionamentos pai-filho e estiver atualizando ou fazendo upsert de dados, pode usar as funções de transformação <SQLIDENTITY> e <SEQUENCE>.

  • <SQLIDENTITY> é usado para todos os bancos de dados que não são Oracle e que suportam chaves de identidade ou geração automática de números. Após a inserção do pai, o filho pode herdar o número gerado do pai mapeando esta função para a chave estrangeira na tabela filha.
  • <SEQUENCE> realiza uma ação semelhante com bancos de dados Oracle.

Use chunking

Ao usar chunking em uma operação onde o target é uma atividade de banco de dados, observe que os dados do target são primeiro gravados em vários arquivos temporários (um para cada chunk). Esses arquivos são então combinados em um único arquivo de target, que é enviado ao banco de dados para inserção/Upsert.

Se você definir a variável Jitterbit jitterbit.target.db.commit_chunks como 1 ou true quando o chunking estiver habilitado, cada chunk será comprometido ao banco de dados assim que estiver disponível. Isso pode melhorar significativamente o desempenho, pois as inserções/Upserts no banco de dados são realizadas em paralelo.

Para instruções e melhores práticas sobre o uso de chunking, consulte Opções de operação.