Tabelas

No Microsoft Power Fx, você pode escrever uma fórmula que acesse informações no Microsoft Excel, no SharePoint, no SQL Server e em várias outras fontes que armazenam dados em registros e tabelas. Para trabalhar com mais eficiência com esse tipo de dados, examine os conceitos que fundamentam essas estruturas.

• Um registro contém uma ou mais categorias de informações sobre uma pessoa, um lugar ou algo. Por exemplo, um registro pode conter o nome, o endereço de email e o número de telefone de um único cliente. Outras ferramentas se referem a um registro como uma "linha" ou "item".
• Uma tabela tem um ou mais registros que contêm as mesmas categorias de informações. Por exemplo, uma tabela pode conter os nomes, endereços de email e números de telefone de 50 clientes.

Você pode criar uma variedade de fórmulas que usam o nome de uma tabela como argumento, semelhante a uma fórmula no Excel que usa uma ou mais referências de célula como argumentos. Algumas fórmulas no Power Fx retornam uma tabela que reflete os outros argumentos que você especificar. Por exemplo, você pode criar uma fórmula:

• para atualizar um registro em uma tabela especificando a tabela como um dos vários argumentos para a função Patch
• para adicionar, remover e renomear colunas em uma tabela especificando a tabela como um argumento para a função AddColumns, DropColumns ou RenameColumns. Nenhuma dessas funções modifica a tabela original. Em vez disso, a função retorna outra tabela com base em outros argumentos que você especificar.

Elementos de uma tabela

Registros

Cada registro contém pelo menos uma categoria de informações para uma pessoa, lugar ou algo. O exemplo acima mostra um registro de cada produto (Chocolate, Bread e Water) e uma coluna para cada categoria de informações (Price, Quantity on Hand e Quantity on Order).

Em uma fórmula, você fazer referência a um registro por si só, fora do contexto de uma tabela, usando chaves. Por exemplo, este registro { Name: "Strawberries", Price: 7.99 } não está associado a uma tabela. Observe que os nomes de campo, como Name e Price neste exemplo, não estão entre aspas duplas.

Campos

Um campo é uma informação individual em um registro. Você pode visualizar esse tipo de campo como um valor em uma coluna para determinado registro.

Assim como em um controle, você faz referência a um campo de um registro usando o .operador no registro. Por exemplo, First(Products).Name retorna o campo Name do primeiro registro na tabela Products.

Um campo pode conter outro registro ou tabela, como o exemplo para a função GroupBy mostra. Você pode aninhar quantos níveis de registros e tabelas desejar.

Colunas

Uma coluna refere-se ao mesmo campo para um ou mais registros em uma tabela. No exemplo acima, cada produto tem um campo de preço, e esse preço está na mesma coluna para todos os produtos. A tabela acima tem quatro colunas, exibidas na horizontal na parte superior:

• Nome
• Preço
• Quantidade disponível
• Quantidade no pedido

O nome da coluna reflete os campos dela.

Todos os valores em uma coluna pertencem ao mesmo tipo de dados. No exemplo acima, a coluna "Quantity on Hand" sempre contém um número e não pode conter uma cadeia de caracteres, como "12 units", para um registro. O valor de qualquer campo também pode ser em branco.

Você pode ter feito referência a colunas como "campos" em outras ferramentas.

Tabela

Uma tabela consiste em um ou mais registros, cada um com vários campos com nomes consistentes entre os registros.

Qualquer tabela que seja armazenada em uma fonte de dados ou em uma coleção tem um nome que você usa para fazer referência à tabela e passá-la para funções que aceitam tabelas como argumentos. Tabelas também podem ser o resultado de uma função ou uma fórmula.

Como no exemplo a seguir, você pode expressar uma tabela em uma fórmula usando a função Table com um conjunto de registros demarcados entre chaves:

Table( { Value: "Strawberry" }, { Value: "Vanilla" } )

Você também pode definir uma tabela de coluna única com colchetes. Uma maneira equivalente de escrever o exemplo acima:

[ "Strawberry", "Vanilla" ]

Fórmulas de tabela

No Excel e no Power Fx, é possível usar fórmulas para manipular números e cadeias de caracteres de texto de maneiras semelhantes:

• No Excel, digite um valor, como 42, na célula A1 e, em seguida, digite uma fórmula, como A1+2, em outra célula para mostrar o valor de 44.
• No Power Apps, defina a propriedade Default de Slider1 como 42 e defina a propriedade Text de um rótulo como Slider1.Value + 2 para mostrar o valor 44.

Em ambos os casos, o valor calculado será alterado automaticamente se você alterar os valores dos argumentos (por exemplo, o número na célula A1 ou o valor de Slider1).

Da mesma forma, você pode usar fórmulas para acessar e manipular dados em tabelas e registros. Você pode usar nomes de tabelas como argumentos em algumas fórmulas, como Min(Catalog, Price) para mostrar o valor mais baixo na coluna Price da tabela Catalog. Outras fórmulas fornecem tabelas inteiras como valores de retorno, como RenameColumns(Catalog, "Price", "Cost"), que retornam todos os registros da tabela Catalog, mas altera o nome da coluna Price para Cost.

Assim como com números, fórmulas que envolvem tabelas e registros são recalculadas automaticamente à medida que a tabela subjacente ou o registro são alterados. Se o custo de um produto na tabela Catalog for reduzido abaixo do mínimo anterior, o valor retornado da fórmula Min alterará automaticamente de acordo com ele.

Funções de tabela e propriedades de controle

Considere a função Lower. Se a variável welcome contiver a cadeia de caracteres de texto "Hello, World", a fórmula Lower( welcome ) retornará "hello, world". Esta função não altera de forma alguma o valor nessa variável. Lower é uma função pura, pois processa apenas a entrada e produz a saída. Isso é tudo; não há efeitos colaterais. Todas as funções no Excel e a maioria das funções no Power Fx é composta de funções puras, que permitem que a pasta de trabalho ou o aplicativo seja recalculada automaticamente.

O Power Fx oferece um conjunto de funções que operam em tabelas da mesma maneira. Essas funções recebem tabelas como entrada e filtro, classificam, transformam, reduzem e resumem tabelas inteiras de dados. Na verdade, Lower e muitas outras funções que normalmente usam um único valor também podem usar uma tabela de coluna única como entrada.

Muitas funções usam uma tabela de coluna única como entrada. Se uma tabela inteira tiver apenas uma coluna, você poderá especificá-la pelo nome. Se uma tabela tiver várias colunas, você poderá especificar uma dessas colunas usando a sintaxe Table.Column. Por exemplo, Products.Name retorna a tabela de coluna única somente com valores Name a tabela Products.

Você pode remodelar completamente uma tabela da maneira que desejar, usando a função AddColumns, RenameColumns, ShowColumns ou DropColumns. Novamente, essas funções alteram apenas sua saída, não sua fonte.

Fórmulas de comportamento

Outras funções são projetadas especificamente para modificar dados e ter efeitos colaterais. Como essas funções não são puras, você deve construí-las com cuidado e elas não podem participar do recálculo automático dos valores no aplicativo. Você pode usar essas funções somente nas fórmulas de comportamento.

Escopo do registro

Algumas funções operam avaliando uma fórmula em todos os registros de uma tabela individualmente. O resultado da fórmula é usado de várias maneiras:

• AddColumns - A fórmula fornece o valor do campo adicionado.
• Média, Máx, Mín, Soma, DesvioPadrãoP, VarP - A fórmula fornece o valor a ser agregado.
• Filtro, Pesquisa - A fórmula determina se o registro deve ser incluído na saída.
• Concat - A fórmula determina as strings a serem concatenadas.
• Distinto - A fórmula retorna um valor, usado para identificar registros duplicados.
• ForAll - A fórmula pode retornar qualquer valor, potencialmente com efeitos colaterais.
• Classificar - A fórmula fornece o valor para classificar os registros.
• Com - A fórmula pode retornar qualquer valor, potencialmente com efeitos colaterais.

Dentro dessas fórmulas, você pode fazer referência aos campos do registro que está sendo processado. Cada uma dessas funções cria um "escopo de registro" em que a fórmula é avaliada, no qual os campos do registro estão disponíveis como identificadores de nível superior. Você também pode fazer referência às propriedades de controle e a outros valores em todo o aplicativo.

Por exemplo, considere uma tabela de Produtos colocados em uma variável global:

Set( Products,
    Table(
        { Product: "Widget",    'Quantity Requested': 6,  'Quantity Available': 3 },
        { Product: "Gadget",    'Quantity Requested': 10, 'Quantity Available': 20 },
        { Product: "Gizmo",     'Quantity Requested': 4,  'Quantity Available': 11 },
        { Product: "Apparatus", 'Quantity Requested': 7,  'Quantity Available': 6 }
    )
)

Para determinar se algum desses produtos foram mais solicitados do que o disponível:

Filter( Products, 'Quantity Requested' > 'Quantity Available' )

O primeiro argumento para Filter é a tabela de registros na qual operar e o segundo argumento é uma fórmula. O filtro cria um escopo de registro para avaliar esta fórmula na qual os campos de cada registro estão disponíveis, neste caso, Produto, Quantidade Solicitada e Quantidade Disponível. O resultado da comparação determina se cada registro deve ser incluído no resultado da função:

Ao adicionar a este exemplo, podemos calcular quanto de cada produto pedir:

AddColumns( 
    Filter( Products, 'Quantity Requested' > 'Quantity Available' ), 
    "Quantity To Order", 'Quantity Requested' - 'Quantity Available'
)

Aqui, estamos adicionando uma coluna calculada ao resultado. AddColumns tem seu próprio escopo de registro que ele usa para calcular a diferença entre o que foi solicitado e o que está disponível.

Por fim, podemos reduzir a tabela de resultados a apenas as colunas que queremos:

ShowColumns(
    AddColumns(
        Filter( Products, 'Quantity Requested' > 'Quantity Available' ),
        "Quantity To Order", 'Quantity Requested' - 'Quantity Available'
    ),
    "Product",
    "Quantity To Order"
)

