Modifica ou cria um ou mais registros em uma fonte de dados ou mescla registros fora de uma fonte de dados.

Use a função Patch para modificar registros em situações complexas, como quando você executa atualizações que não exigem nenhuma interação do usuário ou que usam formulários que abrangem várias telas.

Em situações menos complexas, é possível usar o controle Editar formulário para atualizar registros em uma fonte de dados com mais facilidade. Quando você adiciona um controle Editar formulário, você fornece aos usuários um formulário a ser preenchido e salva as alterações em uma fonte de dados. Para obter mais informações, consulte Noções básicas de formulários de dados.

Visão geral

Use a função Patch para modificar um ou mais registros de uma fonte de dados. Os valores de campos específicos são modificados sem afetar outras propriedades. Por exemplo, essa fórmula altera o número de telefone de um cliente chamado Contoso:

Patch( Customers, First( Filter( Customers, Name = "Contoso" ) ), { Phone: “1-212-555-1234” } )

Use Patch com a função Padrões para criar registros. Use esse comportamento para criar uma única tela para criar e editar registros. Por exemplo, esta fórmula cria um registro para um cliente chamado Contoso:

Patch( Customers, Defaults( Customer ), { Name: “Contoso” } )

Mesmo que você não esteja trabalhando com uma fonte de dados, é possível usar Patch para mesclar dois ou mais registros. Por exemplo, esta fórmula mescla dois registros em um que identifica o número de telefone e a localização de Contoso:

Patch( { Name: "Contoso", Phone: “1-212-555-1234” }, { Name: "Contoso", Location: “Midtown” } )

Descrição

Modificar ou criar um registro em uma fonte de dados

Para usar essa função com uma fonte de dados, especifique a fonte de dados e, em seguida, especifique um registro de base:

  • Para modificar um registro, o registro de base deve ser proveniente de uma fonte de dados. O registro de base pode ter sido fornecido por meio da propriedade Itens da galeria, colocado em uma variável de contexto, ou por meio de outro caminho. Mas você deve ser capaz de rastrear o registro de base de volta para a fonte de dados. Isso é importante, pois o registro incluirá informações adicionais para ajudar a localizar o registro novamente para modificação.

  • Para criar um registro, use a função Padrões para criar um registro de base com valores padrão.

Em seguida, especifique um ou mais registros de alteração, cada um deles contém novos valores de propriedade que substituem os valores de propriedade do registro de base. Registros de alteração são processados na ordem do início da lista de argumentos para o final, com valores de propriedade mais atuais substituindo os mais antigos.

O valor retornado de Patch é o registro modificado ou criado. Se você criou um registro, o valor retornado pode incluir propriedades de fonte de dados gerou automaticamente.

Quando você atualiza uma fonte de dados, um ou mais problemas podem ocorrer. Use a função Erros para identificar e examinar problemas, como descrito em Trabalhando com fontes de dados.

Funções relacionadas incluem a função Atualizar, que você pode usar para substituir um registro inteiro, e a função Coletar, que pode ser usada para criar um registro. Você pode usar a função AtualizarSe para modificar propriedades específicas de vários registros com base em uma condição.

Modificar ou criar um conjunto de registros em uma fonte de dados

Patch também pode ser usado para criar ou modificar vários registros com uma única chamada.

Em vez de passar um único registro de base, uma tabela de registros de base pode ser fornecida no segundo argumento. Registros de alteração também são fornecidos em uma tabela, com correspondência de um para um com os registros de base. O número de registros em cada tabela de alteração deve ser igual ao número de registros na tabela de base.

Ao usar Patch dessa maneira, o valor retornado também é uma tabela com cada registro com correspondência de um para um com os registros de base e alteração.

Mesclar registros fora de uma fonte de dados

Especifique dois ou mais registros que deseja mesclar. Registros são processados na ordem do início da lista de argumentos para o final, com valores de propriedade mais atuais substituindo os mais antigos.

Patch retorna o registro mesclado e não modifica os argumentos nem os registros de nenhuma fonte de dados.

Sintaxe

