Funções AddColumns, DropColumns, RenameColumns e ShowColumns

Aplica-se a: Aplicativos de tela Fluxos da área de trabalho Aplicativos baseados em modelo Power Platform CLI

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

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 Abs.
• 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.

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. Confira Como trabalhar com fontes de dados para obter mais detalhes.

Descrição

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 remove 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 remove 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 tópico 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. E se [dbo](.[AllListings] for pequeno o suficiente e não mudar com frequência, você poderá chamar a função Collect em OnStart para armazenar em cache a fonte de dados no 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( Table, ColumnName1, Formula1 [, ColumnName2, Formula2, ... ] )

• Table - obrigatório. Tabela na qual operar.
• ColumnName(s) - obrigatório. Nomes de colunas para adicionar. Você deve especificar uma cadeia de caracteres (por exemplo, "Nome" com aspas duplas incluídas) para esse argumento. Você deve especificar os nomes das colunas usando seu nome lógico. O Intellisense sugerirá apenas nomes lógicos. O nome lógico diferencia maiúsculas de minúsculas.
• Formula(s) - 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( Table, ColumnName1 [, ColumnName2, ... ] )

• Table - obrigatório. Tabela na qual operar.
• ColumnName(s) - obrigatório. Nomes de colunas para remover. Você deve especificar uma cadeia de caracteres (por exemplo, "Nome" com aspas duplas incluídas) para esse argumento. Você deve especificar os nomes das colunas usando seu nome lógico. O Intellisense sugerirá apenas nomes lógicos. O nome lógico diferencia maiúsculas de minúsculas.

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

• Table - obrigatório. Tabela na qual operar.
• OldColumnName - obrigatório. Nome de uma coluna 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). Esse nome deve ser uma cadeia de caracteres (por exemplo "Nome" com aspas duplas incluídas). Você deve especificar os nomes das colunas usando seu nome lógico. O Intellisense sugerirá apenas nomes lógicos. O nome lógico diferencia maiúsculas de minúsculas.
• NewColumnName - obrigatório. Nome 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). Você deve especificar uma cadeia de caracteres (por exemplo, "Nome do Cliente" com aspas duplas incluídas) para esse argumento. Você deve especificar os nomes das colunas usando seu nome lógico. O Intellisense sugerirá apenas nomes lógicos. O nome lógico diferencia maiúsculas de minúsculas.

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

• Table - obrigatório. Tabela na qual operar.
• ColumnName(s) - obrigatório. Nomes de colunas a serem incluídas. Você deve especificar uma cadeia de caracteres (por exemplo, "Nome" com aspas duplas incluídas) para esse argumento. Você deve especificar os nomes das colunas usando seu nome lógico. O Intellisense sugerirá apenas nomes lógicos. O nome lógico diferencia maiúsculas de minúsculas.

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	Descrição	Resultado
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 esta 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 a função DropColumns para removê-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, "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. Observe que a ordem é importante. Por exemplo, não podemos calcular com UnitPrice depois que ela foi renomeada.

Passo a passo

Vamos experimentar alguns dos exemplos anteriores neste tópico.

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.