AddColumns, DropColumns, RenameColumnse ShowColumns funções

Aplica-se a: Aplicativos de tela Copilot Studio Desktop flui aplicativos baseados em modelo funções do Power Platform CLI Dataverse

Forma uma tabela ou registro adicionando, soltando, renomeando e selecionando suas colunas.

A função ForAll também pode ser usada para formatar uma tabela, retornando uma tabela de novos registros criados a partir de colunas existentes.

Visão geral

Essas funções moldam uma tabela ou registro ajustando suas colunas:

• Reduza uma tabela ou registro que contenha várias colunas até uma única coluna para uso com funções de coluna única, como Lower ou Sqrt.
• Adicione uma coluna calculada a uma tabela ou registro (por exemplo, uma coluna preço total que mostra os resultados da multiplicação da quantidade por preço unitário).
• Renomeie uma coluna para algo mais significativo, para exibir aos usuários ou para uso em fórmulas.

Uma tabela é um valor no Power Apps, assim como uma cadeia de caracteres ou um número. É possível especificar uma tabela como um argumento em uma fórmula e funções podem retornar uma tabela como resultado.

Você não pode modificar as colunas de uma fonte de dados usando essas funções. Você deve modificar os dados em sua origem. Você pode adicionar colunas a uma coleção com a função Collect. Para obter mais informações, consulte Como trabalhar com fontes de dados.

Description

A AddColumns função adiciona uma coluna a uma tabela ou registro e uma fórmula define os valores nessa coluna. As colunas existentes permanecem inalteradas.

A fórmula é avaliada para o registro fornecido ou para cada registro da tabela fornecida.

Os campos do registro que está sendo processado no momento estão disponíveis na fórmula. Use o operador ThisRecord ou simplesmente referencie os campos por nome como faria com qualquer outro valor. O operador Astambém pode ser usado para nomear o registro que está sendo processado, o que pode ajudar a tornar sua fórmula mais fácil de entender e tornar os registros aninhados acessíveis. Para obter mais informações, veja os exemplos abaixo e consulte trabalhando com escopo de registros.

A DropColumns função exclui colunas de uma tabela ou registro. Todas as outras colunas permanecem inalteradas. DropColumns exclui colunas e ShowColumns inclui colunas.

Use a RenameColumns função para renomear uma ou mais colunas de uma tabela ou registro fornecendo pelo menos um par de argumentos que especifica o nome de uma coluna que a tabela ou registro contém (o nome antigo, que você deseja substituir) e o nome de uma coluna que a tabela ou registro não contém (o novo nome, que você deseja usar). O nome antigo já deve existir na tabela ou registro e o novo nome não deve existir. Cada nome de coluna pode aparecer apenas uma vez na lista de argumentos como um nome de coluna antigo ou um novo nome de coluna. Para renomear uma coluna para um nome de coluna existente, primeiro solte a coluna existente com DropColumns, ou renomeie a coluna existente fora do caminho aninhando uma RenameColumns função dentro de outra.

A ShowColumns função inclui colunas de uma tabela ou registro e descarta todas as outras colunas. Você pode usar ShowColumns para criar uma tabela de coluna única ou um registro de uma tabela ou registro de várias colunas. ShowColumns inclui colunas e DropColumns exclui colunas.

Para todas essas funções, o resultado é uma nova tabela ou registro com a transformação aplicada. A tabela ou o registro original não é modificado. Você não pode modificar uma tabela ou registro existente com uma fórmula. O SharePoint, o Microsoft Dataverse, o SQL Server e outras fontes de dados fornecem ferramentas para modificar as colunas de listas e tabelas, que geralmente são conhecidas como o esquema. As funções neste tópico transformam apenas uma tabela ou registro de entrada, sem modificar o original, em uma tabela de saída ou registro para uso adicional.

Os argumentos para essas funções oferecem suporte à delegação. Por exemplo, uma função Filter usada como um argumento para realizar pull de registros relacionados pesquisa todas as listagens, mesmo que a fonte de dados '[dbo].[AllListings]' contém um milhão de linhas:

AddColumns( RealEstateAgents,
   Listings,
   Filter(  '[dbo].[AllListings]', ListingAgentName = AgentName )
)

No entanto, a saída dessas funções está sujeita ao limite de registro de não delegação. Neste exemplo, somente registros 500 são retornados, mesmo se a fonte de dados RealEstateAgents tiver 501 ou mais registros.

