calcite-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From els...@apache.org
Subject [2/2] calcite git commit: [CALCITE-1033] Introduce Avatica protobuf documentation
Date Mon, 21 Dec 2015 20:04:01 GMT
[CALCITE-1033] Introduce Avatica protobuf documentation

Similar enough to JSON docs to be dangerous. Provides
a good place to encapsulate other information on how
to use the generated protobuf code.


Project: http://git-wip-us.apache.org/repos/asf/calcite/repo
Commit: http://git-wip-us.apache.org/repos/asf/calcite/commit/60b2825c
Tree: http://git-wip-us.apache.org/repos/asf/calcite/tree/60b2825c
Diff: http://git-wip-us.apache.org/repos/asf/calcite/diff/60b2825c

Branch: refs/heads/master
Commit: 60b2825c8a49c62ea3caf2212521809ebc545bd8
Parents: e7bbcec
Author: Josh Elser <elserj@apache.org>
Authored: Mon Dec 21 14:57:55 2015 -0500
Committer: Josh Elser <elserj@apache.org>
Committed: Mon Dec 21 15:03:46 2015 -0500

----------------------------------------------------------------------
 site/_data/docs.yml                      |    1 +
 site/_docs/avatica_protobuf_reference.md | 1170 +++++++++++++++++++++++++
 2 files changed, 1171 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/calcite/blob/60b2825c/site/_data/docs.yml
----------------------------------------------------------------------
diff --git a/site/_data/docs.yml b/site/_data/docs.yml
index 88c2c88..a996097 100644
--- a/site/_data/docs.yml
+++ b/site/_data/docs.yml
@@ -32,6 +32,7 @@
   - avatica_overview
   - avatica_roadmap
   - avatica_json_reference
+  - avatica_protobuf_reference
 
 - title: Reference
   docs:

http://git-wip-us.apache.org/repos/asf/calcite/blob/60b2825c/site/_docs/avatica_protobuf_reference.md
----------------------------------------------------------------------
diff --git a/site/_docs/avatica_protobuf_reference.md b/site/_docs/avatica_protobuf_reference.md
new file mode 100644
index 0000000..c6b662d
--- /dev/null
+++ b/site/_docs/avatica_protobuf_reference.md
@@ -0,0 +1,1170 @@
+---
+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: "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" }
+  - { 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;
+}
+{% endhighlight %}
+
+`value` A collection of <a href="#typedvalue">TypedValue</a>s.
+
+### 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`.


Mime
View raw message