QgsVectorDataProvider class

This is the base class for vector data providers.

Reference

Data providers abstract the retrieval and writing (where supported) of feature and attribute information from a spatial datasource.

Base classes

class QgsDataProvider: Abstract base class for spatial data provider implementations.
class QgsFeatureSink: An interface for objects which accept features via addFeature(s) methods.
class QgsFeatureSource: An interface for objects which provide features via a getFeatures method.

Public types

enum Capability { NoCapabilities = 0, AddFeatures = 1, DeleteFeatures = 1 << 1, ChangeAttributeValues = 1 << 2, AddAttributes = 1 << 3, DeleteAttributes = 1 << 4, CreateSpatialIndex = 1 << 6, SelectAtId = 1 << 7, ChangeGeometries = 1 << 8, SelectEncoding = 1 << 13, CreateAttributeIndex = 1 << 12, SimplifyGeometries = 1 << 14, SimplifyGeometriesWithTopologicalValidation = 1 << 15, TransactionSupport = 1 << 16, CircularGeometries = 1 << 17, ChangeFeatures = 1 << 18, RenameAttributes = 1 << 19, FastTruncate = 1 << 20, ReadLayerMetadata = 1 << 21, WriteLayerMetadata = 1 << 22, CancelSupport = 1 << 23, CreateRenderer = 1 << 24, CreateLabeling = 1 << 25 }: enumeration with capabilities that providers might implement
enum FeatureCountState { Uncounted = -2, UnknownCount = -1 }: Enumeration of feature count states.

Public static variables

static const int EditingCapabilities: Bitmask of all provider's editing capabilities.

Public static functions

static auto availableEncodings() -> QStringList: Returns a list of available encodings.

Constructors, destructors, conversion operators

QgsVectorDataProvider(const QString& uri = QString(), const QgsDataProvider::ProviderOptions& options = QgsDataProvider::ProviderOptions()): Constructor for a vector data provider.

Public functions

auto addAttributes(const QList<QgsField>& attributes) -> bool virtual: Adds new attributes to the provider.
auto addFeatures(QgsFeatureList& features, QgsFeatureSink::Flags flags = nullptr) -> bool override: Adds a list of features to the sink.
auto aggregate(QgsAggregateCalculator::Aggregate aggregate, int index, const QgsAggregateCalculator::AggregateParameters& parameters, QgsExpressionContext* context, bool& ok) const -> QVariant virtual: Calculates an aggregated value from the layer's features.
auto attributeIndexes() const -> QgsAttributeList virtual: Returns list of indexes to fetch all attributes in nextFeature()
auto cancelReload() -> bool virtual: Cancels the current reloading of data.
auto capabilities() const -> QgsVectorDataProvider::Capabilities virtual: Returns flags containing the supported capabilities.
auto capabilitiesString() const -> QString: Returns the above in friendly format.
auto changeAttributeValues(const QgsChangedAttributesMap& attr_map) -> bool virtual: Changes attribute values of existing features.
auto changeFeatures(const QgsChangedAttributesMap& attr_map, const QgsGeometryMap& geometry_map) -> bool virtual: Changes attribute values and geometries of existing features.
auto changeGeometryValues(const QgsGeometryMap& geometry_map) -> bool virtual: Changes geometries of existing features.
void clearErrors(): Clear recorded errors.
auto createAttributeIndex(int field) -> bool virtual: Create an attribute index on the datasource.
auto createLabeling(const QVariantMap& configuration = QVariantMap()) const -> QgsAbstractVectorLayerLabeling* virtual: Creates labeling settings, using provider backend specific information.
auto createRenderer(const QVariantMap& configuration = QVariantMap()) const -> QgsFeatureRenderer* virtual: Creates a new vector layer feature renderer, using provider backend specific information.
auto createSpatialIndex() -> bool virtual: Creates a spatial index on the datasource (if supported by the provider type).
auto dataComment() const -> QString virtual: Returns a short comment for the data that this provider is providing access to (e.g.
auto defaultValue(int fieldIndex) const -> QVariant virtual: Returns any literal default values which are present at the provider for a specified field index.
auto defaultValueClause(int fieldIndex) const -> QString virtual: Returns any default value clauses which are present at the provider for a specified field index.
auto deleteAttributes(const QgsAttributeIds& attributes) -> bool virtual: Deletes existing attributes from the provider.
auto deleteFeatures(const QgsFeatureIds& id) -> bool virtual: Deletes one or more features from the provider.
auto dependencies() const -> QSet<QgsMapLayerDependency> virtual: Gets the list of layer ids on which this layer depends.
auto discoverRelations(const QgsVectorLayer* self, const QList<QgsVectorLayer*>& layers) const -> QList<QgsRelation> virtual: Discover the available relations with the given layers.
auto doesStrictFeatureTypeCheck() const -> bool virtual: Returns true if the provider is strict about the type of inserted features (e.g.
auto empty() const -> bool virtual: Returns true if the layer contains at least one feature.
auto encoding() const -> QString: Gets encoding which is used for accessing data.
void enumValues(int index, QStringList& enumList) const virtual: Returns the possible enum values of an attribute.
auto errors() const -> QStringList: Gets recorded errors.
auto featureCount() const -> long override: Number of features in the layer.
auto featureSource() const -> QgsAbstractFeatureSource* pure virtual: Returns feature source object that can be used for querying provider's data.
auto fieldConstraints(int fieldIndex) const -> QgsFieldConstraints::Constraints: Returns any constraints which are present at the provider for a specified field index.
auto fieldNameIndex(const QString& fieldName) const -> int: Returns the index of a field name or -1 if the field does not exist.
auto fieldNameMap() const -> QMap<QString, int>: Returns a map where the key is the name of the field and the value is its index.
auto fields() const -> QgsFields override: Returns the fields associated with this data provider.
void forceReload() virtual: Forces a reload of the underlying datasource if the provider implements this method.
auto getFeatures(const QgsFeatureRequest& request = QgsFeatureRequest()) const -> QgsFeatureIterator override: Query the provider for features specified in request.
auto hasErrors() const -> bool: Provider has errors to report.
auto hasFeatures() const -> QgsFeatureSource::FeatureAvailability override: Will always return FeatureAvailability::FeaturesAvailable or FeatureAvailability::NoFeaturesAvailable.
auto hasMetadata() const -> bool virtual: Returns true if the data source has metadata, false otherwise.
auto isDeleteStyleFromDatabaseSupported() const -> bool virtual: It returns false by default.
auto isSaveAndLoadStyleToDatabaseSupported() const -> bool virtual: It returns false by default.
auto maximumValue(int index) const -> QVariant override: Returns the maximum value of an attribute.
auto metadata() const -> QVariantMap virtual: Gets metadata, dependent on the provider type, that will be display in the metadata tab of the layer properties.
auto minimumValue(int index) const -> QVariant override: Returns the minimum value of an attribute.
auto nativeTypes() const -> QList<QgsVectorDataProvider::NativeType>: Returns the names of the supported types.
auto palAttributeIndexNames() const -> QgsAttrPalIndexNameHash virtual: Returns list of indexes to names for QgsPalLabeling fix.
auto pkAttributeIndexes() const -> QgsAttributeList virtual: Returns list of indexes of fields that make up the primary key.
auto renameAttributes(const QgsFieldNameMap& renamedAttributes) -> bool virtual: Renames existing attributes.
void setEncoding(const QString& e) virtual: Set encoding used for accessing data from layer.
auto skipConstraintCheck(int fieldIndex, QgsFieldConstraints::Constraint constraint, const QVariant& value = QVariant()) const -> bool virtual: Returns true if a constraint check should be skipped for a specified field (e.g., if the value returned by defaultValue() is trusted implicitly.
auto sourceCrs() const -> QgsCoordinateReferenceSystem override: Returns the coordinate reference system for features in the source.
auto sourceExtent() const -> QgsRectangle override: Returns the extent of all geometries from the source.
auto sourceName() const -> QString override: Returns a friendly display name for the source.
auto storageType() const -> QString virtual: Returns the permanent storage type for this layer as a friendly name.
auto supportedType(const QgsField& field) const -> bool: check if provider supports type of field
auto transaction() const -> QgsTransaction* virtual: Returns the transaction this data provider is included in, if any.
auto translateMetadataKey(const QString& mdKey) const -> QString virtual: Gets the translated metadata key.
auto translateMetadataValue(const QString& mdKey, const QVariant& value) const -> QString virtual: Gets the translated metadata value.
auto truncate() -> bool virtual: Removes all features from the layer.
auto uniqueStringsMatching(int index, const QString& substring, int limit = -1, QgsFeedback* feedback = nullptr) const -> QStringList virtual: Returns unique string values of an attribute which contain a specified subset string.
auto wkbType() const -> QgsWkbTypes::Type override: Returns the geometry type which is returned by this layer.

Signals

void raiseError(const QString& msg) const: Signals an error in this provider.

Protected functions

void clearMinMaxCache(): Invalidates the min/max cache.
auto convertToProviderType(const QgsGeometry& geom) const -> QgsGeometry: Converts the geometry to the provider type if possible / necessary.
void fillMinMaxCache() const: Populates the cache of minimum and maximum attribute values.
void pushError(const QString& msg) const: Push a notification about errors that happened in this providers scope.
void setNativeTypes(const QList<QgsVectorDataProvider::NativeType>& nativeTypes): Set the list of native types supported by this provider.
auto textEncoding() const -> QTextCodec*: Gets this providers encoding.

Private functions

void setTransaction(QgsTransaction*) virtual: Includes this data provider in the specified transaction.

Enum documentation

enum QgsVectorDataProvider::Capability

enumeration with capabilities that providers might implement

Enumerators
NoCapabilities	Provider has no capabilities.
AddFeatures	Allows adding features.
DeleteFeatures	Allows deletion of features.
ChangeAttributeValues	Allows modification of attribute values.
AddAttributes	Allows addition of new attributes (fields)
DeleteAttributes	Allows deletion of attributes (fields)
CreateSpatialIndex	Allows creation of spatial index.
SelectAtId	Fast access to features using their ID.
ChangeGeometries	Allows modifications of geometries.
SelectEncoding	Allows user to select encoding.
CreateAttributeIndex	Can create indexes on provider's fields.
SimplifyGeometries	Supports simplification of geometries on provider side according to a distance tolerance.
SimplifyGeometriesWithTopologicalValidation	Supports topological simplification of geometries on provider side according to a distance tolerance.
TransactionSupport	Supports transactions.
CircularGeometries	Supports circular geometry types (circularstring, compoundcurve, curvepolygon)
ChangeFeatures
RenameAttributes	Supports joint updates for attributes and geometry Providers supporting this should still define ChangeGeometries \| ChangeAttributeValues. Supports renaming attributes (fields). Since QGIS 2.16
FastTruncate	Supports fast truncation of the layer (removing all features). Since QGIS 3.0.
ReadLayerMetadata	Provider can read layer metadata from data store. Since QGIS 3.0. See QgsDataProvider::layerMetadata()
WriteLayerMetadata	Provider can write layer metadata to the data store. Since QGIS 3.0. See QgsDataProvider::writeLayerMetadata()
CancelSupport	Supports interruption of pending queries from a separated thread. Since QGIS 3.2.
CreateRenderer	Provider can create feature renderers using backend-specific formatting information. Since QGIS 3.2. See QgsVectorDataProvider::createRenderer().
CreateLabeling	Provider can set labeling settings using backend-specific formatting information. Since QGIS 3.6. See QgsVectorDataProvider::createLabeling().

enum QgsVectorDataProvider::FeatureCountState

Enumeration of feature count states.

Enumerators
Uncounted	Feature count not yet computed.
UnknownCount	Provider returned an unknown feature count.

Function documentation

QgsVectorDataProvider::QgsVectorDataProvider(const QString& uri = QString(), const QgsDataProvider::ProviderOptions& options = QgsDataProvider::ProviderOptions())

Constructor for a vector data provider.

The uri argument specifies the uniform resource locator (URI) for the associated dataset.

Additional creation options are specified within the options value.

bool QgsVectorDataProvider::addAttributes(const QList<QgsField>& attributes) virtual

Adds new attributes to the provider.

Returns true in case of success and false in case of failure. If attributes are added using this method then QgsVectorLayer::updateFields() must be called manually to ensure that the layer's field are correctly reported.

bool QgsVectorDataProvider::addFeatures(QgsFeatureList& features, QgsFeatureSink::Flags flags = nullptr) override

Adds a list of features to the sink.

Returns	true in case of success and false in case of failure

Feature addition behavior is controlled by the specified flags.

QVariant QgsVectorDataProvider::aggregate(QgsAggregateCalculator::Aggregate aggregate, int index, const QgsAggregateCalculator::AggregateParameters& parameters, QgsExpressionContext* context, bool& ok) const virtual

Calculates an aggregated value from the layer's features.

Parameters
aggregate	aggregate to calculate
index	the index of the attribute to calculate aggregate over
parameters	parameters controlling aggregate calculation
context	expression context for filter
ok	will be set to true if calculation was successfully performed by the data provider
Returns	calculated aggregate value

The base implementation does nothing, but subclasses can override this method to handoff calculation of aggregates to the provider.

bool QgsVectorDataProvider::cancelReload() virtual

Cancels the current reloading of data.

Returns	true if the reloading has been correctly interrupted, false otherwise

QgsVectorDataProvider::Capabilities QgsVectorDataProvider::capabilities() const virtual

Returns flags containing the supported capabilities.

bool QgsVectorDataProvider::changeAttributeValues(const QgsChangedAttributesMap& attr_map) virtual

Changes attribute values of existing features.

Parameters
attr_map	a map containing changed attributes
Returns	true in case of success and false in case of failure

This should succeed if the provider reports the ChangeAttributeValues capability.

bool QgsVectorDataProvider::changeFeatures(const QgsChangedAttributesMap& attr_map, const QgsGeometryMap& geometry_map) virtual

Changes attribute values and geometries of existing features.

Parameters
attr_map	a map containing changed attributes
geometry_map	A QgsGeometryMap whose index contains the feature IDs that will have their geometries changed. The second map parameter being the new geometries themselves
Returns	true in case of success and false in case of failure

This should succeed if the provider reports both the ChangeAttributeValues and ChangeGeometries capabilities. Providers which report the ChangeFeatures capability implement an optimised version of this method.

bool QgsVectorDataProvider::changeGeometryValues(const QgsGeometryMap& geometry_map) virtual

Changes geometries of existing features.

Parameters
geometry_map	A QgsGeometryMap whose index contains the feature IDs that will have their geometries changed. The second map parameter being the new geometries themselves
Returns	True in case of success and false in case of failure

QgsAbstractVectorLayerLabeling* QgsVectorDataProvider::createLabeling(const QVariantMap& configuration = QVariantMap()) const virtual

Creates labeling settings, using provider backend specific information.

The configuration map can be used to pass provider-specific configuration maps to the provider to allow customization of the returned labeling object. Support and format of configuration varies by provider.

When called with an empty configuration map the provider's default labeling settings will be returned.

This method returns a new labeling settings and the caller takes ownership of the returned object.

Only providers which report the CreateLabeling capability will return labeling settings. Other providers will return nullptr.

QgsFeatureRenderer* QgsVectorDataProvider::createRenderer(const QVariantMap& configuration = QVariantMap()) const virtual

Creates a new vector layer feature renderer, using provider backend specific information.

The configuration map can be used to pass provider-specific configuration maps to the provider to allow customization of the returned renderer. Support and format of configuration varies by provider.

When called with an empty configuration map the provider's default renderer will be returned.

This method returns a new renderer and the caller takes ownership of the returned object.

Only providers which report the CreateRenderer capability will return a feature renderer. Other providers will return nullptr.

bool QgsVectorDataProvider::createSpatialIndex() virtual

Creates a spatial index on the datasource (if supported by the provider type).

Returns	true in case of success

QString QgsVectorDataProvider::dataComment() const virtual

Returns a short comment for the data that this provider is providing access to (e.g.

the comment for postgres table).

QVariant QgsVectorDataProvider::defaultValue(int fieldIndex) const virtual

Returns any literal default values which are present at the provider for a specified field index.

Important - this should ONLY be called when creating an attribute to insert directly into the database. Do not call this method for non-feature creation or modification, e.g., when validating an attribute or to compare it against an existing value, as calling it can cause changes to the underlying data source (e.g., Postgres provider where the default value is calculated as a result of a sequence). It is recommended that you instead use the methods in QgsVectorLayerUtils such as QgsVectorLayerUtils::createFeature() so that default value handling and validation is automatically carried out.

QString QgsVectorDataProvider::defaultValueClause(int fieldIndex) const virtual

Returns any default value clauses which are present at the provider for a specified field index.

These clauses are usually SQL fragments which must be evaluated by the provider, e.g., sequence values.

bool QgsVectorDataProvider::deleteAttributes(const QgsAttributeIds& attributes) virtual

Deletes existing attributes from the provider.

Parameters
attributes	a set containing indices of attributes
Returns	true in case of success and false in case of failure

If attributes are deleted using this method then QgsVectorLayer::updateFields() must be called manually to ensure that the layer's field are correctly reported.

bool QgsVectorDataProvider::deleteFeatures(const QgsFeatureIds& id) virtual

Deletes one or more features from the provider.

Parameters
id	list containing feature ids to delete
Returns	true in case of success and false in case of failure

This requires the DeleteFeatures capability.

QSet<QgsMapLayerDependency> QgsVectorDataProvider::dependencies() const virtual

Gets the list of layer ids on which this layer depends.

This in particular determines the order of layer loading.

QList<QgsRelation> QgsVectorDataProvider::discoverRelations(const QgsVectorLayer* self, const QList<QgsVectorLayer*>& layers) const virtual

Discover the available relations with the given layers.

Parameters
self	the layer using this data provider.
layers	the other layers.
Returns	the list of N-1 relations from this provider.

bool QgsVectorDataProvider::doesStrictFeatureTypeCheck() const virtual

Returns true if the provider is strict about the type of inserted features (e.g.

no multipolygon in a polygon layer)

bool QgsVectorDataProvider::empty() const virtual

Returns true if the layer contains at least one feature.

void QgsVectorDataProvider::enumValues(int index, QStringList& enumList) const virtual

Returns the possible enum values of an attribute.

Parameters
index	the index of the attribute
enumList	reference to the list to fill

Returns an empty stringlist if a provider does not support enum types or if the given attribute is not an enum type.

long QgsVectorDataProvider::featureCount() const override

Number of features in the layer.

Returns	long containing number of features

QgsAbstractFeatureSource* QgsVectorDataProvider::featureSource() const pure virtual

Returns feature source object that can be used for querying provider's data.

Returns	new instance of QgsAbstractFeatureSource (caller is responsible for deleting it)

The returned feature source is independent from provider - any changes to provider's state (e.g. change of subset string) will not be reflected in the feature source, therefore it can be safely used for processing in background without having to care about possible changes within provider that may happen concurrently. Also, even in the case of provider being deleted, any feature source obtained from the provider will be kept alive and working (they are independent and owned by the caller).

Sometimes there are cases when some data needs to be shared between vector data provider and its feature source. In such cases, the implementation must ensure that the data is not susceptible to run condition. For example, if it is possible that both feature source and provider may need reading/writing to some shared data at the same time, some synchronization mechanisms must be used (e.g. mutexes) to prevent data corruption.

QgsFieldConstraints::Constraints QgsVectorDataProvider::fieldConstraints(int fieldIndex) const

Returns any constraints which are present at the provider for a specified field index.

void QgsVectorDataProvider::forceReload() virtual

Forces a reload of the underlying datasource if the provider implements this method.

In particular on the OGR provider, a pooled connection will be invalidated. This forces QGIS to reopen a file or connection. This can be required if the underlying file is replaced.

QgsFeatureIterator QgsVectorDataProvider::getFeatures(const QgsFeatureRequest& request = QgsFeatureRequest()) const override

Query the provider for features specified in request.

Parameters
request	feature request describing parameters of features to return
Returns	iterator for matching features from provider

QgsFeatureSource::FeatureAvailability QgsVectorDataProvider::hasFeatures() const override

Will always return FeatureAvailability::FeaturesAvailable or FeatureAvailability::NoFeaturesAvailable.

Calls empty() internally. Providers should override empty() instead if they provide an optimized version of this call.

bool QgsVectorDataProvider::hasMetadata() const virtual

Returns true if the data source has metadata, false otherwise.

Returns	true if data source has metadata, false otherwise.

bool QgsVectorDataProvider::isDeleteStyleFromDatabaseSupported() const virtual

It returns false by default.

Must be implemented by providers that support delete styles from db returning true

bool QgsVectorDataProvider::isSaveAndLoadStyleToDatabaseSupported() const virtual

It returns false by default.

Must be implemented by providers that support saving and loading styles to db returning true

QVariant QgsVectorDataProvider::maximumValue(int index) const override

Returns the maximum value of an attribute.

Parameters
index	the index of the attribute

Default implementation walks all numeric attributes and caches minimal and maximal values. If provider has facilities to retrieve maximal value directly, override this function.

QVariantMap QgsVectorDataProvider::metadata() const virtual

Gets metadata, dependent on the provider type, that will be display in the metadata tab of the layer properties.

Returns	The provider metadata

QVariant QgsVectorDataProvider::minimumValue(int index) const override

Returns the minimum value of an attribute.

Parameters
index	the index of the attribute

Default implementation walks all numeric attributes and caches minimal and maximal values. If provider has facilities to retrieve minimal value directly, override this function.

bool QgsVectorDataProvider::renameAttributes(const QgsFieldNameMap& renamedAttributes) virtual

Renames existing attributes.

Parameters
renamedAttributes	map of attribute index to new attribute name
Returns	true in case of success and false in case of failure

If attributes are renamed using this method then QgsVectorLayer::updateFields() must be called manually to ensure that the layer's field are correctly reported.

bool QgsVectorDataProvider::skipConstraintCheck(int fieldIndex, QgsFieldConstraints::Constraint constraint, const QVariant& value = QVariant()) const virtual

Returns true if a constraint check should be skipped for a specified field (e.g., if the value returned by defaultValue() is trusted implicitly.

An optional attribute value can be passed which can help refine the skip constraint check.

QgsRectangle QgsVectorDataProvider::sourceExtent() const override

Returns the extent of all geometries from the source.

The base class implementation uses a non-optimised approach of looping through all features in the source.

QString QgsVectorDataProvider::sourceName() const override

Returns a friendly display name for the source.

The returned value can be an empty string.

QString QgsVectorDataProvider::translateMetadataKey(const QString& mdKey) const virtual

Gets the translated metadata key.

Parameters
mdKey	The metadata key
Returns	The translated metadata value

QString QgsVectorDataProvider::translateMetadataValue(const QString& mdKey, const QVariant& value) const virtual

Gets the translated metadata value.

Parameters
mdKey	The metadata key
value	The metadata value
Returns	The translated metadata value

bool QgsVectorDataProvider::truncate() virtual

Removes all features from the layer.

Returns	true in case of success and false in case of failure.

This requires either the FastTruncate or DeleteFeatures capability. Providers with the FastTruncate capability will use an optimised method to truncate the layer.

QStringList QgsVectorDataProvider::uniqueStringsMatching(int index, const QString& substring, int limit = -1, QgsFeedback* feedback = nullptr) const virtual

Returns unique string values of an attribute which contain a specified subset string.

Parameters
index	the index of the attribute
substring	substring to match (case insensitive)
limit	maxmum number of the values to return, or -1 to return all unique values
feedback	optional feedback object for canceling request
Returns	list of unique strings containing substring

Subset matching is done in a case-insensitive manner.

void QgsVectorDataProvider::raiseError(const QString& msg) const signal

Signals an error in this provider.

void QgsVectorDataProvider::clearMinMaxCache() protected

Invalidates the min/max cache.

This will force the provider to recalculate the cache the next time it is requested.

QgsGeometry QgsVectorDataProvider::convertToProviderType(const QgsGeometry& geom) const protected

Converts the geometry to the provider type if possible / necessary.

Returns	the converted geometry or nullptr if no conversion was necessary or possible

void QgsVectorDataProvider::pushError(const QString& msg) const protected

Push a notification about errors that happened in this providers scope.

Errors should be translated strings that require the users immediate attention.

For general debug information use QgsMessageLog::logMessage() instead.

void QgsVectorDataProvider::setNativeTypes(const QList<QgsVectorDataProvider::NativeType>& nativeTypes) protected

Set the list of native types supported by this provider.

Usually done in the constructor.

QTextCodec* QgsVectorDataProvider::textEncoding() const protected

Gets this providers encoding.

void QgsVectorDataProvider::setTransaction(QgsTransaction*) virtual private

Includes this data provider in the specified transaction.

Ownership of transaction is not transferred.