Funções Filtrar, Pesquisar e Pesquisa no PowerAppsFilter, Search, and LookUp functions in PowerApps

Localiza um ou mais registros em uma tabela.Finds one or more records in a table.

DescriçãoDescription

A função Filtrar localiza registros em uma tabela que atendem a uma fórmula.The Filter function finds records in a table that satisfy a formula. Use Filtrar para localizar um conjunto de registros que correspondem a um ou mais critérios e descartar aqueles que não correspondem.Use Filter to find a set of records that match one or more criteria and to discard those that don't.

A função Pesquisa localiza o primeiro registro em uma tabela que corresponda a uma fórmula.The LookUp function finds the first record in a table that satisfies a formula. Use a função Pesquisa para localizar um único registro que corresponda a um ou mais critérios.Use LookUp to find a single record that matches one or more criteria.

Para ambos os casos, a fórmula é avaliada para cada registro da tabela.For both, the formula is evaluated for each record of the table. Registros que resultam em true são incluídos no resultado.Records that result in true are included in the result. Além de operadores de fórmula normal, você pode usar os operadores in e exactin para correspondências de subsequências.Besides the normal formula operators, you can use the in and exactin operators for substring matches.

Os campos do registro que estão sendo atualmente processados estão disponíveis dentro da fórmula.Fields of the record currently being processed are available within the formula. Basta referenciá-los por nome como você faria com qualquer outro valor.You simply reference them by name as you would any other value. Também é possível fazer referência a propriedades de controle e a outros valores de todo o seu aplicativo.You can also reference control properties and other values from throughout your app. Para obter mais detalhes, consulte os exemplos abaixo e trabalhando com escopo de registro.For more details, see the examples below and working with record scope.

A função Pesquisar localiza registros em uma tabela que contenham uma cadeia de caracteres em uma de suas colunas.The Search function finds records in a table that contain a string in one of their columns. A cadeia de caracteres pode ocorrer em qualquer lugar dentro da coluna; Por exemplo, procurar por "rob" ou "bert" encontraria uma correspondência em uma coluna que contém "Robert".The string may occur anywhere within the column; for example, searching for "rob" or "bert" would find a match in a column that contains "Robert". A pesquisa diferencia maiúsculas de minúsculas.Searching is case-insensitive. Ao contrário de Filtrar e Pesquisa, a função Pesquisar usa uma única cadeia de caracteres para corresponder em vez de uma fórmula.Unlike Filter and LookUp, the Search function uses a single string to match instead of a formula.

As funções Filtrar e Pesquisar retornam uma tabela que contém as mesmas colunas da tabela original e os registros que correspondem aos critérios.Filter and Search return a table that contains the same columns as the original table and the records that match the criteria. A função Pesquisa retorna apenas o primeiro registro encontrado após a aplicação de uma fórmula para reduzir o registro a um único valor.LookUp returns only the first record found, after applying a formula to reduce the record to a single value. Se nenhum registro for encontrado, as funções Filtrar e Pesquisar retornarão uma tabela vazia, e Pesquisa retorna em branco.If no records are found, Filter and Search return an empty table, and LookUp returns blank.

Tabelas são um valor no PowerApps, assim como cadeias de caracteres ou números.Tables are a value in PowerApps, just like a string or number. Elas podem ser passadas e retornadas para funções.They can be passed to and returned from functions. As funções Filtrar, Pesquisar e Pesquisa não modificam uma tabela.Filter, Search, and LookUp don't modify a table. Em vez disso, eles consideram uma tabela como um argumento e retornam uma tabela, um registro ou um único valor dele.Instead, they take a table as an argument and return a table, a record, or a single value from it. Consulte Trabalhando com tabelas para obter mais detalhes.See working with tables for more details.

DelegaçãoDelegation

