#255: Improved documentation

exasol · Sep 13, 2022 · 7525476 · 7525476
1 parent 8aadcc5
commit 7525476
Show file tree

Hide file tree

Showing 9 changed files with 76 additions and 46 deletions.
diff --git a/doc/changes/changelog.md b/doc/changes/changelog.md
diff --git a/doc/changes/changes_16.1.1.md b/doc/changes/changes_16.1.1.md
@@ -0,0 +1,11 @@
+# Common module of Exasol Virtual Schemas Adapters 16.1.1, released 2022-09-13
+
+Code name: Documentation Update
+
+## Summary
+
+Updated documentation.
+
+## Features
+
+* #255: Improved documentation
diff --git a/doc/development/api/capabilities_list.md b/doc/development/api/capabilities_list.md
@@ -2,6 +2,13 @@
 
 Here you can find a list of available Virtual Schema capabilities.
 
+* [Main Capabilities](#main-capabilities)
+* [Literal Capabilities](#literal-capabilities)
+* [Predicate Capabilities](#predicate-capabilities)
+* [Scalar Function Capabilities](#scalar-function-capabilities)
+* [Aggregate Function Capabilities](#aggregate-function-capabilities)
+
+
 ## [Main Capabilities](../../../src/main/java/com/exasol/adapter/capabilities/MainCapability.java)
 
 - AGGREGATE_GROUP_BY_COLUMN
@@ -253,7 +260,7 @@ Here you can find a list of available Virtual Schema capabilities.
 - FN_AGG_AVG
 - FN_AGG_AVG_DISTINCT
 - FN_AGG_COUNT
-- FN_AGG_COUNT_DISTINCT 
+- FN_AGG_COUNT_DISTINCT
 - FN_AGG_COUNT_STAR
 - FN_AGG_COUNT_TUPLE
 - FN_AGG_EVERY
@@ -273,7 +280,7 @@ Here you can find a list of available Virtual Schema capabilities.
 - FN_AGG_LISTAGG_SEPARATOR
 - FN_AGG_MAX
 - FN_AGG_MEDIAN
-- FN_AGG_MIN 
+- FN_AGG_MIN
 - FN_AGG_MUL
 - FN_AGG_MUL_DISTINCT
 - FN_AGG_SOME

diff --git a/doc/development/api/data_types_api.md b/doc/development/api/data_types_api.md
@@ -119,3 +119,7 @@ Notes:
     "bytesize" : 16
 }
 ```
+
+Notes:
+
+* `bytesize`: Optional. The default value is `16`.
diff --git a/doc/development/api/scalar_functions_api.md b/doc/development/api/scalar_functions_api.md
@@ -6,22 +6,22 @@ This page describes how Exasol scalar functions map to the Virtual Schemas push-
 
 ### Functions With a Common API
 
-* [Functions without arguments](#functions-without-arguments);
-* [Functions with a single argument](#functions-with-a-single-argument);
-* [Functions with multiple arguments](#functions-with-multiple-arguments);
-* [Arithmetic operators](#arithmetic-operators).
+* [Functions without arguments](#functions-without-arguments)
+* [Functions with a single argument](#functions-with-a-single-argument)
+* [Functions with multiple arguments](#functions-with-multiple-arguments)
+* [Arithmetic operators](#arithmetic-operators)
 
 ### Functions With a Special API
 
 This section contains functions that have a special API mapping.
-  
+
 | Function Name     | API Mapping Link                            |
 |-------------------|---------------------------------------------|
 | EXTRACT           | [EXTRACT function](#extract-function)       |
 | CASE              | [CASE function](#case-function)             |
 | CAST              | [CAST function](#cast-function)             |
 | JSON_VALUE        | [JSON_VALUE function](#json_value-function) |
-     
+
 ### Functions Not Included in the API
 
 This section contains Exasol functions which are not included in the API.
@@ -287,12 +287,12 @@ Notes:
 * `results`: The different results in the same order as the arguments. If present, the ELSE result is the last entry in the `results` array.
 * `basis`: Optional.
 
-Here is an example of a query containing a CASE function and its JSON representation (only the function part): 
+Here is an example of a query containing a CASE function and its JSON representation (only the function part):
 
 ```sql
 SELECT CASE grade
           WHEN 1 THEN 'GOOD'
-          WHEN 2 THEN 'FAIR' 
+          WHEN 2 THEN 'FAIR'
           WHEN 3 THEN 'POOR'
           ELSE 'INVALID'
           END
@@ -348,7 +348,7 @@ FROM VIRTUAL_SCHEMA_EXASOL.ALL_EXASOL_TYPES;
 
 `JSON_VALUE(arg1, arg2 RETURNING dataType {ERROR | NULL | DEFAULT exp1} ON EMPTY {ERROR | NULL | DEFAULT exp2} ON ERROR)`
  (requires scalar-function capability `JSON_VALUE`)
- 
+
 ```json
 {
     "type": "function_scalar_json_value",
@@ -385,7 +385,7 @@ Notes:
 A scalar function, that does not contain any column references, might be executed before reaching Virtual Schemas.
 That means the JSON request does not contain the scalar function, but a literal value representing its result.
 For example, the query `SELECT ABS(-123), c5 FROM VIRTUAL_SCHEMA_EXASOL.ALL_EXASOL_TYPES` will have the following select list:
-  
+
 ```json
 {
   ...
@@ -402,7 +402,7 @@ For example, the query `SELECT ABS(-123), c5 FROM VIRTUAL_SCHEMA_EXASOL.ALL_EXAS
       "name": "C5"
     }
   ],
-  
+
   ...
 }
 ```
diff --git a/doc/development/api/virtual_schema_api.md b/doc/development/api/virtual_schema_api.md
@@ -36,12 +36,12 @@ To get a better understanding let's take a look on how the Exasol database proce
 
 ![virtual schema query processing](../../../src/uml/requestHandling.png)
 
-The diagram shows how Exasol handles Virtual Schema queries: 
+The diagram shows how Exasol handles Virtual Schema queries:
 
-- When the core receives an SQL query on a Virtual Schema table, it first checks the capabilities of the corresponding Virtual Schema adapter. Based on that information it removes all functions and literals that are not supported by the adapter. 
-- Next, the Exasol Core sends a query to the Virtual Schema adapter as a `PushdownRequest`. 
-- The Virtual Schema adapter now rewrites the query into a new SQL statement that typically invokes the Exasol importer `IMPORT INTO ...`. For details see the [`IMPORT` statements documentation](https://docs.exasol.com/sql/import.htm). The importer statement contains a query to the external database as a string. 
-- Next, the Exasol database parses this statement again and invokes the importer. 
+- When the core receives an SQL query on a Virtual Schema table, it first checks the capabilities of the corresponding Virtual Schema adapter. Based on that information it removes all functions and literals that are not supported by the adapter.
+- Next, the Exasol Core sends a query to the Virtual Schema adapter as a `PushdownRequest`.
+- The Virtual Schema adapter now rewrites the query into a new SQL statement that typically invokes the Exasol importer `IMPORT INTO ...`. For details see the [`IMPORT` statements documentation](https://docs.exasol.com/sql/import.htm). The importer statement contains a query to the external database as a string.
+- Next, the Exasol database parses this statement again and invokes the importer.
 - Finally, the Exasol core applies the functions that were not supported by the remote database itself as post processing and returns that result to the SQL client.
 
 Instead of the `IMPORT` statement the adapter can also create other SQL statements.
@@ -139,7 +139,7 @@ Request to set and unset properties. The Adapter can decide whether it needs to
 
 ```json
 {
-    
+
     "type": "setProperties",
     "properties": {
         "JDBC_CONNECTION_STRING": "new-jdbc-connection-string",
@@ -158,7 +158,7 @@ Request to set and unset properties. The Adapter can decide whether it needs to
 
 The new values appear in a separate object `/properties` directly in the root element. For reference the current property values are still reported under '/schemaMetadataInfo/properties'.
 
-Adapters must apply the properties incrementally, meaning that all parameters not explicitly listed in `/properties`, remain unchanged. 
+Adapters must apply the properties incrementally, meaning that all parameters not explicitly listed in `/properties`, remain unchanged.
 
 **Response:**
 
@@ -261,24 +261,19 @@ LIMIT  10;
 
 ##### Capability Prefixes
 
-- Main Capabilities: No prefix
-- Literal Capabilities: LITERAL_
-- Predicate Capabilities: FN_PRED_
-- Scalar Function Capabilities: FN_
-- Aggregate Function Capabilities: FN_AGG_
-
-See also [a list of supported Capabilities](capabilities_list.md).
+See also [List of supported Capabilities](capabilities_list.md).
 
-Capabilities can be also found in the sources of the Virtual Schema Common Java:
-* [Main Capabilities](https://github.com/exasol/virtual-schema-common-java/blob/master/src/main/java/com/exasol/adapter/capabilities/MainCapability.java)
-* [Literal Capabilities](https://github.com/exasol/virtual-schema-common-java/blob/master/src/main/java/com/exasol/adapter/capabilities/LiteralCapability.java)
-* [Predicate Capabilities](https://github.com/exasol/virtual-schema-common-java/blob/master/src/main/java/com/exasol/adapter/capabilities/PredicateCapability.java)
-* [Scalar Function Capabilities](https://github.com/exasol/virtual-schema-common-java/blob/master/src/main/java/com/exasol/adapter/capabilities/ScalarFunctionCapability.java)
-* [Aggregate Function Capabilities](https://github.com/exasol/virtual-schema-common-java/blob/master/src/main/java/com/exasol/adapter/capabilities/AggregateFunctionCapability.java)
+| Capability 			  | Prefix     | Java Implementation |
+|---------------------------------|------------|---------------------|
+| [Main Capabilities](capabilities_list.md#main-capabilities)                             | (none)     | [MainCapability.java](https://github.com/exasol/virtual-schema-common-java/blob/master/src/main/java/com/exasol/adapter/capabilities/MainCapability.java)                        |
+| [Literal Capabilities](capabilities_list.md#literal-capabilities)		          | `LITERAL_` | [LiteralCapability.java](https://github.com/exasol/virtual-schema-common-java/blob/master/src/main/java/com/exasol/adapter/capabilities/LiteralCapability.java)         	    |
+| [Predicate Capabilities](capabilities_list.md#predicate-capabilities)		          | `FN_PRED_` | [PredicateCapability.java](https://github.com/exasol/virtual-schema-common-java/blob/master/src/main/java/com/exasol/adapter/capabilities/PredicateCapability.java)		    |
+| [Scalar Function Capabilities](capabilities_list.md#scalar-function-capabilities)       | `FN_`      | [ScalarFunctionCapability.java](https://github.com/exasol/virtual-schema-common-java/blob/master/src/main/java/com/exasol/adapter/capabilities/ScalarFunctionCapability.java)	    |
+| [Aggregate Function Capabilities](capabilities_list.md#aggregate-function-capabilities) | `FN_AGG_`  | [AggregateFunctionCapability.java](https://github.com/exasol/virtual-schema-common-java/blob/master/src/main/java/com/exasol/adapter/capabilities/AggregateFunctionCapability.java)|
 
 ### Pushdown
 
-Contains an abstract specification of what to be pushed down, and requests an pushdown SQL statement from the Adapter which can be used to retrieve the requested data.
+Contains an abstract specification of what to be pushed down, and requests a pushdown SQL statement from the Adapter which can be used to retrieve the requested data.
 
 **Request:**
 
@@ -395,6 +390,19 @@ will produce the following Request, assuming that the Adapter has all required c
             "numElements" : 10
         }
     },
+    "selectListDataTypes" :
+    [
+    	{
+    		"precision" : 18,
+    		"scale" : 0,
+    		"type" : "DECIMAL"
+    	},
+    	{
+    		"precision" : 10,
+    		"scale" : 0,
+    		"type" : "DECIMAL"
+    	}
+    ],
     "involvedTables": [
     {
         "name" : "CLICKS",
@@ -456,6 +464,8 @@ Notes
   * `orderBy`: The requested order-by clause, a list of `order_by_element` elements.
   * `limit` The requested limit of the result set, with an optional offset.
 * `involvedTables`: Metadata of the involved tables, encoded like in schemaMetadata.
+* `selectListDataTypes`: List of data tyes expected in the result set.
+  This information is only provided by Exasol database with major version 8 and higher, see [Exasol Data Types API Documentation](data_types_api.md).
 
 **Response:**
 
@@ -607,14 +617,14 @@ This element currently only occurs in from clause
 {
     "type": "join",
     "join_type": "inner",
-    "left": { 
-        ... 
+    "left": {
+        ...
     },
-    "right" : { 
-        ... 
+    "right" : {
+        ...
     },
-    "condition" : { 
-        ... 
+    "condition" : {
+        ...
     }
 }
 ```

diff --git a/doc/error_codes.md b/doc/error_codes.md
diff --git a/pk_generated_parent.pom b/pk_generated_parent.pom
diff --git a/pom.xml b/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>virtual-schema-common-java</artifactId>
-    <version>16.1.0</version>
+    <version>16.1.1</version>
     <name>Common module of Exasol Virtual Schemas Adapters</name>
     <description>This is one of the modules of Virtual Schemas Adapters. The libraries provided by this project are the
         foundation of the adapter development, i.e. adapters must be implemented on top of them.</description>
@@ -102,7 +102,7 @@
     <parent>
         <artifactId>virtual-schema-common-java-generated-parent</artifactId>
         <groupId>com.exasol</groupId>
-        <version>16.1.0</version>
+        <version>16.1.1</version>
         <relativePath>pk_generated_parent.pom</relativePath>
     </parent>
 </project>
-Original file line number
+Diff line change
@@ Expand Up / @@ -119,3 +119,7 @@ Notes: @@
         "bytesize" : 16
     }
     ```
+    Notes:
+    * `bytesize`: Optional. The default value is `16`.