[api] Provider subset string metadata

python/PyQt6/core/auto_generated/pointcloud/qgspointclouddataprovider.sip.in

@@ -252,6 +252,11 @@ Returns the object containing the statistics metadata extracted from the dataset
 %End
 
     virtual bool supportsSubsetString() const;
+
+    virtual QString subsetStringDialect() const;
+
+    virtual QString subsetStringHelpUrl() const;
+
     virtual QString subsetString() const;
 
     virtual bool setSubsetString( const QString &subset, bool updateFeatureCount = false );

python/PyQt6/core/auto_generated/providers/qgsdataprovider.sip.in

@@ -196,29 +196,87 @@ to determine what constitutes a valid layer.
 Update the extents of the layer. Not implemented by default.
 %End
 
+    virtual QString subsetStringDialect() const;
+%Docstring
+Returns a user-friendly string describing the dialect which is supported for subset strings
+by the provider.
 
-    virtual bool setSubsetString( const QString &subset, bool updateFeatureCount = true );
+.. seealso:: :py:func:`subsetStringHelpUrl`
+
+.. seealso:: :py:func:`supportsSubsetString`
+
+.. seealso:: :py:func:`setSubsetString`
+
+.. seealso:: :py:func:`subsetString`
+
+.. versionadded:: 3.40
+%End
+
+    virtual QString subsetStringHelpUrl() const;
 %Docstring
-Set the subset string used to create a subset of features in
-the layer. This may be a sql where clause or any other string
-that can be used by the data provider to create a subset.
-Must be implemented in the dataprovider.
+Returns a URL pointing to documentation describing the dialect which is supported for subset strings
+by the provider.
+
+.. seealso:: :py:func:`subsetStringDialect`
+
+.. seealso:: :py:func:`supportsSubsetString`
+
+.. seealso:: :py:func:`setSubsetString`
+
+.. seealso:: :py:func:`subsetString`
+
+.. versionadded:: 3.40
 %End
 
+    virtual bool setSubsetString( const QString &subset, bool updateFeatureCount = true );
+%Docstring
+Set the ``subset`` string used to create a subset of features in
+the layer.
+
+This may be a SQL where clause, or any other string that can be used by the data provider to create a subset.
+See :py:func:`~QgsDataProvider.subsetStringDialect` and :py:func:`~QgsDataProvider.subsetStringHelpUrl` for additional metadata on the dialect supported
+by the subset string.
+
+Must be implemented in the data provider.
+
+.. seealso:: :py:func:`subsetString`
+
+.. seealso:: :py:func:`subsetStringDialect`
+
+.. seealso:: :py:func:`subsetStringHelpUrl`
+
+.. seealso:: :py:func:`supportsSubsetString`
+%End
 
     virtual bool supportsSubsetString() const;
 %Docstring
 Returns ``True`` if the provider supports setting of subset strings.
+
+.. seealso:: :py:func:`subsetString`
+
+.. seealso:: :py:func:`setSubsetString`
 %End
 
     virtual QString subsetString() const;
 %Docstring
-Returns the subset definition string (typically sql) currently in
+Returns the subset definition string currently in
 use by the layer and used by the provider to limit the feature set.
-Must be overridden in the dataprovider, otherwise returns a null
-QString.
-%End
 
+This may be a SQL where clause, or any other string that can be used by the data provider to create a subset.
+See :py:func:`~QgsDataProvider.subsetStringDialect` and :py:func:`~QgsDataProvider.subsetStringHelpUrl` for additional metadata on the dialect supported
+by the subset string.
+
+Must be overridden in the data provider, otherwise returns an empty
+string.
+
+.. seealso:: :py:func:`setSubsetString`
+
+.. seealso:: :py:func:`subsetStringDialect`
+
+.. seealso:: :py:func:`subsetStringHelpUrl`
+
+.. seealso:: :py:func:`supportsSubsetString`
+%End
 
     virtual QStringList subLayers() const;
 %Docstring

python/core/auto_generated/pointcloud/qgspointclouddataprovider.sip.in

@@ -252,6 +252,11 @@ Returns the object containing the statistics metadata extracted from the dataset
 %End
 
     virtual bool supportsSubsetString() const;
+
+    virtual QString subsetStringDialect() const;
+
+    virtual QString subsetStringHelpUrl() const;
+
     virtual QString subsetString() const;
 
     virtual bool setSubsetString( const QString &subset, bool updateFeatureCount = false );

python/core/auto_generated/providers/qgsdataprovider.sip.in

@@ -196,29 +196,87 @@ to determine what constitutes a valid layer.
 Update the extents of the layer. Not implemented by default.
 %End
 
+    virtual QString subsetStringDialect() const;
+%Docstring
+Returns a user-friendly string describing the dialect which is supported for subset strings
+by the provider.
 