Se você usar AddColumns dessa maneira, Filter deverá fazer chamadas separadas à fonte de dados para cada um desses primeiros registros em RealEstateAgents, o que causa muitas conversas de rede. Se [dbo](.[AllListings] for pequeno o suficiente e não muda com frequência. Você pode chamar a função Collect em OnStart para armazenar em cache a fonte de dados em seu aplicativo quando ele for iniciado. Como alternativa, você pode reestruturar seu aplicativo para extrair os registros relacionados apenas quando o usuário os solicitar.

Sintaxe

AddColumns( TableOrRecord, ColumnName1, Formula1 [, ColumnName2, Formula2, ... ] )

• TableOrRecord – Obrigatório. Tabela ou registro no qual operar.
• ColumnNames - Obrigatório. Nomes de colunas para adicionar.
• Fórmulas - Obrigatório. Fórmulas para avaliar cada registro. O resultado é adicionado como o valor da nova coluna correspondente. Você pode referenciar outras colunas da tabela ou registro nesta fórmula.

DropColumns( TableOrRecord, ColumnName1 [, ColumnName2, ... ] )

• TableOrRecord – Obrigatório. Tabela ou registro no qual operar.
• ColumnNames - Obrigatório. Nomes das colunas para remover.

RenameColumns( TableOrRecord, OldColumnName1, NewColumnName1 [, OldColumnName2, NewColumnName2, ... ] )

• TableOrRecord – Obrigatório. Tabela ou registro no qual operar.
• OldColumnNames - Obrigatório. Nomes das colunas a serem renomeadas da tabela ou registro original. Esse elemento aparece primeiro no par de argumentos (ou primeiro em cada par de argumentos se a fórmula contiver mais de um par).
• NewColumnNames - Obrigatório. Nomes de substituição. Esse elemento aparece por último no par de argumentos (ou por último em cada par de argumentos se a fórmula contiver mais de um par).

ShowColumns( TableOrRecord, ColumnName1 [, ColumnName2, ... ] )

• TableOrRecord – Obrigatório. Tabela ou registro no qual operar.
• ColumnNames - Obrigatório. Nomes das colunas a serem incluídas.

Exemplos

Os exemplos desta seção usam a fonte de dados IceCreamSales que contém os seguintes dados nesta tabela:

Nenhum desses exemplos modificam a fonte de dados IceCreamSales. Cada função transforma o valor da fonte de dados em uma tabela e retorna esse valor como resultado.

Fórmula	Description	Result
AddColumns( IceCreamSales, Revenue, UnitPrice * QuantitySold )	Adiciona uma coluna Receita no resultado. Para cada registro, UnitPrice * QuantitySold são avaliados e o resultado é colocado na nova coluna.
DropColumns( IceCreamSales, UnitPrice )	Exclui a coluna UnitPrice do resultado. Use essa função para excluir colunas e use ShowColumns para incluí-las.
ShowColumns( IceCreamSales, Flavor )	Inclui somente a coluna Flavor no resultado. Use essa função para incluir colunas e use DropColumns para excluí-las.
RenameColumns( IceCreamSales, UnitPrice, Price)	Renomeie a coluna PreçoUnitário no resultado.
RenameColumns( IceCreamSales, UnitPrice, Price, QuantitySold, Number)	Renomeia as colunas UnitPrice e QuantitySold no resultado.
DropColumns( RenameColumns( AddColumns( IceCreamSales, Receita, UnitPrice * QuantitySold ), UnitPrice, Price ), Quantidade )	Executa as seguintes transformações de tabela em ordem, começando por essa fórmula: Adiciona uma coluna Receita com base no cálculo por registro de UnitPrice * Quantity. Renomeia UnitPrice para Price. Exclui a coluna Quantity. A ordem é importante, por exemplo, não podemos calcular com UnitPrice depois que ela for renomeada.

Passo a passo

Vamos experimentar alguns dos exemplos anteriores neste artigo.

1. Crie uma coleção adicionando um controle Button e definindo sua propriedade OnSelect com esta fórmula:

   ClearCollect( IceCreamSales,
      Table(
          { Flavor: "Strawberry", UnitPrice: 1.99, QuantitySold: 20 },
          { Flavor: "Chocolate", UnitPrice: 2.99, QuantitySold: 45 },
          { Flavor: "Vanilla", UnitPrice: 1.50, QuantitySold: 35 }
      )
   )
   

2. Execute a fórmula selecionando o botão enquanto mantém a tecla Alt pressionada.

3. Adicione um segundo controle Button, defina sua propriedade OnSelect como esta fórmula e, em seguida, execute-a:

   ClearCollect( FirstExample,
      AddColumns( IceCreamSales, Revenue, UnitPrice * QuantitySold )
   )
   

4. No menu Arquivo, selecione Coleções e, em seguida, selecione IceCreamSales para mostrar essa coleção.

   Como mostra este gráfico, a segunda fórmula não modificou essa coleção. A AddColumns função usou IceCreamSales como um argumento somente leitura; a função não modificou a tabela à qual esse argumento se refere.

   

5. Selecione FirstExample.

   Como mostra este gráfico, a segunda fórmula retornou uma nova tabela com a coluna adicionada. A função ClearCollect capturou a nova tabela na coleção FirstExample, adicionando algo à tabela original conforme ele fluiu pela função sem modificar a origem:

   

Colunas de mapa em um componente

Consulte Colunas de mapa.