http://git-wip-us.apache.org/repos/asf/calcite/blob/5cee486f/avatica/site/_docs/avatica_json_reference.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/avatica_json_reference.md b/avatica/site/_docs/avatica_json_reference.md new file mode 100644 index 0000000..d49be7c --- /dev/null +++ b/avatica/site/_docs/avatica_json_reference.md @@ -0,0 +1,1086 @@ +--- +layout: docs +title: Avatica JSON Reference +sidebar_title: JSON Reference +permalink: /docs/avatica_json_reference.html +requests: + - { name: "CatalogsRequest" } + - { name: "CloseConnectionRequest" } + - { name: "CloseStatementRequest" } + - { name: "ColumnsRequest" } + - { name: "CommitRequest" } + - { 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: "AvaticaParameter" } + - { name: "AvaticaSeverity" } + - { name: "AvaticaType" } + - { name: "ColumnMetaData" } + - { name: "ConnectionProperties" } + - { name: "CursorFactory" } + - { name: "DatabaseProperty" } + - { name: "Frame" } + - { name: "QueryState" } + - { name: "Rep" } + - { name: "RpcMetadata" } + - { name: "Signature" } + - { name: "StateType" } + - { name: "StatementHandle" } + - { name: "StatementType" } + - { name: "Style" } + - { name: "TypedValue" } +responses: + - { name: "CloseConnectionResponse" } + - { name: "CloseStatementResponse" } + - { name: "CommitResponse" } + - { name: "ConnectionSyncResponse" } + - { name: "CreateStatementResponse" } + - { name: "DatabasePropertyResponse" } + - { name: "ErrorResponse" } + - { name: "ExecuteResponse" } + - { name: "FetchResponse" } + - { name: "OpenConnectionResponse" } + - { name: "PrepareResponse" } + - { name: "ResultSetResponse" } + - { name: "RollbackResponse" } + - { name: "SyncResultsResponse" } +--- + +<!-- +{% comment %} +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to you under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +{% endcomment %} +--> + +As Avatica uses JSON to serialize messages sent over an HTTP transport, +the RPC layer is agnostic of the language used by a client. While the Avatica +server is written in Java, this enables clients to interact with the server +using any language instead of being limited to Java. + +A specification of the JSON request and response objects are documented +below. Programmatic bindings for these JSON objects are only available +in Java. For support outside of Java, see the Protocol Buffer +[bindings]({{ site.baseurl }}/docs/avatica_protobuf_reference.html) + +## Index + +### Requests +<ul> + {% for item in page.requests %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} +</ul> + +### Responses +<ul> + {% for item in page.responses %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} +</ul> + +### Miscellaneous +<ul> + {% for item in page.miscellaneous %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} +</ul> + + +## Requests + +The collection of all JSON objects accepted as requests to Avatica. All Requests include a `request` attribute +which uniquely identifies the concrete Request from all other Requests. + +### CatalogsRequest + +This request is used to fetch the available catalog names in the database. + +{% highlight json %} +{ + "request": "getCatalogs", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to use. + +### CloseConnectionRequest + +This request is used to close the Connection object in the Avatica server identified by the given IDs. + +{% highlight json %} +{ + "request": "closeConnection", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to close. + +### CloseStatementRequest + +This request is used to close the Statement object in the Avatica server identified by the given IDs. + +{% highlight json %} +{ + "request": "closeStatement", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345 +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to which the statement belongs. + +`statementId` (required integer) The identifier of the statement to close. + +### ColumnsRequest + +This request is used to fetch columns in the database given some optional filtering criteria. + +{% highlight json %} +{ + "request": "getColumns", + "connectionId": "000000-0000-0000-00000000", + "catalog": "catalog", + "schemaPattern": "schema_pattern.*", + "tableNamePattern": "table_pattern.*", + "columnNamePattern": "column_pattern.*" +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection on which to fetch the columns. + +`catalog` (optional string) The name of a catalog to limit returned columns. + +`schemaPattern` (optional string) A Java Pattern against schemas to limit returned columns. + +`tableNamePattern` (optional string) A Java Pattern against table names to limit returned columns. + +`columnNamePattern` (optional string) A Java Pattern against column names to limit returned columns. + +### CommitRequest + +This request is used to issue a `commit` on the Connection in the Avatica server identified by the given ID. + +{% highlight json %} +{ + "request": "commit", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection on which to invoke commit. + +### ConnectionSyncRequest + +This request is used to ensure that the client and server have a consistent view of the database properties. + +{% highlight json %} +{ + "request": "connectionSync", + "connectionId": "000000-0000-0000-00000000", + "connProps": ConnectionProperties +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to synchronize. + +`connProps` (optional nested object) A <a href="#connectionproperties">ConnectionProperties</a> object to synchronize between the client and server. + +### CreateStatementRequest + +This request is used to create a new Statement in the Avatica server. + +{% highlight json %} +{ + "request": "createStatement", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to use in creating a statement. + +### DatabasePropertyRequest + +This request is used to fetch all <a href="#databaseproperty">database properties</a>. + +{% highlight json %} +{ + "request": "databaseProperties", +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to use when fetching the database properties. + +### ExecuteRequest + +This request is used to execute a PreparedStatement, optionally with values to bind to the parameters in the Statement. + +{% 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 + +This request is used to fetch a batch of rows from a Statement previously created. + +{% highlight json %} +{ + "request": "fetch", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345, + "offset": 0, + "fetchMaxRowCount": 100 +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to use. + +`statementId` (required integer) The identifier of the statement created using the above connection. + +`offset` (required integer) The positional offset into a result set to fetch. + +`fetchMatchRowCount` (required integer) The maximum number of rows to return in the response to this request. + +### OpenConnectionRequest + +This request is used to open a new Connection in the Avatica server. + +{% 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 + +This request is used as a short-hand for create a Statement and fetching the first batch of results in a single call without any parameter substitution. + +{% highlight json %} +{ + "request": "prepareAndExecute", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345, + "sql": "SELECT * FROM table", + "maxRowCount": 100, +} +{% endhighlight %} + +`connectionId` (required string) The identifier for the connection to use. + +`statementId` (required integer) The identifier for the statement created by the above connection to use. + +`sql` (required string) A SQL statement + +`maxRowCount` (required long) The maximum number of rows returned in the response. + +### PrepareRequest + +This request is used to create create a new Statement with the given query in the Avatica server. + +{% highlight json %} +{ + "request": "prepare", + "connectionId": "000000-0000-0000-00000000", + "sql": "SELECT * FROM table", + "maxRowCount": 100, +} +{% endhighlight %} + +`connectionId` (required string) The identifier for the connection to use. + +`sql` (required string) A SQL statement + +`maxRowCount` (required long) The maximum number of rows returned in the response. + +### SyncResultsRequest + +This request is used to reset a ResultSet's iterator to a specific offset in the Avatica server. + +{% 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 + +This request is used to issue a `rollback` on the Connection in the Avatica server identified by the given ID. + +{% highlight json %} +{ + "request": "rollback", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` (required string) The identifier for the connection on which to invoke rollback. + +### SchemasRequest + +This request is used to fetch the schemas matching the provided criteria in the database. + +{% highlight json %} +{ + "request": "getSchemas", + "connectionId": "000000-0000-0000-00000000", + "catalog": "name", + "schemaPattern": "pattern.*" +} +{% endhighlight %} + +`connection_id` The identifier for the connection to fetch schemas from. + +`catalog` (required string) The name of the catalog to fetch the schema from. + +`schemaPattern` (required string) A Java pattern of schemas to fetch. + +### TableTypesRequest + +This request is used to fetch the table types available in this database. + +{% highlight json %} +{ + "request": "getTableTypes", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` The identifier of the connection to fetch the table types from. + +### TablesRequest + +This request is used to fetch the tables available in this database filtered by the provided criteria. + +{% highlight json %} +{ + "request": "getTables", + "connectionId": "000000-0000-0000-00000000", + "catalog": "catalog_name", + "schemaPattern": "schema_pattern.*", + "tableNamePattern": "table_name_pattern.*", + "typeList": [ "TABLE", "VIEW", ... ] +} +{% endhighlight %} + +`catalog` (optional string) The name of a catalog to restrict fetched tables. + +`connectionId` The identifier of the connection to fetch the tables from. + +`schemaPattern` (optional string) A Java Pattern representing schemas to include in fetched tables. + +`tableNamePattern` (optional string) A Java Pattern representing table names to include in fetched tables. + +`typeList` (optional array of string) A list of table types used to restrict fetched tables. + +### TypeInfoRequest + +This request is used to fetch the types available in this database. + +{% highlight json %} +{ + "request": "getTypeInfo", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` The identifier of the connection to fetch the types from. + +## Responses + +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. + +### CloseConnectionResponse + +A response to the <a href="#closeconnectionrequest">CloseConnectionRequest</a>. + +{% highlight json %} +{ + "response": "closeConnection", + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### CloseStatementResponse + +A response to the <a href="#closestatementrequest">CloseStatementRequest</a>. + +{% highlight json %} +{ + "response": "closeStatement", + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### CommitResponse + +A response to the <a href="#commitrequest">CommitRequest</a>. + +{% highlight json %} +{ + "response": "commit" +} +{% endhighlight %} + +There are no extra attributes on this Response. + +### ConnectionSyncResponse + +A response to the <a href="#connectionsyncrequest">ConnectionSyncRequest</a>. Properties included in the +response are those of the Connection in the Avatica server. + +{% highlight json %} +{ + "response": "connectionSync", + "connProps": ConnectionProperties, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`connProps` The <a href="#connectionproperties">ConnectionProperties</a> that were synchronized. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### CreateStatementResponse + +A response to the <a href="#createstatementrequest">CreateStatementRequest</a>. The ID of the statement +that was created is included in the response. Clients will use this `statementId` in subsequent calls. + +{% highlight json %} +{ + "response": "createStatement", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`connectionId` The identifier for the connection used to create the statement. + +`statementId` The identifier for the created statement. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### DatabasePropertyResponse + +A response to the <a href="#databasepropertyrequest">DatabasePropertyRequest</a>. See <a hred="#databaseproperty">DatabaseProperty</a> +for information on the available property keys. + +{% highlight json %} +{ + "response": "databaseProperties", + "map": { DatabaseProperty: Object, DatabaseProperty: Object, ... }, + "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. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### ErrorResponse + +A response when an error was caught executing a request. Any request may return this response. + +{% highlight json %} +{ + "response": "error", + "exceptions": [ "stacktrace", "stacktrace", ... ], + "errorMessage": "The error message", + "errorCode": 42, + "sqlState": "ABC12", + "severity": AvaticaSeverity, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`exceptions` A list of stringified Java StackTraces. + +`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 + +A response to the <a href="#executerequest">ExecuteRequest</a> which contains the results for a metadata query. + +{% highlight json %} +{ + "response": "executeResults", + "resultSets": [ ResultSetResponse, ResultSetResponse, ... ], + "missingStatement": false, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`resultSets` An array of <a href="#resultsetresponse">ResultSetResponse</a>s. + +`missingStatement` A boolean which denotes if the request failed due to a missing Statement. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### FetchResponse + +A response to the <a href="#fetchrequest">FetchRequest</a> which contains the request for the query. + +{% highlight json %} +{ + "response": "fetch", + "frame": Frame, + "missingStatement": false, + "missingResults": false, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`frame` A <a href="#frame">Frame</a> containing the results of the fetch. + +`missingStatement` A boolean which denotes if the request failed due to a missing Statement. + +`missingResults` A boolean which denotes if the request failed due to a missing ResultSet. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### OpenConnectionResponse + +A response to the <a href="#openconnectionrequest">OpenConnectionRequest</a>. The ID for the connection that +the client should use in subsequent calls was provided by the client in the request. + +{% highlight json %} +{ + "response": "openConnection", + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### PrepareResponse + +A response to the <a href="#preparerequest">PrepareRequest</a>. This response includes a <a href="#statementhandle">StatementHandle</a> +which clients must use to fetch the results from the Statement. + +{% highlight json %} +{ + "response": "prepare", + "statement": StatementHandle, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`statement` A <a href="#statementhandle">StatementHandle</a> object. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### ResultSetResponse + +A response which contains the results and type details from a query. + +{% highlight json %} +{ + "response": "resultSet", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345, + "ownStatement": true, + "signature": Signature, + "firstFrame": Frame, + "updateCount": 10, + "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. + +### RollbackResponse + +A response to the <a href="#rollbackrequest">RollBackRequest</a>. + +{% highlight json %} +{ + "response": "rollback" +} +{% endhighlight %} + +There are no extra attributes on this Response. + +### SyncResultsResponse + +A response to the <a href="#syncresultsrequest">SyncResultsRequest</a>. When `moreResults` is true, a <a href="#fetchrequest">FetchRequest</a> +should be issued to get the next batch of records. When `missingStatement` is true, the statement must be re-created using <a href="#preparerequest">PrepareRequest</a> +or the appropriate Request for a DDL request (e.g. <a href="#catalogsrequest">CatalogsRequest</a> or <a href="#schemasrequest">SchemasRequest</a>). + +{% highlight json %} +{ + "response": "syncResults", + "moreResults": true, + "missingStatement": false, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`moreResults` A boolean which denotes if results exist for the ResultSet being "synced" per the request. + +`missingStatement` A boolean which denotes if the statement for the ResultSet still exists. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +## Miscellaneous + +### AvaticaParameter + +This object describes the "simple", or scalar, JDBC type representation of a column in a result. This does not include +complex types such as arrays. + +{% highlight json %} +{ + "signed": true, + "precision": 10, + "scale": 2, + "parameterType": 8, + "typeName": "integer", + "className": "java.lang.Integer", + "name": "number" +} +{% endhighlight %} + +`signed` A boolean denoting whether the column is a signed numeric. + +`precision` The maximum numeric precision supported by this column. + +`scale` The maximum numeric scale supported by this column. + +`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 + +This enumeration describes the various levels of concern for an error in the Avatica server. + +One of: + +* `UNKNOWN` +* `FATAL` +* `ERROR` +* `WARNING` + +### AvaticaType + +This object describes a simple or complex type for a column. Complex types will contain +additional information in the `component` or `columns` attribute which describe the nested +types of the complex parent type. + +{% highlight json %} +{ + "type": "scalar", + "id": "identifier", + "name": "column", + "rep": Rep, + "columns": [ ColumnMetaData, ColumnMetaData, ... ], + "component": AvaticaType +} +{% endhighlight %} + +`type` One of: `scalar`, `array`, `struct`. + +`id` A numeric value corresponding to the type of the object per the JDBC Types class. + +`name` The readable name of the JDBC type. + +`rep` A nested <a href="#rep">Rep</a> object used by Avatica to hold additional type information. + +`columns` For `STRUCT` types, a list of the columns contained in that `STRUCT`. + +`component` For `ARRAY` types, the type of the elements contained in that `ARRAY`. + +### ColumnMetaData + +This object represents the JDBC ResultSetMetaData for a column. + +{% highlight json %} +{ + "ordinal": 0, + "autoIncrement": true, + "caseSensitive": true, + "searchable": false, + "currency": false, + "nullable": 0, + "signed": true, + "displaySize": 20, + "label": "Description", + "columnName": "col1", + "schemaName": "schema", + "precision": 10, + "scale": 2, + "tableName": "table", + "catalogName": "catalog", + "type": AvaticaType, + "readOnly": false, + "writable": true, + "definitelyWritable": true, + "columnClassName": "java.lang.String" +} +{% endhighlight %} + +`ordinal` A positional offset number. + +`autoIncrement` A boolean denoting whether the column is automatically incremented. + +`caseSensitive` A boolean denoting whether the column is case sensitive. + +`searchable` A boolean denoting whether this column supports all WHERE search clauses. + +`currency` A boolean denoting whether this column represents currency. + +`nullable` A number denoting whether this column supports null values. + +* 0 = No null values are allowed +* 1 = Null values are allowed +* 2 = It is unknown if null values are allowed + +`signed` A boolean denoting whether the column is a signed numeric. + +`displaySize` The character width of the column. + +`label` A description for this column. + +`columnName` The name of the column. + +`schemaName` The schema to which this column belongs. + +`precision` The maximum numeric precision supported by this column. + +`scale` The maximum numeric scale supported by this column. + +`tableName` The name of the table to which this column belongs. + +`catalogName` The name of the catalog to which this column belongs. + +`type` A nested <a href="#avaticatype">AvaticaType</a> representing the type of the column. + +`readOnly` A boolean denoting whether the column is read-only. + +`writable` A boolean denoting whether the column is possible to be updated. + +`definitelyWritable` A boolean denoting whether the column definitely can be updated. + +`columnClassName` The name of the Java class backing the column's type. + +### ConnectionProperties + +This object represents the properties for a given JDBC Connection. + +{% highlight json %} +{ + "connProps": "connPropsImpl", + "autoCommit": true, + "readOnly": true, + "transactionIsolation": 0, + "catalog": "catalog", + "schema": "schema" +} +{% endhighlight %} + +`autoCommit` (optional boolean) A boolean denoting if autoCommit is enabled for transactions. + +`readOnly` (optional boolean) A boolean denoting if a JDBC connection is read-only. + +`transactionIsolation` (optional integer) An integer which denotes the level of transactions isolation per the JDBC +specification. This value is analogous to the values defined in `java.sql.Connection`. + +* 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. + +`catalog` (optional string) The name of the catalog to include when fetching connection properties. + +`schema` (optional string) The name of the schema to include when fetching connection properties. + +### CursorFactory + +This object represents the information required to cast untyped objects into the necessary type for some results. + +{% highlight json %} +{ + "style": Style, + "clazz": "java.lang.String", + "fieldNames": [ "column1", "column2", ... ] +} +{% endhighlight %} + +`style` A string denoting the <a href="#style">Style</a> of the contained objects. + +### DatabaseProperty + +This object represents the exposed database properties for a Connection through the Avatica server. + +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 + +This object represents a batch of results, tracking the offset into the results and whether more results still exist +to be fetched in the Avatica server. + +{% highlight json %} +{ + "offset": 100, + "done": true, + "rows": [ [ val1, val2, ... ], ... ] +} +{% endhighlight %} + +`offset` The starting position of these `rows` in the encompassing result set. + +`done` A boolean denoting whether more results exist for this result set. + +`rows` An array of arrays corresponding to the rows and columns for the result set. + +### QueryState + +This object represents the way a ResultSet was created in the Avatica server. A ResultSet could be created by a user-provided +SQL or by a DatabaseMetaData operation with arguments on that operation. + +{% highlight json %} +{ + "type": StateType, + "sql": "SELECT * FROM table", + "metaDataOperation": MetaDataOperation, + "operationArgs": ["arg0", "arg1", ... ] +} +{% endhighlight %} + +`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 + +This enumeration represents the concrete Java type for some value. + +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` + +### RpcMetadata + +This object contains assorted per-call/contextual metadata returned by the Avatica server. + +{% highlight json %} +{ + "serverAddress": "localhost:8765" +} +{% endhighlight %} + +`serverAddress` The `host:port` of the server which created this object. + +### Signature + +This object represents the result of preparing a Statement in the Avatica server. + +{% highlight json %} +{ + "columns": [ ColumnMetaData, ColumnMetaData, ... ], + "sql": "SELECT * FROM table", + "parameters": [ AvaticaParameter, AvaticaParameter, ... ], + "cursorFactory": CursorFactory, + "statementType": StatementType +} +{% 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. + +`statementType` An <a href="#statementtype">StatementType</a> object representing the type of Statement. + +### StateType + +This enumeration denotes whether user-provided SQL or a DatabaseMetaData operation was used to create some ResultSet. + +One of: + +* `SQL` +* `METADATA` + +### StatementHandle + +This object encapsulates all of the information of a Statement created in the Avatica server. + +{% 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. + +### StatementType + +This enumeration represents what kind the Statement is. + +One of: + +* `SELECT` +* `INSERT` +* `UPDATE` +* `DELETE` +* `UPSERT` +* `MERGE` +* `OTHER_DML` +* `CREATE` +* `DROP` +* `ALTER` +* `OTHER_DDL` +* `CALL` + +### Style + +This enumeration represents the generic "class" of type for a value. + +One of: + +* `OBJECT` +* `RECORD` +* `RECORD_PROJECTION` +* `ARRAY` +* `LIST` +* `MAP` + +### TypedValue + +This object encapsulates the type and value for a column in a row. + +{% 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.
http://git-wip-us.apache.org/repos/asf/calcite/blob/5cee486f/avatica/site/_docs/avatica_overview.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/avatica_overview.md b/avatica/site/_docs/avatica_overview.md new file mode 100644 index 0000000..6c77eb9 --- /dev/null +++ b/avatica/site/_docs/avatica_overview.md @@ -0,0 +1,130 @@ +--- +layout: docs +title: Avatica Overview +sidebar_title: Overview +permalink: /docs/avatica_overview.html +--- + +<!-- +{% comment %} +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to you under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +{% endcomment %} +--> + +Avatica is a framework for building JDBC and ODBC drivers for databases, +and an RPC wire protocol. + + + +Avatica's Java binding has very few dependencies. +Even though it is part of Apache Calcite it does not depend on other parts of +Calcite. It depends only on JDK 1.7+ and Jackson. + +Avatica's wire protocol is JSON over HTTP. +The Java implementation uses Jackson to convert request/response command +objects to/from JSON. + +Avatica-Server is a Java implementation of Avatica RPC. + +Core concepts: + +* Meta is a local API sufficient to implement any Avatica provider +* Factory creates implementations of the JDBC classes (Driver, Connection, + Statement, ResultSet) on top of a Meta +* Service is an interface that implements the functions of Meta in terms + of request and response command objects + +## JDBC + +Avatica implements JDBC by means of Factory. +Factory creates implementations of the JDBC classes (Driver, Connection, +Statement, PreparedStatement, ResultSet) on top of a Meta. + +## ODBC + +Work has not started on Avatica ODBC. + +Avatica ODBC would use the same wire protocol and could use the same server +implementation in Java. The ODBC client would be written in C or C++. + +Since the Avatica protocol abstracts many of the differences between providers, +the same ODBC client could be used for different databases. + +## HTTP Server + +Avatica-server embeds the Jetty HTTP server, providing a class +[HttpServer]({{ site.apiRoot }}/org/apache/calcite/avatica/server/HttpServer.html) +that implements the Avatica RPC protocol +and can be run as a standalone Java application. + +Connectors in HTTP server can be configured if needed by extending +`HttpServer` class and overriding its `configureConnector()` method. +For example, user can set `requestHeaderSize` to 64K bytes as follows: + +{% highlight java %} +HttpServer server = new HttpServer(handler) { + @Override + protected ServerConnector configureConnector( + ServerConnector connector, int port) { + HttpConnectionFactory factory = (HttpConnectionFactory) + connector.getDefaultConnectionFactory(); + factory.getHttpConfiguration().setRequestHeaderSize(64 << 10); + return super.configureConnector(connector, port); + } +}; +server.start(); +{% endhighlight %} + +## Project structure + +We know that it is important that client libraries have minimal dependencies. + +Avatica is currently part of Apache Calcite. +It does not depend upon any other part of Calcite. +At some point Avatica could become a separate project. + +Packages: + +* [org.apache.calcite.avatica]({{ site.apiRoot }}/org/apache/calcite/avatica/package-summary.html) Core framework +* [org.apache.calcite.avatica.remote]({{ site.apiRoot }}/org/apache/calcite/avatica/remote/package-summary.html) JDBC driver that uses remote procedure calls +* [org.apache.calcite.avatica.server]({{ site.apiRoot }}/org/apache/calcite/avatica/server/package-summary.html) HTTP server +* [org.apache.calcite.avatica.util]({{ site.apiRoot }}/org/apache/calcite/avatica/util/package-summary.html) Utilities + +## Status + +### Implemented + +* Create connection, create statement, metadata, prepare, bind, execute, fetch +* RPC using JSON over HTTP +* Local implementation +* Implementation over an existing JDBC driver +* Composite RPCs (combining several requests into one round trip) + * Execute-Fetch + * Metadata-Fetch (metadata calls such as getTables return all rows) + +### Not implemented + +* ODBC +* RPCs + * CloseStatement + * CloseConnection +* Composite RPCs + * CreateStatement-Prepare + * CloseStatement-CloseConnection + * Prepare-Execute-Fetch (Statement.executeQuery should fetch first N rows) +* Remove statements from statement table +* DML (INSERT, UPDATE, DELETE) +* Statement.execute applied to SELECT statement http://git-wip-us.apache.org/repos/asf/calcite/blob/5cee486f/avatica/site/_docs/avatica_protobuf_reference.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/avatica_protobuf_reference.md b/avatica/site/_docs/avatica_protobuf_reference.md new file mode 100644 index 0000000..02a8ab1 --- /dev/null +++ b/avatica/site/_docs/avatica_protobuf_reference.md @@ -0,0 +1,1181 @@ +--- +layout: docs +title: Avatica Protocol Buffers Reference +sidebar_title: Protobuf Reference +permalink: /docs/avatica_protobuf_reference.html +requests: + - { name: "CatalogsRequest" } + - { name: "CloseConnectionRequest" } + - { name: "CloseStatementRequest" } + - { name: "ColumnsRequest" } + - { name: "CommitRequest" } + - { 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: "AvaticaParameter" } + - { name: "AvaticaSeverity" } + - { name: "AvaticaType" } + - { name: "ColumnMetaData" } + - { name: "ColumnValue" } + - { name: "ConnectionProperties" } + - { name: "CursorFactory" } + - { name: "DatabaseProperty" } + - { name: "Frame" } + - { name: "QueryState" } + - { name: "Rep" } + - { name: "Row" } + - { name: "RpcMetadata" } + - { name: "Signature" } + - { name: "StateType" } + - { name: "StatementHandle" } + - { name: "StatementType" } + - { name: "Style" } + - { name: "TypedValue" } + - { name: "WireMessage" } +responses: + - { name: "CloseConnectionResponse" } + - { name: "CloseStatementResponse" } + - { name: "CommitResponse" } + - { name: "ConnectionSyncResponse" } + - { name: "CreateStatementResponse" } + - { name: "DatabasePropertyResponse" } + - { name: "ErrorResponse" } + - { name: "ExecuteResponse" } + - { name: "FetchResponse" } + - { name: "OpenConnectionResponse" } + - { name: "PrepareResponse" } + - { name: "ResultSetResponse" } + - { name: "RollbackResponse" } + - { name: "SyncResultsResponse" } +--- + +<!-- +{% comment %} +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to you under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +{% endcomment %} +--> + +Avatica also supports [Protocol Buffers](https://developers.google.com/protocol-buffers/) +as a message format since version 1.5.0. The Protocol Buffer, or protobuf for +short, implementation is extremely similar to the JSON implementation. Some +differences include protobuf's expanded type support (such as native byte arrays) +and inability to differentiate between the default value for a field and the +absence of a value for a field. + +Other notable structural differences to JSON include the addition of a +`WireMessage` message which is used to identify the type of the wrapped message +returned by the server (synonymous with `request` or `response` attribute on the +JSON messages) and a change to `TypedValue` containing an `Object` value to +a collection of optional strongly-typed values (as protobuf does not natively +support an `Object` type that is unwrapped at runtime). + +Unless otherwise specified with use of the `required` modifier, all fields in +all protocol buffer messages are `optional` by default. + +## Index + +### Requests +<ul> + {% for item in page.requests %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} +</ul> + +### Responses +<ul> + {% for item in page.responses %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} +</ul> + +### Miscellaneous +<ul> + {% for item in page.miscellaneous %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} +</ul> + + +## Requests + +The collection of all protobuf objects accepted as requests to Avatica. All request +objects should be wrapped in a `WireMessage` before being sent to Avatica. + +### CatalogsRequest + +This request is used to fetch the available catalog names in the database. + +{% highlight protobuf %} +message CatalogsRequest { + string connection_id = 1; +} +{% endhighlight %} + +`connection_id` The identifier for the connection to use. + +### CloseConnectionRequest + +This request is used to close the Connection object in the Avatica server identified by the given IDs. + +{% highlight protobuf %} +message CloseConnectionRequest { + string connection_id = 1; +} +{% endhighlight %} + +`connection_id` The identifier of the connection to close. + +### CloseStatementRequest + +This request is used to close the Statement object in the Avatica server identified by the given IDs. + +{% highlight protobuf %} +message CloseStatementRequest { + string connection_id = 1; + uint32 statement_id = 2; +} +{% endhighlight %} + +`connection_id` The identifier of the connection to which the statement belongs. + +`statement_id` The identifier of the statement to close. + +### ColumnsRequest + +This request is used to fetch columns in the database given some optional filtering criteria. + +{% highlight protobuf %} +message ColumnsRequest { + string catalog = 1; + string schema_pattern = 2; + string table_name_pattern = 3; + string column_name_pattern = 4; + string connection_id = 5; +} +{% endhighlight %} + +`catalog` The name of a catalog to limit returned columns. + +`schema_pattern` A Java Pattern against schemas to limit returned columns. + +`table_name_pattern` A Java Pattern against table names to limit returned columns. + +`column_name_pattern` A Java Pattern against column names to limit returned columns. + +`connection_id` The identifier of the connection which to use to fetch the columns. + +### CommitRequest + +This request is used to issue a `commit` on the Connection in the Avatica server identified by the given ID. + +{% highlight protobuf %} +message CommitRequest { + string connection_id = 1; +} +{% endhighlight %} + +`connection_id` The identifier of the connection on which to invoke commit. + +### ConnectionSyncRequest + +This request is used to ensure that the client and server have a consistent view of the database properties. + +{% highlight protobuf %} +message ConnectionSyncRequest { + string connection_id = 1; + ConnectionProperties conn_props = 2; +} +{% endhighlight %} + +`connection_id` The identifier of the connection to synchronize. + +`conn_props` A <a href="#connectionproperties">ConnectionProperties</a> object to synchronize between the client and server. + +### CreateStatementRequest + +This request is used to create a new Statement in the Avatica server. + +{% highlight protobuf %} +message CreateStatementRequest { + string connection_id = 1; +} +{% endhighlight %} + +`connection_id` The identifier of the connection to use in creating a statement. + +### DatabasePropertyRequest + +This request is used to fetch all <a href="#databaseproperty">database properties</a>. + +{% highlight protobuf %} +message DatabasePropertyRequest { + string connection_id = 1; +} +{% endhighlight %} + +`connection_id` The identifier of the connection to use when fetching the database properties. + +### ExecuteRequest + +This request is used to execute a PreparedStatement, optionally with values to bind to the parameters in the Statement. + +{% highlight protobuf %} +message ExecuteRequest { + StatementHandle statementHandle = 1; + repeated TypedValue parameter_values = 2; + uint64 max_row_count = 3; + bool has_parameter_values = 4; +} +{% endhighlight %} + +`statementHandle` A <a href="#statementhandle">StatementHandle</a> object. + +`parameter_values` The <a href="#typedvalue">TypedValue</a> for each parameter on the prepared statement. + +`max_row_count` The maximum number of rows returned in the response. + +`has_parameter_values` A boolean which denotes if the user set a value for the `parameter_values` field. + +### FetchRequest + +This request is used to fetch a batch of rows from a Statement previously created. + +{% highlight protobuf %} +message FetchRequest { + string connection_id = 1; + uint32 statement_id = 2; + uint64 offset = 3; + uint32 fetch_max_row_count = 4; // Maximum number of rows to be returned in the frame. Negative means no limit. +} +{% endhighlight %} + +`connection_id` The identifier of the connection to use. + +`statement_id` The identifier of the statement created using the above connection. + +`offset` The positional offset into a result set to fetch. + +`fetch_match_row_count` The maximum number of rows to return in the response to this request. + +### OpenConnectionRequest + +This request is used to open a new Connection in the Avatica server. + +{% highlight protobuf %} +message OpenConnectionRequest { + string connection_id = 1; + map<string, string> info = 2; +} +{% endhighlight %} + +`connection_id` The identifier of the connection to open in the server. + +`info` A Map containing properties to include when creating the Connection. + +### PrepareAndExecuteRequest + +This request is used as a short-hand for create a Statement and fetching the first batch of results in a single call without any parameter substitution. + +{% highlight protobuf %} +message PrepareAndExecuteRequest { + string connection_id = 1; + uint32 statement_id = 4; + string sql = 2; + uint64 max_row_count = 3; +} +{% endhighlight %} + +`connection_id` The identifier for the connection to use. + +`statement_id` The identifier for the statement created by the above connection to use. + +`sql` A SQL statement + +`max_row_count` The maximum number of rows returned in the response. + +### PrepareRequest + +This request is used to create create a new Statement with the given query in the Avatica server. + +{% highlight protobuf %} +message PrepareRequest { + string connection_id = 1; + string sql = 2; + uint64 max_row_count = 3; +} +{% endhighlight %} + +`connection_id` The identifier for the connection to use. + +`sql` A SQL statement + +`max_row_count` The maximum number of rows returned in the response. + +### SyncResultsRequest + +This request is used to reset a ResultSet's iterator to a specific offset in the Avatica server. + +{% highlight protobuf %} +message SyncResultsRequest { + string connection_id = 1; + uint32 statement_id = 2; + QueryState state = 3; + uint64 offset = 4; +} +{% endhighlight %} + +`connection_id` The identifier for the connection to use. + +`statement_id` The identifier for the statement to use. + +`state` The <a href="#querystate">QueryState</a> object. + +`offset` The offset into the ResultSet to seek to. + +### RollbackRequest + +This request is used to issue a `rollback` on the Connection in the Avatica server identified by the given ID. + +{% highlight protobuf %} +message RollbackRequest { + string connection_id = 1; +} +{% endhighlight %} + +`connection_id` The identifier for the connection on which to invoke rollback. + +### SchemasRequest + +This request is used to fetch the schemas matching the provided criteria in the database. + +{% highlight protobuf %} +message SchemasRequest { + string catalog = 1; + string schema_pattern = 2; + string connection_id = 3; +} +{% endhighlight %} + +`catalog` The name of the catalog to fetch the schema from. + +`schema_pattern` A Java pattern of schemas to fetch. + +`connection_id` The identifier for the connection to fetch schemas from. + +### TableTypesRequest + +This request is used to fetch the table types available in this database. + +{% highlight protobuf %} +message TableTypesRequest { + string connection_id = 1; +} +{% endhighlight %} + +`connection_id` The identifier of the connection to fetch the table types from. + +### TablesRequest + +This request is used to fetch the tables available in this database filtered by the provided criteria. + +{% highlight protobuf %} +message TablesRequest { + string catalog = 1; + string schema_pattern = 2; + string table_name_pattern = 3; + repeated string type_list = 4; + bool has_type_list = 6; + string connection_id = 7; +} +{% endhighlight %} + +`catalog` The name of a catalog to restrict fetched tables. + +`schema_pattern` A Java Pattern representing schemas to include in fetched tables. + +`table_name_pattern` A Java Pattern representing table names to include in fetched tables. + +`type_list` A list of table types used to restrict fetched tables. + +`has_type_list` A boolean which denotes if the field `type_list` was provided. + +`connection_id` The identifier of the connection to fetch the tables from. + +### TypeInfoRequest + +This request is used to fetch the types available in this database. + +{% highlight protobuf %} +message TypeInfoRequest { + string connection_id = 1; +} +{% endhighlight %} + +`connection_id` The identifier of the connection to fetch the types from. + +## Responses + +The collection of all protobuf objects accepted as requests to Avatica. All response +objects will be wrapped in a `WireMessage` before being returned from Avatica. + +### CloseConnectionResponse + +A response to the <a href="#closeconnectionrequest">CloseConnectionRequest</a>. + +{% highlight protobuf %} +message CloseConnectionResponse { + RpcMetadata metadata = 1; +} +{% endhighlight %} + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### CloseStatementResponse + +A response to the <a href="#closestatementrequest">CloseStatementRequest</a>. + +{% highlight protobuf %} +message CloseStatementResponse { + RpcMetadata metadata = 1; +} +{% endhighlight %} + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### CommitResponse + +A response to the <a href="#commitrequest">CommitRequest</a>. + +{% highlight protobuf %} +message CommitResponse { + +} +{% endhighlight %} + +There are no attributes on this Response. + +### ConnectionSyncResponse + +A response to the <a href="#connectionsyncrequest">ConnectionSyncRequest</a>. Properties included in the +response are those of the Connection in the Avatica server. + +{% highlight protobuf %} +message ConnectionSyncResponse { + ConnectionProperties conn_props = 1; + RpcMetadata metadata = 2; +} +{% endhighlight %} + +`conn_props` The <a href="#connectionproperties">ConnectionProperties</a> that were synchronized. + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### CreateStatementResponse + +A response to the <a href="#createstatementrequest">CreateStatementRequest</a>. The ID of the statement +that was created is included in the response. Clients will use this `statement_id` in subsequent calls. + +{% highlight protobuf %} +message CreateStatementResponse { + string connection_id = 1; + uint32 statement_id = 2; + RpcMetadata metadata = 3; +} +{% endhighlight %} + +`connection_id` The identifier for the connection used to create the statement. + +`statement_id` The identifier for the created statement. + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### DatabasePropertyResponse + +A response to the <a href="#databasepropertyrequest">DatabasePropertyRequest</a>. See <a hred="#databaseproperty">DatabaseProperty</a> +for information on the available property keys. + +{% highlight protobuf %} +message DatabasePropertyResponse { + repeated DatabasePropertyElement props = 1; + RpcMetadata metadata = 2; +} +{% endhighlight %} + +`props` A collection of <a href="#databaseproperty">DatabaseProperty</a>'s. + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### ErrorResponse + +A response when an error was caught executing a request. Any request may return this response. + +{% highlight protobuf %} +message ErrorResponse { + repeated string exceptions = 1; + bool has_exceptions = 7; + string error_message = 2; + Severity severity = 3; + uint32 error_code = 4; + string sql_state = 5; + RpcMetadata metadata = 6; +} +{% endhighlight %} + +`exceptions` A list of stringified Java StackTraces. + +`has_exceptions` A boolean which denotes the presence of `exceptions`. + +`error_message` A human-readable error message. + +`error_code` A numeric code for this error. + +`sql_state` A five character alphanumeric code for this error. + +`severity` An <a href="#avaticaseverity">AvaticaSeverity</a> object which denotes how critical the error is. + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### ExecuteResponse + +A response to the <a href="#executerequest">ExecuteRequest</a> which contains the results for a metadata query. + +{% highlight protobuf %} +message ExecuteResponse { + repeated ResultSetResponse results = 1; + bool missing_statement = 2; + RpcMetadata metadata = 3; +} +{% endhighlight %} + +`results` An array of <a href="#resultsetresponse">ResultSetResponse</a>s. + +`missing_statement` A boolean which denotes if the request failed due to a missing statement. + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### FetchResponse + +A response to the <a href="#fetchrequest">FetchRequest</a> which contains the request for the query. + +{% highlight protobuf %} +message FetchResponse { + Frame frame = 1; + bool missing_statement = 2; + bool missing_results = 3; + RpcMetadata metadata = 4; +} +{% endhighlight %} + +`frame` A <a href="#frame">Frame</a> containing the results of the fetch. + +`missing_statement` A boolean which denotes if the request failed due to a missing Statement. + +`missing_results` A boolean which denotes if the request failed due to a missing ResultSet. + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### OpenConnectionResponse + +A response to the <a href="#openconnectionrequest">OpenConnectionRequest</a>. The ID for the connection that +the client should use in subsequent calls was provided by the client in the request. + +{% highlight protobuf %} +message OpenConnectionResponse { + RpcMetadata metadata = 1; +} + +{% endhighlight %} + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### PrepareResponse + +A response to the <a href="#preparerequest">PrepareRequest</a>. This response includes a <a href="#statementhandle">StatementHandle</a> +which clients must use to fetch the results from the Statement. + +{% highlight protobuf %} +message PrepareResponse { + StatementHandle statement = 1; + RpcMetadata metadata = 2; +} +{% endhighlight %} + +`statement` A <a href="#statementhandle">StatementHandle</a> object. + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### ResultSetResponse + +A response which contains the results and type details from a query. + +{% highlight protobuf %} +message ResultSetResponse { + string connection_id = 1; + uint32 statement_id = 2; + bool own_statement = 3; + Signature signature = 4; + Frame first_frame = 5; + uint64 update_count = 6; + RpcMetadata metadata = 7; +} +{% endhighlight %} + +`connection_id` The identifier for the connection used to generate this response. + +`statement_id` The identifier for the statement used to generate this response. + +`own_statement` 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> + +`first_frame` A optional nested object <a href="#frame">Frame</a> + +`update_count` 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. + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### RollbackResponse + +A response to the <a href="#rollbackrequest">RollBackRequest</a>. + +{% highlight protobuf %} +message RollbackResponse { + +} +{% endhighlight %} + +There are no attributes on this Response. + +### SyncResultsResponse + +A response to the <a href="#syncresultsrequest">SyncResultsRequest</a>. When `moreResults` is true, a <a href="#fetchrequest">FetchRequest</a> +should be issued to get the next batch of records. When `missingStatement` is true, the statement must be re-created using <a href="#preparerequest">PrepareRequest</a> +or the appropriate Request for a DDL request (e.g. <a href="#catalogsrequest">CatalogsRequest</a> or <a href="#schemasrequest">SchemasRequest</a>). + +{% highlight protobuf %} +message SyncResultsResponse { + bool missing_statement = 1; + bool more_results = 2; + RpcMetadata metadata = 3; +} +{% endhighlight %} + +`more_results` A boolean which denotes if results exist for the ResultSet being "synced" per the request. + +`missing_statement` A boolean which denotes if the statement for the ResultSet still exists. + +`metadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +## Miscellaneous + +### AvaticaParameter + +This object describes the "simple", or scalar, JDBC type representation of a column in a result. This does not include +complex types such as arrays. + +{% highlight protobuf %} +message AvaticaParameter { + bool signed = 1; + uint32 precision = 2; + uint32 scale = 3; + uint32 parameter_type = 4; + string class_name = 5; + string class_name = 6; + string name = 7; +} +{% endhighlight %} + +`signed` A boolean denoting whether the column is a signed numeric. + +`precision` The maximum numeric precision supported by this column. + +`scale` The maximum numeric scale supported by this column. + +`parameter_type` An integer corresponding to the JDBC Types class denoting the column's type. + +`type_name` The JDBC type name for this column. + +`class_name` The Java class backing the JDBC type for this column. + +`name` The name of the column. + +### AvaticaSeverity + +This enumeration describes the various levels of concern for an error in the Avatica server. + +{% highlight protobuf %} +enum Severity { + UNKNOWN_SEVERITY = 0; + FATAL_SEVERITY = 1; + ERROR_SEVERITY = 2; + WARNING_SEVERITY = 3; +} +{% endhighlight %} + +### AvaticaType + +This object describes a simple or complex type for a column. Complex types will contain +additional information in the `component` or `columns` attribute which describe the nested +types of the complex parent type. + +{% highlight protobuf %} +message AvaticaType { + uint32 id = 1; + string name = 2; + Rep rep = 3; + repeated ColumnMetaData columns = 4; + AvaticaType component = 5; +} +{% endhighlight %} + +`type` One of: `scalar`, `array`, `struct`. + +`id` A numeric value corresponding to the type of the object per the JDBC Types class. + +`name` The readable name of the JDBC type. + +`rep` A nested <a href="#rep">Rep</a> object used by Avatica to hold additional type information. + +`columns` For `STRUCT` types, a list of the columns contained in that `STRUCT`. + +`component` For `ARRAY` types, the type of the elements contained in that `ARRAY`. + +### ColumnMetaData + +This object represents the JDBC ResultSetMetaData for a column. + +{% highlight protobuf %} +message ColumnMetaData { + uint32 ordinal = 1; + bool auto_increment = 2; + bool case_sensitive = 3; + bool searchable = 4; + bool currency = 5; + uint32 nullable = 6; + bool signed = 7; + uint32 display_size = 8; + string label = 9; + string column_name = 10; + string schema_name = 11; + uint32 precision = 12; + uint32 scale = 13; + string table_name = 14; + string catalog_name = 15; + bool read_only = 16; + bool writable = 17; + bool definitely_writable = 18; + string column_class_name = 19; + AvaticaType type = 20; +} +{% endhighlight %} + +`ordinal` A positional offset number. + +`auto_increment` A boolean denoting whether the column is automatically incremented. + +`case_sensitive` A boolean denoting whether the column is case sensitive. + +`searchable` A boolean denoting whether this column supports all WHERE search clauses. + +`currency` A boolean denoting whether this column represents currency. + +`nullable` A number denoting whether this column supports null values. + +* 0 = No null values are allowed +* 1 = Null values are allowed +* 2 = It is unknown if null values are allowed + +`signed` A boolean denoting whether the column is a signed numeric. + +`display_size` The character width of the column. + +`label` A description for this column. + +`column_name` The name of the column. + +`schema_name` The schema to which this column belongs. + +`precision` The maximum numeric precision supported by this column. + +`scale` The maximum numeric scale supported by this column. + +`table_name` The name of the table to which this column belongs. + +`catalog_name` The name of the catalog to which this column belongs. + +`type` A nested <a href="#avaticatype">AvaticaType</a> representing the type of the column. + +`read_only` A boolean denoting whether the column is read-only. + +`writable` A boolean denoting whether the column is possible to be updated. + +`definitely_writable` A boolean denoting whether the column definitely can be updated. + +`column_class_name` The name of the Java class backing the column's type. + +### ConnectionProperties + +This object represents the properties for a given JDBC Connection. + +{% highlight protobuf %} +message ConnectionProperties { + bool is_dirty = 1; + bool auto_commit = 2; + bool has_auto_commit = 7; + bool read_only = 3; + bool has_read_only = 8; + uint32 transaction_isolation = 4; + string catalog = 5; + string schema = 6; +} +{% endhighlight %} + +`is_dirty` A boolean denoting if the properties have been altered. + +`auto_commit` A boolean denoting if autoCommit is enabled for transactions. + +`has_auto_commit` A boolean denoting if `auto_commit` was set. + +`read_only` A boolean denoting if a JDBC connection is read-only. + +`has_read_only` A boolean denoting if `read_only` was set. + +`transaction_isolation` An integer which denotes the level of transactions isolation per the JDBC +specification. This value is analogous to the values defined in `java.sql.Connection`. + +* 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. + +`catalog` The name of a catalog to use when fetching connection properties. + +`schema` The name of the schema to use when fetching connection properties. + +### CursorFactory + +This object represents the information required to cast untyped objects into the necessary type for some results. + +{% highlight protobuf %} +message CursorFactory { + enum Style { + OBJECT = 0; + RECORD = 1; + RECORD_PROJECTION = 2; + ARRAY = 3; + LIST = 4; + MAP = 5; + } + + Style style = 1; + string class_name = 2; + repeated string field_names = 3; +} +{% endhighlight %} + +`style` A string denoting the <a href="#style">Style</a> of the contained objects. + +`class_name` The name of the for `RECORD` or `RECORD_PROJECTION`. + +### DatabaseProperty + +This object represents the exposed database properties for a Connection through the Avatica server. + +{% highlight protobuf %} +message DatabaseProperty { + string name = 1; + repeated string functions = 2; +} +{% endhighlight %} + +`name` The name of the database property. + +`functions` A collection of values for the property. + +### Frame + +This object represents a batch of results, tracking the offset into the results and whether more results still exist +to be fetched in the Avatica server. + +{% highlight protobuf %} +message Frame { + uint64 offset = 1; + bool done = 2; + repeated Row rows = 3; +} +{% endhighlight %} + +`offset` The starting position of these `rows` in the encompassing result set. + +`done` A boolean denoting whether more results exist for this result set. + +`rows` A collection of <a href="#row">Row</a>s. + +### Row + +This object represents a row in a relational database table. + +{% highlight protobuf %} +message Row { + repeated ColumnValue value = 1; +} +{% endhighlight %} + +`value` A collection of <a href="#columnvalue">ColumnValue</a>s, the columns in the row. + +### ColumnValue + +{% highlight protobuf %} +message ColumnValue { + repeated TypedValue value = 1; // Deprecated! + repeated ColumnValue array_value = 2; + boolean has_array_value = 3; + TypedValue scalar_value = 4; +} +{% endhighlight %} + +`value` The pre Calcite-1.6 means of serializing <a href="#typedvalue">TypedValue</a>s. Not used anymore. + +`array_value` The value of this column if it is an array (not a scalar). + +`has_array_value` Should be set to true if `array_value` is set. + +`scalar_value` The value of this column if it is a scalar (not an array). + +### QueryState + +This object represents the way a ResultSet was created in the Avatica server. A ResultSet could be created by a user-provided +SQL or by a DatabaseMetaData operation with arguments on that operation. + +{% highlight protobuf %} +message QueryState { + StateType type = 1; + string sql = 2; + MetaDataOperation op = 3; + repeated MetaDataOperationArgument args = 4; + bool has_args = 5; + bool has_sql = 6; + bool has_op = 7; +} +{% endhighlight %} + +`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`. + +`op` The DML operation which created the ResultSet for this query. Required if the `type` is `METADATA`. + +`args` The arguments to the invoked DML operation. Required if the `type` is `METADATA`. + +`has_args` A boolean which denotes if the field `args` is provided. + +`has_sql` A boolean which denotes if the field `sql` is provided. + +`has_op` A boolean which denotes if the field `op` is provided. + +### Rep + +This enumeration represents the concrete Java type for some value. + +{% highlight protobuf %} +enum Rep { + PRIMITIVE_BOOLEAN = 0; + PRIMITIVE_BYTE = 1; + PRIMITIVE_CHAR = 2; + PRIMITIVE_SHORT = 3; + PRIMITIVE_INT = 4; + PRIMITIVE_LONG = 5; + PRIMITIVE_FLOAT = 6; + PRIMITIVE_DOUBLE = 7; + BOOLEAN = 8; + BYTE = 9; + CHARACTER = 10; + SHORT = 11; + INTEGER = 12; + LONG = 13; + FLOAT = 14; + DOUBLE = 15; + BIG_INTEGER = 25; + BIG_DECIMAL = 26; + JAVA_SQL_TIME = 16; + JAVA_SQL_TIMESTAMP = 17; + JAVA_SQL_DATE = 18; + JAVA_UTIL_DATE = 19; + BYTE_STRING = 20; + STRING = 21; + NUMBER = 22; + OBJECT = 23; + NULL = 24; + ARRAY = 27; + STRUCT = 28; + MULTISET = 29; +} +{% endhighlight %} + +### RpcMetadata + +This object contains assorted per-call/contextual metadata returned by the Avatica server. + +{% highlight protobuf %} +message RpcMetadata { + string server_address = 1; +} +{% endhighlight %} + +`serverAddress` The `host:port` of the server which created this object. + +### Signature + +This object represents the result of preparing a Statement in the Avatica server. + +{% highlight protobuf %} +message Signature { + repeated ColumnMetaData columns = 1; + string sql = 2; + repeated AvaticaParameter parameters = 3; + CursorFactory cursor_factory = 4; + StatementType statementType = 5; +} +{% 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. + +`cursor_factory` An <a href="#cursorfactory">CursorFactory</a> object representing the Java representation of the frame. + +`statementType` The type of the statement. + +### StateType + +This enumeration denotes whether user-provided SQL or a DatabaseMetaData operation was used to create some ResultSet. + +{% highlight protobuf %} +enum StateType { + SQL = 0; + METADATA = 1; +} +{% endhighlight %} + +### StatementHandle + +This object encapsulates all of the information of a Statement created in the Avatica server. + +{% highlight protobuf %} +message StatementHandle { + string connection_id = 1; + uint32 id = 2; + Signature signature = 3; +} +{% endhighlight %} + +`connection_id` 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. + +### StatementType + +This message represents what kind the Statement is. + +{% highlight protobuf %} +enum StatementType { + SELECT = 0; + INSERT = 1; + UPDATE = 2; + DELETE = 3; + UPSERT = 4; + MERGE = 5; + OTHER_DML = 6; + CREATE = 7; + DROP = 8; + ALTER = 9; + OTHER_DDL = 10; + CALL = 11; +} +{% endhighlight %} + +### Style + +This enumeration represents the generic "class" of type for a value. Defined within <a href="#cursorfactory">CursorFactory</a>. + +{% highlight protobuf %} +enum Style { + OBJECT = 0; + RECORD = 1; + RECORD_PROJECTION = 2; + ARRAY = 3; + LIST = 4; + MAP = 5; +} +{% endhighlight %} + +### TypedValue + +This object encapsulates the type and value for a column in a row. + +{% highlight protobuf %} +message TypedValue { + Rep type = 1; + bool bool_value = 2; + string string_value = 3; + sint64 number_value = 4; + bytes bytes_values = 5; + double double_value = 6; + bool null = 7; +} +{% endhighlight %} + +`type` A name referring to which attribute is populated with the column's value. + +`bool_value` A boolean value. + +`string_value` A character/string value. + +`number_value` A numeric value (non-`double`). + +`bytes_value` A byte-array value. + +`double_value` A `double` value. + +`null` A boolean which denotes if the value was null. + +### WireMessage + +This message wraps all `Request`s and `Response`s. + +{% highlight protobuf %} +message WireMessage { + string name = 1; + bytes wrapped_message = 2; +} +{% endhighlight %} + +`name` The Java class name of the wrapped message. + +`wrapped_message` A serialized representation of the wrapped message of the same type specified by `name`. http://git-wip-us.apache.org/repos/asf/calcite/blob/5cee486f/avatica/site/_docs/avatica_roadmap.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/avatica_roadmap.md b/avatica/site/_docs/avatica_roadmap.md new file mode 100644 index 0000000..4caebd4 --- /dev/null +++ b/avatica/site/_docs/avatica_roadmap.md @@ -0,0 +1,51 @@ +--- +layout: docs +title: Avatica Roadmap +sidebar_title: Roadmap +permalink: /docs/avatica_roadmap.html +--- + +<!-- +{% comment %} +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to you under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +{% endcomment %} +--> + +## Status + +### Implemented + +* Create connection, create statement, metadata, prepare, bind, execute, fetch +* RPC using JSON over HTTP +* Local implementation +* Implementation over an existing JDBC driver +* Composite RPCs (combining several requests into one round trip) + * Execute-Fetch + * Metadata-Fetch (metadata calls such as getTables return all rows) + +### Not implemented + +* ODBC +* RPCs + * CloseStatement + * CloseConnection +* Composite RPCs + * CreateStatement-Prepare + * CloseStatement-CloseConnection + * Prepare-Execute-Fetch (Statement.executeQuery should fetch first N rows) +* Remove statements from statement table +* DML (INSERT, UPDATE, DELETE) +* Statement.execute applied to SELECT statement
