Funções AddColumns, DropColumns, RenameColumns e ShowColumns

Aplica-se a: Aplicações de tela Fluxos de ambiente de trabalho Aplicações condicionadas por modelo Power Platform CLI

Forma uma tabela ao adicionar, remover, mudar o nome e selecionar as colunas.

A função **ForAll também pode ser utilizada para dar forma a uma tabela, devolvendo uma tabela de novos registos criada a partir de colunas existentes.

Descrição geral

Estas funções formam uma tabela ao ajustar as colunas:

• Reduza uma tabela com várias colunas numa coluna única para utilizar com as funções de coluna única, tais 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 da Quantidade pelo Preço Unitário).
• Mude o nome de uma coluna para um nome mais significativo para apresentar aos utilizadores ou utilizar em fórmulas.

Uma tabela é um valor no Power Apps, tal como uma cadeia ou um número. Pode especificar uma tabela como um argumento numa fórmula e as funções podem devolver uma tabela como um resultado.

Nota

As funções que este tópico descreve não modificam a tabela original. Em vez disso, consideram essa tabela como um argumento e devolvem uma nova tabela com uma transformação aplicada. Para mais informações, consulte trabalhar com tabelas.

Não pode modificar as colunas de uma origem de dados através destas funções. Tem de modificar os dados na origem. Pode adicionar colunas a uma coleção com a função Collect. Para mais informações, consulte trabalhar com origens de dados.

Description

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

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

Os atuais campos do registo em processamento estão disponíveis na fórmula. Utilize o operador ThisRecord ou simplesmente campos de referência pelo nome, como com qualquer outro valor. O operador As também pode ser usado para nomear o registo que está a ser processado, o que pode ajudar a tornar a sua fórmula mais fácil de compreender e tornar os registos aninhados acessíveis. Para mais informações, consulte os exemplos abaixo e trabalhar com o âmbito de registo.

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

Utilize a função RenameColumns para mudar o nome de uma ou mais colunas de uma tabela ao fornecer, pelo menos, um par de argumentos que especifique o nome de uma coluna que a tabela contenha (o nome antigo, que quer substituir) e o nome de uma coluna que a tabela não contenha (o nome novo, o que quer utilizar). O nome antigo já tem de existir na tabela e o novo nome não pode existir. Cada nome de coluna poderá aparecer apenas uma vez na lista de argumentos como um nome de coluna antigo ou um novo nome de coluna. Para mudar o nome de uma coluna para um nome de coluna existente, remova primeiro a coluna existente com DropColumns ou mude o nome da coluna existente ao aninhar a função RenameColumns dentro de outra.

A função ShowColumns inclui colunas de uma tabela e remove todas as outras colunas. Pode utilizar ShowColumns 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 estas funções, o resultado é uma nova tabela com a transformação aplicada. A tabela original não é modificada. Não é possível modificar uma tabela existente com uma fórmula. SharePoint, Microsoft Dataverse, SQL Server, e outras fontes de dados fornecem ferramentas para modificar as colunas de listas, tabelas e tabelas, que são frequentemente referidas como o esquema. As funções existentes neste artigo apenas transformam uma tabela de entrada, sem modificar o original numa tabela de saída para utilização adicional.

Os argumentos para estas funções suportam delegação. Por exemplo, uma função Filter utilizada como argumento para puxar registos relacionados procura todas as listagens, mesmo que a origem de dados '[dbo].[AllListings]' contenha milhões de linhas:

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

No entanto, a saída destas funções está sujeita ao limite de registo de não delegação. Neste exemplo, apenas 500 registos são devolvidos mesmo que a origem de dados RealEstateAgents tenha 501 ou mais registos.

