This class wraps a request for features to a vector layer (or directly its vector data provider). More...

#include <qgsfeaturerequest.h>

Classes
class	OrderBy
	Represents a list of OrderByClauses, with the most important first and the least important last. More...

class	OrderByClause
	The OrderByClause class represents an order by clause for a QgsFeatureRequest. More...

Public Types
enum	FilterType { FilterNone, FilterRect, FilterFid, FilterExpression, FilterFids }
	Types of filters. More...

enum	Flag { NoFlags = 0, NoGeometry = 1, SubsetOfAttributes = 2, ExactIntersect = 4 }

Public Member Functions
	QgsFeatureRequest ()
	construct a default request: for all features get attributes and geometries More...

	QgsFeatureRequest (QgsFeatureId fid)
	construct a request with feature ID filter More...

	QgsFeatureRequest (const QgsRectangle &rect)
	construct a request with rectangle filter More...

	QgsFeatureRequest (const QgsExpression &expr, const QgsExpressionContext &context=QgsExpressionContext())
	construct a request with a filter expression More...

	QgsFeatureRequest (const QgsFeatureRequest &rh)
	copy constructor More...

	~QgsFeatureRequest ()

bool	acceptFeature (const QgsFeature &feature)
	Check if a feature is accepted by this requests filter. More...

QgsFeatureRequest &	addOrderBy (const QString &expression, bool ascending=true)
	Adds a new OrderByClause, appending it as the least important one. More...

QgsFeatureRequest &	addOrderBy (const QString &expression, bool ascending, bool nullsfirst)
	Adds a new OrderByClause, appending it as the least important one. More...

QgsFeatureRequest &	combineFilterExpression (const QString &expression)
	Modifies the existing filter expression to add an additional expression filter. More...

QgsFeatureRequest &	disableFilter ()
	Disables filter conditions. More...

QgsExpressionContext *	expressionContext ()
	Returns the expression context used to evaluate filter expressions. More...

QgsExpression *	filterExpression () const
	Returns the filter expression if set. More...

QgsFeatureId	filterFid () const
	Get the feature ID that should be fetched. More...

const QgsFeatureIds &	filterFids () const
	Get feature IDs that should be fetched. More...

const QgsRectangle &	filterRect () const
	Get the rectangle from which features will be taken. More...

FilterType	filterType () const
	Return the filter type which is currently set on this request. More...

const Flags &	flags () const

long	limit () const
	Returns the maximum number of features to request, or -1 if no limit set. More...

QgsFeatureRequest &	operator= (const QgsFeatureRequest &rh)
	Assignment operator. More...

OrderBy	orderBy () const
	Return a list of order by clauses specified for this feature request. More...

QgsFeatureRequest &	setExpressionContext (const QgsExpressionContext &context)
	Sets the expression context used to evaluate filter expressions. More...

QgsFeatureRequest &	setFilterExpression (const QString &expression)
	Set the filter expression. More...

QgsFeatureRequest &	setFilterFid (QgsFeatureId fid)
	Set feature ID that should be fetched. More...

QgsFeatureRequest &	setFilterFids (const QgsFeatureIds &fids)
	Set feature IDs that should be fetched. More...

QgsFeatureRequest &	setFilterRect (const QgsRectangle &rect)
	Set rectangle from which features will be taken. More...

QgsFeatureRequest &	setFlags (const QgsFeatureRequest::Flags &flags)
	Set flags that affect how features will be fetched. More...

QgsFeatureRequest &	setLimit (long limit)
	Set the maximum number of features to request. More...

QgsFeatureRequest &	setOrderBy (const OrderBy &orderBy)
	Set a list of order by clauses. More...

QgsFeatureRequest &	setSimplifyMethod (const QgsSimplifyMethod &simplifyMethod)
	Set a simplification method for geometries that will be fetched. More...

QgsFeatureRequest &	setSubsetOfAttributes (const QgsAttributeList &attrs)
	Set a subset of attributes that will be fetched. More...

QgsFeatureRequest &	setSubsetOfAttributes (const QStringList &attrNames, const QgsFields &fields)
	Set a subset of attributes by names that will be fetched. More...

const QgsSimplifyMethod &	simplifyMethod () const
	Get simplification method for geometries that will be fetched. More...

QgsAttributeList	subsetOfAttributes () const
	Return the subset of attributes which at least need to be fetched. More...

Static Public Attributes
static const QString	AllAttributes = QString( "#!allattributes!#" )
	A special attribute that if set matches all attributes. More...

Protected Attributes
QgsAttributeList	mAttrs

QgsExpressionContext	mExpressionContext

FilterType	mFilter

QgsExpression *	mFilterExpression

QgsFeatureId	mFilterFid

QgsFeatureIds	mFilterFids

QgsRectangle	mFilterRect

Flags	mFlags

long	mLimit

OrderBy	mOrderBy

QgsSimplifyMethod	mSimplifyMethod

Detailed Description

This class wraps a request for features to a vector layer (or directly its vector data provider).

The request may apply a filter to fetch only a particular subset of features. Currently supported filters:

no filter - all features are returned
feature id - only feature that matches given feature id is returned
feature ids - only features that match any of the given feature ids are returned
filter expression - only features that match the given filter expression are returned

Additionally a spatial rectangle can be set in combination: Only features that intersect given rectangle should be fetched. For the sake of speed, the intersection is often done only using feature's bounding box. There is a flag ExactIntersect that makes sure that only intersecting features will be returned.

For efficiency, it is also possible to tell provider that some data is not required:

NoGeometry flag
SubsetOfAttributes flag
SimplifyMethod for geometries to fetch

The options may be chained, e.g.: QgsFeatureRequest().setFilterRect(QgsRectangle(0,0,1,1)).setFlags(QgsFeatureRequest::ExactIntersect)

Examples:

fetch all features: QgsFeatureRequest()
fetch all features, only one attribute QgsFeatureRequest().setSubsetOfAttributes(QStringList("myfield"), provider->fieldMap())
fetch all features, without geometries QgsFeatureRequest().setFlags(QgsFeatureRequest::NoGeometry)
fetch only features from particular extent QgsFeatureRequest().setFilterRect(QgsRectangle(0,0,1,1))
fetch only one feature QgsFeatureRequest().setFilterFid(45)

Definition at line 63 of file qgsfeaturerequest.h.

Member Enumeration Documentation

◆ FilterType

enum QgsFeatureRequest::FilterType

Types of filters.

Enumerator
FilterNone	No filter is applied.
FilterRect	Obsolete, will be ignored. If a filterRect is set it will be used anyway. Filter using a rectangle, no need to set NoGeometry. Instead check for request.filterRect().isNull()
FilterFid	Filter using feature ID.
FilterExpression	Filter using expression.
FilterFids	Filter using feature IDs.

Definition at line 78 of file qgsfeaturerequest.h.

◆ Flag

enum QgsFeatureRequest::Flag

Enumerator
NoFlags
NoGeometry	Geometry is not required. It may still be returned if e.g. required for a filter condition.
SubsetOfAttributes	Fetch only a subset of attributes (setSubsetOfAttributes sets this flag)
ExactIntersect	Use exact geometry intersection (slower) instead of bounding boxes.

Definition at line 66 of file qgsfeaturerequest.h.

Constructor & Destructor Documentation

◆ QgsFeatureRequest() [1/5]

QgsFeatureRequest::QgsFeatureRequest ( )

construct a default request: for all features get attributes and geometries

Definition at line 25 of file qgsfeaturerequest.cpp.

◆ QgsFeatureRequest() [2/5]

QgsFeatureRequest::QgsFeatureRequest ( QgsFeatureId fid )

explicit

construct a request with feature ID filter

Definition at line 34 of file qgsfeaturerequest.cpp.

◆ QgsFeatureRequest() [3/5]

QgsFeatureRequest::QgsFeatureRequest ( const QgsRectangle & rect )

explicit

construct a request with rectangle filter

Definition at line 43 of file qgsfeaturerequest.cpp.

◆ QgsFeatureRequest() [4/5]

QgsFeatureRequest::QgsFeatureRequest	(	const QgsExpression &	expr,
		const QgsExpressionContext &	context = `QgsExpressionContext()`
	)

explicit

construct a request with a filter expression

Definition at line 53 of file qgsfeaturerequest.cpp.

◆ QgsFeatureRequest() [5/5]

QgsFeatureRequest::QgsFeatureRequest ( const QgsFeatureRequest & rh )

copy constructor

Definition at line 63 of file qgsfeaturerequest.cpp.

◆ ~QgsFeatureRequest()

QgsFeatureRequest::~QgsFeatureRequest ( )

Definition at line 91 of file qgsfeaturerequest.cpp.

Member Function Documentation

◆ acceptFeature()

bool QgsFeatureRequest::acceptFeature ( const QgsFeature & feature )

Check if a feature is accepted by this requests filter.

Parameters

feature The feature which will be tested

Returns: true, if the filter accepts the feature

Note: added in 2.1

Definition at line 214 of file qgsfeaturerequest.cpp.

◆ addOrderBy() [1/2]

QgsFeatureRequest & QgsFeatureRequest::addOrderBy	(	const QString &	expression,
		bool	ascending = `true`
	)

Adds a new OrderByClause, appending it as the least important one.

Parameters

expression	The expression to use for ordering
ascending	If the order should be ascending (1,2,3) or descending (3,2,1) If the order is ascending, by default nulls are last If the order is descending, by default nulls are first

Note: added in QGIS 2.14

Definition at line 145 of file qgsfeaturerequest.cpp.

◆ addOrderBy() [2/2]

QgsFeatureRequest & QgsFeatureRequest::addOrderBy	(	const QString &	expression,
		bool	ascending,
		bool	nullsfirst
	)

Adds a new OrderByClause, appending it as the least important one.

Parameters

expression	The expression to use for ordering
ascending	If the order should be ascending (1,2,3) or descending (3,2,1)
nullsfirst	If true, NULLS are at the beginning, if false, NULLS are at the end

Note: added in QGIS 2.14

Definition at line 151 of file qgsfeaturerequest.cpp.

◆ combineFilterExpression()

QgsFeatureRequest & QgsFeatureRequest::combineFilterExpression ( const QString & expression )

Modifies the existing filter expression to add an additional expression filter.

The filter expressions are combined using AND, so only features matching both the existing expression and the additional expression will be returned.

Note: added in QGIS 2.14

Definition at line 126 of file qgsfeaturerequest.cpp.

◆ disableFilter()

QgsFeatureRequest& QgsFeatureRequest::disableFilter ( )

inline

Disables filter conditions.

The spatial filter (filterRect) will be kept in place.

Returns: The object the method is called on for chaining

Note: Added in 2.12

Definition at line 310 of file qgsfeaturerequest.h.

◆ expressionContext()

QgsExpressionContext* QgsFeatureRequest::expressionContext ( )

inline

Returns the expression context used to evaluate filter expressions.

Note: added in QGIS 2.12

See also: setExpressionContext; filterExpression

Definition at line 293 of file qgsfeaturerequest.h.

◆ filterExpression()

QgsExpression* QgsFeatureRequest::filterExpression ( ) const

inline

Returns the filter expression if set.

See also: setFilterExpression; expressionContext

Definition at line 279 of file qgsfeaturerequest.h.

◆ filterFid()

QgsFeatureId QgsFeatureRequest::filterFid ( ) const

inline

Get the feature ID that should be fetched.

Definition at line 261 of file qgsfeaturerequest.h.

◆ filterFids()

const QgsFeatureIds& QgsFeatureRequest::filterFids ( ) const

inline

Get feature IDs that should be fetched.

Definition at line 266 of file qgsfeaturerequest.h.

◆ filterRect()

const QgsRectangle& QgsFeatureRequest::filterRect ( ) const

inline

Get the rectangle from which features will be taken.

Definition at line 256 of file qgsfeaturerequest.h.

◆ filterType()

FilterType QgsFeatureRequest::filterType ( ) const

inline

Return the filter type which is currently set on this request.

Returns: Filter type

Definition at line 246 of file qgsfeaturerequest.h.

◆ flags()

const Flags& QgsFeatureRequest::flags ( ) const

inline

Definition at line 364 of file qgsfeaturerequest.h.

◆ limit()

long QgsFeatureRequest::limit ( ) const

inline

Returns the maximum number of features to request, or -1 if no limit set.

See also: setLimit

Note: added in QGIS 2.14

Definition at line 360 of file qgsfeaturerequest.h.

◆ operator=()

QgsFeatureRequest & QgsFeatureRequest::operator= ( const QgsFeatureRequest & rh )

Assignment operator.

Definition at line 68 of file qgsfeaturerequest.cpp.

◆ orderBy()

QgsFeatureRequest::OrderBy QgsFeatureRequest::orderBy ( ) const

Return a list of order by clauses specified for this feature request.

Note: added in 2.14

Definition at line 157 of file qgsfeaturerequest.cpp.

◆ setExpressionContext()

QgsFeatureRequest & QgsFeatureRequest::setExpressionContext ( const QgsExpressionContext & context )

Sets the expression context used to evaluate filter expressions.

Note: added in QGIS 2.12

See also: expressionContext; setFilterExpression

Definition at line 139 of file qgsfeaturerequest.cpp.

◆ setFilterExpression()

QgsFeatureRequest & QgsFeatureRequest::setFilterExpression ( const QString & expression )

Set the filter expression.

{

See also: QgsExpression}

Parameters

expression expression string

See also: filterExpression; setExpressionContext

Definition at line 118 of file qgsfeaturerequest.cpp.

◆ setFilterFid()

QgsFeatureRequest & QgsFeatureRequest::setFilterFid ( QgsFeatureId fid )

Set feature ID that should be fetched.

Definition at line 104 of file qgsfeaturerequest.cpp.

◆ setFilterFids()

QgsFeatureRequest & QgsFeatureRequest::setFilterFids ( const QgsFeatureIds & fids )

Set feature IDs that should be fetched.

Definition at line 111 of file qgsfeaturerequest.cpp.

◆ setFilterRect()

QgsFeatureRequest & QgsFeatureRequest::setFilterRect ( const QgsRectangle & rect )

Set rectangle from which features will be taken.

Empty rectangle removes the filter.

Definition at line 96 of file qgsfeaturerequest.cpp.

◆ setFlags()

QgsFeatureRequest & QgsFeatureRequest::setFlags ( const QgsFeatureRequest::Flags & flags )

Set flags that affect how features will be fetched.

Definition at line 174 of file qgsfeaturerequest.cpp.

◆ setLimit()

QgsFeatureRequest & QgsFeatureRequest::setLimit ( long limit )

Set the maximum number of features to request.

Parameters

limit maximum number of features, or -1 to request all features.

See also: limit()

Note: added in QGIS 2.14

Definition at line 168 of file qgsfeaturerequest.cpp.

◆ setOrderBy()

QgsFeatureRequest & QgsFeatureRequest::setOrderBy ( const OrderBy & orderBy )

Set a list of order by clauses.

Note: added in 2.14

Definition at line 162 of file qgsfeaturerequest.cpp.

◆ setSimplifyMethod()

QgsFeatureRequest & QgsFeatureRequest::setSimplifyMethod ( const QgsSimplifyMethod & simplifyMethod )

Set a simplification method for geometries that will be fetched.

Note: added in 2.2

Definition at line 208 of file qgsfeaturerequest.cpp.

◆ setSubsetOfAttributes() [1/2]

QgsFeatureRequest & QgsFeatureRequest::setSubsetOfAttributes ( const QgsAttributeList & attrs )

Set a subset of attributes that will be fetched.

Empty list means that all attributes are used. To disable fetching attributes, reset the FetchAttributes flag (which is set by default)

Definition at line 180 of file qgsfeaturerequest.cpp.

◆ setSubsetOfAttributes() [2/2]

QgsFeatureRequest & QgsFeatureRequest::setSubsetOfAttributes	(	const QStringList &	attrNames,
		const QgsFields &	fields
	)

Set a subset of attributes by names that will be fetched.

Definition at line 187 of file qgsfeaturerequest.cpp.

◆ simplifyMethod()

const QgsSimplifyMethod& QgsFeatureRequest::simplifyMethod ( ) const

inline

Get simplification method for geometries that will be fetched.

Note: added in 2.2

Definition at line 383 of file qgsfeaturerequest.h.

◆ subsetOfAttributes()

QgsAttributeList QgsFeatureRequest::subsetOfAttributes ( ) const

inline

Return the subset of attributes which at least need to be fetched.

Returns: A list of attributes to be fetched

Definition at line 373 of file qgsfeaturerequest.h.

Member Data Documentation

◆ AllAttributes

const QString QgsFeatureRequest::AllAttributes = QString( "#!allattributes!#" )

static

A special attribute that if set matches all attributes.

Definition at line 224 of file qgsfeaturerequest.h.

◆ mAttrs

QgsAttributeList QgsFeatureRequest::mAttrs

protected

Definition at line 407 of file qgsfeaturerequest.h.

◆ mExpressionContext

QgsExpressionContext QgsFeatureRequest::mExpressionContext

protected

Definition at line 405 of file qgsfeaturerequest.h.

◆ mFilter

FilterType QgsFeatureRequest::mFilter

protected

Definition at line 400 of file qgsfeaturerequest.h.

◆ mFilterExpression

QgsExpression* QgsFeatureRequest::mFilterExpression

protected

Definition at line 404 of file qgsfeaturerequest.h.

◆ mFilterFid

QgsFeatureId QgsFeatureRequest::mFilterFid

protected

Definition at line 402 of file qgsfeaturerequest.h.

◆ mFilterFids

QgsFeatureIds QgsFeatureRequest::mFilterFids

protected

Definition at line 403 of file qgsfeaturerequest.h.

◆ mFilterRect

QgsRectangle QgsFeatureRequest::mFilterRect

protected

Definition at line 401 of file qgsfeaturerequest.h.

◆ mFlags

Flags QgsFeatureRequest::mFlags

protected

Definition at line 406 of file qgsfeaturerequest.h.

◆ mLimit

long QgsFeatureRequest::mLimit

protected

Definition at line 409 of file qgsfeaturerequest.h.

◆ mOrderBy

OrderBy QgsFeatureRequest::mOrderBy

protected

Definition at line 410 of file qgsfeaturerequest.h.

◆ mSimplifyMethod

QgsSimplifyMethod QgsFeatureRequest::mSimplifyMethod

protected

Definition at line 408 of file qgsfeaturerequest.h.

The documentation for this class was generated from the following files:

/tmp/buildd/qgis-2.18.21+99unstable/src/core/qgsfeaturerequest.h
/tmp/buildd/qgis-2.18.21+99unstable/src/core/qgsfeaturerequest.cpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ FilterType

◆ Flag

Constructor & Destructor Documentation

◆ QgsFeatureRequest() [1/5]

◆ QgsFeatureRequest() [2/5]

◆ QgsFeatureRequest() [3/5]

◆ QgsFeatureRequest() [4/5]

◆ QgsFeatureRequest() [5/5]

◆ ~QgsFeatureRequest()

Member Function Documentation

◆ acceptFeature()

◆ addOrderBy() [1/2]

◆ addOrderBy() [2/2]

◆ combineFilterExpression()

◆ disableFilter()

◆ expressionContext()

◆ filterExpression()

◆ filterFid()

◆ filterFids()

◆ filterRect()

◆ filterType()

◆ flags()

◆ limit()

◆ operator=()

◆ orderBy()

◆ setExpressionContext()

◆ setFilterExpression()

◆ setFilterFid()

◆ setFilterFids()

◆ setFilterRect()

◆ setFlags()

◆ setLimit()

◆ setOrderBy()

◆ setSimplifyMethod()

◆ setSubsetOfAttributes() [1/2]

◆ setSubsetOfAttributes() [2/2]

◆ simplifyMethod()

◆ subsetOfAttributes()

Member Data Documentation

◆ AllAttributes

◆ mAttrs

◆ mExpressionContext

◆ mFilter

◆ mFilterExpression

◆ mFilterFid

◆ mFilterFids

◆ mFilterRect

◆ mFlags

◆ mLimit

◆ mOrderBy

◆ mSimplifyMethod