-    virtual bool setSubsetString( const QString &subset, bool updateFeatureCount = true );
+.. seealso:: :py:func:`subsetStringHelpUrl`
+
+.. seealso:: :py:func:`supportsSubsetString`
+
+.. seealso:: :py:func:`setSubsetString`
+
+.. seealso:: :py:func:`subsetString`
+
+.. versionadded:: 3.40
+%End
+
+    virtual QString subsetStringHelpUrl() const;
 %Docstring
-Set the subset string used to create a subset of features in
-the layer. This may be a sql where clause or any other string
-that can be used by the data provider to create a subset.
-Must be implemented in the dataprovider.
+Returns a URL pointing to documentation describing the dialect which is supported for subset strings
+by the provider.
+
+.. seealso:: :py:func:`subsetStringDialect`
+
+.. seealso:: :py:func:`supportsSubsetString`
+
+.. seealso:: :py:func:`setSubsetString`
+
+.. seealso:: :py:func:`subsetString`
+
+.. versionadded:: 3.40
 %End
 
+    virtual bool setSubsetString( const QString &subset, bool updateFeatureCount = true );
+%Docstring
+Set the ``subset`` string used to create a subset of features in
+the layer.
+
+This may be a SQL where clause, or any other string that can be used by the data provider to create a subset.
+See :py:func:`~QgsDataProvider.subsetStringDialect` and :py:func:`~QgsDataProvider.subsetStringHelpUrl` for additional metadata on the dialect supported
+by the subset string.
+
+Must be implemented in the data provider.
+
+.. seealso:: :py:func:`subsetString`
+
+.. seealso:: :py:func:`subsetStringDialect`
+
+.. seealso:: :py:func:`subsetStringHelpUrl`
+
+.. seealso:: :py:func:`supportsSubsetString`
+%End
 
     virtual bool supportsSubsetString() const;
 %Docstring
 Returns ``True`` if the provider supports setting of subset strings.
+
+.. seealso:: :py:func:`subsetString`
+
+.. seealso:: :py:func:`setSubsetString`
 %End
 
     virtual QString subsetString() const;
 %Docstring
-Returns the subset definition string (typically sql) currently in
+Returns the subset definition string currently in
 use by the layer and used by the provider to limit the feature set.
-Must be overridden in the dataprovider, otherwise returns a null
-QString.
-%End
 
+This may be a SQL where clause, or any other string that can be used by the data provider to create a subset.
+See :py:func:`~QgsDataProvider.subsetStringDialect` and :py:func:`~QgsDataProvider.subsetStringHelpUrl` for additional metadata on the dialect supported
+by the subset string.
+
+Must be overridden in the data provider, otherwise returns an empty
+string.
+
+.. seealso:: :py:func:`setSubsetString`
+
+.. seealso:: :py:func:`subsetStringDialect`
+
+.. seealso:: :py:func:`subsetStringHelpUrl`
+
+.. seealso:: :py:func:`supportsSubsetString`
+%End
 
     virtual QStringList subLayers() const;
 %Docstring

src/core/pointcloud/qgspointclouddataprovider.cpp

@@ -237,6 +237,22 @@ QgsPointCloudStatistics QgsPointCloudDataProvider::metadataStatistics()
   return QgsPointCloudStatistics();
 }
 
