AddColumns, DropColumns, RenameColumns, e ShowColumns funções

Aplica-se a: Aplicativos do Canvas Fluxos do Copilot Studio Desktop Aplicativos orientados por modelos 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 dar forma a uma tabela, retornando uma tabela de novos registros criados a partir de colunas existentes.

Descrição geral

Estas funções dão forma a uma tabela ou registo ajustando as suas colunas:

Reduza uma tabela ou registro que contém várias colunas para uma única coluna para uso com funções de coluna única, como Inferior 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 de Quantidade por 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.

Descrição

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

A fórmula é avaliada para o registo fornecido ou para cada registo do quadro fornecido.

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 DropColumns função exclui colunas de uma tabela ou registro. Todas as outras colunas existentes 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 especifique 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 pretende utilizar). O nome antigo já deve existir na tabela ou no 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 ou registro de coluna única a partir 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 registro original não é modificado. Não é possível modificar uma tabela ou registo existente com uma fórmula. SharePoint, Microsoft Dataverse, SQL Server e outras fontes de dados fornecem ferramentas para modificar as colunas de listas e tabelas, que geralmente são chamadas de esquema. As funções neste tópico apenas transformam uma tabela ou registro de entrada, sem modificar o original, em uma tabela ou registro de saída para uso posterior.

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 você usar AddColumns dessa maneira, o Filter deverá fazer chamadas separadas para a fonte de dados para cada um desses primeiros registros no RealEstateAgents, o que causa muitas conversas 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( TableOrRecord, ColumnName1, Formula1 [, ColumnName2, Formula2, ... ] )

TableOrRecord - Obrigatório. Tabela ou registro para operar.
ColumnNames - Obrigatório. Nomes das colunas a adicionar.
Fórmulas - Obrigatório. Fórmulas a avaliar para cada registo. O resultado é adicionado como o valor da nova coluna correspondente. Pode fazer referência a outras colunas da tabela ou registo nesta fórmula.

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

TableOrRecord - Obrigatório. Tabela ou registro para operar.
ColumnNames - Obrigatório. Nomes das colunas a remover.

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

TableOrRecord - Obrigatório. Tabela ou registro para operar.
OldColumnNames - Obrigatório. Nomes das colunas a serem renomeadas da tabela ou registro 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).
NewColumnNames - 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( TableOrRecord, ColumnName1 [, ColumnName2, ... ] )

TableOrRecord - Obrigatório. Tabela ou registro para operar.
ColumnNames - 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:

Exemplo de gelado.

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	Descrição	Result
*AddColumns( IceCreamSales, Receita, PreçoUnitário QuantidadeVendida )**	Adiciona uma coluna Receitas ao resultado. Para cada registo, é avaliado o valor *UnitPrice QuantitySold** e o resultado é colocado numa nova coluna.
DropColumns( IceCreamSales, PreçoUnitário )	Exclui a coluna UnitPrice do resultado. Use esta função para excluir colunas e use ShowColumns para incluí-las.
ShowColumns( IceCreamSales, Sabor )	Inclui apenas a coluna Sabor no resultado. Use esta função incluir colunas e use DropColumns para excluí-las.
RenameColumns( IceCreamSales, Preço Unitário, Preço)	Muda o nome da coluna UnitPrice no resultado.
RenameColumns( IceCreamSales, Preço Unitário, Preço, QuantidadeVendido, Número)	Muda o nome das colunas UnitPrice e QuantitySold no resultado.
DropColumns( RenameColumns( AddColumns( IceCreamSales, Receita, Preço Unitário * QuantidadeVendida ), Preço unitário, Preço), Quantidade )	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.

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 }
   )
)

Execute a fórmula selecionando o botão enquanto mantém a tecla Alt pressionada.
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 )
)
```
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 AddColumns função usou IceCreamSales como um argumento somente leitura, a função não modificou a tabela à qual esse argumento se refere.
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: