diff --git a/doc/source/user/ogr_sql_dialect.rst b/doc/source/user/ogr_sql_dialect.rst index 2bc522392ef3..b78c298ff026 100644 --- a/doc/source/user/ogr_sql_dialect.rst +++ b/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. diff --git a/doc/source/user/ogr_sql_sqlite_dialect.rst b/doc/source/user/ogr_sql_sqlite_dialect.rst index 1330f67da475..96d86b117861 100644 --- a/doc/source/user/ogr_sql_sqlite_dialect.rst +++ b/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. diff --git a/doc/source/user/sql_sqlite_dialect.rst b/doc/source/user/sql_sqlite_dialect.rst index f46291994b28..cac5098aba7c 100644 --- a/doc/source/user/sql_sqlite_dialect.rst +++ b/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 `_ 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