O método query()

A indexação booleana do Pandas é poderosa, mas pode ficar prolixa ao combinar muitas condições. O método query() permite escrever expressões de filtro como strings simples, o que muitas pessoas consideram mais legível — especialmente quem vem de uma experiência com SQL. Em vez de df[(df['age'] > 30) & (df['salary'] > 50000)], escreva df.query('age > 30 and salary > 50000').

A string da consulta é avaliada com base nos nomes das colunas do DataFrame, portanto os nomes das colunas funcionam como nomes de variáveis dentro da string.

Dentro de uma string de consulta, você pode usar os operadores de comparação padrão do Python (>, <, ==, !=, >=, <=) e os conectores lógicos and, or, not. Diferentemente da indexação booleana comum, aqui você pode usar as palavras em inglês — não é necessário usar e comerciais ou barras verticais.

Nomes de colunas com espaços ou que entrem em conflito com palavras-chave do Python devem ser delimitados por crases: df.query('`first name` == "Alice"').

Um recurso importante de query() é a possibilidade de referenciar variáveis do Python do escopo ao redor usando o prefixo @. Isso facilita a parametrização de filtros: calcule um limite, armazene-o em uma variável e use @variable_name dentro da string da consulta em vez de inserir o valor diretamente.

Esse padrão é muito útil em funções que aceitam argumentos de filtro durante a execução.

Como query() retorna um novo DataFrame, você pode encadear várias chamadas de query ou combiná-las com outros métodos do Pandas em um pipeline. O encadeamento mantém cada etapa de filtragem em sua própria linha, facilitando a leitura, a depuração e a modificação da lógica.

Você também pode encadear query() com métodos como .groupby(), .sort_values() ou .head() para criar pipelines de análise concisos.

Ambos os métodos produzem o mesmo resultado, mas cada um é adequado a uma situação. query() é excelente para filtros com várias condições que exigiriam muitos parênteses na indexação booleana. A indexação booleana é melhor quando sua condição envolve expressões complexas do Python, como chamadas de métodos que não são compatíveis com strings de consulta.

O desempenho é semelhante na maioria dos casos; query() pode ser um pouco mais rápido em DataFrames muito grandes porque usa a biblioteca numexpr internamente.

Você pode filtrar valores de colunas de strings dentro de uma string de consulta colocando o literal de string entre aspas. Use aspas duplas para a string de consulta externa e aspas simples para o valor da string, ou vice-versa — basta manter a consistência. Observe que query() não oferece suporte a métodos .str, como contains(); nesses casos, use a indexação booleana com .str.

Dentro das strings de consulta, o Pandas oferece suporte aos operadores in e not in para testes de pertencimento, de forma semelhante às listas do Python. Essa é uma alternativa clara ao encadeamento de várias condições == com or. A lista de valores é escrita diretamente na string da consulta.

As comparações encadeadas do Python, como 10 < price < 500, funcionam dentro de strings de consulta, tornando os filtros de intervalo muito expressivos. Isso não é possível com a indexação booleana padrão sem usar between() ou duas condições separadas combinadas com &.

query() é poderoso, mas tem algumas limitações. Nomes de colunas com espaços ou caracteres especiais precisam ser delimitados por crases. Expressões muito complexas do Python, como funções personalizadas e lógica distribuída em várias linhas, não são compatíveis dentro da string. Além disso, query() pode produzir resultados inesperados se os nomes das colunas entrarem em conflito com palavras-chave do Python, como class ou if — delimite esses nomes com crases também.

Para qualquer situação que query() não consiga expressar de forma clara, recorra à indexação booleana padrão.

Aqui está uma demonstração prática que combina query() com uma referência a uma variável e um encadeamento até um groupby. Esse padrão — filtrar primeiro e agregar depois — evita processar linhas desnecessárias, o que é mais claro e mais rápido em grandes conjuntos de dados.

Usar query() dentro de um encadeamento de métodos é uma prática recomendada no código moderno do Pandas. Isso torna cada etapa do pipeline de transformação clara e autodocumentada. Coloque todo o encadeamento entre parênteses para poder dividi-lo em várias linhas sem barras invertidas.

Combine query() com assign() para adicionar colunas, groupby() para agregações e pipe() para funções personalizadas, criando pipelines totalmente legíveis.

Nesta lição, você aprendeu que: query() aceita expressões de filtro como strings, tornando os filtros com várias condições mais legíveis; @variable_name insere variáveis do Python na consulta; e é possível usar in/not in e comparações encadeadas, algo que não é possível com a indexação booleana padrão. A seguir, exploraremos isin() e between() para criar filtros concisos de pertencimento e intervalo.