@sap/xsodata 8.0.2 → 8.1.2

package/documentation/customExits.md

@@ -0,0 +1,270 @@
+Custom Exits
+============
+
+The xsodata library supports custom exits to enable the application to define JavaScript functions which are called while processing the OData request. These exits can be implemented either as JavaScript function or as stored procedure.
+
+## Available exits
+
+Exits are existing for **Create**ing (POST), **Update**ing (PUT) and **Delete**ing (DELETE) entities and for the database commit ( **precommit** and **postcommit** ), but not for simple **read** requests.
+
+## Exit Definition in an xsodata File
+
+Sample
+
+```xsodata
+service {
+    "my_name_space::customers" as "Customers"
+        keys("CustomerID")
+        navigates("CustomerToProduct" as "Product" from principal)
+        create forbidden
+        update using "sap.abc.xyz:myExits.xsjslib::updateEntity"
+            events( before "sap.abc.xyz:myLoggingInfrastructure.xsjslib::log" )
+        delete forbidden;
+}
+```
+
+### Exit Types
+
+* **Validation Exits**
+    Validation exits allow the application to validate data before/after the data is changed on the database. Any error returned from the application exit function stops the further processing of the request and a rollback is performed. For batch requests also the processing of further requests in the same change set is stopped.
+
+    * Create
+        * ```create events (before "<custom exit 1>", after "<custom exit 2>", ...)```
+            The xsodata library calls the exit **custom exit 1** before creating the entity, and the exit **custom exit 2** after creating the entity
+        * ```create events (precommit "<custom exit 1>", postcommit "<custom exit 2>", ...)```
+            The xsodata library calls the exit **custom exit 1** before committing the data, and the exit **custom exit 2** after committing
+        * ```create forbidden```
+            Prohibits any create on the entity set
+
+    * Update
+        * ```update events (before "<custom exit 1>", after "<custom exit 2>", ...)```
+            The xsodata library calls the exit **custom exit 1** before creating the entity, and the exit **custom exit 2** after updating the entity
+        * ```update events (precommit "<custom exit 1>", postcommit "<custom exit 2>", ...)```
+            The xsodata library calls the exit **custom exit 1** before committing the data, and the exit **custom exit 2** after committing
+        * ```update forbidden```
+            Prohibits any update of the entity
+
+    * Delete
+        * ```delete events (before "<custom exit 1>", after "<custom exit 2>", ...)```
+            The xsodata library calls the exit **custom exit 1** before creating the entity, and the exit **custom exit 2** after deleting the entity
+        * ```delete events (precommit "<custom exit 1>", postcommit "<custom exit 2>", ...)```
+            The xsodata library calls the exit **custom exit 1** before committing the data, and the exit **custom exit 2** after committing
+        * ```delete forbidden```
+            Prohibits the deletion of the entity
+
+* **Modification Exits**
+    * Create
+        * ```create using "<custom exit>"```
+            The xsodata library calls the exit **custom exit** instead of creating the entity directly
+    * Update
+        * ```update using "<custom exit>"```
+            The xsodata library calls the exit **custom exit** instead of updating the entity directly
+    * Delete
+        * ```delete using "<custom exit>"```
+            The xsodata library calls the exit **custom exit** instead of deleting the entity directly
+
+* **Combination of Modification and Validation Exits**
+   Validation and Modification exits can be combined as follows
+   ```create using "<custom exit>" events(before "<custom exit 1>", after "<custom exit 2>", ...)```
+
+**Note**
+You **must not** insert in a validation exit the data from the temporary table into the real table.
+The xsodata library inserts after the validation exit processing the temporary table content into the real table, which will fail if the data is already inserted (dublicate key, constraint violation).
+
+### Exit Execution Order
+
+The execution order of exits for single OData requests:
+
+* **before**
+* **using** (or update by lib happens)
+* **after**
+* **precommit**
+* commit happens
+* **postcommit**
+
+The execution order of exits for batch OData requests (assuming there are 2 requests and a change set with 2 requests inside the batch request)
+
+* Processing of request 1
+    * **before**
+    * **using**
+    * **after**
+    * **precommit**
+    * **postcommit**
+* Processing of change set
+    * Processing of first request in change set
+        * **before**
+        * **using**
+        * **after**
+    * Processing of second request in change set
+        * **before**
+        * **using**
+        * **after**
+    * Commit processing
+        * **precommit** (of first request)
+        * **precommit** (of second request)
+        * commit happens
+        * **postcommit** (of first request)
+        * **postcommit** (of second request)
+* Processing of request 2
+    * **before**
+    * **using**
+    * **after**
+    * **precommit**
+    * **postcommit**
+
+## Exit Implementation
+
+### 1. As xsjs - JavaScript function
+
+#### Exit Function Content
+
+The JavaScript function needs to be implemented within an *.xsjslib file. There is no need to use the export mechanism of node.js, a plain function is fine.
+
+    //myLoggingInfrastructure.xsjslib
+
+    function my_create_before_exit(param) {
+    }
+
+The input parameter `param` is an object with the following content:
+
+* connection: The SQL connection used in the OData request
+* beforeTableName: The name of a temporary table with the single entry before the operation (UPDATE and DELETE events only)
+* afterTableName: The name of a temporary table with the single entry after the operation (UPDATE and CREATE events only)
+
+The content of the temporary tables can be fetched using the available connection as the following example shows:
+
+```js
+var stmt = 'select * from "'+ param.afterTableName + '"',
+    xStmt = param.connection.prepareStatement( stmt ).executeQuery(),
+    data = xStmt._rows[0]; // {col1:val1, col2:val2, ...}
+```
+
+For more details check example validation and modification: **Appendix 1**
+For the service xsodata file check: **Appendix 2**
+
+
+#### Exceptions Handling
+
+The developer of the custom exit function has two possibilities to return an error:
+
+1. Throw an error using `throw "error message";`
+   This way the response will have the status code: 500, and this can't be controlled.
+2. Return an object with the following structure
+    ```
+    return {
+        HTTP_STATUS_CODE: code,   // e.g. 400, 500, etc.
+        ERROR_MESSAGE: 'error message',
+        DETAILS: 'more details'
+    };
+    ```
+    This way the developer is able to add more details, and control the response status code.
+
+#### Referencing the Exit Function
+
+Within the xsodata files, exit functions are referenced with a colon separated string in the format  ```<directory>:<file>::<function>```.
+Considering ```sap.abc.xyz:myLoggingInfrastructure.xsjslib::my_create_before_exit``` as function reference, the first part ```sap.abc.xyz``` references the directory, the second part ```myLoggingInfrastructure.xsjslib``` the xsjslib file and the third part ```my_create_before_exit``` the exit function.
+
+**Example:**
+
+An xsjs startup configuration with two root folders <app directory>/_SYS_REPO and <app directory>/my_content like this:
+
+    //Start xsjs listener
+    xsjs({
+       compress: false,
+       rootDirs: [
+           path.join(__dirname, '_SYS_REPO')
+           path.join(__dirname, 'my_content')
+       ],
+       ...}).listen(...)
+
+Requires that the file ```myLoggingInfrastructure.xsjslib``` is stored in location ```<app directory>/_SYS_REPO/sap/abc/xyz/myLoggingInfrastructure.xsjslib``` or ```<app directory>/my_content/sap/abc/xyz/myLoggingInfrastructure.xsjslib```
+
+
+### 2. As StoredProcedure
+
+Within the xsodata files exit procedures are referenced with a colon separated string in the format  ```<package>::<procedure>```. Considering ```exits::proc_create_update``` as function reference, the first part ```exits``` references the package, the second part ```proc_create_update``` the procedure.
+
+
+## Exit Parameters
+
+The API for an exit function is the same as in *xs classic* (XS1).
+Refer to the ``SAP_HANA_Developer_Guide_for_SAP_HANA_Studio_en_SPS10.pdf`` for more details.
+
+
+## Appendix 1
+
+```js
+function createEmployeeInstead(param) {
+    var after = param.afterTableName,
+        stmt = 'select * from "'+ after + '"',
+        pStmt = param.connection.prepareStatement( stmt ),
+        xStmt = pStmt.executeQuery(),
+        cols = xStmt._columnNames,// [col1, col2, ...]
+        data = xStmt._rows[0];// {col1:val1, col2:val2, ...}
+
+    pStmt.close();
+
+    if (data['id']>100) {
+        console.log('** Err: Not Inserted, throwing ..');
+        // logs can be checked using: xs logs <backend-app> --recent
+
+        throw "ID must not be greater than 100";
+    }
+    else {
+        stmt = 'insert into "com.sap.xsa.samples::EmpOffice.Employee" ("id", "name", "age", "location.id") values (' ;
+            stmt += data['id'] + ',';
+            stmt += '\'' + data['name'] + '\',';
+            stmt += '\'' + data['age'] + '\',';
+            stmt += data['location.id'] + ')';
+
+        console.log('** Inserted');
+        console.log(stmt);
+
+        pStmt = param.connection.prepareStatement( stmt );
+        xStmt = pStmt.executeQuery();
+        pStmt.close();
+    }
+}
+
+function createOfficeBefore(param) {
+    var after = param.afterTableName,
+        stmt = 'select * from "'+ after + '"',
+        pStmt = param.connection.prepareStatement( stmt ),
+        xStmt = pStmt.executeQuery(),
+        cols = xStmt._columnNames,// [col1, col2, ...]
+        data = xStmt._rows[0];// {col1:val1, col2:val2, ...}
+
+    pStmt.close();
+
+    if (data['id']>50) {
+        console.log('** Err: Not Inserted');
+
+        return { HTTP_STATUS_CODE: 400, ERROR_MESSAGE: 'ID is beyond the range', DETAILS: 'ID can not be greater than 50'};
+    } else {
+        console.log('** Continue to create');
+    }
+}
+```
+
+
+## Appendix 2
+
+```js
+service {
+   	"com.sap.xsa.samples::EmpOffice.Office" as "Office"
+   		navigates(
+   			"a_OfEmp" as "nf_Employee" from dependent
+   		)
+   		create events(before "odata.resources:custom.xsjslib::createOfficeBefore");
+
+   	"com.sap.xsa.samples::EmpOffice.Employee" as "Employee"
+   		navigates(
+			"a_OfEmp" as "ne_Office" from principal
+		)
+		create using "odata.resources:custom.xsjslib::createEmployeeInstead";
+
+   	association "a_OfEmp"
+        	principal "Employee"("location.id") multiplicity "*"
+    		dependent "Office"("id") multiplicity "1";
+}
+```