Modificar ou criar um registro em uma fonte de dados

Patch( DataSource, BaseRecord, ChangeRecord1 [, ChangeRecord2, … ])

  • DataSource – Obrigatório. A fonte de dados que contém o registro que deseja modificar ou conterá o registro que deseja criar.

  • BaseRecord – Obrigatório. O registro a ser modificado ou criado. Se o registro for proveniente de uma fonte de dados, ele será encontrado e modificado. Se o resultado de Padrões for usado, um registro será criado.

  • ChangeRecord(s) – Obrigatório. Um ou mais registros que contêm propriedades para modificar no BaseRecord. Registros de alteração são processados na ordem do início da lista de argumentos para o final, com valores de propriedade mais atuais substituindo os mais antigos.

Modificar ou criar um conjunto de registros em uma fonte de dados

Patch( DataSource, BaseRecordsTable, ChageRecordTable1, [, ChangeRecordTable2, … ] )

  • DataSource – Obrigatório. A fonte de dados que contém os registros que deseja modificar ou conterá os registros que deseja criar.

  • BaseRecordTable – Obrigatório. Uma tabela de registros a ser modificada ou criada. Se o registro for proveniente de uma fonte de dados, ele será encontrado e modificado. Se o resultado de Padrões for usado, um registro será criado.

  • ChangeRecordTable(s) – Obrigatório. Uma ou mais tabelas de registros que contêm propriedades para modificar para cada registro do BaseRecordTable. Registros de alteração são processados na ordem do início da lista de argumentos para o final, com valores de propriedade mais atuais substituindo os mais antigos.

Mesclar registros

Patch( Record1, Record2 [, …] )

  • Registros – Obrigatório. Pelo menos, dois registros que você deseja mesclar. Registros são processados na ordem do início da lista de argumentos para o final, com valores de propriedade mais atuais substituindo os mais antigos.

Exemplos

Modificar ou criar um registro (em uma fonte de dados)

Nesses exemplos, você modificará ou criará um registro em uma fonte de dados chamado IceCream, que contém os dados nessa tabela e gera automaticamente os valores da coluna ID:

Fórmula Descrição Resultado
Patch( IceCream,
First( Filter( IceCream, Flavor = "Chocolate" ) ), { Quantity: 400 } )		 Modifica um registro na fonte de dados IceCream:
  • A coluna ID do registro a ser modificado contém o valor de 1. (O registro Chocolate tem essa ID.)
  • O valor na coluna Quantidade é alterado para 400.
 { ID: 1, Flavor: "Chocolate", Quantity: 400 }

A entrada Chocolate da fonte de dados IceCream foi modificada.
Patch( IceCream, Defaults( IceCream ), { Flavor: “Strawberry” } ) Cria um registro na fonte de dados IceCream:
  • A coluna ID contém o valor 3, que a fonte de dados gera automaticamente.
  • A coluna Quantidade contém 0, que é o valor padrão para essa coluna na fonte de dados IceCream, como a função Padrões especifica.
  • A coluna Flavor contém o valor de Strawberry.
 { ID: 3, Flavor: “Strawberry”, Quantity: 0 }

A entrada Strawberry da fonte de dados IceCream foi criada.

Depois de as fórmulas anteriores terem sido avaliadas, a fonte de dados termina com estes valores:

Mesclar registros (fora de uma fonte de dados)

Fórmula Descrição Resultado
Patch( { Name: "James", Score: 90 }, { Name: "Jim", Passed: true } ) Mesclar dois registros fora de uma fonte de dados:
  • Os valores na coluna Nome de cada registro não correspondem. O resultado contém o valor (Jim) no registro que esteja mais próximo ao final da lista de argumentos em vez do valor (James) no registro que esteja mais próximo do início.
  • O primeiro registro contém uma coluna (Score) que não existe no segundo registro. O resultado contém essa coluna com seu valor (90).
  • O segundo registro contém uma coluna (Passed) que não existe no primeiro registro. O resultado contém essa coluna com seu valor (true).
 { Name: "Jim", Score: 90, Passed: true }