Updated documentation regarding known limitations (#106)

Co-authored-by: Sebastian Bär <[email protected]>

doc/changes/changes_7.1.2.md

@@ -0,0 +1,41 @@
+# Exasol Virtual Schema 7.1.2, released 2023-06-20
+
+Code name: Documentation Update
+
+## Summary
+
+This release updates the documentation for the Exasol Virtual Schema dialect regarding known limitations.
+
+## Features
+
+* #104: Updated documentation regarding known limitations
+
+## Dependency Updates
+
+### Compile Dependency Updates
+
+* Updated `com.exasol:exasol-jdbc:7.1.19` to `7.1.20`
+* Removed `org.glassfish:jakarta.json:2.0.1`
+
+### Test Dependency Updates
+
+* Updated `com.exasol:exasol-testcontainers:6.5.1` to `6.6.0`
+* Updated `com.exasol:hamcrest-resultset-matcher:1.5.3` to `1.6.0`
+* Updated `org.jacoco:org.jacoco.agent:0.8.8` to `0.8.9`
+* Updated `org.junit.jupiter:junit-jupiter:5.9.2` to `5.9.3`
+* Updated `org.mockito:mockito-junit-jupiter:5.2.0` to `5.4.0`
+* Updated `org.testcontainers:junit-jupiter:1.17.6` to `1.18.3`
+
+### Plugin Dependency Updates
+
+* Updated `com.exasol:error-code-crawler-maven-plugin:1.2.2` to `1.2.3`
+* Updated `com.exasol:project-keeper-maven-plugin:2.9.6` to `2.9.7`
+* Updated `org.apache.maven.plugins:maven-compiler-plugin:3.10.1` to `3.11.0`
+* Updated `org.apache.maven.plugins:maven-deploy-plugin:3.1.0` to `3.1.1`
+* Updated `org.apache.maven.plugins:maven-enforcer-plugin:3.2.1` to `3.3.0`
+* Updated `org.apache.maven.plugins:maven-failsafe-plugin:3.0.0-M8` to `3.0.0`
+* Updated `org.apache.maven.plugins:maven-surefire-plugin:3.0.0-M8` to `3.0.0`
+* Added `org.basepom.maven:duplicate-finder-maven-plugin:1.5.1`
+* Updated `org.codehaus.mojo:flatten-maven-plugin:1.3.0` to `1.4.1`
+* Updated `org.codehaus.mojo:versions-maven-plugin:2.14.2` to `2.15.0`
+* Updated `org.jacoco:jacoco-maven-plugin:0.8.8` to `0.8.9`

doc/dialects/exasol.md

@@ -17,7 +17,7 @@ The SQL statement below creates the adapter script, defines the Java class that
 ```sql
 CREATE JAVA ADAPTER SCRIPT SCHEMA_FOR_VS_SCRIPT.ADAPTER_SCRIPT_EXASOL AS
     %scriptclass com.exasol.adapter.RequestDispatcher;
-    %jar /buckets/<BFS service>/<bucket>/virtual-schema-dist-10.5.0-exasol-7.1.1.jar;
+    %jar /buckets/<BFS service>/<bucket>/virtual-schema-dist-10.5.0-exasol-7.1.2.jar;
 /
 ```
 
@@ -47,9 +47,9 @@ You can learn more about [defining named connections](https://docs.exasol.com/sq
 
 You have three options to pick from when connecting to an Exasol instance or cluster. The options are explained below.
 
-### Using IMPORT FROM EXA
+### Using `IMPORT FROM EXA`
 
-Exasol provides the faster and parallel `IMPORT FROM EXA` command for loading data from another Exasol instance. You can tell the adapter to use this command instead of `IMPORT FROM JDBC` by setting the `IMPORT_FROM_EXA` property. 
+Exasol provides the faster and parallel `IMPORT FROM EXA` command for loading data from another Exasol instance. You can tell the adapter to use this command instead of `IMPORT FROM JDBC` by setting the `IMPORT_FROM_EXA` property.
 
 In this case you have to provide the additional `EXA_CONNECTION` which contains the name of the connection definition used for the internally used `IMPORT FROM EXA` command.
 
@@ -76,7 +76,7 @@ IDENTIFIED BY '<password>'
 ```
 
 ```sql
-CREATE VIRTUAL SCHEMA VIRTUAL_EXASOL 
+CREATE VIRTUAL SCHEMA VIRTUAL_EXASOL
 USING SCHEMA_FOR_VS_SCRIPT.ADAPTER_SCRIPT_EXASOL WITH
     CONNECTION_NAME = 'JDBC_CONNECTION'
     SCHEMA_NAME     = '<schema name>'
@@ -91,7 +91,7 @@ You can alternatively use a regular JDBC connection for the `IMPORT`. Note that
 #### Creating a Virtual Schema With JDBC Import
 
 ```sql
-CREATE VIRTUAL SCHEMA <virtual schema name> 
+CREATE VIRTUAL SCHEMA <virtual schema name>
 USING SCHEMA_FOR_VS_SCRIPT.ADAPTER_SCRIPT_EXASOL WITH
     CONNECTION_NAME = 'JDBC_CONNECTION'
     SCHEMA_NAME     = '<schema name>';
@@ -118,7 +118,7 @@ And that `SELECT` can be directly executed by the core database, whereas the `IM
 #### Creating a Local Virtual Schema
 
 ```sql
-CREATE VIRTUAL SCHEMA <virtual schema name> 
+CREATE VIRTUAL SCHEMA <virtual schema name>
 USING SCHEMA_FOR_VS_SCRIPT.ADAPTER_SCRIPT_EXASOL WITH
     CONNECTION_NAME = 'JDBC_CONNECTION'
     SCHEMA_NAME     = '<schema name>'
@@ -170,11 +170,28 @@ IDENTIFIED BY '<password>';
 
 The Exasol SQL dialect supports all capabilities that are supported by the virtual schema framework.
 
-## Known limitations
+## Known Limitations
 
-* Using literals and constant expressions with `TIMESTAMP WITH LOCAL TIME ZONE` data type in Virtual Schemas can produce an incorrect results.
-   * We recommend using `TIMESTAMP` instead.
-   * If you are willing to take the risk and want to use `TIMESTAMP WITH LOCAL TIME ZONE` anyway, please, create a Virtual Schema with the following additional property `IGNORE_ERRORS = 'TIMESTAMP_WITH_LOCAL_TIME_ZONE_USAGE'`.
-   * We also recommend to set Exasol system `time_zone` to UTC while working with `TIMESTAMP WITH LOCAL TIME ZONE`.
-* When using an EXA connection, the outermost order of the imported result rows is not guaranteed. This is not a bug, but a deliberate speed optimization in the ExaLoader (the part that runs the `IMPORT`) caused by parallel import.
-  If you need ordering, please wrap your query into an extra `SELECT * FROM (<virtual-schema-query>) ORDER BY <criteria> [, ...]` which will then be executed on the target Exasol database instead of the source.
+### Data type `TIMESTAMP WITH LOCAL TIME ZONE`
+
+Using literals and constant expressions with `TIMESTAMP WITH LOCAL TIME ZONE` data type in Virtual Schemas can produce an incorrect results.
+* We recommend using `TIMESTAMP` instead.
+* If you are willing to take the risk and want to use `TIMESTAMP WITH LOCAL TIME ZONE` anyway, please, create a Virtual Schema with the following additional property `IGNORE_ERRORS = 'TIMESTAMP_WITH_LOCAL_TIME_ZONE_USAGE'`.
+* We also recommend to set Exasol system `time_zone` to UTC while working with `TIMESTAMP WITH LOCAL TIME ZONE`.
+
+### Clause `ORDER BY`
+
+Clause `ORDER BY` can be used without limitations when using [local connection](#using-is_local).
+
+Connections [EXA](#using-import-from-exa) and [JDBC](#using-import-from-jdbc) are using `IMPORT` which only supports unordered data transfer. Therefore the outermost order of the imported result rows is not guaranteed.
+
+If you need ordering then please
+* apply the ordering on top-level in the Exasol target database outside the virtual schema,
+* use a sub-query to access the virtual schema and
+* annotate the sub-query with `ORDER BY FALSE` to prevent push down of the top-level `ORDER BY`, e.g.
+
+```sql
+SELECT * FROM (<virtual-schema-query> ORDER BY FALSE) ORDER BY <criteria> [, ...]
+```
+
+See also [General Known Limitations](https://docs.exasol.com/db/latest/database_concepts/virtual_schemas.htm#KnownLimitations) in official Exasol documentation on Virtual Schemas.

pom.xml

@@ -2,7 +2,7 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <artifactId>exasol-virtual-schema</artifactId>
-    <version>7.1.1</version>
+    <version>7.1.2</version>
     <name>Exasol Virtual Schema</name>
     <description>This projects contains the Exasol dialect for Exasol's Virtual Schema</description>
     <url>https://github.com/exasol/exasol-virtual-schema/</url>
@@ -28,18 +28,13 @@
         <dependency>
             <groupId>com.exasol</groupId>
             <artifactId>exasol-jdbc</artifactId>
-            <version>7.1.19</version>
+            <version>7.1.20</version>
         </dependency>
         <dependency>
             <groupId>com.exasol</groupId>
             <artifactId>error-reporting-java</artifactId>
             <version>1.0.1</version>
         </dependency>
-        <dependency>
-            <groupId>org.glassfish</groupId>
-            <artifactId>jakarta.json</artifactId>
-            <version>2.0.1</version>
-        </dependency>
         <!--Unit test dependencies -->
         <dependency>
             <groupId>com.exasol</groupId>
@@ -58,32 +53,32 @@
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter</artifactId>
-            <version>5.9.2</version>
+            <version>5.9.3</version>
             <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>org.mockito</groupId>
             <artifactId>mockito-junit-jupiter</artifactId>
-            <version>5.2.0</version>
+            <version>5.4.0</version>
             <scope>test</scope>
         </dependency>
         <!--Integration test dependencies -->
         <dependency>
             <groupId>com.exasol</groupId>
             <artifactId>exasol-testcontainers</artifactId>
-            <version>6.5.1</version>
+            <version>6.6.0</version>
             <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>org.testcontainers</groupId>
             <artifactId>junit-jupiter</artifactId>
-            <version>1.17.6</version>
+            <version>1.18.3</version>
             <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>com.exasol</groupId>
             <artifactId>hamcrest-resultset-matcher</artifactId>
-            <version>1.5.3</version>
+            <version>1.6.0</version>
             <scope>test</scope>
         </dependency>
         <dependency>
@@ -110,7 +105,7 @@
             <plugin>
                 <groupId>com.exasol</groupId>
                 <artifactId>project-keeper-maven-plugin</artifactId>
-                <version>2.9.6</version>
+                <version>2.9.7</version>
                 <executions>
                     <execution>
                         <goals>
@@ -195,7 +190,7 @@
     <parent>
         <artifactId>exasol-virtual-schema-generated-parent</artifactId>
         <groupId>com.exasol</groupId>
-        <version>7.1.1</version>
+        <version>7.1.2</version>
         <relativePath>pk_generated_parent.pom</relativePath>
     </parent>
 </project>

src/test/java/com/exasol/adapter/dialects/exasol/IntegrationTestConfiguration.java

@@ -8,7 +8,7 @@ public final class IntegrationTestConfiguration {
      * Do not use MavenProjectVersionGetter here to enable reference checker to check if reference points to the latest
      * version.
      */
-    public static final String VIRTUAL_SCHEMAS_JAR_NAME_AND_VERSION = "virtual-schema-dist-10.5.0-exasol-7.1.1.jar";
+    public static final String VIRTUAL_SCHEMAS_JAR_NAME_AND_VERSION = "virtual-schema-dist-10.5.0-exasol-7.1.2.jar";
     public static final Path PATH_TO_VIRTUAL_SCHEMAS_JAR = Path.of("target", VIRTUAL_SCHEMAS_JAR_NAME_AND_VERSION);
 
     private IntegrationTestConfiguration() {