package/documentation/db.md

@@ -0,0 +1,35 @@
+Database connector
+=======================
+
+From version 4.0.0 onwards the xsodata library is supporting also the new **hana-client** DB connector beside 
+the **hdb** DB connector.
+
+The hana-client uses a native library for communication with the HANA database server which is also 
+used by the hana-client for other languages (e.g. java and python). 
+
+By default, when the xsodata library is used the XSA migration scenario, the xsjs layer injects a db connection 
+into the xsodata library (via RequestOptions.dbClient). With xsodata version >= 4.0.0 this object can be either 
+a hana-client client object or a hdb client object, the xsodata is detects the client type and acts accordingly.
+
+If the xsodata library is used standalone (which is not recommended) and the db connections open
+parameters are provided (via HandlerOptions.dbConfiguration) by default the new hana-client is used to 
+open the db connection. To used the hdb client please use the HandlerOptions.dbClient setting.
+
+HandlerOptions.dbClient = 'hdb' // used hdb db client 
+HandlerOptions.dbClient = 'hana-client' // used hana-client db client
+
+**ATTENTION**
+
+Please be aware that the new hana-client is not packaged inside the xsodata library, nor installed automatically 
+with "npm install" due to its size. So if your application is using the xsodata library directly (without xsjs) 
+you must add the dbClient='hdb' configuration setting to use the hdb client or install the hana-client library 
+manually (within the applications package.json). 
+This has been decided to have a defined default client (the **hana-client**) and 
+because the direct usage of the xsodata library is not recommended.
+
+
+  
+ 
+
+   
+

