You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@calcite.apache.org by el...@apache.org on 2015/12/21 21:04:00 UTC
[1/2] calcite git commit: [CALCITE-1029] Add "purpose" descriptions
to Avatica JSON docs
Repository: calcite
Updated Branches:
refs/heads/master eaa35a41b -> 60b2825c8
[CALCITE-1029] Add "purpose" descriptions to Avatica JSON docs
Also includes some more updates to inaccurate docs.
Project: http://git-wip-us.apache.org/repos/asf/calcite/repo
Commit: http://git-wip-us.apache.org/repos/asf/calcite/commit/e7bbcec8
Tree: http://git-wip-us.apache.org/repos/asf/calcite/tree/e7bbcec8
Diff: http://git-wip-us.apache.org/repos/asf/calcite/diff/e7bbcec8
Branch: refs/heads/master
Commit: e7bbcec8f451dbc2b02434eba6d17138e1d44e6e
Parents: eaa35a4
Author: Josh Elser <el...@apache.org>
Authored: Mon Dec 21 14:49:57 2015 -0500
Committer: Josh Elser <el...@apache.org>
Committed: Mon Dec 21 15:03:45 2015 -0500
----------------------------------------------------------------------
site/_docs/avatica_json_reference.md | 186 +++++++++++++++++++++++++++---
1 file changed, 170 insertions(+), 16 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/calcite/blob/e7bbcec8/site/_docs/avatica_json_reference.md
----------------------------------------------------------------------
diff --git a/site/_docs/avatica_json_reference.md b/site/_docs/avatica_json_reference.md
index 857e948..d49be7c 100644
--- a/site/_docs/avatica_json_reference.md
+++ b/site/_docs/avatica_json_reference.md
@@ -38,6 +38,7 @@ miscellaneous:
- { name: "Signature" }
- { name: "StateType" }
- { name: "StatementHandle" }
+ - { name: "StatementType" }
- { name: "Style" }
- { name: "TypedValue" }
responses:
@@ -83,9 +84,8 @@ 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, so non-Java clients presently must re-implement language
-specific objects on their own. Efforts to use [Protocol Buffers](https://developers.google.com/protocol-buffers/)
-instead are underway that will provide native objects in many languages.
+in Java. For support outside of Java, see the Protocol Buffer
+[bindings]({{ site.baseurl }}/docs/avatica_protobuf_reference.html)
## Index
@@ -112,16 +112,21 @@ 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 %}
-There are no extra attributes on this Request.
+`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",
@@ -133,6 +138,8 @@ There are no extra attributes on this Request.
### CloseStatementRequest
+This request is used to close the Statement object in the Avatica server identified by the given IDs.
+
{% highlight json %}
{
"request": "closeStatement",
@@ -147,9 +154,12 @@ There are no extra attributes on this Request.
### 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.*",
@@ -157,6 +167,8 @@ There are no extra attributes on this Request.
}
{% 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.
@@ -167,6 +179,8 @@ There are no extra attributes on this Request.
### 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",
@@ -174,10 +188,12 @@ There are no extra attributes on this Request.
}
{% endhighlight %}
-`connectionId`: (required string) The identifier of the connection on which to invoke commit.
+`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",
@@ -192,6 +208,8 @@ There are no extra attributes on this Request.
### CreateStatementRequest
+This request is used to create a new Statement in the Avatica server.
+
{% highlight json %}
{
"request": "createStatement",
@@ -203,16 +221,20 @@ There are no extra attributes on this Request.
### DatabasePropertyRequest
+This request is used to fetch all <a href="#databaseproperty">database properties</a>.
+
{% highlight json %}
{
"request": "databaseProperties",
}
{% endhighlight %}
-There are no extra attributes on this Request.
+`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",
@@ -230,14 +252,15 @@ There are no extra attributes on this Request.
### 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,
- "parameterValues": [TypedValue, TypedValue, ...]
+ "fetchMaxRowCount": 100
}
{% endhighlight %}
@@ -249,10 +272,10 @@ There are no extra attributes on this Request.
`fetchMatchRowCount` (required integer) The maximum number of rows to return in the response to this request.
-`parameterValues` (optional array of nested objects) The <a href="#typedvalue">TypedValue</a> for each parameter on the prepared statement.
-
### OpenConnectionRequest
+This request is used to open a new Connection in the Avatica server.
+
{% highlight json %}
{
"request": "openConnection",
@@ -267,6 +290,8 @@ There are no extra attributes on this Request.
### 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",
@@ -287,6 +312,8 @@ There are no extra attributes on this Request.
### PrepareRequest
+This request is used to create create a new Statement with the given query in the Avatica server.
+
{% highlight json %}
{
"request": "prepare",
@@ -304,6 +331,8 @@ There are no extra attributes on this Request.
### SyncResultsRequest
+This request is used to reset a ResultSet's iterator to a specific offset in the Avatica server.
+
{% highlight json %}
{
"request": "syncResults",
@@ -324,6 +353,8 @@ There are no extra attributes on this Request.
### 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",
@@ -335,33 +366,44 @@ There are no extra attributes on this Request.
### 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 %}
-There are no extra attributes on this Request.
+`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.*",
@@ -371,6 +413,8 @@ There are no extra attributes on this Request.
`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.
@@ -379,13 +423,16 @@ There are no extra attributes on this Request.
### TypeInfoRequest
+This request is used to fetch the types available in this database.
+
{% highlight json %}
{
"request": "getTypeInfo",
+ "connectionId": "000000-0000-0000-00000000"
}
{% endhighlight %}
-There are no extra attributes on this Request.
+`connectionId` The identifier of the connection to fetch the types from.
## Responses
@@ -394,6 +441,8 @@ which uniquely identifies the concrete Response from all other Responses.
### CloseConnectionResponse
+A response to the <a href="#closeconnectionrequest">CloseConnectionRequest</a>.
+
{% highlight json %}
{
"response": "closeConnection",
@@ -405,6 +454,8 @@ which uniquely identifies the concrete Response from all other Responses.
### CloseStatementResponse
+A response to the <a href="#closestatementrequest">CloseStatementRequest</a>.
+
{% highlight json %}
{
"response": "closeStatement",
@@ -416,6 +467,8 @@ which uniquely identifies the concrete Response from all other Responses.
### CommitResponse
+A response to the <a href="#commitrequest">CommitRequest</a>.
+
{% highlight json %}
{
"response": "commit"
@@ -426,6 +479,9 @@ 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",
@@ -440,6 +496,9 @@ There are no extra attributes on this Response.
### 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",
@@ -457,6 +516,9 @@ There are no extra attributes on this Response.
### 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",
@@ -472,6 +534,8 @@ primitive type or an array of primitive types.
### ErrorResponse
+A response when an error was caught executing a request. Any request may return this response.
+
{% highlight json %}
{
"response": "error",
@@ -498,34 +562,50 @@ primitive type or an array of primitive types.
### 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",
@@ -537,6 +617,9 @@ primitive type or an array of primitive types.
### 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",
@@ -551,6 +634,8 @@ primitive type or an array of primitive types.
### ResultSetResponse
+A response which contains the results and type details from a query.
+
{% highlight json %}
{
"response": "resultSet",
@@ -582,6 +667,8 @@ that only contains this count and no additional data.
### RollbackResponse
+A response to the <a href="#rollbackrequest">RollBackRequest</a>.
+
{% highlight json %}
{
"response": "rollback"
@@ -592,6 +679,10 @@ 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",
@@ -611,6 +702,9 @@ There are no extra attributes on this Response.
### 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,
@@ -639,6 +733,8 @@ There are no extra attributes on this Response.
### AvaticaSeverity
+This enumeration describes the various levels of concern for an error in the Avatica server.
+
One of:
* `UNKNOWN`
@@ -648,6 +744,10 @@ One of:
### 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",
@@ -673,6 +773,8 @@ One of:
### ColumnMetaData
+This object represents the JDBC ResultSetMetaData for a column.
+
{% highlight json %}
{
"ordinal": 0,
@@ -744,6 +846,8 @@ One of:
### ConnectionProperties
+This object represents the properties for a given JDBC Connection.
+
{% highlight json %}
{
"connProps": "connPropsImpl",
@@ -760,7 +864,7 @@ One of:
`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 define in `java.sql.Connection`.
+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.
@@ -768,8 +872,14 @@ specification. This value is analogous to the values define in `java.sql.Connect
* 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,
@@ -782,6 +892,8 @@ specification. This value is analogous to the values define in `java.sql.Connect
### DatabaseProperty
+This object represents the exposed database properties for a Connection through the Avatica server.
+
One of:
* `GET_STRING_FUNCTIONS`
@@ -793,6 +905,9 @@ One of:
### 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,
@@ -809,6 +924,9 @@ One of:
### 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,
@@ -828,6 +946,8 @@ One of:
### Rep
+This enumeration represents the concrete Java type for some value.
+
One of:
* `PRIMITIVE_BOOLEAN`
@@ -857,22 +977,27 @@ One of:
### RpcMetadata
+This object contains assorted per-call/contextual metadata returned by the Avatica server.
+
{% highlight json %}
{
- "serverAddress": "http://localhost:8765"
+ "serverAddress": "localhost:8765"
}
{% endhighlight %}
-`serverAddress` The URL of the server which created this object.
+`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
+ "cursorFactory": CursorFactory,
+ "statementType": StatementType
}
{% endhighlight %}
@@ -884,8 +1009,12 @@ One of:
`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`
@@ -893,6 +1022,8 @@ One of:
### StatementHandle
+This object encapsulates all of the information of a Statement created in the Avatica server.
+
{% highlight json %}
{
"connectionId": "000000-0000-0000-00000000",
@@ -907,8 +1038,29 @@ One of:
`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`
@@ -920,6 +1072,8 @@ One of:
### TypedValue
+This object encapsulates the type and value for a column in a row.
+
{% highlight json %}
{
"type": "type_name",
[2/2] calcite git commit: [CALCITE-1033] Introduce Avatica protobuf
documentation
Posted by el...@apache.org.
[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 <el...@apache.org>
Authored: Mon Dec 21 14:57:55 2015 -0500
Committer: Josh Elser <el...@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`.