http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_docs/protobuf_reference.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/protobuf_reference.md b/avatica/site/_docs/protobuf_reference.md new file mode 100644 index 0000000..4840ceb --- /dev/null +++ b/avatica/site/_docs/protobuf_reference.md @@ -0,0 +1,1181 @@ +--- +layout: docs +title: Protocol Buffers Reference +sidebar_title: Protobuf Reference +permalink: /docs/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/65f2afa7/avatica/site/_docs/reference.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/reference.md b/avatica/site/_docs/reference.md deleted file mode 100644 index 7bc9bc3..0000000 --- a/avatica/site/_docs/reference.md +++ /dev/null @@ -1,1248 +0,0 @@ ---- -layout: docs -title: SQL language -permalink: /docs/reference.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 %} ---> - -The page describes the SQL dialect recognized by Calcite's default SQL parser. - -## Grammar - -SQL grammar in [BNF](http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form)-like -form. - -{% highlight sql %} -statement: - setStatement - | resetStatement - | explain - | insert - | update - | merge - | delete - | query - -setStatement: - [ ALTER ( SYSTEM | SESSION ) ] SET identifier '=' expression - -resetStatement: - [ ALTER ( SYSTEM | SESSION ) ] RESET identifier - | [ ALTER ( SYSTEM | SESSION ) ] RESET ALL - -explain: - EXPLAIN PLAN - [ WITH TYPE | WITH IMPLEMENTATION | WITHOUT IMPLEMENTATION ] - [ EXCLUDING ATTRIBUTES | INCLUDING [ ALL ] ATTRIBUTES ] - FOR ( insert | update | merge | delete | query ) - -insert: - ( INSERT | UPSERT ) INTO tablePrimary - [ '(' column [, column ]* ')' ] - query - -update: - UPDATE tablePrimary - SET assign [, assign ]* - [ WHERE booleanExpression ] - -assign: - identifier '=' expression - -merge: - MERGE INTO tablePrimary [ [ AS ] alias ] - USING tablePrimary - ON booleanExpression - [ WHEN MATCHED THEN UPDATE SET assign [, assign ]* ] - [ WHEN NOT MATCHED THEN INSERT VALUES '(' value [ , value ]* ')' ] - -delete: - DELETE FROM tablePrimary [ [ AS ] alias ] - [ WHERE booleanExpression ] - -query: - [ WITH withItem [ , withItem ]* query ] - | { - select - | query UNION [ ALL ] query - | query EXCEPT query - | query INTERSECT query - } - [ ORDER BY orderItem [, orderItem ]* ] - [ LIMIT { count | ALL } ] - [ OFFSET start { ROW | ROWS } ] - [ FETCH { FIRST | NEXT } [ count ] { ROW | ROWS } ] - -withItem: - name - [ '(' column [, column ]* ')' ] - AS '(' query ')' - -orderItem: - expression [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ] - -select: - SELECT [ STREAM ] [ ALL | DISTINCT ] - { * | projectItem [, projectItem ]* } - FROM tableExpression - [ WHERE booleanExpression ] - [ GROUP BY { groupItem [, groupItem ]* } ] - [ HAVING booleanExpression ] - [ WINDOW windowName AS windowSpec [, windowName AS windowSpec ]* ] - -projectItem: - expression [ [ AS ] columnAlias ] - | tableAlias . * - -tableExpression: - tableReference [, tableReference ]* - | tableExpression [ NATURAL ] [ LEFT | RIGHT | FULL ] JOIN tableExpression [ joinCondition ] - -joinCondition: - ON booleanExpression - | USING '(' column [, column ]* ')' - -tableReference: - [ LATERAL ] - tablePrimary - [ [ AS ] alias [ '(' columnAlias [, columnAlias ]* ')' ] ] - -tablePrimary: - [ TABLE ] [ [ catalogName . ] schemaName . ] tableName - | '(' query ')' - | values - | UNNEST '(' expression ')' [ WITH ORDINALITY ] - | TABLE '(' [ SPECIFIC ] functionName '(' expression [, expression ]* ')' ')' - -values: - VALUES expression [, expression ]* - -groupItem: - expression - | '(' ')' - | '(' expression [, expression ]* ')' - | CUBE '(' expression [, expression ]* ')' - | ROLLUP '(' expression [, expression ]* ')' - | GROUPING SETS '(' groupItem [, groupItem ]* ')' - -windowRef: - windowName - | windowSpec - -windowSpec: - [ windowName ] - '(' - [ ORDER BY orderItem [, orderItem ]* ] - [ PARTITION BY expression [, expression ]* ] - [ - RANGE numericOrIntervalExpression { PRECEDING | FOLLOWING } - | ROWS numericExpression { PRECEDING | FOLLOWING } - ] - ')' -{% endhighlight %} - -In *merge*, at least one of the WHEN MATCHED and WHEN NOT MATCHED clauses must -be present. - -In *orderItem*, if *expression* is a positive integer *n*, it denotes -the <em>n</em>th item in the SELECT clause. - -An aggregate query is a query that contains a GROUP BY or a HAVING -clause, or aggregate functions in the SELECT clause. In the SELECT, -HAVING and ORDER BY clauses of an aggregate query, all expressions -must be constant within the current group (that is, grouping constants -as defined by the GROUP BY clause, or constants), or aggregate -functions, or a combination of constants and aggregate -functions. Aggregate and grouping functions may only appear in an -aggregate query, and only in a SELECT, HAVING or ORDER BY clause. - -A scalar sub-query is a sub-query used as an expression. -If the sub-query returns no rows, the value is NULL; if it -returns more than one row, it is an error. - -IN, EXISTS and scalar sub-queries can occur -in any place where an expression can occur (such as the SELECT clause, -WHERE clause, ON clause of a JOIN, or as an argument to an aggregate -function). - -An IN, EXISTS or scalar sub-query may be correlated; that is, it -may refer to tables in the FROM clause of an enclosing query. - -## Keywords - -The following is a list of SQL keywords. -Reserved keywords are **bold**. - -{% comment %} start {% endcomment %} -A, -**ABS**, -ABSOLUTE, -ACTION, -ADA, -ADD, -ADMIN, -AFTER, -**ALL**, -**ALLOCATE**, -**ALLOW**, -**ALTER**, -ALWAYS, -**AND**, -**ANY**, -**ARE**, -**ARRAY**, -**AS**, -ASC, -**ASENSITIVE**, -ASSERTION, -ASSIGNMENT, -**ASYMMETRIC**, -**AT**, -**ATOMIC**, -ATTRIBUTE, -ATTRIBUTES, -**AUTHORIZATION**, -**AVG**, -BEFORE, -**BEGIN**, -BERNOULLI, -**BETWEEN**, -**BIGINT**, -**BINARY**, -**BIT**, -**BLOB**, -**BOOLEAN**, -**BOTH**, -BREADTH, -**BY**, -C, -**CALL**, -**CALLED**, -**CARDINALITY**, -CASCADE, -**CASCADED**, -**CASE**, -**CAST**, -CATALOG, -CATALOG_NAME, -**CEIL**, -**CEILING**, -CHAIN, -**CHAR**, -**CHARACTER**, -CHARACTERISTICTS, -CHARACTERS, -**CHARACTER_LENGTH**, -CHARACTER_SET_CATALOG, -CHARACTER_SET_NAME, -CHARACTER_SET_SCHEMA, -**CHAR_LENGTH**, -**CHECK**, -CLASS_ORIGIN, -**CLOB**, -**CLOSE**, -**COALESCE**, -COBOL, -**COLLATE**, -COLLATION, -COLLATION_CATALOG, -COLLATION_NAME, -COLLATION_SCHEMA, -**COLLECT**, -**COLUMN**, -COLUMN_NAME, -COMMAND_FUNCTION, -COMMAND_FUNCTION_CODE, -**COMMIT**, -COMMITTED, -**CONDITION**, -CONDITION_NUMBER, -**CONNECT**, -CONNECTION, -CONNECTION_NAME, -**CONSTRAINT**, -CONSTRAINTS, -CONSTRAINT_CATALOG, -CONSTRAINT_NAME, -CONSTRAINT_SCHEMA, -CONSTRUCTOR, -CONTAINS, -CONTINUE, -**CONVERT**, -**CORR**, -**CORRESPONDING**, -**COUNT**, -**COVAR_POP**, -**COVAR_SAMP**, -**CREATE**, -**CROSS**, -**CUBE**, -**CUME_DIST**, -**CURRENT**, -**CURRENT_CATALOG**, -**CURRENT_DATE**, -**CURRENT_DEFAULT_TRANSFORM_GROUP**, -**CURRENT_PATH**, -**CURRENT_ROLE**, -**CURRENT_SCHEMA**, -**CURRENT_TIME**, -**CURRENT_TIMESTAMP**, -**CURRENT_TRANSFORM_GROUP_FOR_TYPE**, -**CURRENT_USER**, -**CURSOR**, -CURSOR_NAME, -**CYCLE**, -DATA, -**DATE**, -DATETIME_INTERVAL_CODE, -DATETIME_INTERVAL_PRECISION, -**DAY**, -**DEALLOCATE**, -**DEC**, -**DECIMAL**, -**DECLARE**, -**DEFAULT**, -DEFAULTS, -DEFERRABLE, -DEFERRED, -DEFINED, -DEFINER, -DEGREE, -**DELETE**, -**DENSE_RANK**, -DEPTH, -**DEREF**, -DERIVED, -DESC, -**DESCRIBE**, -DESCRIPTION, -DESCRIPTOR, -**DETERMINISTIC**, -DIAGNOSTICS, -**DISALLOW**, -**DISCONNECT**, -DISPATCH, -**DISTINCT**, -DOMAIN, -**DOUBLE**, -**DROP**, -**DYNAMIC**, -DYNAMIC_FUNCTION, -DYNAMIC_FUNCTION_CODE, -**EACH**, -**ELEMENT**, -**ELSE**, -**END**, -**END-EXEC**, -EQUALS, -**ESCAPE**, -**EVERY**, -**EXCEPT**, -EXCEPTION, -EXCLUDE, -EXCLUDING, -**EXEC**, -**EXECUTE**, -**EXISTS**, -**EXP**, -**EXPLAIN**, -**EXTEND**, -**EXTERNAL**, -**EXTRACT**, -**FALSE**, -**FETCH**, -**FILTER**, -FINAL, -FIRST, -**FIRST_VALUE**, -**FLOAT**, -**FLOOR**, -FOLLOWING, -**FOR**, -**FOREIGN**, -FORTRAN, -FOUND, -**FREE**, -**FROM**, -**FULL**, -**FUNCTION**, -**FUSION**, -G, -GENERAL, -GENERATED, -**GET**, -**GLOBAL**, -GO, -GOTO, -**GRANT**, -GRANTED, -**GROUP**, -**GROUPING**, -**HAVING**, -HIERARCHY, -**HOLD**, -**HOUR**, -**IDENTITY**, -IMMEDIATE, -IMPLEMENTATION, -**IMPORT**, -**IN**, -INCLUDING, -INCREMENT, -**INDICATOR**, -INITIALLY, -**INNER**, -**INOUT**, -INPUT, -**INSENSITIVE**, -**INSERT**, -INSTANCE, -INSTANTIABLE, -**INT**, -**INTEGER**, -**INTERSECT**, -**INTERSECTION**, -**INTERVAL**, -**INTO**, -INVOKER, -**IS**, -ISOLATION, -JAVA, -**JOIN**, -K, -KEY, -KEY_MEMBER, -KEY_TYPE, -LABEL, -**LANGUAGE**, -**LARGE**, -LAST, -**LAST_VALUE**, -**LATERAL**, -**LEADING**, -**LEFT**, -LENGTH, -LEVEL, -LIBRARY, -**LIKE**, -**LIMIT**, -**LN**, -**LOCAL**, -**LOCALTIME**, -**LOCALTIMESTAMP**, -LOCATOR, -**LOWER**, -M, -MAP, -**MATCH**, -MATCHED, -**MAX**, -MAXVALUE, -**MEMBER**, -**MERGE**, -MESSAGE_LENGTH, -MESSAGE_OCTET_LENGTH, -MESSAGE_TEXT, -**METHOD**, -**MIN**, -**MINUTE**, -MINVALUE, -**MOD**, -**MODIFIES**, -**MODULE**, -**MONTH**, -MORE, -**MULTISET**, -MUMPS, -NAME, -NAMES, -**NATIONAL**, -**NATURAL**, -**NCHAR**, -**NCLOB**, -NESTING, -**NEW**, -**NEXT**, -**NO**, -**NONE**, -**NORMALIZE**, -NORMALIZED, -**NOT**, -**NULL**, -NULLABLE, -**NULLIF**, -NULLS, -NUMBER, -**NUMERIC**, -OBJECT, -OCTETS, -**OCTET_LENGTH**, -**OF**, -**OFFSET**, -**OLD**, -**ON**, -**ONLY**, -**OPEN**, -OPTION, -OPTIONS, -**OR**, -**ORDER**, -ORDERING, -ORDINALITY, -OTHERS, -**OUT**, -**OUTER**, -OUTPUT, -**OVER**, -**OVERLAPS**, -**OVERLAY**, -OVERRIDING, -PAD, -**PARAMETER**, -PARAMETER_MODE, -PARAMETER_NAME, -PARAMETER_ORDINAL_POSITION, -PARAMETER_SPECIFIC_CATALOG, -PARAMETER_SPECIFIC_NAME, -PARAMETER_SPECIFIC_SCHEMA, -PARTIAL, -**PARTITION**, -PASCAL, -PASSTHROUGH, -PATH, -**PERCENTILE_CONT**, -**PERCENTILE_DISC**, -**PERCENT_RANK**, -PLACING, -PLAN, -PLI, -**POSITION**, -**POWER**, -PRECEDING, -**PRECISION**, -**PREPARE**, -PRESERVE, -**PRIMARY**, -PRIOR, -PRIVILEGES, -**PROCEDURE**, -PUBLIC, -**RANGE**, -**RANK**, -READ, -**READS**, -**REAL**, -**RECURSIVE**, -**REF**, -**REFERENCES**, -**REFERENCING**, -**REGR_AVGX**, -**REGR_AVGY**, -**REGR_COUNT**, -**REGR_INTERCEPT**, -**REGR_R2**, -**REGR_SLOPE**, -**REGR_SXX**, -**REGR_SXY**, -**REGR_SYY**, -RELATIVE, -**RELEASE**, -REPEATABLE, -**RESET**, -RESTART, -RESTRICT, -**RESULT**, -**RETURN**, -RETURNED_CARDINALITY, -RETURNED_LENGTH, -RETURNED_OCTET_LENGTH, -RETURNED_SQLSTATE, -**RETURNS**, -**REVOKE**, -**RIGHT**, -ROLE, -**ROLLBACK**, -**ROLLUP**, -ROUTINE, -ROUTINE_CATALOG, -ROUTINE_NAME, -ROUTINE_SCHEMA, -**ROW**, -**ROWS**, -ROW_COUNT, -**ROW_NUMBER**, -**SAVEPOINT**, -SCALE, -SCHEMA, -SCHEMA_NAME, -**SCOPE**, -SCOPE_CATALOGS, -SCOPE_NAME, -SCOPE_SCHEMA, -**SCROLL**, -**SEARCH**, -**SECOND**, -SECTION, -SECURITY, -**SELECT**, -SELF, -**SENSITIVE**, -SEQUENCE, -SERIALIZABLE, -SERVER, -SERVER_NAME, -SESSION, -**SESSION_USER**, -**SET**, -SETS, -**SIMILAR**, -SIMPLE, -SIZE, -**SMALLINT**, -**SOME**, -SOURCE, -SPACE, -**SPECIFIC**, -**SPECIFICTYPE**, -SPECIFIC_NAME, -**SQL**, -**SQLEXCEPTION**, -**SQLSTATE**, -**SQLWARNING**, -**SQRT**, -**START**, -STATE, -STATEMENT, -**STATIC**, -**STDDEV_POP**, -**STDDEV_SAMP**, -**STREAM**, -STRUCTURE, -STYLE, -SUBCLASS_ORIGIN, -**SUBMULTISET**, -SUBSTITUTE, -**SUBSTRING**, -**SUM**, -**SYMMETRIC**, -**SYSTEM**, -**SYSTEM_USER**, -**TABLE**, -**TABLESAMPLE**, -TABLE_NAME, -TEMPORARY, -**THEN**, -TIES, -**TIME**, -**TIMESTAMP**, -**TIMEZONE_HOUR**, -**TIMEZONE_MINUTE**, -**TINYINT**, -**TO**, -TOP_LEVEL_COUNT, -**TRAILING**, -TRANSACTION, -TRANSACTIONS_ACTIVE, -TRANSACTIONS_COMMITTED, -TRANSACTIONS_ROLLED_BACK, -TRANSFORM, -TRANSFORMS, -**TRANSLATE**, -**TRANSLATION**, -**TREAT**, -**TRIGGER**, -TRIGGER_CATALOG, -TRIGGER_NAME, -TRIGGER_SCHEMA, -**TRIM**, -**TRUE**, -TYPE, -**UESCAPE**, -UNBOUNDED, -UNCOMMITTED, -UNDER, -**UNION**, -**UNIQUE**, -**UNKNOWN**, -UNNAMED, -**UNNEST**, -**UPDATE**, -**UPPER**, -**UPSERT**, -USAGE, -**USER**, -USER_DEFINED_TYPE_CATALOG, -USER_DEFINED_TYPE_CODE, -USER_DEFINED_TYPE_NAME, -USER_DEFINED_TYPE_SCHEMA, -**USING**, -**VALUE**, -**VALUES**, -**VARBINARY**, -**VARCHAR**, -**VARYING**, -**VAR_POP**, -**VAR_SAMP**, -VERSION, -VIEW, -**WHEN**, -**WHENEVER**, -**WHERE**, -**WIDTH_BUCKET**, -**WINDOW**, -**WITH**, -**WITHIN**, -**WITHOUT**, -WORK, -WRAPPER, -WRITE, -XML, -**YEAR**, -ZONE. -{% comment %} end {% endcomment %} - -## Identifiers - -Identifiers are the names of tables, columns and other metadata -elements used in a SQL query. - -Unquoted identifiers, such as emp, must start with a letter and can -only contain letters, digits, and underscores. They are implicitly -converted to upper case. - -Quoted identifiers, such as `"Employee Name"`, start and end with -double quotes. They may contain virtually any character, including -spaces and other punctuation. If you wish to include a double quote -in an identifier, use another double quote to escape it, like this: -`"An employee called ""Fred""."`. - -In Calcite, matching identifiers to the name of the referenced object is -case-sensitive. But remember that unquoted identifiers are implicitly -converted to upper case before matching, and if the object it refers -to was created using an unquoted identifier for its name, then its -name will have been converted to upper case also. - -## Data types - -### Scalar types - -| Data type | Description | Range and examples | -|:----------- |:------------------------- |:---------------------| -| BOOLEAN | Logical values | Values: TRUE, FALSE, UNKNOWN -| TINYINT | 1 byte signed integer | Range is -255 to 256 -| SMALLINT | 2 byte signed integer | Range is -32768 to 32767 -| INTEGER, INT | 4 byte signed integer | Range is -2147483648 to 2147483647 -| BIGINT | 8 byte signed integer | Range is -9223372036854775808 to 9223372036854775807 -| DECIMAL(p, s) | Fixed point | Example: 123.45 is a DECIMAL(5, 2) value. -| NUMERIC | Fixed point | -| REAL, FLOAT | 4 byte floating point | 6 decimal digits precision -| DOUBLE | 8 byte floating point | 15 decimal digits precision -| CHAR(n), CHARACTER(n) | Fixed-width character string | 'Hello', '' (empty string), _latin1'Hello', n'Hello', _UTF16'Hello', 'Hello' 'there' (literal split into multiple parts) -| VARCHAR(n), CHARACTER VARYING(n) | Variable-length character string | As CHAR(n) -| BINARY(n) | Fixed-width binary string | x'45F0AB', x'' (empty binary string), x'AB' 'CD' (multi-part binary string literal) -| VARBINARY(n), BINARY VARYING(n) | Variable-length binary string | As BINARY(n) -| DATE | Date | Example: DATE '1969-07-20' -| TIME | Time of day | Example: TIME '20:17:40' -| TIMESTAMP [ WITHOUT TIME ZONE ] | Date and time | Example: TIMESTAMP '1969-07-20 20:17:40' -| TIMESTAMP WITH TIME ZONE | Date and time with time zone | Example: TIMESTAMP '1969-07-20 20:17:40 America/Los Angeles' -| INTERVAL timeUnit [ TO timeUnit ] | Date time interval | Examples: INTERVAL '1:5' YEAR TO MONTH, INTERVAL '45' DAY -| Anchored interval | Date time interval | Example: (DATE '1969-07-20', DATE '1972-08-29') - -Where: - -{% highlight sql %} -timeUnit: - YEAR | MONTH | DAY | HOUR | MINUTE | SECOND -{% endhighlight %} - -Note: - -* DATE, TIME and TIMESTAMP have no time zone. There is not even an implicit - time zone, such as UTC (as in Java) or the local time zone. It is left to - the user or application to supply a time zone. - -### Non-scalar types - -| Type | Description -|:-------- |:----------------------------------------------------------- -| ANY | A value of an unknown type -| ROW | Row with 1 or more columns -| MAP | Collection of keys mapped to values -| MULTISET | Unordered collection that may contain duplicates -| ARRAY | Ordered, contiguous collection that may contain duplicates -| CURSOR | Cursor over the result of executing a query - -## Operators and functions - -### Comparison operators - -| Operator syntax | Description -|:------------------------------------------------- |:----------- -| value1 = value2 | Equals -| value1 <> value2 | Not equal -| value1 > value2 | Greater than -| value1 >= value2 | Greater than or equal -| value1 < value2 | Less than -| value1 <= value2 | Less than or equal -| value IS NULL | Whether *value* is null -| value IS NOT NULL | Whether *value* is not null -| value1 IS DISTINCT FROM value2 | Whether two values are not equal, treating null values as the same -| value1 IS NOT DISTINCT FROM value2 | Whether two values are equal, treating null values as the same -| value1 BETWEEN value2 AND value3 | Whether *value1* is greater than or equal to *value2* and less than or equal to *value3* -| value1 NOT BETWEEN value2 AND value3 | Whether *value1* is less than *value2* or greater than *value3* -| string1 LIKE string2 [ ESCAPE string3 ] | Whether *string1* matches pattern *string2* -| string1 NOT LIKE string2 [ ESCAPE string3 ] | Whether *string1* does not match pattern *string2* -| string1 SIMILAR TO string2 [ ESCAPE string3 ] | Whether *string1* matches regular expression *string2* -| string1 NOT SIMILAR TO string2 [ ESCAPE string3 ] | Whether *string1* does not match regular expression *string2* -| value IN (value [, value]* ) | Whether *value* is equal to a value in a list -| value NOT IN (value [, value]* ) | Whether *value* is not equal to every value in a list -| value IN (sub-query) | Whether *value* is equal to a row returned by *sub-query* -| value NOT IN (sub-query) | Whether *value* is not equal to every row returned by *sub-query* -| EXISTS (sub-query) | Whether *sub-query* returns at least one row - -### Logical operators - -| Operator syntax | Description -|:---------------------- |:----------- -| boolean1 OR boolean2 | Whether *boolean1* is TRUE or *boolean2* is TRUE -| boolean1 AND boolean2 | Whether *boolean1* and *boolean2* are both TRUE -| NOT boolean | Whether *boolean* is not TRUE; returns UNKNOWN if *boolean* is UNKNOWN -| boolean IS FALSE | Whether *boolean* is FALSE; returns FALSE if *boolean* is UNKNOWN -| boolean IS NOT FALSE | Whether *boolean* is not FALSE; returns TRUE if *boolean* is UNKNOWN -| boolean IS TRUE | Whether *boolean* is TRUE; returns FALSE if *boolean* is UNKNOWN -| boolean IS NOT TRUE | Whether *boolean* is not TRUE; returns TRUE if *boolean* is UNKNOWN -| boolean IS UNKNOWN | Whether *boolean* is UNKNOWN -| boolean IS NOT UNKNOWN | Whether *boolean* is not UNKNOWN - -### Arithmetic operators and functions - -| Operator syntax | Description -|:------------------------- |:----------- -| + numeric | Returns *numeric* -|:- numeric | Returns negative *numeric* -| numeric1 + numeric2 | Returns *numeric1* plus *numeric2* -| numeric1 - numeric2 | Returns *numeric1* minus *numeric2* -| numeric1 * numeric2 | Returns *numeric1* multiplied by *numeric2* -| numeric1 / numeric2 | Returns *numeric1* divided by *numeric2* -| POWER(numeric1, numeric2) | Returns *numeric1* raised to the power of *numeric2* -| ABS(numeric) | Returns the absolute value of *numeric* -| MOD(numeric, numeric) | Returns the remainder (modulus) of *numeric1* divided by *numeric2*. The result is negative only if *numeric1* is negative -| SQRT(numeric) | Returns the square root of *numeric* -| LN(numeric) | Returns the natural logarithm (base *e*) of *numeric* -| LOG10(numeric) | Returns the base 10 logarithm of *numeric* -| EXP(numeric) | Returns *e* raised to the power of *numeric* -| CEIL(numeric) | Rounds *numeric* up, and returns the smallest number that is greater than or equal to *numeric* -| FLOOR(numeric) | Rounds *numeric* down, and returns the largest number that is less than or equal to *numeric* - -### Character string operators and functions - -| Operator syntax | Description -|:-------------------------- |:----------- -| string || string | Concatenates two character strings. -| CHAR_LENGTH(string) | Returns the number of characters in a character string -| CHARACTER_LENGTH(string) | As CHAR_LENGTH(*string*) -| UPPER(string) | Returns a character string converted to upper case -| LOWER(string) | Returns a character string converted to lower case -| POSITION(string1 IN string2) | Returns the position of the first occurrence of *string1* in *string2* -| TRIM( { BOTH | LEADING | TRAILING } string1 FROM string2) | Removes the longest string containing only the characters in *string1* from the start/end/both ends of *string1* -| OVERLAY(string1 PLACING string2 FROM integer [ FOR integer2 ]) | Replaces a substring of *string1* with *string2* -| SUBSTRING(string FROM integer) | Returns a substring of a character string starting at a given point. -| SUBSTRING(string FROM integer FOR integer) | Returns a substring of a character string starting at a given point with a given length. -| INITCAP(string) | Returns *string* with the first letter of each word converter to upper case and the rest to lower case. Words are sequences of alphanumeric characters separated by non-alphanumeric characters. - -Not implemented: - -* SUBSTRING(string FROM regexp FOR regexp) - -### Binary string operators and functions - -| Operator syntax | Description -|:--------------- |:----------- -| binary || binary | Concatenates two binary strings. -| POSITION(binary1 IN binary2) | Returns the position of the first occurrence of *binary1* in *binary2* -| OVERLAY(binary1 PLACING binary2 FROM integer [ FOR integer2 ]) | Replaces a substring of *binary1* with *binary2* -| SUBSTRING(binary FROM integer) | Returns a substring of *binary* starting at a given point -| SUBSTRING(binary FROM integer FOR integer) | Returns a substring of *binary* starting at a given point with a given length - -### Date/time functions - -| Operator syntax | Description -|:------------------------- |:----------- -| LOCALTIME | Returns the current date and time in the session time zone in a value of datatype TIME -| LOCALTIME(precision) | Returns the current date and time in the session time zone in a value of datatype TIME, with *precision* digits of precision -| LOCALTIMESTAMP | Returns the current date and time in the session time zone in a value of datatype TIMESTAMP -| LOCALTIMESTAMP(precision) | Returns the current date and time in the session time zone in a value of datatype TIMESTAMP, with *precision* digits of precision -| CURRENT_TIME | Returns the current time in the session time zone, in a value of datatype TIMESTAMP WITH TIME ZONE -| CURRENT_DATE | Returns the current date in the session time zone, in a value of datatype DATE -| CURRENT_TIMESTAMP | Returns the current date and time in the session time zone, in a value of datatype TIMESTAMP WITH TIME ZONE -| EXTRACT(timeUnit FROM datetime) | Extracts and returns the value of a specified datetime field from a datetime value expression -| FLOOR(datetime TO timeUnit) | Rounds *datetime* down to *timeUnit* -| CEIL(datetime TO timeUnit) | Rounds *datetime* up to *timeUnit* - -Not implemented: - -* EXTRACT(timeUnit FROM interval) -* CEIL(interval) -* FLOOR(interval) -* datetime - datetime timeUnit [ TO timeUnit ] -* interval OVERLAPS interval -* \+ interval -* \- interval -* interval + interval -* interval - interval -* interval / interval -* datetime + interval -* datetime - interval - -### System functions - -| Operator syntax | Description -|:--------------- |:----------- -| USER | Equivalent to CURRENT_USER -| CURRENT_USER | User name of current execution context -| SESSION_USER | Session user name -| SYSTEM_USER | Returns the name of the current data store user as identified by the operating system -| CURRENT_PATH | Returns a character string representing the current lookup scope for references to user-defined routines and types -| CURRENT_ROLE | Returns the current active role - -### Conditional functions and operators - -| Operator syntax | Description -|:--------------- |:----------- -| CASE value<br/>WHEN value1 [, value11 ]* THEN result1<br/>[ WHEN valueN [, valueN1 ]* THEN resultN ]*<br/>[ ELSE resultZ ]<br/> END | Simple case -| CASE<br/>WHEN condition1 THEN result1<br/>[ WHEN conditionN THEN resultN ]*<br/>[ ELSE resultZ ]<br/>END | Searched case -| NULLIF(value, value) | Returns NULL if the values are the same.<br/><br/>For example, <code>NULLIF(5, 5)</code> returns NULL; <code>NULLIF(5, 0)</code> returns 5. -| COALESCE(value, value [, value ]* ) | Provides a value if the first value is null.<br/><br/>For example, <code>COALESCE(NULL, 5)</code> returns 5. - -### Type conversion - -| Operator syntax | Description -|:--------------- | :---------- -| CAST(value AS type) | Converts a value to a given type. - -### Value constructors - -| Operator syntax | Description -|:--------------- |:----------- -| ROW (value [, value]* ) | Creates a row from a list of values. -| (value [, value]* ) | Creates a row from a list of values. -| map '[' key ']' | Returns the element of a map with a particular key. -| array '[' index ']' | Returns the element at a particular location in an array. -| ARRAY '[' value [, value ]* ']' | Creates an array from a list of values. -| MAP '[' key, value [, key, value ]* ']' | Creates a map from a list of key-value pairs. - -### Collection functions - -| Operator syntax | Description -|:--------------- |:----------- -| ELEMENT(value) | Returns the sole element of a array or multiset; null if the collection is empty; throws if it has more than one element. -| CARDINALITY(value) | Returns the number of elements in an array or multiset. - -See also: UNNEST relational operator converts a collection to a relation. - -### JDBC function escape - -#### Numeric - -| Operator syntax | Description -|:------------------------------ |:----------- -| {fn LOG10(numeric)} | Returns the base-10 logarithm of *numeric* -| {fn POWER(numeric1, numeric2)} | Returns *numeric1* raised to the power of *numeric2* - -Not implemented: - -* {fn ABS(numeric)} - Returns the absolute value of *numeric* -* {fn ACOS(numeric)} - Returns the arc cosine of *numeric* -* {fn ASIN(numeric)} - Returns the arc sine of *numeric* -* {fn ATAN(numeric)} - Returns the arc tangent of *numeric* -* {fn ATAN2(numeric, numeric)} -* {fn CEILING(numeric)} - Rounds *numeric* up, and returns the smallest number that is greater than or equal to *numeric* -* {fn COS(numeric)} - Returns the cosine of *numeric* -* {fn COT(numeric)} -* {fn DEGREES(numeric)} - Converts *numeric* from radians to degrees -* {fn EXP(numeric)} - Returns *e* raised to the power of *numeric* -* {fn FLOOR(numeric)} - Rounds *numeric* down, and returns the largest number that is less than or equal to *numeric* -* {fn LOG(numeric)} - Returns the natural logarithm (base *e*) of *numeric* -* {fn MOD(numeric1, numeric2)} - Returns the remainder (modulus) of *numeric1* divided by *numeric2*. The result is negative only if *numeric1* is negative -* {fn PI()} - Returns a value that is closer than any other value to *pi* -* {fn RADIANS(numeric)} - Converts *numeric* from degrees to radians -* {fn RAND(numeric)} -* {fn ROUND(numeric, numeric)} -* {fn SIGN(numeric)} -* {fn SIN(numeric)} - Returns the sine of *numeric* -* {fn SQRT(numeric)} - Returns the square root of *numeric* -* {fn TAN(numeric)} - Returns the tangent of *numeric* -* {fn TRUNCATE(numeric, numeric)} - -#### String - -| Operator syntax | Description -|:--------------- |:----------- -| {fn LOCATE(string1, string2)} | Returns the position in *string2* of the first occurrence of *string1*. Searches from the beginning of the second CharacterExpression, unless the startIndex parameter is specified. -| {fn INSERT(string1, start, length, string2)} | Inserts *string2* into a slot in *string1* -| {fn LCASE(string)} | Returns a string in which all alphabetic characters in *string* have been converted to lower case - -Not implemented: - -* {fn ASCII(string)} - Convert a single-character string to the corresponding ASCII code, an integer between 0 and 255 -* {fn CHAR(string)} -* {fn CONCAT(character, character)} - Returns the concatenation of character strings -* {fn DIFFERENCE(string, string)} -* {fn LEFT(string, integer)} -* {fn LENGTH(string)} -* {fn LOCATE(string1, string2 [, integer])} - Returns the position in *string2* of the first occurrence of *string1*. Searches from the beginning of *string2*, unless *integer* is specified. -* {fn LTRIM(string)} -* {fn REPEAT(string, integer)} -* {fn REPLACE(string, string, string)} -* {fn RIGHT(string, integer)} -* {fn RTRIM(string)} -* {fn SOUNDEX(string)} -* {fn SPACE(integer)} -* {fn SUBSTRING(string, integer, integer)} -* {fn UCASE(string)} - Returns a string in which all alphabetic characters in *string* have been converted to upper case - -#### Date/time - -Not implemented: - -* {fn CURDATE()} -* {fn CURTIME()} -* {fn DAYNAME(date)} -* {fn DAYOFMONTH(date)} -* {fn DAYOFWEEK(date)} -* {fn DAYOFYEAR(date)} -* {fn HOUR(time)} -* {fn MINUTE(time)} -* {fn MONTH(date)} -* {fn MONTHNAME(date)} -* {fn NOW()} -* {fn QUARTER(date)} -* {fn SECOND(time)} -* {fn TIMESTAMPADD(interval, count, timestamp)} -* {fn TIMESTAMPDIFF(interval, timestamp, timestamp)} -* {fn WEEK(date)} -* {fn YEAR(date)} - -#### System - -Not implemented: - -* {fn DATABASE()} -* {fn IFNULL(value, value)} -* {fn USER(value, value)} -* {fn CONVERT(value, type)} - -### Aggregate functions - -Syntax: - -{% highlight sql %} -aggregateCall: - agg( [ DISTINCT ] value [, value]* ) [ FILTER ( WHERE condition ) ] - | agg(*) [ FILTER ( WHERE condition ) ] -{% endhighlight %} - -If `FILTER` is present, the aggregate function only considers rows for which -*condition* evaluates to TRUE. - -If `DISTINCT` is present, duplicate argument values are eliminated before being -passed to the aggregate function. - -| Operator syntax | Description -|:---------------------------------- |:----------- -| COLLECT( [ DISTINCT ] value) | Returns a multiset of the values -| COUNT( [ DISTINCT ] value [, value]* ) | Returns the number of input rows for which *value* is not null (wholly not null if *value* is composite) -| COUNT(*) | Returns the number of input rows -| AVG( [ DISTINCT ] numeric) | Returns the average (arithmetic mean) of *numeric* across all input values -| SUM( [ DISTINCT ] numeric) | Returns the sum of *numeric* across all input values -| MAX( [ DISTINCT ] value) | Returns the maximum value of *value* across all input values -| MIN( [ DISTINCT ] value) | Returns the minimum value of *value* across all input values -| STDDEV_POP( [ DISTINCT ] numeric) | Returns the population standard deviation of *numeric* across all input values -| STDDEV_SAMP( [ DISTINCT ] numeric) | Returns the sample standard deviation of *numeric* across all input values -| VAR_POP( [ DISTINCT ] value) | Returns the population variance (square of the population standard deviation) of *numeric* across all input values -| VAR_SAMP( [ DISTINCT ] numeric) | Returns the sample variance (square of the sample standard deviation) of *numeric* across all input values -| COVAR_POP(numeric1, numeric2) | Returns the population covariance of the pair (*numeric1*, *numeric2*) across all input values -| COVAR_SAMP(numeric1, numeric2) | Returns the sample covariance of the pair (*numeric1*, *numeric2*) across all input values -| REGR_SXX(numeric1, numeric2) | Returns the sum of squares of the dependent expression in a linear regression model -| REGR_SYY(numeric1, numeric2) | Returns the sum of squares of the independent expression in a linear regression model - -Not implemented: - -* REGR_AVGX(numeric1, numeric2) -* REGR_AVGY(numeric1, numeric2) -* REGR_COUNT(numeric1, numeric2) -* REGR_INTERCEPT(numeric1, numeric2) -* REGR_R2(numeric1, numeric2) -* REGR_SLOPE(numeric1, numeric2) -* REGR_SXY(numeric1, numeric2) - -### Window functions - -| Operator syntax | Description -|:----------------------------------------- |:----------- -| COUNT(value [, value ]* ) OVER window | Returns the number of rows in *window* for which *value* is not null (wholly not null if *value* is composite) -| COUNT(*) OVER window | Returns the number of rows in *window* -| AVG(numeric) OVER window | Returns the average (arithmetic mean) of *numeric* across all values in *window* -| SUM(numeric) OVER window | Returns the sum of *numeric* across all values in *window* -| MAX(value) OVER window | Returns the maximum value of *value* across all values in *window* -| MIN(value) OVER window | Returns the minimum value of *value* across all values in *window* -| RANK() OVER window | Returns the rank of the current row with gaps; same as ROW_NUMBER of its first peer -| DENSE_RANK() OVER window | Returns the rank of the current row without gaps; this function counts peer groups -| ROW_NUMBER() OVER window | Returns the number of the current row within its partition, counting from 1 -| FIRST_VALUE(value) OVER window | Returns *value* evaluated at the row that is the first row of the window frame -| LAST_VALUE(value) OVER window | Returns *value* evaluated at the row that is the last row of the window frame -| LEAD(value, offset, default) OVER window | Returns *value* evaluated at the row that is *offset* rows after the current row within the partition; if there is no such row, instead returns *default*. Both *offset* and *default* are evaluated with respect to the current row. If omitted, *offset* defaults to 1 and *default* to NULL -| LAG(value, offset, default) OVER window | Returns *value* evaluated at the row that is *offset* rows before the current row within the partition; if there is no such row, instead returns *default*. Both *offset* and *default* are evaluated with respect to the current row. If omitted, *offset* defaults to 1 and *default* to NULL -| NTILE(value) OVER window | Returns an integer ranging from 1 to *value*, dividing the partition as equally as possible - -Not implemented: - -* COUNT(DISTINCT value) OVER window -* FIRST_VALUE(value) IGNORE NULLS OVER window -* LAST_VALUE(value) IGNORE NULLS OVER window -* PERCENT_RANK(value) OVER window -* CUME_DIST(value) OVER window -* NTH_VALUE(value, nth) OVER window - -### Grouping functions - -| Operator syntax | Description -|:-------------------- |:----------- -| GROUPING(expression) | Returns 1 if expression is rolled up in the current row's grouping set, 0 otherwise -| GROUP_ID() | Returns an integer that uniquely identifies the combination of grouping keys -| GROUPING_ID(expression [, expression ] * ) | Returns a bit vector of the given grouping expressions - -### User-defined functions - -Calcite is extensible. You can define each kind of function using user code. -For each kind of function there are often several ways to define a function, -varying from convenient to efficient. - -To implement a *scalar function*, there are 3 options: - -* Create a class with a public static `eval` method, - and register the class; -* Create a class with a public non-static `eval` method, - and a public constructor with no arguments, - and register the class; -* Create a class with one or more public static methods, - and register each class/method combination. - -To implement an *aggregate function*, there are 2 options: - -* Create a class with public static `init`, `add` and `result` methods, - and register the class; -* Create a class with public non-static `init`, `add` and `result` methods, - and a public constructor with no arguments, - and register the class. - -Optionally, add a public `merge` method to the class; this allows Calcite to -generate code that merges sub-totals. - -Optionally, make your class implement the -[SqlSplittableAggFunction]({{ site.apiRoot }}/org/apache/calcite/sql/SqlSplittableAggFunction.html) -interface; this allows Calcite to decompose the function across several stages -of aggregation, roll up from summary tables, and push it through joins. - -To implement a *table function*, there are 3 options: - -* Create a class with a static `eval` method that returns - [ScannableTable]({{ site.apiRoot }}/org/apache/calcite/schema/ScannableTable.html) - or - [QueryableTable]({{ site.apiRoot }}/org/apache/calcite/schema/QueryableTable.html), - and register the class; -* Create a class with a non-static `eval` method that returns - [ScannableTable]({{ site.apiRoot }}/org/apache/calcite/schema/ScannableTable.html) - or - [QueryableTable]({{ site.apiRoot }}/org/apache/calcite/schema/QueryableTable.html), - and register the class; -* Create a class with one or more public static methods that return - [ScannableTable]({{ site.apiRoot }}/org/apache/calcite/schema/ScannableTable.html) - or - [QueryableTable]({{ site.apiRoot }}/org/apache/calcite/schema/QueryableTable.html), - and register each class/method combination. - -To implement a *table macro*, there are 3 options: - -* Create a class with a static `eval` method that returns - [TranslatableTable]({{ site.apiRoot }}/org/apache/calcite/schema/TranslatableTable.html), - and register the class; -* Create a class with a non-static `eval` method that returns - [TranslatableTable]({{ site.apiRoot }}/org/apache/calcite/schema/TranslatableTable.html), - and register the class; -* Create a class with one or more public static methods that return - [TranslatableTable]({{ site.apiRoot }}/org/apache/calcite/schema/TranslatableTable.html), - and register each class/method combination. - -Calcite deduces the parameter types and result type of a function from the -parameter and return types of the Java method that implements it. Further, you -can specify the name and optionality of each parameter using the -[Parameter]({{ site.apiRoot }}/org/apache/calcite/linq4j/function/Parameter.html) -annotation. - -### Calling functions with named and optional parameters - -Usually when you call a function, you need to specify all of its parameters, -in order. But that can be a problem if a function has a lot of parameters, -and especially if you want to add more parameters over time. - -To solve this problem, the SQL standard allows you to pass parameters by name, -and to define parameters which are optional (that is, have a default value -that is used if they are not specified). - -Suppose you have a function `f`, declared as in the following pseudo syntax: - -```FUNCTION f( - INTEGER a, - INTEGER b DEFAULT NULL, - INTEGER c, - INTEGER d DEFAULT NULL, - INTEGER e DEFAULT NULL) RETURNS INTEGER``` - -All of the function's parameters have names, and parameters `b`, `d` and `e` -have a default value of `NULL` and are therefore optional. -(In Calcite, `NULL` is the only allowable default value for optional parameters; -this may change -[in future](https://issues.apache.org/jira/browse/CALCITE-947).) - -When calling a function with optional parameters, -you can omit optional arguments at the end of the list, or use the `DEFAULT` -keyword for any optional arguments. -Here are some examples: - -* `f(1, 2, 3, 4, 5)` provides a value to each parameter, in order; -* `f(1, 2, 3, 4)` omits `e`, which gets its default value, `NULL`; -* `f(1, DEFAULT, 3)` omits `d` and `e`, - and specifies to use the default value of `b`; -* `f(1, DEFAULT, 3, DEFAULT, DEFAULT)` has the same effect as the previous - example; -* `f(1, 2)` is not legal, because `c` is not optional; -* `f(1, 2, DEFAULT, 4)` is not legal, because `c` is not optional. - -You can specify arguments by name using the `=>` syntax. -If one argument is named, they all must be. -Arguments may be in any other, but must not specify any argument more than once, -and you need to provide a value for every parameter which is not optional. -Here are some examples: - -* `f(c => 3, d => 1, a => 0)` is equivalent to `f(0, NULL, 3, 1, NULL)`; -* `f(c => 3, d => 1)` is not legal, because you have not specified a value for - `a` and `a` is not optional. - http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_docs/roadmap.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/roadmap.md b/avatica/site/_docs/roadmap.md new file mode 100644 index 0000000..30618ee --- /dev/null +++ b/avatica/site/_docs/roadmap.md @@ -0,0 +1,51 @@ +--- +layout: docs +title: Roadmap +sidebar_title: Roadmap +permalink: /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
