Repository: calcite Updated Branches: refs/heads/master 1bbb6a2b9 -> 1c5eddd04
[CALCITE-984] Massive cleanup of Avatica JSON docs * Added docs for many missing messages * Ensured Requests/Responses/Misc were sorted alphabetically * Added missing `rpcMetadata` fields * Changed styling of enum list items Project: http://git-wip-us.apache.org/repos/asf/calcite/repo Commit: http://git-wip-us.apache.org/repos/asf/calcite/commit/1c5eddd0 Tree: http://git-wip-us.apache.org/repos/asf/calcite/tree/1c5eddd0 Diff: http://git-wip-us.apache.org/repos/asf/calcite/diff/1c5eddd0 Branch: refs/heads/master Commit: 1c5eddd0494f8b292736a4c6e300da4c697235f0 Parents: 1bbb6a2 Author: Josh Elser <[email protected]> Authored: Fri Dec 18 14:19:00 2015 -0500 Committer: Josh Elser <[email protected]> Committed: Fri Dec 18 14:34:39 2015 -0500 ---------------------------------------------------------------------- site/_docs/avatica_json_reference.md | 559 ++++++++++++++++++++---------- 1 file changed, 371 insertions(+), 188 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/calcite/blob/1c5eddd0/site/_docs/avatica_json_reference.md ---------------------------------------------------------------------- diff --git a/site/_docs/avatica_json_reference.md b/site/_docs/avatica_json_reference.md index c2244a6..857e948 100644 --- a/site/_docs/avatica_json_reference.md +++ b/site/_docs/avatica_json_reference.md @@ -12,39 +12,49 @@ requests: - { name: "ConnectionSyncRequest" } - { name: "CreateStatementRequest" } - { name: "DatabasePropertyRequest" } + - { name: "ExecuteRequest" } - { name: "FetchRequest" } + - { name: "OpenConnectionRequest" } - { name: "PrepareAndExecuteRequest" } - { name: "PrepareRequest" } - { name: "RollbackRequest" } - { name: "SchemasRequest" } + - { name: "SyncResultsRequest" } - { name: "TableTypesRequest" } - { name: "TablesRequest" } - { name: "TypeInfoRequest" } miscellaneous: - - { name: "ConnectionProperties" } - - { name: "TypedValue" } - - { name: "Signature" } - - { name: "Frame" } - - { name: "StatementHandle" } - - { name: "DatabaseProperty" } - - { name: "ColumnMetaData" } - { name: "AvaticaParameter" } + - { name: "AvaticaSeverity" } - { name: "AvaticaType" } - - { name: "Rep" } + - { name: "ColumnMetaData" } + - { name: "ConnectionProperties" } - { name: "CursorFactory" } + - { name: "DatabaseProperty" } + - { name: "Frame" } + - { name: "QueryState" } + - { name: "Rep" } + - { name: "RpcMetadata" } + - { name: "Signature" } + - { name: "StateType" } + - { name: "StatementHandle" } - { name: "Style" } + - { name: "TypedValue" } responses: - - { name: "ResultSetResponse" } - - { name: "ExecuteResponse" } - - { name: "PrepareResponse" } - - { name: "FetchResponse" } - - { name: "CreateStatementResponse" } - - { name: "CloseStatementResponse" } - { name: "CloseConnectionResponse" } + - { name: "CloseStatementResponse" } + - { name: "CommitResponse" } - { name: "ConnectionSyncResponse" } + - { name: "CreateStatementResponse" } - { name: "DatabasePropertyResponse" } - - { name: "CommitResponse" } + - { name: "ErrorResponse" } + - { name: "ExecuteResponse" } + - { name: "FetchResponse" } + - { name: "OpenConnectionResponse" } + - { name: "PrepareResponse" } + - { name: "ResultSetResponse" } - { name: "RollbackResponse" } + - { name: "SyncResultsResponse" } --- <!-- @@ -201,6 +211,23 @@ There are no extra attributes on this Request. There are no extra attributes on this Request. +### ExecuteRequest + +{% highlight json %} +{ + "request": "execute", + "statementHandle": StatementHandle, + "parameterValues": [TypedValue, TypedValue, ... ], + "maxRowCount": 100 +} +{% endhighlight %} + +`statementHandle` (required object) A <a href="#statementhandle">StatementHandle</a> object. + +`parameterValues` (optional array of nested objects) The <a href="#typedvalue">TypedValue</a> for each parameter on the prepared statement. + +`maxRowCount` (required long) The maximum number of rows returned in the response. + ### FetchRequest {% highlight json %} @@ -222,7 +249,21 @@ There are no extra attributes on this Request. `fetchMatchRowCount` (required integer) The maximum number of rows to return in the response to this request. -`parameterValues` (optional array of nested objects) The types of the object to set on the prepared statement in use. +`parameterValues` (optional array of nested objects) The <a href="#typedvalue">TypedValue</a> for each parameter on the prepared statement. + +### OpenConnectionRequest + +{% highlight json %} +{ + "request": "openConnection", + "connectionId": "000000-0000-0000-00000000", + "info": {"key":"value", ...} +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to open in the server. + +`info` (optional string-to-string map) A Map containing properties to include when creating the Connection. ### PrepareAndExecuteRequest @@ -261,6 +302,26 @@ There are no extra attributes on this Request. `maxRowCount` (required long) The maximum number of rows returned in the response. +### SyncResultsRequest + +{% highlight json %} +{ + "request": "syncResults", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345, + "state": QueryState, + "offset": 200 +} +{% endhighlight %} + +`connectionId` (required string) The identifier for the connection to use. + +`statementId` (required integer) The identifier for the statement to use. + +`state` (required object) The <a href="#querystate">QueryState</a> object. + +`offset` (required long) The offset into the ResultSet to seek to. + ### RollbackRequest {% highlight json %} @@ -331,66 +392,51 @@ There are no extra attributes on this Request. The collection of all JSON objects returned as responses from Avatica. All Responses include a `response` attribute which uniquely identifies the concrete Response from all other Responses. -### ResultSetResponse +### CloseConnectionResponse {% highlight json %} { - "response": "resultSet", - "connectionId": "000000-0000-0000-00000000", - "statementId": 12345, - "ownStatement": true, - "signature": Signature, - "firstFrame": Frame, - "updateCount": 10 + "response": "closeConnection", + "rpcMetadata": RpcMetadata } {% endhighlight %} -`connectionId` The identifier for the connection used to generate this response. - -`statementId` The identifier for the statement used to generate this response. - -`ownStatement` Whether the result set has its own dedicated statement. If true, the server must automatically close the -statement when the result set is closed. This is used for JDBC metadata result sets, for instance. - -`signature` A non-optional nested object <a href="#signature">Signature</a> - -`firstFrame` A optional nested object <a href="#frame">Frame</a> - -`updateCount` A number which is always `-1` for normal result sets. Any other value denotes a "dummy" result set -that only contains this count and no additional data. +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. -### ExecuteResponse +### CloseStatementResponse {% highlight json %} { - "response": "executeResults", - "resultSets": [ ResultSetResponse, ResultSetResponse, ... ] + "response": "closeStatement", + "rpcMetadata": RpcMetadata } {% endhighlight %} -`resultSets` An array of <a href="#resultsetresponse">ResultSetResponse</a>s. +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. -### PrepareResponse +### CommitResponse {% highlight json %} { - "response": "prepare", - "statement": StatementHandle + "response": "commit" } {% endhighlight %} -`statement` A <a href="#statementhandle">StatementHandle</a> object. +There are no extra attributes on this Response. -### FetchResponse +### ConnectionSyncResponse {% highlight json %} { - "response": "fetch", - "frame": Frame + "response": "connectionSync", + "connProps": ConnectionProperties, + "rpcMetadata": RpcMetadata } {% endhighlight %} -`frame` A <a href="#frame">Frame</a> containing the results of the fetch. +`connProps` The <a href="#connectionproperties">ConnectionProperties</a> that were synchronized. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. ### CreateStatementResponse @@ -398,7 +444,8 @@ that only contains this count and no additional data. { "response": "createStatement", "connectionId": "000000-0000-0000-00000000", - "statementId": 12345 + "statementId": 12345, + "rpcMetadata": RpcMetadata } {% endhighlight %} @@ -406,171 +453,223 @@ that only contains this count and no additional data. `statementId` The identifier for the created statement. -### CloseStatementResponse +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### DatabasePropertyResponse {% highlight json %} { - "response": "closeStatement", + "response": "databaseProperties", + "map": { DatabaseProperty: Object, DatabaseProperty: Object, ... }, + "rpcMetadata": RpcMetadata } {% endhighlight %} -This response has no attributes. +`map` A map of <a href="#databaseproperty">DatabaseProperty</a> to value of that property. The value may be some +primitive type or an array of primitive types. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. -### CloseConnectionResponse +### ErrorResponse {% highlight json %} { - "response": "closeConnection", + "response": "error", + "exceptions": [ "stacktrace", "stacktrace", ... ], + "errorMessage": "The error message", + "errorCode": 42, + "sqlState": "ABC12", + "severity": AvaticaSeverity, + "rpcMetadata": RpcMetadata } {% endhighlight %} -There are no extra attributes on this Response. +`exceptions` A list of stringified Java StackTraces. -### ConnectionSyncResponse +`errorMessage` A human-readable error message. + +`errorCode` A numeric code for this error. + +`sqlState` A five character alphanumeric code for this error. + +`severity` An <a href="#avaticaseverity">AvaticaSeverity</a> object which denotes how critical the error is. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### ExecuteResponse {% highlight json %} { - "response": "connectionSync", - "connProps": ConnectionProperties + "response": "executeResults", + "resultSets": [ ResultSetResponse, ResultSetResponse, ... ], + "rpcMetadata": RpcMetadata } {% endhighlight %} -`connProps` The <a href="#connectionproperties">ConnectionProperties</a> that were synchronized. +`resultSets` An array of <a href="#resultsetresponse">ResultSetResponse</a>s. -### DatabasePropertyResponse +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### FetchResponse {% highlight json %} { - "response": "databaseProperties", - "map": { DatabaseProperty: Object, DatabaseProperty: Object, ... } + "response": "fetch", + "frame": Frame, + "rpcMetadata": RpcMetadata } {% endhighlight %} -`map` A map of <a href="#databaseproperty">DatabaseProperty</a> to value of that property. The value may be some -primitive type or an array of primitive types. +`frame` A <a href="#frame">Frame</a> containing the results of the fetch. -### CommitResponse +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### OpenConnectionResponse {% highlight json %} { - "response": "commit" + "response": "openConnection", + "rpcMetadata": RpcMetadata } {% endhighlight %} -There are no extra attributes on this Response. +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. -### RollbackResponse +### PrepareResponse {% highlight json %} { - "response": "rollback" + "response": "prepare", + "statement": StatementHandle, + "rpcMetadata": RpcMetadata } {% endhighlight %} -There are no extra attributes on this Response. +`statement` A <a href="#statementhandle">StatementHandle</a> object. -## Miscellaneous +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. -### ConnectionProperties +### ResultSetResponse {% highlight json %} { - "connProps": "connPropsImpl", - "autoCommit": true, - "readOnly": true, - "transactionIsolation": 0, - "catalog": "catalog", - "schema": "schema" + "response": "resultSet", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345, + "ownStatement": true, + "signature": Signature, + "firstFrame": Frame, + "updateCount": 10, + "rpcMetadata": RpcMetadata } {% endhighlight %} -`autoCommit` (optional boolean) A boolean denoting if autoCommit is enabled for transactions. +`connectionId` The identifier for the connection used to generate this response. -`readOnly` (optional boolean) A boolean denoting if a JDBC connection is read-only. +`statementId` The identifier for the statement used to generate this response. -`transactionIsolation` (optional integer) An integer which denotes the level of transactions isolation per the JDBC -specification. This value is analogous to the values define in `java.sql.Connection`. +`ownStatement` Whether the result set has its own dedicated statement. If true, the server must automatically close the +statement when the result set is closed. This is used for JDBC metadata result sets, for instance. -* 0 = Transactions are not supported -* 1 = Dirty reads, non-repeatable reads and phantom reads may occur. -* 2 = Dirty reads are prevented, but non-repeatable reads and phantom reads may occur. -* 4 = Dirty reads and non-repeatable reads are prevented, but phantom reads may occur. -* 8 = Dirty reads, non-repeatable reads, and phantom reads are all prevented. +`signature` A non-optional nested object <a href="#signature">Signature</a> -### TypedValue +`firstFrame` A optional nested object <a href="#frame">Frame</a> + +`updateCount` A number which is always `-1` for normal result sets. Any other value denotes a "dummy" result set +that only contains this count and no additional data. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### RollbackResponse {% highlight json %} { - "type": "type_name", - "value": object + "response": "rollback" } {% endhighlight %} -`type` A name referring to the type of the object stored in `value`. +There are no extra attributes on this Response. -`value` A JSON representation of a JDBC type. - -### Signature +### SyncResultsResponse {% highlight json %} { - "columns": [ ColumnMetaData, ColumnMetaData, ... ], - "sql": "SELECT * FROM table", - "parameters": [ AvaticaParameter, AvaticaParameter, ... ], - "cursorFactory": CursorFactory + "response": "syncResults", + "moreResults": true, + "missingStatement": false, + "rpcMetadata": RpcMetadata } {% endhighlight %} -`columns` An array of <a href="#columnmetadata">ColumnMetaData</a> objects denoting the schema of the result set. +`moreResults` A boolean which denotes if results exist for the ResultSet being "synced" per the request. -`sql` The SQL executed. +`missingStatement` A boolean which denotes if the statement for the ResultSet still exists. -`parameters` An array of <a href="#avaticaparameter">AvaticaParameter</a> objects denoting type-specific details. +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. -`cursorFactory` An <a href="#cursorfactory">CursorFactory</a> object representing the Java representation of the frame. +## Miscellaneous -### Frame +### AvaticaParameter {% highlight json %} { - "offset": 100, - "done": true, - "rows": [ [ val1, val2, ... ], ... ] + "signed": true, + "precision": 10, + "scale": 2, + "parameterType": 8, + "typeName": "integer", + "className": "java.lang.Integer", + "name": "number" } {% endhighlight %} -`offset` The starting position of these `rows` in the encompassing result set. +`signed` A boolean denoting whether the column is a signed numeric. -`done` A boolean denoting whether more results exist for this result set. +`precision` The maximum numeric precision supported by this column. -`rows` An array of arrays corresponding to the rows and columns for the result set. +`scale` The maximum numeric scale supported by this column. -### StatementHandle +`parameterType` An integer corresponding to the JDBC Types class denoting the column's type. + +`typeName` The JDBC type name for this column. + +`className` The Java class backing the JDBC type for this column. + +`name` The name of the column. + +### AvaticaSeverity + +One of: + +* `UNKNOWN` +* `FATAL` +* `ERROR` +* `WARNING` + +### AvaticaType {% highlight json %} { - "connectionId": "000000-0000-0000-00000000", - "id": 12345, - "signature": Signature + "type": "scalar", + "id": "identifier", + "name": "column", + "rep": Rep, + "columns": [ ColumnMetaData, ColumnMetaData, ... ], + "component": AvaticaType } {% endhighlight %} -`connectionId` The identifier of the connection to which this statement belongs. +`type` One of: `scalar`, `array`, `struct`. -`id` The identifier of the statement. +`id` A numeric value corresponding to the type of the object per the JDBC Types class. -`signature` A <a href="#signature">Signature</a> object for the statement. +`name` The readable name of the JDBC type. -### DatabaseProperty +`rep` A nested <a href="#rep">Rep</a> object used by Avatica to hold additional type information. -One of: +`columns` For `STRUCT` types, a list of the columns contained in that `STRUCT`. -* "GET_STRING_FUNCTIONS" -* "GET_NUMERIC_FUNCTIONS" -* "GET_SYSTEM_FUNCTIONS" -* "GET_TIME_DATE_FUNCTIONS" -* "GET_S_Q_L_KEYWORDS" -* "GET_DEFAULT_TRANSACTION_ISOLATION" +`component` For `ARRAY` types, the type of the elements contained in that `ARRAY`. ### ColumnMetaData @@ -643,107 +742,191 @@ One of: `columnClassName` The name of the Java class backing the column's type. -### AvaticaParameter +### ConnectionProperties {% highlight json %} { - "signed": true, - "precision": 10, - "scale": 2, - "parameterType": 8, - "typeName": "integer", - "className": "java.lang.Integer", - "name": "number" + "connProps": "connPropsImpl", + "autoCommit": true, + "readOnly": true, + "transactionIsolation": 0, + "catalog": "catalog", + "schema": "schema" } {% endhighlight %} -`signed` A boolean denoting whether the column is a signed numeric. +`autoCommit` (optional boolean) A boolean denoting if autoCommit is enabled for transactions. -`precision` The maximum numeric precision supported by this column. +`readOnly` (optional boolean) A boolean denoting if a JDBC connection is read-only. -`scale` The maximum numeric scale supported by this column. +`transactionIsolation` (optional integer) An integer which denotes the level of transactions isolation per the JDBC +specification. This value is analogous to the values define in `java.sql.Connection`. -`parameterType` An integer corresponding to the JDBC Types class denoting the column's type. +* 0 = Transactions are not supported +* 1 = Dirty reads, non-repeatable reads and phantom reads may occur. +* 2 = Dirty reads are prevented, but non-repeatable reads and phantom reads may occur. +* 4 = Dirty reads and non-repeatable reads are prevented, but phantom reads may occur. +* 8 = Dirty reads, non-repeatable reads, and phantom reads are all prevented. -`typeName` The JDBC type name for this column. +### CursorFactory -`className` The Java class backing the JDBC type for this column. +{% highlight json %} +{ + "style": Style, + "clazz": "java.lang.String", + "fieldNames": [ "column1", "column2", ... ] +} +{% endhighlight %} -`name` The name of the column. +`style` A string denoting the <a href="#style">Style</a> of the contained objects. -### AvaticaType +### DatabaseProperty + +One of: + +* `GET_STRING_FUNCTIONS` +* `GET_NUMERIC_FUNCTIONS` +* `GET_SYSTEM_FUNCTIONS` +* `GET_TIME_DATE_FUNCTIONS` +* `GET_S_Q_L_KEYWORDS` +* `GET_DEFAULT_TRANSACTION_ISOLATION` + +### Frame {% highlight json %} { - "type": "scalar", - "id": "identifier", - "name": "column", - "rep": Rep, - "columns": [ ColumnMetaData, ColumnMetaData, ... ], - "component": AvaticaType + "offset": 100, + "done": true, + "rows": [ [ val1, val2, ... ], ... ] } {% endhighlight %} -`type` One of: `scalar`, `array`, `struct`. +`offset` The starting position of these `rows` in the encompassing result set. -`id` A numeric value corresponding to the type of the object per the JDBC Types class. +`done` A boolean denoting whether more results exist for this result set. -`name` The readable name of the JDBC type. +`rows` An array of arrays corresponding to the rows and columns for the result set. -`rep` A nested <a href="#rep">Rep</a> object used by Avatica to hold additional type information. +### QueryState -`columns` For `STRUCT` types, a list of the columns contained in that `STRUCT`. +{% highlight json %} +{ + "type": StateType, + "sql": "SELECT * FROM table", + "metaDataOperation": MetaDataOperation, + "operationArgs": ["arg0", "arg1", ... ] +} +{% endhighlight %} -`component` For `ARRAY` types, the type of the elements contained in that `ARRAY`. +`type` A <a href="#statetype">StateType</a> object denoting what type of operation backs the ResultSet for this query. + +`sql` The SQL statement which created the ResultSet for this query. Required if the `type` is `SQL`. + +`metaDataOperation` The DML operation which created the ResultSet for this query. Required if the `type` is `METADATA`. + +`operationArgs` The arguments to the invoked DML operation. Required if the `type` is `METADATA`. ### Rep One of: -* "PRIMITIVE_BOOLEAN" -* "PRIMITIVE_BYTE" -* "PRIMITIVE_CHAR" -* "PRIMITIVE_SHORT" -* "PRIMITIVE_INT" -* "PRIMITIVE_LONG" -* "PRIMITIVE_FLOAT" -* "PRIMITIVE_DOUBLE" -* "BOOLEAN" -* "BYTE" -* "CHARACTER" -* "SHORT" -* "INTEGER" -* "LONG" -* "FLOAT" -* "DOUBLE" -* "JAVA_SQL_TIME" -* "JAVA_SQL_TIMESTAMP" -* "JAVA_SQL_DATE" -* "JAVA_UTIL_DATE" -* "BYTE_STRING" -* "STRING" -* "NUMBER" -* "OBJECT" +* `PRIMITIVE_BOOLEAN` +* `PRIMITIVE_BYTE` +* `PRIMITIVE_CHAR` +* `PRIMITIVE_SHORT` +* `PRIMITIVE_INT` +* `PRIMITIVE_LONG` +* `PRIMITIVE_FLOAT` +* `PRIMITIVE_DOUBLE` +* `BOOLEAN` +* `BYTE` +* `CHARACTER` +* `SHORT` +* `INTEGER` +* `LONG` +* `FLOAT` +* `DOUBLE` +* `JAVA_SQL_TIME` +* `JAVA_SQL_TIMESTAMP` +* `JAVA_SQL_DATE` +* `JAVA_UTIL_DATE` +* `BYTE_STRING` +* `STRING` +* `NUMBER` +* `OBJECT` -### CursorFactory +### RpcMetadata {% highlight json %} { - "style": Style, - "clazz": "java.lang.String", - "fieldNames": [ "column1", "column2", ... ] + "serverAddress": "http://localhost:8765"; } {% endhighlight %} -`style` A string denoting the <a href="#style">Style</a> of the contained objects. +`serverAddress` The URL of the server which created this object. + +### Signature + +{% highlight json %} +{ + "columns": [ ColumnMetaData, ColumnMetaData, ... ], + "sql": "SELECT * FROM table", + "parameters": [ AvaticaParameter, AvaticaParameter, ... ], + "cursorFactory": CursorFactory +} +{% endhighlight %} + +`columns` An array of <a href="#columnmetadata">ColumnMetaData</a> objects denoting the schema of the result set. + +`sql` The SQL executed. + +`parameters` An array of <a href="#avaticaparameter">AvaticaParameter</a> objects denoting type-specific details. + +`cursorFactory` An <a href="#cursorfactory">CursorFactory</a> object representing the Java representation of the frame. + +### StateType + +One of: + +* `SQL` +* `METADATA` + +### StatementHandle + +{% highlight json %} +{ + "connectionId": "000000-0000-0000-00000000", + "id": 12345, + "signature": Signature +} +{% endhighlight %} + +`connectionId` The identifier of the connection to which this statement belongs. + +`id` The identifier of the statement. + +`signature` A <a href="#signature">Signature</a> object for the statement. ### Style One of: -* "OBJECT" -* "RECORD" -* "RECORD_PROJECTION" -* "ARRAY" -* "LIST" -* "MAP" +* `OBJECT` +* `RECORD` +* `RECORD_PROJECTION` +* `ARRAY` +* `LIST` +* `MAP` + +### TypedValue + +{% highlight json %} +{ + "type": "type_name", + "value": object +} +{% endhighlight %} + +`type` A name referring to the type of the object stored in `value`. + +`value` A JSON representation of a JDBC type.