package/documentation/debugView.md

@@ -0,0 +1,13 @@
+# Debug View
+
+The debug view can be used from any http client (ideally a browser) to obtain internal information about a odata request. If used, a the original odata response is replaced with an html page. This html page is send back to the client by the xsodata library with Content-Type *text/html* and contains the original odata response (as html) as well as debug information.
+
+### Prerequisites
+
+In order to get a detailed debug output for a request, two things are necessary:
+
+1.  The xsodata library has to be in *developer mode* for the given request
+    For enabling the developer mode see [Modes](./modes.md)
+1.  The `sap-ds-debug` query parameter has to be set to 'json'
+
+

package/documentation/generatedKeys.md

@@ -0,0 +1,58 @@
+Generated Keys
+==============
+
+### What the HANA SPS10 Dev Guide has to say
+
+For objects that do not have a unique key in their results, for example, calculation views or aggregated tables, you can
+generate a locally valid key. This key value numbers the results starting with 1 and is not meant for dereferencing the entity;
+so you cannot use this key to retrieve the entity. The key is valid only for the duration of the current session and is used only
+to satisfy OData's need for a unique ID in the results. The property type of a generated local key is Edm.String and cannot be
+changed.
+
+Service definition *test.xsodata*
+  
+```xsodata
+service {
+  "xsodata.test.views::all_types_view" as "all_types_view_genkey" key generate local "GenID";
+}
+```
+
+**Metadata retrieved via /test.xsodata/$metadata:** 
+ 
+```xml
+<EntityType Name="all_types_view_genkeyType">
+  <Key>
+    <PropertyRef Name="GenID"/>
+  </Key>
+  <Property Name="GenID" Type="Edm.String" Nullable="false" MaxLength="2147483647"/>
+  <Property Name="KEY" Type="Edm.Int32" Nullable="false"/>
+  <Property Name="DATE" Type="Edm.DateTime"/>
+  <Property Name="TIME" Type="Edm.Time"/>
+  ...
+</EntityType>
+```
+
+### Differences to XS Classic
+
+Error messages differ for requests involving a generated local key:
+
+| Request            | XS1                         | XS2                                     |
+|--------------------|-----------------------------|-----------------------------------------|
+| GET on Entity      | 404 Resource Not Found      | 501 Not Implemented with specific error |
+| DELETE on Entity   | 404 Resource Not Found      | 501 Not Implemented with specific error |
+| PUT on Entity      | 500 with SQL Error          | 501 Not Implemented with specific error |
+| POST on Entity Set | 501 Feature Not Implemented | 501 Not Implemented with specific error |
+
+### Generated Key Checks
+
+Several URI restrictions apply to generated keys.
+
+If an entity type uses a generated key, the following HTTP Methods are not allowed:
+
+| Method   | EntitySet | Entity  |
+|----------|-----------|---------|
+| GET      |           | :x:     |
+| POST     | :x:       | :x:     |
+| PUT      | :x:       | :x:     |
+| DELETE   | :x:       | :x:     |
+

