Class: QgsExpressionNode

class qgis.core.QgsExpressionNode

Bases: sip.wrapper

Abstract base class for all nodes that can appear in an expression.

QgsExpressionNode() Constructor.

QgsExpressionNode(other: QgsExpressionNode) Copy constructor

Methods

cachedStaticValue

Returns the node's static cached value.

clone

Generate a clone of this node.

dump

Dump this node into a serialized (part) of an expression.

effectiveNode

Returns a reference to the simplest node which represents this node, after any compilation optimizations have been applied.

eval

Evaluate this node with the given context and parent.

hasCachedStaticValue

Returns True if the node can be replaced by a static cached value.

isStatic

Returns True if this node can be evaluated for a static value.

needsGeometry

Abstract virtual method which returns if the geometry is required to evaluate this expression.

nodeType

Gets the type of this node.

prepare

Prepare this node for evaluation.

referencedColumns

Abstract virtual method which returns a list of columns required to evaluate this node.

referencedFunctions

Returns a set of all functions which are used in this expression.

referencedVariables

Returns a set of all variables which are used in this expression.

Attributes

ntBetweenOperator

ntBinaryOperator

ntColumnRef

ntCondition

ntFunction

ntInOperator

ntIndexOperator

ntLiteral

ntUnaryOperator

class NamedNode(name: str, node: QgsExpressionNode)

Bases: sip.wrapper

Constructor for NamedNode

Parameters:
  • name – node name

  • node – node

QgsExpressionNode.NamedNode(QgsExpressionNode.NamedNode)

name
node
class NodeList

Bases: sip.wrapper

A list of expression nodes.

append(self, node: QgsExpressionNode)

Takes ownership of the provided node

append(self, node: QgsExpressionNode.NamedNode) Adds a named node. Takes ownership of the provided node.

New in version 2.16.

Parameters:

node (QgsExpressionNode) –

at(self, i: int) QgsExpressionNode

Gets the node at position i in the list.

New in version 3.0.

Parameters:

i (int) –

Return type:

QgsExpressionNode

clone(self) QgsExpressionNode.NodeList

Creates a deep copy of this list. Ownership is transferred to the caller

Return type:

QgsExpressionNode.NodeList

count(self) int

Returns the number of nodes in the list.

Return type:

int

dump(self) str

Returns a string dump of the expression node.

Return type:

str

hasNamedNodes(self) bool

Returns True if list contains any named nodes

New in version 2.16.

Return type:

bool

list(self) List[QgsExpressionNode]

Gets a list of all the nodes.

Return type:

List[QgsExpressionNode]

names(self) List[str]

Returns a list of names for nodes. Unnamed nodes will be indicated by an empty string in the list.

New in version 2.16.

Return type:

List[str]

class NodeType

Bases: int

cachedStaticValue(self) Any

Returns the node’s static cached value. Only valid if hasCachedStaticValue() is True.

New in version 3.18.

Return type:

Any

clone(self) QgsExpressionNode

Generate a clone of this node. Ownership is transferred to the caller.

Return type:

QgsExpressionNode

Returns:

a deep copy of this node.

dump(self) str

Dump this node into a serialized (part) of an expression. The returned expression does not necessarily literally match the original expression, it’s just guaranteed to behave the same way.

Return type:

str

effectiveNode(self) QgsExpressionNode

Returns a reference to the simplest node which represents this node, after any compilation optimizations have been applied.

Eg. a node like “CASE WHEN true THEN “some_field” WHEN other condition THEN … END” can effectively be replaced entirely by a QgsExpressionNodeColumnRef referencing the “some_field” field, as the CASE WHEN … will ALWAYS evaluate to “some_field”.

Returns a reference to the current object if no optimizations were applied.

New in version 3.20.

Return type:

QgsExpressionNode

eval(self, parent: QgsExpression, context: QgsExpressionContext) Any

Evaluate this node with the given context and parent. This will return a cached value if it has been determined to be static during the prepare() execution.

New in version 2.12.

Parameters:
Return type:

Any

hasCachedStaticValue(self) bool

Returns True if the node can be replaced by a static cached value.

New in version 3.18.

Return type:

bool

isStatic(self, parent: QgsExpression, context: QgsExpressionContext) bool

Returns True if this node can be evaluated for a static value. This is used during the prepare() step and in case it returns True, the value of this node will already be evaluated and the result cached (and therefore not re-evaluated in subsequent calls to eval()). In case this returns True, prepareNode() will never be called.

New in version 3.0.

Parameters:
Return type:

bool

needsGeometry(self) bool

Abstract virtual method which returns if the geometry is required to evaluate this expression.

This needs to call :py:func:`~QgsExpressionNode.needsGeometry` recursively on any child nodes.

Return type:

bool

Returns:

True if a geometry is required to evaluate this expression

nodeType(self) QgsExpressionNode.NodeType

Gets the type of this node.

Return type:

QgsExpressionNode.NodeType

Returns:

The type of this node

ntBetweenOperator = 8
ntBinaryOperator = 1
ntColumnRef = 5
ntCondition = 6
ntFunction = 3
ntInOperator = 2
ntIndexOperator = 7
ntLiteral = 4
ntUnaryOperator = 0
parserFirstColumn
parserFirstLine
parserLastColumn
parserLastLine
prepare(self, parent: QgsExpression, context: QgsExpressionContext) bool

Prepare this node for evaluation. This will check if the node content is static and in this case cache the value. If it’s not static it will call prepareNode() to allow the node to do initialization work like for example resolving a column name to an attribute index.

New in version 2.12.

Parameters:
Return type:

bool

referencedColumns(self) Set[str]

Abstract virtual method which returns a list of columns required to evaluate this node.

When reimplementing this, you need to return any column that is required to evaluate this node and in addition recursively collect all the columns required to evaluate child nodes.

Warning

If the expression has been prepared via a call to QgsExpression.prepare(), or a call to QgsExpressionNode.prepare() for a node has been made, then some nodes in the expression may have been determined to evaluate to a static pre-calculatable value. In this case the results will omit attribute indices which are used by these pre-calculated nodes, regardless of their actual referenced columns. If you are seeking to use these functions to introspect an expression you must take care to do this with an unprepared expression node.

Return type:

Set[str]

Returns:

A list of columns required to evaluate this expression

referencedFunctions(self) Set[str]

Returns a set of all functions which are used in this expression.

Note

In contrast to the referencedColumns() function this method is not affected by any previous calls to QgsExpressionNode.prepare().

Return type:

Set[str]

referencedVariables(self) Set[str]

Returns a set of all variables which are used in this expression.

Note

In contrast to the referencedColumns() function this method is not affected by any previous calls to QgsExpressionNode.prepare().

Return type:

Set[str]