Quando possível, o PowerApps delegará operações de filtragem e classificação à fonte de dados e à página por meio dos resultados sob demanda.When possible, PowerApps will delegate filter and sort operations to the data source and page through the results on demand. Por exemplo, quando você inicia um aplicativo que mostra um controle Galeria cheio de dados, apenas o primeiro conjunto de registros será inicialmente levado ao dispositivo.For example, when you start an app that shows a Gallery control filled with data, only the first set of records will be initially brought to the device. Conforme o usuário rola, mais dados são desativados da fonte de dados.As the user scrolls, additional data is brought down from the data source. O resultado é uma hora de início mais rápida para o aplicativo e o acesso a grandes conjuntos de dados.The result is a faster start time for the app and access to very large data sets.

No entanto, a delegação talvez nem sempre seja possível.However, delegation may not always be possible. As fontes de dados variam quanto a quais funções e operadores elas dão suporte com a delegação.Data sources vary on what functions and operators they support with delegation. Se a delegação completa de uma fórmula não for possível, o ambiente de criação marcará a parte que não puder ser delegada com um aviso.If complete delegation of a formula isn't possible, the authoring environment will flag the portion that can't be delegated with a warning. Quando possível, considere alterar a fórmula para evitar funções e operadores que não podem ser delegados.When possible, consider changing the formula to avoid functions and operators that can't be delegated. A lista de delegação detalha quais fontes de dados e operações podem ser delegados.The delegation list details which data sources and operations can be delegated.

Se a delegação não for possível, o PowerApps extrairá um pequeno conjunto de registros para trabalhar no local.If delegation is not possible, PowerApps will pull down only a small set of records to work on locally. As funções de filtro e de classificação operarão em um conjunto reduzido de registros.Filter and sort functions will operate on a reduced set of records. O que está disponível na Galeria talvez não seja a história completa, que pode ser confusa para os usuários.What is available in the Gallery may not be the complete story, which could be confusing to users.

Consulte a visão geral de delegação para obter mais informações.See the delegation overview for more information.

SintaxeSyntax

Filter( Table, Formula1 [, Formula2, ... ] )Filter( Table, Formula1 [, Formula2, ... ] )

  • Table – Obrigatório.Table - Required. Tabela para pesquisar.Table to search.
  • Formula(s) – Obrigatório.Formula(s) - Required. A fórmula com a qual cada registro da tabela é avaliado.The formula by which each record of the table is evaluated. A função retorna todos os registros que resultam em true.The function returns all records that result in true. É possível referenciar colunas dentro da tabela.You can reference columns within the table. Se você fornecer mais de uma fórmula, os resultados de todas as fórmulas serão combinados com a função And.If you supply more than one formula, the results of all formulas are combined with the And function.

Search( Table, SearchString, Column1 [, Column2, ... ] )Search( Table, SearchString, Column1 [, Column2, ... ] )

  • Table – Obrigatório.Table - Required. Tabela para pesquisar.Table to search.
  • SearchString – Obrigatório.SearchString - Required. A cadeia de caracteres a ser pesquisada.The string to search for. Se em branco ou uma cadeia de caracteres vazia, todos os registros serão retornados.If blank or an empty string, all records are returned.
  • Column(s) – Obrigatório.Column(s) - Required. Os nomes das colunas na tabela para pesquisar.The names of columns within Table to search. As colunas a serem pesquisadas devem conter o texto.Columns to search must contain text. Nomes de coluna devem ser cadeias de caracteres e estar entre aspas duplas.Column names must be strings and enclosed in double quotes. No entanto, os nomes de coluna devem ser estáticos e não podem ser calculados com uma fórmula.However, the column names must be static and cannot be calculated with a formula. Se SearchString estiver dentro dos dados de qualquer uma dessas colunas como uma correspondência parcial, o registro completo será retornado.If SearchString is found within the data of any of these columns as a partial match, the full record will be returned.

Observação

Nas fontes de dados do Excel e do SharePoint que contêm nomes de colunas com espaços, especifique cada espaço como "_x0020_".For SharePoint and Excel data sources that contain column names with spaces, specify each space as "_x0020_". Por exemplo, especifique "Nome da Coluna" como "Nome_x0020_da_x0020_Coluna".For example, specify "Column Name" as "Column_x0020_Name".