package/documentation/limitations.md

@@ -0,0 +1,20 @@
+Limitations & General Incompatibilities and Differences
+=======================================================
+
+## Batch content
+
+**xsodata** uses CRLF as line separator instead of LF as in XSC SP10. This is defined in 
+See "2.2.7.6.4 Batch Request Syntax" in [ms-odata] specification "June, 10 2011" 
+ 
+## Merge / Patch operations
+
+The Merge / Patch operations are not supported.
+
+## Associations
+
+### Referential Constraints
+
+The metadata response in **XSC SP10** only returns referential constraints, if they
+have been configured in the xsodata file. **XSC SP8** returned them for every
+association. **xsodata** adheres to XSC SP10.
+

package/documentation/modes.md

@@ -0,0 +1,48 @@
+### Modes
+
+The xsodata library currently supports two modes, **development** and **productive**.
+The mode is configured globally per xsodata handler instance, but can be set to
+*development* for an individual request. As the development mode might expose sensitive
+data the default is *productive*.
+
+The mode can only set via Code!
+
+#### Global configuration
+
+For any productive usage, the mode should be set to **productive**, which is also
+the default, if nothing is specified.
+
+
+Samples:
+
+```js
+// Instantiate an xsodata handler in productive mode
+var xsodata = require('sap-xsodata');
+
+var odataHandler = new xsodata.ODataHandler({
+    mode: xsodata.modes.productive
+    // other options
+});
+
+// Instantiate an xsodata handler in development mode
+var xsodata = require('sap-xsodata');
+
+var odataHandler = new xsodata.ODataHandler({
+    mode: xsodata.modes.development
+    // other options
+});
+```
+
+#### Per Request
+
+The developer mode can be activated per request. This enables the application to
+get debug output for a request, for example for specific users having the necessary
+authorization. To enable it, the application has to actively set a property in the
+*RequestOptions*.
+
+```js
+odataHandler.processRequest(request, response, new xsodata.RequestOptions({
+    mode: xsodata.modes.development
+    // other request options
+}), callback);
+```

