Doc: SQL dialects: improvements

doc/source/user/ogr_sql_dialect.rst

@@ -13,8 +13,12 @@ used to provide a subset of SQL SELECT capability to applications.  This
 page discusses the generic SQL implementation implemented within OGR, and
 issues with driver specific SQL support.
 
-An alternate "dialect", the SQLite dialect, can be used
-instead of the OGRSQL dialect. Refer to the :ref:`sql_sqlite_dialect` page for more details.
+The ``OGRSQL`` dialect can be requested with the ``OGRSQL`` string passed
+as the dialect parameter of :cpp:func:`GDALDataset::ExecuteSQL`, or with the
+`-dialect` option switch of the :ref:`ogrinfo` or :ref:`ogr2ogr` utilities.
+
+An alternate dialect, the ``SQLite`` dialect, can be used
+instead of the ``OGRSQL`` dialect. Refer to the :ref:`sql_sqlite_dialect` page for more details.
 
 The OGRLayer class also supports applying an attribute query filter to
 features returned using the :cpp:func:`OGRLayer::SetAttributeFilter()` method.  The
@@ -678,43 +682,3 @@ supported on datasources that declare the ODsCDeleteLayer capability.
 .. code-block::
 
     DROP TABLE nation
-
-ExecuteSQL()
-------------
-
-SQL is executed against an GDALDataset, not against a specific layer.  The
-call looks like this:
-
-.. code-block:: cpp
-
-    OGRLayer * GDALDataset::ExecuteSQL( const char *pszSQLCommand,
-                                        OGRGeometry *poSpatialFilter,
-                                        const char *pszDialect );
-
-The ``pszDialect`` argument is in theory intended to allow for support of
-different command languages against a provider, but for now applications
-should always pass an empty (not NULL) string to get the default dialect.
-
-The ``poSpatialFilter`` argument is a geometry used to select a bounding rectangle
-for features to be returned in a manner similar to the
-:cpp:func:`OGRLayer::SetSpatialFilter` method.  It may be NULL for no special spatial
-restriction.
-
-The result of an ExecuteSQL() call is usually a temporary OGRLayer representing
-the results set from the statement.  This is the case for a SELECT statement
-for instance.  The returned temporary layer should be released with
-:cpp:func:`GDALDataset::ReleaseResultsSet` method when no longer needed.  Failure
-to release it before the datasource is destroyed may result in a crash.
-
-Non-OGR SQL
------------
-
-All OGR drivers for database systems: :ref:`vector.mysql`, :ref:`vector.pg`,
-:ref:`vector.oci`, :ref:`vector.sqlite`, :ref:`vector.odbc`, :ref:`vector.pgeo`,
-:ref:`vector.hana` and :ref:`vector.mssqlspatial`,
-override the :cpp:func:`GDALDataset::ExecuteSQL` function with dedicated implementation
-and, by default, pass the SQL statements directly to the underlying RDBMS.
-In these cases the SQL syntax varies in some particulars from OGR SQL.
-Also, anything possible in SQL can then be accomplished for these particular
-databases.  Only the result of SQL WHERE statements will be returned as
-layers.

doc/source/user/ogr_sql_sqlite_dialect.rst

@@ -4,8 +4,60 @@
 OGR SQL dialect and SQLITE SQL dialect
 ================================================================================
 
+The GDALDataset supports executing commands against a datasource via the
+:cpp:func:`GDALDataset::ExecuteSQL` method. How such commands are evaluated
+is dependent on the datasets.
+
+- For most file formats (e.g. Shapefiles, GeoJSON, MapInfo files), the built-in
+  :ref:`ogr_sql_dialect` dialect will be used by defaults. It is also possible
+  to request the :ref:`sql_sqlite_dialect` alternate dialect to be used, which
+  will use the SQLite engine to evaluate commands on GDAL datasets.
+
+- All OGR drivers for database systems: :ref:`vector.mysql`, :ref:`vector.pg`,
+  :ref:`vector.oci`, :ref:`vector.sqlite`, :ref:`vector.gpkg`,
+  :ref:`vector.odbc`, :ref:`vector.pgeo`, :ref:`vector.hana` and :ref:`vector.mssqlspatial`,
+  override the :cpp:func:`GDALDataset::ExecuteSQL` function with dedicated implementation
+  and, by default, pass the SQL statements directly to the underlying RDBMS.
+  In these cases the SQL syntax varies in some particulars from OGR SQL.
+  Also, anything possible in SQL can then be accomplished for these particular
+  databases. Generally, only the result of SELECT statements will be returned as
+  layers. For those drivers, it is also possible to explicitly request the
+  ``OGRSQL`` and ``SQLITE`` dialects, although performance will generally be
+  much less as the native SQL engine of those database systems.
+
+Dialects
+--------
+
 .. toctree::
    :maxdepth: 1
 
    ogr_sql_dialect
    sql_sqlite_dialect
+
+
+ExecuteSQL()
+------------
+
+SQL is executed against an GDALDataset, not against a specific layer.  The
+call looks like this:
+
+.. code-block:: cpp
+
+    OGRLayer * GDALDataset::ExecuteSQL( const char *pszSQLCommand,
+                                        OGRGeometry *poSpatialFilter,
+                                        const char *pszDialect );
+
+The ``pszDialect`` argument is in theory intended to allow for support of
+different command languages against a provider, but for now applications
+should always pass an empty (not NULL) string to get the default dialect.
+
+The ``poSpatialFilter`` argument is a geometry used to select a bounding rectangle
+for features to be returned in a manner similar to the
+:cpp:func:`OGRLayer::SetSpatialFilter` method.  It may be NULL for no special spatial
+restriction.
+
+The result of an ExecuteSQL() call is usually a temporary OGRLayer representing
+the results set from the statement.  This is the case for a SELECT statement
+for instance.  The returned temporary layer should be released with
+:cpp:func:`GDALDataset::ReleaseResultsSet` method when no longer needed.  Failure
+to release it before the datasource is destroyed may result in a crash.

doc/source/user/sql_sqlite_dialect.rst

@@ -6,15 +6,15 @@ SQL SQLite dialect
 
 .. highlight:: sql
 
-The SQLite "dialect" can be used as an alternate SQL dialect to the
+The ``SQLite`` dialect can be used as an alternate SQL dialect to the
 :ref:`ogr_sql_dialect`.
 This assumes that GDAL/OGR is built with support for SQLite, and preferably
 with `Spatialite <https://www.gaia-gis.it/fossil/libspatialite/index>`_ support too to benefit from spatial functions.
 
-The SQLite dialect may be used with any OGR datasource, like the OGR SQL dialect. It
-is available through the GDALDataset::ExecuteSQL() method by specifying the pszDialect to
-"SQLITE". For the :ref:`ogrinfo` or :ref:`ogr2ogr`
-utility, you must specify the "-dialect SQLITE" option.
+The SQLite dialect may be used with any OGR datasource, like the OGR SQL dialect.
+The ``SQLite`` dialect can be requested with the ``SQLite`` string passed
+as the dialect parameter of :cpp:func:`GDALDataset::ExecuteSQL`, or with the
+`-dialect` option of the :ref:`ogrinfo` or :ref:`ogr2ogr` utilities.
 
 This is mainly aimed to execute SELECT statements, but, for datasources that support
 update, INSERT/UPDATE/DELETE statements can also be run. GDAL is internally using