LookUp( Table, Formula [, ReductionFormula ] )LookUp( Table, Formula [, ReductionFormula ] )

  • Table – Obrigatório.Table - Required. Tabela para pesquisar.Table to search. Na interface do usuário, a sintaxe é mostrada como fonte acima da caixa de função.In the UI, the syntax is shown as source above the function box.
  • Formula – Obrigatório.Formula - Required. A fórmula com a qual cada registro da tabela é avaliado.The formula by which each record of the table is evaluated. A função retorna o primeiro registro que resulta em true.The function returns the first record that results in true. É possível referenciar colunas dentro da tabela.You can reference columns within the table. Na interface do usuário, a sintaxe é mostrada como condição acima da caixa de função.In the UI, the syntax is shown as condition above the function box.
  • ReductionFormula – Opcional.ReductionFormula - Optional. Essa fórmula é avaliada em um registro que foi encontrado e, depois, reduz o registro a um único valor.This formula is evaluated over the record that was found, and then reduces the record to a single value. É possível referenciar colunas dentro da tabela.You can reference columns within the table. Se você não usar esse parâmetro, a função retornará o registro completo da tabela.If you don't use this parameter, the function returns the full record from the table. Na interface do usuário, a sintaxe é mostrada como resultado acima da caixa de função.In the UI, the syntax is shown as result above the function box.

ExemplosExamples

Os exemplos a seguir usam a fonte de dados IceCream:The following examples use the IceCream data source:

FórmulaFormula DescriçãoDescription ResultadoResult
Filter( IceCream, OnOrder > 0 )Filter( IceCream, OnOrder > 0 ) Retorna registros em que OnOrder é maior que zero.Returns records where OnOrder is greater than zero.
Filter( IceCream, Quantity + OnOrder > 225 )Filter( IceCream, Quantity + OnOrder > 225 ) Retorna registros em que a soma das colunas Quantity e OnOrder é maior que 225.Returns records where the sum of Quantity and OnOrder columns is greater than 225.
Filter( IceCream, "chocolate" in Lower( Flavor ) )Filter( IceCream, "chocolate" in Lower( Flavor ) ) Retorna registros onde a palavra "chocolate" aparece no nome Flavor, independentemente de letras maiúsculas ou minúsculas.Returns records where the word "chocolate" appears in the Flavor name, independent of uppercase or lowercase letters.
Filter( IceCream, Quantity < 10 && OnOrder < 20 )Filter( IceCream, Quantity < 10 && OnOrder < 20 ) Retorna registros em que Quantity é menor que 10 e OnOrder é menor que 20.Returns records where the Quantity is less than 10 and OnOrder is less than 20. Nenhum registro corresponde a esses critérios, portanto, uma tabela vazia é retornada.No records match these criteria, so an empty table is returned.
Search( IceCream, "choc", "Flavor" )Search( IceCream, "choc", "Flavor" ) Retorna registros em que a cadeia de caracteres "choc" aparece no nome Flavor, independentemente de letras maiúsculas ou minúsculas.Returns records where the string "choc" appears in the Flavor name, independent of uppercase or lowercase letters.
Search( IceCream, "", "Flavor" )Search( IceCream, "", "Flavor" ) Como o termo de pesquisa está vazio, todos os registros são retornados.Because the search term is empty, all records are returned.
LookUp( IceCream, Flavor = "Chocolate", Quantity )LookUp( IceCream, Flavor = "Chocolate", Quantity ) Procura um registro com Flavor igual a "Chocolate", que há um.Searches for a record with Flavor equal to "Chocolate", of which there is one. Para o primeiro registro for encontrado, retorna a Quantity desse registro.For the first record that's found, returns the Quantity of that record. 100100
LookUp( IceCream, Quantity > 150, Quantity + OnOrder )LookUp( IceCream, Quantity > 150, Quantity + OnOrder ) Procura um registro com Quantity maior que 100 e há vários.Searches for a record with Quantity greater than 100, of which there are multiple. Para o primeiro registro encontrado, o que é Flavor "Vanilla", retorna a soma das colunas Quantity e OnOrder.For the first record that's found, which is "Vanilla" Flavor, returns the sum of Quantity and OnOrder columns. 250250
LookUp( IceCream, Flavor = "Pistachio", OnOrder )LookUp( IceCream, Flavor = "Pistachio", OnOrder ) Procura um registro com Flavor igual a "Pistachio", que não há nenhum.Searches for a record with Flavor equal to "Pistachio", of which there are none. Como nenhum foi encontrado, LookUp retorna em branco.Because none were found, Lookup returns blank. em brancoblank
LookUp( IceCream, Flavor = "Vanilla" )LookUp( IceCream, Flavor = "Vanilla" ) Procura um registro com Flavor igual a "Vanilla", que há um.Searches for a record with Flavor equal to "Vanilla", of which there is one. Como nenhuma fórmula de redução foi fornecida, todo o registro é retornado.Since no reduction formula was supplied, the entire record is returned. { Flavor: "Vanilla", Quantity: 200, OnOrder: 75 }{ Flavor: "Vanilla", Quantity: 200, OnOrder: 75 }