package/documentation/readme.md

@@ -0,0 +1,83 @@
+Releases and bug fixes
+======================
+
+* [Release overview](./releaseOverview.md)
+
+Limitations
+===========
+
+* [Limitations](./limitations.md)
+
+Samples
+=======
+
+* [xsodata code samples without xsjs](./code_samples_pure_node/readme.md)
+* [Calcview](./calcviewSample.md)
+ 
+Documentation
+=============
+
+* [HANA database connector](./db.md)
+* [Aggregations](./aggregations.md)
+* [Custom Exits](./customExits.md)
+* [Debug View](./debugView.md)
+* [Generated Keys](./generatedKeys.md)
+* [List of supported HTTP methods](./supportedMethods.md)
+* [List of allowed system query options](./supportedSystemQueryOptions.md)
+* [Modes](./modes.md)
+* [Settings](xsodataSettings.md)
+* [Typemapping HANA<->OData](./typemapping.md)
+* [xsodata file definition XS classic](./xsodataEbnf.md)
+* [xsodata file definition XS advanced extentions](xsodataSettings.md)
+
+Features per HANA DB Artifact
+=============================
+
+### Table
+
+Supports the following Features:
+- [Explicit Aggregations](./aggregations.md#explicit-aggregations)
+- [Generated Local Key](./generatedKeys.md)
+ 
+Supported Http Verbs:
+- GET, PUT, POST, DELETE
+
+### SQL View
+
+Supports the following Features:
+- [Explicit Aggregations](./aggregations.md#explicit-aggregations)
+- [Generated Local Key](./generatedKeys.md)
+
+Supported Http Verbs:
+- GET
+
+### XS Advanced Calculation View
+
+Supports the following Features:
+- [Implicit Aggregations](./aggregations.md#implicitderived-aggregations)
+- [Generated Local Key](./generatedKeys.md)
+
+Supported Http Verbs:
+- GET
+
+Supported "hints" setting in xsodata file definition to provide custom hints for SQL-select:
+- By default some SQL statements are executed with hint "NO_CALC_VIEW_UNFOLDING." This is to avoid backward compatibility issues.
+However, since NO_CALC_VIEW_UNFOLDING prohibits some calcview optimisations this hint can be disabled or overwritten.
+For more detail about hints please see [Settings](xsodataSettings.md)
+
+Samples:
+ * Disable all hints (replaces the hints list with an empty list)
+   ```xsodata
+     settings {
+       hints null;
+     }
+   ```
+
+* Custom hints
+   ```xsodata
+     settings {
+       hints "NO_CALC_VIEW_UNFOLDING","<another hint>" ;
+     }
+   ```
+   
+

package/documentation/supportedMethods.md

@@ -0,0 +1,28 @@
+Allowed HTTP Methods
+====================
+
+| URL                               | GET | POST | PUT | DELETE |  
+|-----------------------------------|-----|------|-----|--------|
+| Metadata Document                 |     | :x:  | :x: | :x:    |
+| Service Document                  |     | :x:  | :x: | :x:    |
+| Batch Requests                    | :x: |      | :x: | :x:    |
+| Generated Key Entity Set          |     | :x:  | :x: | :x:    |
+| Generated Key Single Entity       | :x: | :x:  | :x: | :x:    |
+| Regular Entity Set                |     |      | :x: | :x:    |
+| Regular Single Entity             |     | :x:  |     |        |
+| Regular Property                  |     | :x:  |     | :x:    |
+| $value                            |     |      | :x: | :x:    |
+| Indirect Entity Sets              |     | :x:  | :x: | :x:    |
+
+ 
+Modification Forbidden
+======================
+
+Each modifying method can also be explicitly forbidden for an entity type in the service configuration.
+ 
+```xsodata
+"xsodata.test.tables::all_types_modify" as "all_types_modify_forbidden"
+    create forbidden
+    update forbidden
+    delete forbidden;
+```

package/documentation/supportedSystemQueryOptions.md

@@ -0,0 +1,75 @@
+URI Checks
+==========
+
+General System Query Options
+----------------------------
+
+The xsodata library supports the following URI-types (the URI type value is written into the xsodata log file on debug level):
+
+| Uri Type | URI Pattern                                                                                           |
+|----------|-------------------------------------------------------------------------------------------------------|
+| URI0     | scheme serviceRoot                                                                                    |
+| URI1     | scheme serviceRoot "/" entitySet                                                                      |
+| URI2     | scheme serviceRoot "/" entitySet "(" keyPredicate ")"                                                 |
+| URI51    | scheme serviceRoot "/" entitySet "(" keyPredicate ")/" entityProperty                                 |
+| URI52    | scheme serviceRoot "/" entitySet "(" keyPredicate ")/" entityProperty $value                          |
+| URI61    | scheme serviceRoot "/" entitySet "(" keyPredicate ")/" entityNavProperty                              |
+| URI62    | scheme serviceRoot "/" entitySet "(" keyPredicate ")/" collectionNavProperty                          |
+| URI71    | scheme serviceRoot "/" entitySet "(" keyPredicate ")/$links/" entityNavProperty                       |
+| URI72    | scheme serviceRoot "/" entitySet "(" keyPredicate ")/$links/" collectionNavProperty                   |
+| URI8     | scheme serviceRoot "/$metadata"                                                                       |
+| URI9     | scheme serviceRoot "/$batch"                                                                          |
+| URI15    | scheme serviceRoot "/" entitySet /$count                                                              |
+| URI16    | scheme serviceRoot "/" entitySet "(" keyPredicate ")" /$count                                         |
+
+Dependent on the requested resource (e.g. an EntitySet or an Entity) different sets of System Query Options (SQO) are allowed.
+The check for allowed SQO is depending on the URI type and is done in [checkSystemQueryOptions.js](/lib/uri/checks/checkSystemQueryOptions.js).
+
+
+The URI types and their allowed SQO are listed in the following table:
+
+| Uri Type | $expand            | $filter            | $format            | $orderby           | $skip              | $top               | $skiptoken         | $inlinecount       | $select            |
+|----------|--------------------|--------------------|--------------------|--------------------|--------------------|--------------------|--------------------|--------------------|--------------------|
+| URI0     |                    |                    | :white_check_mark: |                    |                    |                    |                    |                    |                    |
+| URI1     | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |                    | :white_check_mark: | :white_check_mark: |
+| URI2     | :white_check_mark: | :white_check_mark: | :white_check_mark: |                    |                    |                    |                    |                    | :white_check_mark: |
+| URI51    |                    |                    | :white_check_mark: |                    |                    |                    |                    |                    |                    |
+| URI52    |                    |                    |                    |                    |                    |                    |                    |                    |                    |
+| URI61    | :white_check_mark: |                    | :white_check_mark: |                    |                    |                    |                    |                    | :white_check_mark: |
+| URI62    | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |                    | :white_check_mark: | :white_check_mark: |
+| URI71    |                    | :white_check_mark: | :white_check_mark: |                    |                    |                    |                    |                    |                    |
+| URI72    |                    | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |                    | :white_check_mark: |                    |
+| URI8     |                    |                    | :white_check_mark: |                    |                    |                    |                    |                    |                    |
+| URI9     |                    |                    |                    |                    |                    |                    |                    |                    |                    |
+| URI15    |                    | :white_check_mark: |                    |                    |                    |                    |                    |                    |                    |
+| URI16    |                    | :white_check_mark: |                    |                    |                    |                    |                    |                    |                    |
+
+#### Remarks:
+
+- The $format option allows only value "json" (the default); except on $metadata requests, where only "xml" (the default) is allowed
+- URI Type 2 supports $filter according to OData 2.0 specification, but in contrast to XS Classic
+- URI Types not listed here, but listed in the OData 2.0 specification, are not supported
+- URI Type 8 allows $format to stay compatible with XS Classic
+- $skiptoken is not supported on all URI types in accordance with XS Classic, return 501 '$skiptoken is not supported'
+
+$filter, $orderby not allowed for Generated Key Columns
+-------------------------------------------------------
+
+*$filter* and *$orderby* are not allowed to contain generated key columns. The server will
+return `400 Bad Request - $filter/$orderby is not allowed for generated key columns.`
+
+**Sample**:
+```
+/all_types_view_genkey?$format=json&$filter=GenID eq 1
+```
+
+$filter not allowed for Aggregated Columns
+-------------------------------------------
+
+*$filter* is not allowed to contain generated key columns. The server will
+return `400 Bad Request - $filter is not allowed for generated key columns.`
+
+**Sample**:
+```
+/ExpAggregationSumAmountFactor?$format=json&$select=Amount,Year&$orderby=Amount&$filter=Amount gt 100
+```

package/documentation/typemapping.md

@@ -0,0 +1,32 @@
+Type mapping OData <--> HANA
+============================
+
+| SAP HANA SQL Type | OData EDM Type    |
+|-------------------|-------------------|
+| Time              |   Edm.Time        |
+| Date              |   Edm.DateTime    |
+| SecondDate        |   Edm.DateTime    |
+| LongDate          |   Edm.DateTime    |
+| Timestamp         |   Edm.DateTime    |
+| TinyInt           |   Edm.Byte        |
+| SmallInt          |   Edm.Int16       |
+| Integer           |   Edm.Int32       |
+| BigInt            |   Edm.Int64       |
+| SmallDecimal      |   Edm.Decimal     |
+| Decimal           |   Edm.Decimal     |
+| Real              |   Edm.Single      |
+| Float             |   Edm.Single      |
+| Double            |   Edm.Double      |
+| Varchar           |   Edm.String      |
+| NVarchar          |   Edm.String      |
+| Char              |   Edm.String      |
+| NChar             |   Edm.String      |
+| Binary            |   Edm.Binary      |
+| Varbinary         |   Edm.Binary      |     
+| Alphanum          |  Edm.String      |
+| Shorttext*          |  Edm.String      |
+| Blob*           |   Edm.Binary      |
+| Clob*           |   Edm.String      |
+| NClob*           |   Edm.String      |
+
+* not as table key type