Se utilizar AddColumns desta forma, Filtrar tem de fazer chamadas separadas para a origem de dados para cada um dos primeiros registos em RealEstateAgents, o que causa várias comunicações na rede. Se [dbo](.[AllListings] é pequeno o suficiente e não muda com frequência. Pode chamar a função Collect em OnStart para colocar em cache a origem de dados na sua aplicação quando for iniciada. Como alternativa, pode reestruturar a sua aplicação para que retire os registos relacionados apenas quando o utilizador pedir.

Nota

Antes da versão 3.24042 do Power Apps, os nomes das colunas eram especificados com uma cadeia de texto com aspas duplas e, se estivessem ligados a uma origem de dados também precisavam de ser nomes lógicos. Por exemplo, foi utilizado o nome lógico "cr43e_name" com aspas em vez do nome a apresentar Nome sem aspas. Para as origens 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, todas as aplicações foram atualizadas automaticamente para a nova sintaxe descrita neste artigo.

Sintaxe

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

• Table – Obrigatório. Tabela a ser utilizada.
• ColumnName(s) – Obrigatório. Nomes das colunas a adicionar.
• Fórmula(s) – Obrigatório. Fórmulas a avaliar para cada registo. O resultado é adicionado como o valor da nova coluna correspondente. Pode referenciar outras colunas da tabela nesta fórmula.

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

• Table – Obrigatório. Tabela a ser utilizada.
• ColumnName(s) – Obrigatório. Nomes das colunas a remover.

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

• Table – Obrigatório. Tabela a ser utilizada.
• OldColumnName(s) - Obrigatório. Nomes das colunas a mudar o nome a partir da tabela original. Este elemento aparece em primeiro lugar no par de argumentos (ou pela primeira vez em cada par de argumentos se a fórmula incluir mais de um par).
• NewColumnName(s) - Obrigatório. Nomes de substituição. Este elemento aparece em último lugar no par de argumentos (ou em último lugar em cada par de argumentos se a fórmula incluir mais de um par).

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

• Table – Obrigatório. Tabela a ser utilizada.
• ColumnName(s) – Obrigatório. Nomes das colunas a incluir.

Exemplos

Para os exemplos desta secção, utilize a origem de dados IceCreamSales, que contém os dados nesta tabela:

Nenhum destes exemplos modifica a origem de dados IceCreamSales. Cada função transforma o valor da origem de dados como uma tabela e devolve esse valor como resultado.

Fórmula	Description	Result
AddColumns( IceCreamSales, Revenue, UnitPrice * QuantitySold )	Adiciona uma coluna Receitas ao resultado. Para cada registo, é avaliado o valor UnitPrice * QuantitySold e o resultado é colocado numa nova coluna.
DropColumns( IceCreamSales, UnitPrice )	Exclui a coluna UnitPrice do resultado. Utilize esta função para excluir colunas e utilize ShowColumns para as incluir.
ShowColumns( IceCreamSales, Flavor )	Inclui apenas a coluna Sabor no resultado. Utilize esta função para incluir colunas e utilize DropColumns para as excluir.
RenameColumns( IceCreamSales, UnitPrice, Price)	Muda o nome da coluna UnitPrice no resultado.
RenameColumns( IceCreamSales, UnitPrice, Price, QuantitySold, Number)	Muda o nome das colunas UnitPrice e QuantitySold no resultado.
DropColumns( RenameColumns( AddColumns( IceCreamSales, Revenue, UnitPrice * QuantitySold ), UnitPrice, Price ), Quantity )	Efetua as seguintes transformações de tabela por ordem, a partir da fórmula: Adiciona uma coluna Revenue com base no cálculo por registo de UnitPrice * Quantity. Muda o nome UnitPrice para Preço. Exclui a coluna Quantidade. A ordem é importante, por exemplo, não se consegue calcular com UnitPrice depois de o seu nome ser mudado.

Passo a passo

Vamos experimentar alguns dos exemplos apresentados anteriormente neste artigo.

1. Crie uma coleção adicionando um controlo Button e definindo a propriedade OnSelect como 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 controlo Button e defina a propriedade OnSelect para esta fórmula e, em seguida, execute-o:

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

4. No menu Ficheiro, 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 esta coleção. A função AddColumns usava IceCreamSales como argumento só de leitura; a função não modificou a tabela à qual o argumento se refere.

   

5. Selecione FirstExample.

   Como mostra este gráfico, a segunda fórmula devolveu uma nova tabela com a coluna adicionada. A função ClearCollect capturou a nova tabela na coleção FirstExample, adicionando algo à tabela original à medida que flui ao longo da função sem modificar a origem:

   

Colunas de mapa num componente

Ver Mapear colunas.