+bool QgsPointCloudDataProvider::supportsSubsetString() const
+{
+  return true;
+}
+
+QString QgsPointCloudDataProvider::subsetStringDialect() const
+{
+  return tr( "QGIS expression" );
+}
+
+QString QgsPointCloudDataProvider::subsetStringHelpUrl() const
+{
+  // unfortunately we can't access QgsHelp here, that's a GUI class!
+  return QString();
+}
+
 struct MapIndexedPointCloudNode
 {
   typedef QVector<QMap<QString, QVariant>> result_type;

src/core/pointcloud/qgspointclouddataprovider.h

@@ -338,7 +338,9 @@ class CORE_EXPORT QgsPointCloudDataProvider: public QgsDataProvider
      */
     QgsPointCloudStatistics metadataStatistics();
 
-    bool supportsSubsetString() const override { return true; }
+    bool supportsSubsetString() const override;
+    QString subsetStringDialect() const override;
+    QString subsetStringHelpUrl() const override;
     QString subsetString() const override;
     bool setSubsetString( const QString &subset, bool updateFeatureCount = false ) override;
 

src/core/providers/memory/qgsmemoryprovider.cpp

@@ -765,6 +765,22 @@ bool QgsMemoryProvider::setSubsetString( const QString &theSQL, bool updateFeatu
   return true;
 }
 
+bool QgsMemoryProvider::supportsSubsetString() const
+{
+  return true;
+}
+
+QString QgsMemoryProvider::subsetStringDialect() const
+{
+  return tr( "QGIS expression" );
+}
+
+QString QgsMemoryProvider::subsetStringHelpUrl() const
+{
+  // unfortunately we can't access QgsHelp here, that's a GUI class!
+  return QString();
+}
+
 bool QgsMemoryProvider::createSpatialIndex()
 {
   if ( !mSpatialIndex )

src/core/providers/memory/qgsmemoryprovider.h

@@ -61,7 +61,9 @@ class QgsMemoryProvider final: public QgsVectorDataProvider
     bool changeGeometryValues( const QgsGeometryMap &geometry_map ) override;
     QString subsetString() const override;
     bool setSubsetString( const QString &theSQL, bool updateFeatureCount = true ) override;
-    bool supportsSubsetString() const override { return true; }
+    bool supportsSubsetString() const override;
+    QString subsetStringDialect() const override;
+    QString subsetStringHelpUrl() const override;
     bool createSpatialIndex() override;
     Qgis::SpatialIndexPresence hasSpatialIndex() const override;
     Qgis::VectorProviderCapabilities capabilities() const override;

src/core/providers/ogr/qgsogrprovider.cpp

@@ -559,6 +559,68 @@ QString QgsOgrProvider::subsetString() const
   return mSubsetString;
 }
 
+bool QgsOgrProvider::supportsSubsetString() const
+{
+  return true;
+}
+
+QString QgsOgrProvider::subsetStringDialect() const
+{
+#if GDAL_VERSION_NUM >= GDAL_COMPUTE_VERSION(3,6,0)
+  if ( mOgrLayer )
+  {
+    if ( const char *pszSqlDialects = GDALGetMetadataItem( mOgrLayer->driver(), GDAL_DMD_SUPPORTED_SQL_DIALECTS, nullptr ) )
+    {
+      const QStringList dialects = QString( pszSqlDialects ).split( ' ' );
+      // first dialect is default, which is what QGIS uses
+      const QString defaultDialect = !dialects.isEmpty() ? dialects.at( 0 ) : QString();
+      if ( defaultDialect == QLatin1String( "NATIVE" ) )
+      {
+        return tr( "%1 query" ).arg( GDALGetDriverLongName( mOgrLayer->driver() ) );
+      }
+      else if ( defaultDialect == QLatin1String( "OGRSQL" ) )
+      {
+        return tr( "OGR SQL query" );
+      }
+      else if ( defaultDialect == QLatin1String( "SQLITE" ) )
+      {
+        return tr( "SQLite query" );
+      }
+      return defaultDialect;
+    }
+  }
+#endif
+  return QString();
+}
+
+QString QgsOgrProvider::subsetStringHelpUrl() const
+{
+#if GDAL_VERSION_NUM >= GDAL_COMPUTE_VERSION(3,6,0)
+  if ( mOgrLayer )
+  {
+    if ( const char *pszSqlDialects = GDALGetMetadataItem( mOgrLayer->driver(), GDAL_DMD_SUPPORTED_SQL_DIALECTS, nullptr ) )
+    {
+      const QStringList dialects = QString( pszSqlDialects ).split( ' ' );
+      // first dialect is default, which is what QGIS uses
+      const QString defaultDialect = !dialects.isEmpty() ? dialects.at( 0 ) : QString();
+      if ( defaultDialect == QLatin1String( "NATIVE" ) )
+      {
+        return QgsGdalUtils::gdalDocumentationUrlForDriver( mOgrLayer->driver() );
+      }
+      else if ( defaultDialect == QLatin1String( "OGRSQL" ) )
+      {
+        return QStringLiteral( "https://gdal.org/user/ogr_sql_dialect.html" );
+      }
+      else if ( defaultDialect == QLatin1String( "SQLITE" ) )
+      {
+        return QStringLiteral( "https://gdal.org/user/sql_sqlite_dialect.html" );
+      }
+    }
+  }
+#endif
+  return QString();
+}
+
 uint QgsOgrProvider::subLayerCount() const
 {
   uint count = layerCount();

src/core/providers/ogr/qgsogrprovider.h

@@ -92,7 +92,9 @@ class QgsOgrProvider final: public QgsVectorDataProvider
     QString storageType() const override;
     QgsFeatureIterator getFeatures( const QgsFeatureRequest &request ) const override;
     QString subsetString() const override;
-    bool supportsSubsetString() const override { return true; }
+    bool supportsSubsetString() const override;
+    QString subsetStringDialect() const override;
+    QString subsetStringHelpUrl() const override;
     bool setSubsetString( const QString &theSQL, bool updateFeatureCount = true ) override;
     Qgis::WkbType wkbType() const override;
     virtual size_t layerCount() const;