Experiência do usuário de pesquisaSearch user experience

Em muitos aplicativos, você pode digitar um ou mais caracteres em uma caixa de pesquisa para filtrar uma lista de registros de um grande conjunto de dados.In many apps, you can type one or more characters into a search box to filter a list of records in a large data set. Conforme você digita, a lista mostra apenas os registros que correspondem aos critérios da pesquisa.As you type, the list shows only those records that match the search criteria.

Os exemplos no restante deste tópico mostram os resultados da pesquisa em uma lista chamada Clientes que contém esses dados:The examples in the rest of this topic show the results of searching a list, named Customers, that contains this data:

Para criar essa fonte de dados como uma coleção, crie um controle Button e defina sua propriedade OnSelect como esta fórmula:To create this data source as a collection, create a Button control and set its OnSelect property to this formula:

ClearCollect( Customers, Table( { Name: "Fred Garcia", Company: "Northwind Traders" }, { Name: "Cole Miller", Company: "Contoso" }, { Name: "Glenda Johnson", Company: "Contoso" }, { Name: "Mike Collins", Company: "Adventure Works" }, { Name: "Colleen Jones", Company: "Adventure Works" } ) )ClearCollect( Customers, Table( { Name: "Fred Garcia", Company: "Northwind Traders" }, { Name: "Cole Miller", Company: "Contoso" }, { Name: "Glenda Johnson", Company: "Contoso" }, { Name: "Mike Collins", Company: "Adventure Works" }, { Name: "Colleen Jones", Company: "Adventure Works" } ) )

Assim como neste exemplo, você pode mostrar uma lista de registros em um Controle de galeria na parte inferior da tela.As in this example, you can show a list of records in a Gallery control at the bottom of a screen. Próximo à parte superior da tela, adicione um controle Entrada de texto, chamado SearchInput, para que os usuários possam especificar quais registros os interessam.Near the top of the screen, you can add a Text input control, named SearchInput, so that users can specify which records interest them.

Conforme o usuário digita os caracteres em SearchInput, os resultados da galeria são filtrados automaticamente.As the user types characters in SearchInput, the results in the gallery are automatically filtered. Nesse caso, a galeria está configurada para mostrar os registros dos quais o nome do cliente (não o nome da empresa) começa com a sequência de caracteres em SearchInput.In this case, the gallery is configured to show records for which the name of the customer (not the name of the company) starts with the sequence of characters in SearchInput. Se o usuário digitar co na caixa de pesquisa, a galeria mostrará estes resultados:If the user types co in the search box, the gallery shows these results:

Para filtrar com base na coluna Name, defina a propriedade Items do controle da galeria como uma destas fórmulas:To filter based on the Name column, set the Items property of the gallery control to one of these formulas:

FórmulaFormula DescriçãoDescription ResultadoResult
Filter( Customers, StartsWith( Name, SearchInput.Text ) )Filter( Customers, StartsWith( Name, SearchInput.Text ) ) Filtra a fonte de dados Clientes em busca de registros nos quais a cadeia de caracteres de pesquisa apareça no início da coluna Name.Filters the Customers data source for records in which the search string appears at the start of the Name column. O teste diferencia maiúsculas de minúsculas.The test is case insensitive. Se o usuário digitar co na caixa de pesquisa, a galeria mostrará Colleen Jones e Cole Miller.If the user types co in the search box, the gallery shows Colleen Jones and Cole Miller. A Galeria não mostra Mike Collins, porque a coluna Name desse registro não começa com a cadeia de caracteres de pesquisa.The gallery doesn't show Mike Collins because the Name column for that record doesn't start with the search string.
Filter( Customers, SearchInput.Text in Name )Filter( Customers, SearchInput.Text in Name ) Filtra a fonte de dados Customers em busca de registros nos quais a cadeia de caracteres de pesquisa apareça em qualquer lugar da coluna Name.Filters the Customers data source for records in which the search string appears anywhere in the Name column. O teste diferencia maiúsculas de minúsculas.The test is case insensitive. Se o usuário digitar co na caixa de pesquisa, a galeria mostrará Colleen Jones, Cole Miller e Mike Collins, pois a cadeia de caracteres de pesquisa aparecerá em algum lugar da coluna Name de todos os registros.If the user types co in the search box, the gallery shows Colleen Jones, Cole Miller, and Mike Collins because the search string appears somewhere in the Name column of all of those records.
Search( Customers, SearchInput.Text, "Name" )Search( Customers, SearchInput.Text, "Name" ) Assim como o operador in, a função Pesquisar procura uma correspondência em qualquer lugar da coluna Name de cada registro.Similar to using the in operator, the Search function searches for a match anywhere within the Name column of each record. Observe que você deve colocar o nome da coluna entre aspas duplas.Note that you must enclose the column name in double quotation marks.

Você pode expandir sua pesquisa para incluir a coluna Company, bem como a coluna Name:You can expand your search to include the Company column as well as the Name column:

FórmulaFormula DescriçãoDescription ResultadoResult
Filter( Customers, StartsWith( Name, SearchInput.Text ) || StartsWith( Company, SearchInput.Text ) )Filter( Customers, StartsWith( Name, SearchInput.Text ) || StartsWith( Company, SearchInput.Text ) ) Filtra a fonte de dados Customers em busca de registros nos quais a coluna Name ou a coluna Company comece com a cadeia de caracteres de pesquisa (por exemplo, co).Filters the Customers data source for records in which either the Name column or the Company column starts with the search string (for example, co). O operador || será true se a função StartsWith for true.The || operator is true if either StartsWith function is true.
Filter( Customers, SearchInput.Text in Name || SearchInput.Text in Company )Filter( Customers, SearchInput.Text in Name || SearchInput.Text in Company ) Filtra a fonte de dados Customers em busca de registros nos quais a coluna Name ou a coluna Company contenham a cadeia de caracteres de pesquisa (por exemplo, co em qualquer lugar).Filters the Customers data source for records in which either the Name column or the Company column contains the search string (for example, co) anywhere within it.
Search( Customers, SearchInput.Text, "Name", "Company" )Search( Customers, SearchInput.Text, "Name", "Company" ) Assim como o operador in, a função Pesquisar pesquisa na fonte de dados Customers por registros nos quais a coluna Name ou a coluna Company contém a cadeia de caracteres de pesquisa (por exemplo, co) em qualquer lugar.Similar to using the in operator, the Search function searches the Customers data source for records in which either the Name column or the Company column contains the search string (for example, co) anywhere within it. A função Pesquisar é mais fácil de ler e gravar do que Filtrar se quiser especificar várias colunas e vários operadores in.The Search function is easier to read and write than Filter if you want to specify multiple columns and multiple in operators. Observe que você deve colocar os nomes de coluna entre aspas duplas.Note that you must enclose the names of the columns in double quotation marks.