pandas.DataFrame.query#

DataFrame.query(expr,*,inplace=False,**kwargs)[source]#

Query the columns of a DataFrame with a boolean expression.

Parameters:

exprstr

The query string to evaluate.

You can refer to variablesin the environment by prefixing them with an ‘@’ character like@a+b.

You can refer to column names that are not valid Python variable namesby surrounding them in backticks. Thus, column names containing spacesor punctuations (besides underscores) or starting with digits must besurrounded by backticks. (For example, a column named “Area (cm^2)” wouldbe referenced as`Area(cm^2)`). Column names which are Python keywords(like “list”, “for”, “import”, etc) cannot be used.

For example, if one of your columns is calledaa and you wantto sum it withb, your query should be`aa`+b.

inplacebool

Whether to modify the DataFrame rather than creating a new one.

**kwargs

See the documentation foreval() for complete detailson the keyword arguments accepted byDataFrame.query().

Returns:

DataFrame or None

DataFrame resulting from the provided query expression orNone ifinplace=True.

See also

eval

Evaluate a string describing operations on DataFrame columns.

DataFrame.eval

Evaluate a string describing operations on DataFrame columns.

Notes

The result of the evaluation of this expression is first passed toDataFrame.loc and if that fails because of amultidimensional key (e.g., a DataFrame) then the result will be passedtoDataFrame.__getitem__().

This method uses the top-leveleval() function toevaluate the passed query.

Thequery() method uses a slightlymodified Python syntax by default. For example, the& and|(bitwise) operators have the precedence of their boolean cousins,and andor. Thisis syntactically valid Python,however the semantics are different.

You can change the semantics of the expression by passing the keywordargumentparser='python'. This enforces the same semantics asevaluation in Python space. Likewise, you can passengine='python'to evaluate an expression using Python itself as a backend. This is notrecommended as it is inefficient compared to usingnumexpr as theengine.

TheDataFrame.index andDataFrame.columns attributes of theDataFrame instance are placed in the query namespaceby default, which allows you to treat both the index and columns of theframe as a column in the frame.The identifierindex is used for the frame index; you can alsouse the name of the index to identify it in a query. Please note thatPython keywords may not be used as identifiers.

For further details and examples see thequery documentation inindexing.

Backtick quoted variables

Backtick quoted variables are parsed as literal Python code andare converted internally to a Python valid identifier.This can lead to the following problems.

During parsing a number of disallowed characters inside the backtickquoted string are replaced by strings that are allowed as a Python identifier.These characters include all operators in Python, the space character, thequestion mark, the exclamation mark, the dollar sign, and the euro sign.For other characters that fall outside the ASCII range (U+0001..U+007F)and those that are not further specified in PEP 3131,the query parser will raise an error.This excludes whitespace different than the space character,but also the hashtag (as it is used for comments) and the backtickitself (backtick can also not be escaped).

In a special case, quotes that make a pair around a backtick canconfuse the parser.For example,`it's`>`that's` will raise an error,as it forms a quoted string ('s>`that') with a backtick inside.

See also the Python documentation about lexical analysis(https://docs.python.org/3/reference/lexical_analysis.html)in combination with the source code inpandas.core.computation.parsing.

Examples

>>>df=pd.DataFrame({'A':range(1,6),...'B':range(10,0,-2),...'C C':range(10,5,-1)})>>>df   A   B  C C0  1  10   101  2   8    92  3   6    83  4   4    74  5   2    6>>>df.query('A > B')   A  B  C C4  5  2    6

The previous expression is equivalent to

>>>df[df.A>df.B]   A  B  C C4  5  2    6

For columns with spaces in their name, you can use backtick quoting.

>>>df.query('B == `C C`')   A   B  C C0  1  10   10

The previous expression is equivalent to

>>>df[df.B==df['C C']]   A   B  C C0  1  10   10