Observe que, nos itens acima, usamos aspas duplas (") em alguns lugares e aspas simples (') em outros lugares. Aspas simples são necessárias ao referenciar o valor de um objeto, como um campo ou uma tabela, em que o nome do objeto contém um espaço. Aspas duplas são usadas quando não estamos fazendo referência ao valor de um objeto, mas, apenas falando dele, especialmente em situações em que o objeto ainda não existe, como no caso de AddColumns.

Desambiguidade

Os nomes de campo adicionados com o escopo de registro substituem os mesmos nomes de outro lugar no aplicativo. Quando isso acontece, ainda é possível acessar os valores de fora do escopo de registro com o operador de @ desambiguidade:

• Para acessar valores de escopos de registro aninhados, use o operador @ com o nome da tabela que está sendo operada usando este padrão:
  Tabela[@NomeDoCampo]
• Para acessar valores globais, como fontes de dados, coleções e variáveis de contexto, use o padrão [@NomeDoObjeto] (sem uma designação de tabela).

Se a tabela que está sendo operada for uma expressão, como Filter(Table, ... ), o operador de desambiguidade não poderá ser usado. Apenas o escopo interno do registro pode acessar os campos de expressão dessa tabela ao não utilizar o operador de desambiguidade.

Por exemplo, imagine ter uma coleção X:

Você pode criar essa coleção com ClearCollect( X, [1, 2] ).

E outra coleção Y:

Você pode criar essa coleção com ClearCollect( Y, ["A", "B"] ).

Além disso, defina uma variável de contexto chamada Value com esta fórmula: UpdateContext( {Value: "!"} )

Vamos reunir tudo isso. Nesse contexto, a fórmula a seguir:

Ungroup(
    ForAll( X,
        ForAll( Y,
            Y[@Value] & Text( X[@Value] ) & [@Value]
        )
    ),
    "Value"
)

produz esta tabela:

O que está acontecendo aqui? A função ForAll mais externa define um escopo de registro para X, permitindo o acesso ao campo Value de cada registro à medida que ele é processado. Para acessá-lo, basta usar a palavra Value ou usar X[@Value].

A função ForAll mais interna define outro escopo de registro para Y. Como esta tabela também possui um campo Value definido, o uso de Value aqui refere-se ao campo no registro Ye não é mais o de X. Aqui, para acessar o campo Value de X, devemos usar a versão mais longa com o operador de desambiguação.

Como Y é o escopo de registro interno, acessar campos dessa tabela não exige desambiguidade, permitindo que usemos esta fórmula com o mesmo resultado:

Ungroup(
    ForAll( X,
        ForAll( Y,
            Value & Text( X[@Value] ) & [@Value]
        )
    ),
    "Value"
)

Todos os escopos do registro ForAll substituem o escopo global. A variável de contexto Value que definimos não está disponível por nome sem o operador de desambiguidade. Para acessar esse valor, use [@Value].

Desagrupar nivela o resultado porque funções aninhadas ForAll resultam em uma tabela de resultados aninhada.

Tabelas de coluna única

Para operar em uma única coluna de uma tabela, use a função ShowColumns como neste exemplo:

ShowColumns( Products, "Product" )

Esta fórmula produz esta tabela de coluna única:

Para uma alternativa mais curta, especifique Table.Column, que extrai a tabela de coluna única somente de Column de Table. Por exemplo, esta fórmula produz exatamente o mesmo resultado que o uso de ShowColumns.

Products.Product

Registro em linha

Você pode expressar registros usando chaves que contêm valores de campos nomeados. Por exemplo, você pode expressar o primeiro registro na tabela no início deste tópico usando esta fórmula:

{ Name: "Chocolate", Price: 3.95, 'Quantity on Hand': 12, 'Quantity on Order': 10 }

Também é possível inserir fórmulas dentro de outras fórmulas, como exibido neste exemplo:

{ Name: First(Products).Name, Price: First(Products).Price * 1.095 }

Você pode aninhar registros aninhando entre chaves, como demonstrado neste exemplo:

{ 'Quantity': { 'OnHand': ThisItem.QuantOnHand, 'OnOrder': ThisItem.QuantOnOrder } }

Coloque cada nome de coluna que contém um caractere especial, como um espaço ou um vírgula, entre aspas simples. Para usar uma aspa simples em um nome de coluna, clique duas vezes nele.

Observe que o valor na coluna Price não inclui o símbolo da moeda, como um sinal de cifrão. Essa formatação será aplicada quando o valor é exibido.

Tabelas em linha

Você pode criar uma tabela usando a função Table e um conjunto de registros. Você pode expressar a tabela no início deste tópico usando esta fórmula:

Table( 
	{ Name: "Chocolate", Price: 3.95, 'Quantity on Hand': 12, 'Quantity on Order': 10 },
	{ Name: "Bread", Price: 4.95, 'Quantity on Hand': 34, 'Quantity on Order': 0 },
	{ Name: "Water", Price: 4.95, 'Quantity on Hand': 10, 'Quantity on Order': 0 } 
)

Você também pode aninhar tabelas:

Table( 
	{ Name: "Chocolate", 
	  'Quantity History': Table( { Quarter: "Q1", OnHand: 10, OnOrder: 10 },
	                             { Quarter: "Q2", OnHand: 18, OnOrder: 0 } ) 
	}
)

Tabelas de valores em linha

Você pode criar tabelas de coluna única especificando valores entre colchetes. A tabela resultante tem uma única coluna, chamada Value.

Por exemplo, [ 1, 2, 3, 4 ] é equivalente a Table( { Value: 1 }, { Value: 2 }, { Value: 3 }, { Value: 4 } ) e retorna esta tabela: