Add note to QgsFeatureRequest::setSubsetOfAttributes methods

to indicate that providers may ignore the subset in certain circumstances Refs #44621
qgis · Aug 25, 2021 · f3ffe76 · f3ffe76
1 parent 6369c08
commit f3ffe76
Show file tree

Hide file tree

Showing 2 changed files with 69 additions and 0 deletions.
diff --git a/python/core/auto_generated/qgsfeaturerequest.sip.in b/python/core/auto_generated/qgsfeaturerequest.sip.in
@@ -660,6 +660,14 @@ An empty attributes list indicates that no attributes will be fetched.
 To revert a call to setSubsetOfAttributes and fetch all available attributes,
 the SubsetOfAttributes flag should be removed from the request.
 
+.. note::
+
+   This is intended as hint to data providers for optimising feature retrieval. Depending
+   on the provider, it may be trivial for the provider to always return all attributes instead of
+   the requested subset, or actually result in slower retrieval when the attributes are filtered out.
+   In these cases the provider may ignore this hint and return all attributes regardless of the
+   requested attributes.
+
 .. seealso:: :py:func:`subsetOfAttributes`
 
 .. seealso:: :py:func:`setNoAttributes`
@@ -672,8 +680,16 @@ Set that no attributes will be fetched.
 To revert a call to setNoAttributes and fetch all or some available attributes,
 the SubsetOfAttributes flag should be removed from the request.
 
+.. note::
+
+   This is intended as hint to data providers for optimising feature retrieval. Depending
+   on the provider, it may be trivial for the provider to always return all attributes instead of
+   removing them. In these cases the provider may ignore this hint and return all attributes
+   regardless of whether this method has been called.
+
 .. seealso:: :py:func:`setSubsetOfAttributes`
 
+
 .. versionadded:: 3.4
 %End
 
@@ -683,6 +699,14 @@ Returns the subset of attributes which at least need to be fetched.
 
 :return: A list of attributes to be fetched
 
+.. note::
+
+   This is intended as hint to data providers for optimising feature retrieval. Depending
+   on the provider, it may be trivial for the provider to always return all attributes instead of
+   the requested subset, or actually result in slower retrieval when the attributes are filtered out.
+   In these cases the provider may ignore this hint and return all attributes regardless of the
+   requested attributes.
+
 .. seealso:: :py:func:`setSubsetOfAttributes`
 
 .. seealso:: :py:func:`setNoAttributes`
@@ -692,13 +716,29 @@ Returns the subset of attributes which at least need to be fetched.
 %Docstring
 Sets a subset of attributes by names that will be fetched.
 
+.. note::
+
+   This is intended as hint to data providers for optimising feature retrieval. Depending
+   on the provider, it may be trivial for the provider to always return all attributes instead of
+   the requested subset, or actually result in slower retrieval when the attributes are filtered out.
+   In these cases the provider may ignore this hint and return all attributes regardless of the
+   requested attributes.
+
 .. seealso:: :py:func:`subsetOfAttributes`
 %End
 
     QgsFeatureRequest &setSubsetOfAttributes( const QSet<QString> &attrNames, const QgsFields &fields );
 %Docstring
 Sets a subset of attributes by names that will be fetched.
 
+.. note::
+
+   This is intended as hint to data providers for optimising feature retrieval. Depending
+   on the provider, it may be trivial for the provider to always return all attributes instead of
+   the requested subset, or actually result in slower retrieval when the attributes are filtered out.
+   In these cases the provider may ignore this hint and return all attributes regardless of the
+   requested attributes.
+
 .. seealso:: :py:func:`subsetOfAttributes`
 %End
 

diff --git a/src/core/qgsfeaturerequest.h b/src/core/qgsfeaturerequest.h
@@ -643,6 +643,12 @@ class CORE_EXPORT QgsFeatureRequest
      * To revert a call to setSubsetOfAttributes and fetch all available attributes,
      * the SubsetOfAttributes flag should be removed from the request.
      *
+     * \note This is intended as hint to data providers for optimising feature retrieval. Depending
+     * on the provider, it may be trivial for the provider to always return all attributes instead of
+     * the requested subset, or actually result in slower retrieval when the attributes are filtered out.
+     * In these cases the provider may ignore this hint and return all attributes regardless of the
+     * requested attributes.
+     *
      * \see subsetOfAttributes()
      * \see setNoAttributes()
      */
@@ -654,6 +660,11 @@ class CORE_EXPORT QgsFeatureRequest
      * To revert a call to setNoAttributes and fetch all or some available attributes,
      * the SubsetOfAttributes flag should be removed from the request.
      *
+     * \note This is intended as hint to data providers for optimising feature retrieval. Depending
+     * on the provider, it may be trivial for the provider to always return all attributes instead of
+     * removing them. In these cases the provider may ignore this hint and return all attributes
+     * regardless of whether this method has been called.
+     *
      * \see setSubsetOfAttributes()
      *
      * \since QGIS 3.4
@@ -664,6 +675,12 @@ class CORE_EXPORT QgsFeatureRequest
      * Returns the subset of attributes which at least need to be fetched.
      * \returns A list of attributes to be fetched
      *
+     * \note This is intended as hint to data providers for optimising feature retrieval. Depending
+     * on the provider, it may be trivial for the provider to always return all attributes instead of
+     * the requested subset, or actually result in slower retrieval when the attributes are filtered out.
+     * In these cases the provider may ignore this hint and return all attributes regardless of the
+     * requested attributes.
+     *
      * \see setSubsetOfAttributes()
      * \see setNoAttributes()
      */
@@ -672,13 +689,25 @@ class CORE_EXPORT QgsFeatureRequest
     /**
      * Sets a subset of attributes by names that will be fetched.
      *
+     * \note This is intended as hint to data providers for optimising feature retrieval. Depending
+     * on the provider, it may be trivial for the provider to always return all attributes instead of
+     * the requested subset, or actually result in slower retrieval when the attributes are filtered out.
+     * In these cases the provider may ignore this hint and return all attributes regardless of the
+     * requested attributes.
+     *
      * \see subsetOfAttributes()
      */
     QgsFeatureRequest &setSubsetOfAttributes( const QStringList &attrNames, const QgsFields &fields );
 
     /**
      * Sets a subset of attributes by names that will be fetched.
      *
+     * \note This is intended as hint to data providers for optimising feature retrieval. Depending
+     * on the provider, it may be trivial for the provider to always return all attributes instead of
+     * the requested subset, or actually result in slower retrieval when the attributes are filtered out.
+     * In these cases the provider may ignore this hint and return all attributes regardless of the
+     * requested attributes.
+     *
      * \see subsetOfAttributes()
      */
     QgsFeatureRequest &setSubsetOfAttributes( const QSet<QString> &attrNames, const QgsFields &fields );