Repository: calcite Updated Branches: refs/heads/master 9f23e1a0d -> 55ffb5edd
[CALCITE-1677] Replace duplicate avatica docs with a redirect Closes apache/calcite#401 Project: http://git-wip-us.apache.org/repos/asf/calcite/repo Commit: http://git-wip-us.apache.org/repos/asf/calcite/commit/55ffb5ed Tree: http://git-wip-us.apache.org/repos/asf/calcite/tree/55ffb5ed Diff: http://git-wip-us.apache.org/repos/asf/calcite/diff/55ffb5ed Branch: refs/heads/master Commit: 55ffb5edd2761147396356154491f29ffd194f47 Parents: 9f23e1a Author: Josh Elser <[email protected]> Authored: Mon Mar 13 15:34:13 2017 -0400 Committer: Josh Elser <[email protected]> Committed: Tue Mar 14 23:10:11 2017 -0400 ---------------------------------------------------------------------- site/Gemfile | 1 + site/_config.yml | 3 + site/_docs/avatica_json_reference.md | 1080 +---------------------- site/_docs/avatica_overview.md | 125 +-- site/_docs/avatica_protobuf_reference.md | 1176 +------------------------ site/_docs/avatica_roadmap.md | 46 +- 6 files changed, 8 insertions(+), 2423 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/calcite/blob/55ffb5ed/site/Gemfile ---------------------------------------------------------------------- diff --git a/site/Gemfile b/site/Gemfile index 5425d95..d608db6 100644 --- a/site/Gemfile +++ b/site/Gemfile @@ -17,4 +17,5 @@ source 'https://rubygems.org' gem 'github-pages', '67' gem 'rouge' gem 'jekyll-oembed', :require => 'jekyll_oembed' +gem 'jekyll-redirect-from' # End Gemfile http://git-wip-us.apache.org/repos/asf/calcite/blob/55ffb5ed/site/_config.yml ---------------------------------------------------------------------- diff --git a/site/_config.yml b/site/_config.yml index f3efdf1..b0a0cdb 100644 --- a/site/_config.yml +++ b/site/_config.yml @@ -47,4 +47,7 @@ jdkApiRoot: https://docs.oracle.com/javase/8/docs/api/ # The base path where the website is deployed baseurl: +gems: + - jekyll-redirect-from + # End _config.yml http://git-wip-us.apache.org/repos/asf/calcite/blob/55ffb5ed/site/_docs/avatica_json_reference.md ---------------------------------------------------------------------- diff --git a/site/_docs/avatica_json_reference.md b/site/_docs/avatica_json_reference.md index d49be7c..ead7c62 100644 --- a/site/_docs/avatica_json_reference.md +++ b/site/_docs/avatica_json_reference.md @@ -2,1085 +2,7 @@ layout: docs title: Avatica JSON Reference sidebar_title: JSON Reference +redirect_to: /avatica/docs/json_reference.html 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/55ffb5ed/site/_docs/avatica_overview.md ---------------------------------------------------------------------- diff --git a/site/_docs/avatica_overview.md b/site/_docs/avatica_overview.md index 6c77eb9..a8f4ea3 100644 --- a/site/_docs/avatica_overview.md +++ b/site/_docs/avatica_overview.md @@ -3,128 +3,5 @@ layout: docs title: Avatica Overview sidebar_title: Overview permalink: /docs/avatica_overview.html +redirect_to: /avatica/docs/index.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/55ffb5ed/site/_docs/avatica_protobuf_reference.md ---------------------------------------------------------------------- diff --git a/site/_docs/avatica_protobuf_reference.md b/site/_docs/avatica_protobuf_reference.md index 02a8ab1..9335558 100644 --- a/site/_docs/avatica_protobuf_reference.md +++ b/site/_docs/avatica_protobuf_reference.md @@ -2,1180 +2,6 @@ layout: docs title: Avatica Protocol Buffers Reference sidebar_title: Protobuf Reference +redirect_to: /avatica/docs/protobuf_reference.html 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/55ffb5ed/site/_docs/avatica_roadmap.md ---------------------------------------------------------------------- diff --git a/site/_docs/avatica_roadmap.md b/site/_docs/avatica_roadmap.md index 4caebd4..d98ff02 100644 --- a/site/_docs/avatica_roadmap.md +++ b/site/_docs/avatica_roadmap.md @@ -3,49 +3,5 @@ layout: docs title: Avatica Roadmap sidebar_title: Roadmap permalink: /docs/avatica_roadmap.html +redirect_to: /avatica/docs/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
