Readable conditional filtering
Select rows using readable column expressions.
Pandas · Module
df.query
Filters a DataFrame using a boolean expression written as a string. The expression can use DataFrame columns and configurable evaluation context, parser, and engine settings.
How it works
DataFrame.query evaluates a string expression against a DataFrame's columns and returns the matching rows. Its parser and evaluation engine are configurable; external variables can be supplied through the evaluation context, and inplace=True updates the existing frame instead of returning a new one.
Syntax
DataFrame.query(expr, *, parser='pandas', engine=None, local_dict=None, global_dict=None, resolvers=None, level=0, inplace=False)Parameters
| Name | Type | Description |
|---|---|---|
expr | str | Query string to evaluate against the DataFrame. |
parser | {'pandas', 'python'}, default 'pandas' | Expression parser: 'pandas' or 'python'; defaults to 'pandas'. |
engine | {'python', 'numexpr'}, default None | Evaluation engine: 'python', 'numexpr', or None; defaults to None. |
local_dict | dict or None, optional | Mapping of local variables used while evaluating the expression. |
global_dict | dict or None, optional | Mapping of global variables used while evaluating the expression. |
resolvers | list-like, optional | Additional resolvers used during expression evaluation. |
level | int, default 0 | Stack level used to resolve variables. |
inplace | bool, default False | Whether to modify this DataFrame instead of creating a new one. |
Returns
DataFrame or None: the DataFrame produced by the query, or None when inplace=True.
Key points
- Use query to select rows whose DataFrame-column expression evaluates as true.
- The required expr argument is the string containing the row-selection expression.
- parser chooses how pandas constructs the expression syntax tree; supported choices are 'pandas' and 'python'.
- engine selects the evaluator, with None allowing pandas to try numexpr before Python.
- local_dict supplies names from a local mapping, defaulting to the current local variables.
- global_dict supplies names from a global mapping, defaulting to the current global variables.
Common mistakes
- The default parser does not follow strict Python parsing rules; select parser='python' when strict Python semantics are required.
- When inplace=True, the method mutates the DataFrame and returns None rather than a result frame.
Example: Filter rows with an external value
import pandas as pd
orders = pd.DataFrame({
"customer": ["A", "B", "A"],
"amount": [120, 80, 200],
})
minimum = 100
selected = orders.query("amount >= @minimum")
print(selected)Filters rows with an expression, while @minimum refers to a Python variable outside the DataFrame.
When to use it
Filter with external variables
Reuse a threshold or other runtime value in a filter.
In-place filtering
Apply the selection directly to an existing frame.
Interview questions
QWhat does DataFrame.query do?
The method accepts a string expression and evaluates it against DataFrame columns, returning the filtered DataFrame. By default it uses the pandas parser and chooses an evaluation engine automatically.
Follow-up: How would you preserve strict Python expression semantics? Set parser='python' and, when needed, choose engine='python'.
QHow can query use values outside the DataFrame?
Use @ before a name in the expression to refer to a variable from the surrounding evaluation environment, such as query('amount >= @minimum'). The expression itself remains a string.
Follow-up: How can the available external names be controlled? Provide local_dict or global_dict mappings to define the evaluation context.
QWhat are parser and engine used for?
The engine controls expression evaluation. With engine=None, pandas tries numexpr and falls back to Python; engine='numexpr' can accelerate complex expressions on large frames.
Follow-up: What happens when inplace=True? The matching rows are applied to the existing DataFrame and the return value is None.
Related
pandas.DataFrame.evalpandas.eval