Funções AddColumns, DropColumns, RenameColumns e ShowColumns

Aplica-se a: Aplicativos Canvas Fluxos de desktop Aplicativos orientados a modelos Power Platform CLI

Forma uma tabela ao adicionar, remover, renomear e selecionar as suas colunas.

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

Visão geral

Essas funções formam uma tabela ajustando suas colunas:

• Reduza uma tabela que contenha várias colunas para uma única coluna para usá-la com funções de coluna única, como Lower ou Sqrt.
• Adicione uma coluna calculada a uma tabela (por exemplo, uma coluna Preço total que mostra os resultados da multiplicação de 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.

Nota

As funções descritas neste tópico não modificam a tabela original. Em vez disso, eles consideram essa tabela como um argumento e retornam uma nova tabela com uma transformação aplicada. Para obter mais informações, consulte Como trabalhar com tabelas.

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 função AddColumns adiciona uma coluna a uma tabela, e uma fórmula define os valores dessa coluna. As colunas existentes permanecem inalteradas.

A fórmula é avaliada para cada registro da tabela.

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 função DropColumns remove colunas de uma tabela. Todas as outras colunas permanecem inalteradas. DropColumns exclui colunas e ShowColumns inclui colunas.

Use a função RenameColumns para renomear uma ou mais colunas de uma tabela fornecendo pelo menos um par de argumentos que especifica o nome de uma coluna que a tabela contém (o nome antigo, que você deseja substituir) e o nome de uma coluna que a tabela não contém (o novo nome, que você deseja usar). O nome antigo já deve existir na tabela 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 remova a coluna existente com DropColumns ou renomeie-a fora do caminho aninhando uma função RenameColumns dentro de outra.

A função ShowColumns inclui colunas de uma tabela e remove todas as outras colunas. Você pode usar aShowColumns para criar uma tabela de coluna única a partir de uma tabela de várias colunas. ShowColumns inclui colunas e DropColumns exclui colunas.

Para todas essas funções, o resultado é uma nova tabela com uma transformação aplicada. A tabela original não é modificada. Não é possível modificar uma tabela existente com uma fórmula. O SharePoint, Microsoft Dataverse, SQL Server e outras fontes de dados fornecem ferramentas para modificar as colunas de listas e tabelas, que geralmente são mencionadas como esquema. As funções neste artigo só transformam uma tabela de entrada, sem modificar o original, em uma tabela de saída para uso posterior.

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 para o fonte de dados para cada um daqueles primeiros registros em RealEstateAgents, o que causa muito ruído na 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.

Observação

Antes da versão 3.24042 do Power Apps, os nomes das colunas eram especificados com uma cadeia de texto usando aspas duplas e, se conectados a uma fonte de dados também precisavam ser nomes lógicos. Por exemplo, o nome lógico "cr43e_name" entre aspas duplas foi usado em vez do nome de exibição Name sem aspas. Para fontes de dados do SharePoint e do Excel que contêm nomes de colunas com espaços, cada espaço foi especificado com "_x0020_", por exemplo "Nome da coluna" como "Column_x0020_Name". Após esta versão, todos os aplicativos foram atualizados automaticamente para a nova sintaxe descrita neste artigo.

Sintaxe

AddColumns( Tabela, NomeColuna1, Fórmula1 [, NomeColuna2, Fórmula2, ... ] )

• Tabela - Obrigatório. Tabela na 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 fazer referência a outras colunas da tabela nesta fórmula.

DropColumns( Tabela, NomeColuna1 [, NomeColuna2, ... ] )

• Tabela - Obrigatório. Tabela na qual operar.
• ColumnNames - Obrigatório. Nomes das colunas para remover.

RenomearColunas( Tabela, NomeColunaAntigo1, NomeColunaNovo1 [, NomeColunaAntigo2, NomeColunaNovo2, ... ] )

• Tabela - Obrigatório. Tabela na qual operar.
• OldColumnNames - Obrigatório. Nomes das colunas para renomear da tabela 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( Tabela, NomeColuna1 [, NomeColuna2, ... ] )

• Tabela - Obrigatório. Tabela na 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(VendasDeSorvete, Receita, PreçoUnitário * QuantidadeVendida)	Adiciona uma coluna Receita no resultado. Para cada registro, UnitPrice * QuantitySold são avaliados e o resultado é colocado na nova coluna.
DropColumns(VendasDeSorvete,PreçoUnitário)	Exclui a coluna UnitPrice do resultado. Use esta função para excluir colunas e use ShowColumns para incluí-las.
ShowColumns (Vendas de Sorvete, Sabor)	Inclui somente a coluna Flavor no resultado. Use essa função para incluir colunas, e a função DropColumns para removê-las.
RenomearColunas(VendasDeSorvete,PreçoUnitário, Preço)	Renomeie a coluna PreçoUnitário no resultado.
RenameColumns(VendasDeSorvete,PreçoUnitário,Preço,QuantidadeVendida,Número)	Renomeia as colunas UnitPrice e QuantitySold no resultado.
SoltarColunas( RenameColumns( AddColumns( IceCreamSales, Revenue, UnitPrice * QuantitySold ), UnitPrice, Price ), Quantity )	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 função AddColumns 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.