http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_docs/index.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/index.md b/avatica/site/_docs/index.md index f0c4afd..da4fd2d 100644 --- a/avatica/site/_docs/index.md +++ b/avatica/site/_docs/index.md @@ -22,124 +22,107 @@ limitations under the License. {% endcomment %} --> -Apache Calcite is a dynamic data management framework. +Avatica is a framework for building JDBC and ODBC drivers for databases, +and an RPC wire protocol. -It contains many of the pieces that comprise a typical database -management system, but omits some key functions: storage of data, -algorithms to process data, and a repository for storing metadata. + -Calcite intentionally stays out of the business of storing and -processing data. As we shall see, this makes it an excellent choice -for mediating between applications and one or more data storage -locations and data processing engines. It is also a perfect foundation -for building a database: just add data. +Avatica's Java binding has very few dependencies. +Even though it is part of Apache Calcite it does not depend on other parts of +Calcite. It depends only on JDK 1.7+ and Jackson. -To illustrate, let's create an empty instance of Calcite and then -point it at some data. +Avatica's wire protocol is JSON over HTTP. +The Java implementation uses Jackson to convert request/response command +objects to/from JSON. -{% highlight java %} -public static class HrSchema { - public final Employee[] emps = 0; - public final Department[] depts = 0; -} -Class.forName("org.apache.calcite.jdbc.Driver"); -Properties info = new Properties(); -info.setProperty("lex", "JAVA"); -Connection connection = DriverManager.getConnection("jdbc:calcite:", info); -CalciteConnection calciteConnection = - connection.unwrap(CalciteConnection.class); -ReflectiveSchema.create(calciteConnection, - calciteConnection.getRootSchema(), "hr", new HrSchema()); -Statement statement = calciteConnection.createStatement(); -ResultSet resultSet = statement.executeQuery( - "select d.deptno, min(e.empid)\n" - + "from hr.emps as e\n" - + "join hr.depts as d\n" - + " on e.deptno = d.deptno\n" - + "group by d.deptno\n" - + "having count(*) > 1"); -print(resultSet); -resultSet.close(); -statement.close(); -connection.close(); -{% endhighlight %} +Avatica-Server is a Java implementation of Avatica RPC. -Where is the database? There is no database. The connection is -completely empty until `ReflectiveSchema.create` registers a Java -object as a schema and its collection fields `emps` and `depts` as -tables. +Core concepts: -Calcite does not want to own data; it does not even have favorite data -format. This example used in-memory data sets, and processed them -using operators such as `groupBy` and `join` from the linq4j -library. But Calcite can also process data in other data formats, such -as JDBC. In the first example, replace +* Meta is a local API sufficient to implement any Avatica provider +* Factory creates implementations of the JDBC classes (Driver, Connection, + Statement, ResultSet) on top of a Meta +* Service is an interface that implements the functions of Meta in terms + of request and response command objects -{% highlight java %} -ReflectiveSchema.create(calciteConnection, - calciteConnection.getRootSchema(), "hr", new HrSchema()); -{% endhighlight %} +## JDBC -with +Avatica implements JDBC by means of Factory. +Factory creates implementations of the JDBC classes (Driver, Connection, +Statement, PreparedStatement, ResultSet) on top of a Meta. -{% highlight java %} -Class.forName("com.mysql.jdbc.Driver"); -BasicDataSource dataSource = new BasicDataSource(); -dataSource.setUrl("jdbc:mysql://localhost"); -dataSource.setUsername("username"); -dataSource.setPassword("password"); -JdbcSchema.create(calciteConnection.getRootSchema(), "name", dataSource, - null, "hr"); -{% endhighlight %} +## ODBC -and Calcite will execute the same query in JDBC. To the application, -the data and API are the same, but behind the scenes the -implementation is very different. Calcite uses optimizer rules to push -the `JOIN` and `GROUP BY` operations to the source database. +Work has not started on Avatica ODBC. -In-memory and JDBC are just two familiar examples. Calcite can handle -any data source and data format. To add a data source, you need to -write an adapter that tells Calcite what collections in the data -source it should consider "tables". +Avatica ODBC would use the same wire protocol and could use the same server +implementation in Java. The ODBC client would be written in C or C++. -For more advanced integration, you can write optimizer -rules. Optimizer rules allow Calcite to access data of a new format, -allow you to register new operators (such as a better join algorithm), -and allow Calcite to optimize how queries are translated to -operators. Calcite will combine your rules and operators with built-in -rules and operators, apply cost-based optimization, and generate an -efficient plan. +Since the Avatica protocol abstracts many of the differences between providers, +the same ODBC client could be used for different databases. -### Writing an adapter +## HTTP Server -The subproject under example/csv provides a CSV adapter, which is -fully functional for use in applications but is also simple enough to -serve as a good template if you are writing your own adapter. +Avatica-server embeds the Jetty HTTP server, providing a class +[HttpServer]({{ site.apiRoot }}/org/apache/calcite/avatica/server/HttpServer.html) +that implements the Avatica RPC protocol +and can be run as a standalone Java application. -See the <a href="{{ site.baseurl }}/docs/tutorial.html">tutorial</a> for information on using -the CSV adapter and writing other adapters. +Connectors in HTTP server can be configured if needed by extending +`HttpServer` class and overriding its `configureConnector()` method. +For example, user can set `requestHeaderSize` to 64K bytes as follows: -See the <a href="howto.html">HOWTO</a> for more information about -using other adapters, and about using Calcite in general. +{% highlight java %} +HttpServer server = new HttpServer(handler) { + @Override + protected ServerConnector configureConnector( + ServerConnector connector, int port) { + HttpConnectionFactory factory = (HttpConnectionFactory) + connector.getDefaultConnectionFactory(); + factory.getHttpConfiguration().setRequestHeaderSize(64 << 10); + return super.configureConnector(connector, port); + } +}; +server.start(); +{% endhighlight %} -## Status +## Project structure + +We know that it is important that client libraries have minimal dependencies. -The following features are complete. - -* Query parser, validator and optimizer -* Support for reading models in JSON format -* Many standard functions and aggregate functions -* JDBC queries against Linq4j and JDBC back-ends -* Linq4j front-end -* SQL features: SELECT, FROM (including JOIN syntax), WHERE, GROUP BY - (including GROUPING SETS), aggregate functions (including - COUNT(DISTINCT ...) and FILTER), HAVING, ORDER BY (including NULLS - FIRST/LAST), set operations (UNION, INTERSECT, MINUS), sub-queries - (including correlated sub-queries), windowed aggregates, LIMIT - (syntax as <a - href="http://www.postgresql.org/docs/8.4/static/sql-select.html#SQL-LIMIT";>Postgres</a>); - more details in the [SQL reference](reference.html) -* Local and remote JDBC drivers; see [Avatica](avatica_overview.html) -* Several [adapters](adapter.html) +Avatica is currently part of Apache Calcite. +It does not depend upon any other part of Calcite. +At some point Avatica could become a separate project. +Packages: + +* [org.apache.calcite.avatica]({{ site.apiRoot }}/org/apache/calcite/avatica/package-summary.html) Core framework +* [org.apache.calcite.avatica.remote]({{ site.apiRoot }}/org/apache/calcite/avatica/remote/package-summary.html) JDBC driver that uses remote procedure calls +* [org.apache.calcite.avatica.server]({{ site.apiRoot }}/org/apache/calcite/avatica/server/package-summary.html) HTTP server +* [org.apache.calcite.avatica.util]({{ site.apiRoot }}/org/apache/calcite/avatica/util/package-summary.html) Utilities + +## Status +### Implemented + +* Create connection, create statement, metadata, prepare, bind, execute, fetch +* RPC using JSON over HTTP +* Local implementation +* Implementation over an existing JDBC driver +* Composite RPCs (combining several requests into one round trip) + * Execute-Fetch + * Metadata-Fetch (metadata calls such as getTables return all rows) + +### Not implemented + +* ODBC +* RPCs + * CloseStatement + * CloseConnection +* Composite RPCs + * CreateStatement-Prepare + * CloseStatement-CloseConnection + * Prepare-Execute-Fetch (Statement.executeQuery should fetch first N rows) +* Remove statements from statement table +* DML (INSERT, UPDATE, DELETE) +* Statement.execute applied to SELECT statement
http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_docs/json_reference.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/json_reference.md b/avatica/site/_docs/json_reference.md new file mode 100644 index 0000000..85db8f5 --- /dev/null +++ b/avatica/site/_docs/json_reference.md @@ -0,0 +1,1086 @@ +--- +layout: docs +title: JSON Reference +sidebar_title: JSON Reference +permalink: /docs/json_reference.html +requests: + - { name: "CatalogsRequest" } + - { name: "CloseConnectionRequest" } + - { name: "CloseStatementRequest" } + - { name: "ColumnsRequest" } + - { name: "CommitRequest" } + - { name: "ConnectionSyncRequest" } + - { name: "CreateStatementRequest" } + - { name: "DatabasePropertyRequest" } + - { name: "ExecuteRequest" } + - { name: "FetchRequest" } + - { name: "OpenConnectionRequest" } + - { name: "PrepareAndExecuteRequest" } + - { name: "PrepareRequest" } + - { name: "RollbackRequest" } + - { name: "SchemasRequest" } + - { name: "SyncResultsRequest" } + - { name: "TableTypesRequest" } + - { name: "TablesRequest" } + - { name: "TypeInfoRequest" } +miscellaneous: + - { name: "AvaticaParameter" } + - { name: "AvaticaSeverity" } + - { name: "AvaticaType" } + - { name: "ColumnMetaData" } + - { name: "ConnectionProperties" } + - { name: "CursorFactory" } + - { name: "DatabaseProperty" } + - { name: "Frame" } + - { name: "QueryState" } + - { name: "Rep" } + - { name: "RpcMetadata" } + - { name: "Signature" } + - { name: "StateType" } + - { name: "StatementHandle" } + - { name: "StatementType" } + - { name: "Style" } + - { name: "TypedValue" } +responses: + - { name: "CloseConnectionResponse" } + - { name: "CloseStatementResponse" } + - { name: "CommitResponse" } + - { name: "ConnectionSyncResponse" } + - { name: "CreateStatementResponse" } + - { name: "DatabasePropertyResponse" } + - { name: "ErrorResponse" } + - { name: "ExecuteResponse" } + - { name: "FetchResponse" } + - { name: "OpenConnectionResponse" } + - { name: "PrepareResponse" } + - { name: "ResultSetResponse" } + - { name: "RollbackResponse" } + - { name: "SyncResultsResponse" } +--- + +<!-- +{% comment %} +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to you under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +{% endcomment %} +--> + +As Avatica uses JSON to serialize messages sent over an HTTP transport, +the RPC layer is agnostic of the language used by a client. While the Avatica +server is written in Java, this enables clients to interact with the server +using any language instead of being limited to Java. + +A specification of the JSON request and response objects are documented +below. Programmatic bindings for these JSON objects are only available +in Java. For support outside of Java, see the Protocol Buffer +[bindings]({{ site.baseurl }}/docs/avatica_protobuf_reference.html) + +## Index + +### Requests +<ul> + {% for item in page.requests %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} +</ul> + +### Responses +<ul> + {% for item in page.responses %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} +</ul> + +### Miscellaneous +<ul> + {% for item in page.miscellaneous %}<li><a href="#{{ item.name | downcase }}">{{ item.name }}</a></li>{% endfor %} +</ul> + + +## Requests + +The collection of all JSON objects accepted as requests to Avatica. All Requests include a `request` attribute +which uniquely identifies the concrete Request from all other Requests. + +### CatalogsRequest + +This request is used to fetch the available catalog names in the database. + +{% highlight json %} +{ + "request": "getCatalogs", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to use. + +### CloseConnectionRequest + +This request is used to close the Connection object in the Avatica server identified by the given IDs. + +{% highlight json %} +{ + "request": "closeConnection", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to close. + +### CloseStatementRequest + +This request is used to close the Statement object in the Avatica server identified by the given IDs. + +{% highlight json %} +{ + "request": "closeStatement", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345 +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to which the statement belongs. + +`statementId` (required integer) The identifier of the statement to close. + +### ColumnsRequest + +This request is used to fetch columns in the database given some optional filtering criteria. + +{% highlight json %} +{ + "request": "getColumns", + "connectionId": "000000-0000-0000-00000000", + "catalog": "catalog", + "schemaPattern": "schema_pattern.*", + "tableNamePattern": "table_pattern.*", + "columnNamePattern": "column_pattern.*" +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection on which to fetch the columns. + +`catalog` (optional string) The name of a catalog to limit returned columns. + +`schemaPattern` (optional string) A Java Pattern against schemas to limit returned columns. + +`tableNamePattern` (optional string) A Java Pattern against table names to limit returned columns. + +`columnNamePattern` (optional string) A Java Pattern against column names to limit returned columns. + +### CommitRequest + +This request is used to issue a `commit` on the Connection in the Avatica server identified by the given ID. + +{% highlight json %} +{ + "request": "commit", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection on which to invoke commit. + +### ConnectionSyncRequest + +This request is used to ensure that the client and server have a consistent view of the database properties. + +{% highlight json %} +{ + "request": "connectionSync", + "connectionId": "000000-0000-0000-00000000", + "connProps": ConnectionProperties +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to synchronize. + +`connProps` (optional nested object) A <a href="#connectionproperties">ConnectionProperties</a> object to synchronize between the client and server. + +### CreateStatementRequest + +This request is used to create a new Statement in the Avatica server. + +{% highlight json %} +{ + "request": "createStatement", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to use in creating a statement. + +### DatabasePropertyRequest + +This request is used to fetch all <a href="#databaseproperty">database properties</a>. + +{% highlight json %} +{ + "request": "databaseProperties", +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to use when fetching the database properties. + +### ExecuteRequest + +This request is used to execute a PreparedStatement, optionally with values to bind to the parameters in the Statement. + +{% highlight json %} +{ + "request": "execute", + "statementHandle": StatementHandle, + "parameterValues": [TypedValue, TypedValue, ... ], + "maxRowCount": 100 +} +{% endhighlight %} + +`statementHandle` (required object) A <a href="#statementhandle">StatementHandle</a> object. + +`parameterValues` (optional array of nested objects) The <a href="#typedvalue">TypedValue</a> for each parameter on the prepared statement. + +`maxRowCount` (required long) The maximum number of rows returned in the response. + +### FetchRequest + +This request is used to fetch a batch of rows from a Statement previously created. + +{% highlight json %} +{ + "request": "fetch", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345, + "offset": 0, + "fetchMaxRowCount": 100 +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to use. + +`statementId` (required integer) The identifier of the statement created using the above connection. + +`offset` (required integer) The positional offset into a result set to fetch. + +`fetchMatchRowCount` (required integer) The maximum number of rows to return in the response to this request. + +### OpenConnectionRequest + +This request is used to open a new Connection in the Avatica server. + +{% highlight json %} +{ + "request": "openConnection", + "connectionId": "000000-0000-0000-00000000", + "info": {"key":"value", ...} +} +{% endhighlight %} + +`connectionId` (required string) The identifier of the connection to open in the server. + +`info` (optional string-to-string map) A Map containing properties to include when creating the Connection. + +### PrepareAndExecuteRequest + +This request is used as a short-hand for create a Statement and fetching the first batch of results in a single call without any parameter substitution. + +{% highlight json %} +{ + "request": "prepareAndExecute", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345, + "sql": "SELECT * FROM table", + "maxRowCount": 100, +} +{% endhighlight %} + +`connectionId` (required string) The identifier for the connection to use. + +`statementId` (required integer) The identifier for the statement created by the above connection to use. + +`sql` (required string) A SQL statement + +`maxRowCount` (required long) The maximum number of rows returned in the response. + +### PrepareRequest + +This request is used to create create a new Statement with the given query in the Avatica server. + +{% highlight json %} +{ + "request": "prepare", + "connectionId": "000000-0000-0000-00000000", + "sql": "SELECT * FROM table", + "maxRowCount": 100, +} +{% endhighlight %} + +`connectionId` (required string) The identifier for the connection to use. + +`sql` (required string) A SQL statement + +`maxRowCount` (required long) The maximum number of rows returned in the response. + +### SyncResultsRequest + +This request is used to reset a ResultSet's iterator to a specific offset in the Avatica server. + +{% highlight json %} +{ + "request": "syncResults", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345, + "state": QueryState, + "offset": 200 +} +{% endhighlight %} + +`connectionId` (required string) The identifier for the connection to use. + +`statementId` (required integer) The identifier for the statement to use. + +`state` (required object) The <a href="#querystate">QueryState</a> object. + +`offset` (required long) The offset into the ResultSet to seek to. + +### RollbackRequest + +This request is used to issue a `rollback` on the Connection in the Avatica server identified by the given ID. + +{% highlight json %} +{ + "request": "rollback", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` (required string) The identifier for the connection on which to invoke rollback. + +### SchemasRequest + +This request is used to fetch the schemas matching the provided criteria in the database. + +{% highlight json %} +{ + "request": "getSchemas", + "connectionId": "000000-0000-0000-00000000", + "catalog": "name", + "schemaPattern": "pattern.*" +} +{% endhighlight %} + +`connection_id` The identifier for the connection to fetch schemas from. + +`catalog` (required string) The name of the catalog to fetch the schema from. + +`schemaPattern` (required string) A Java pattern of schemas to fetch. + +### TableTypesRequest + +This request is used to fetch the table types available in this database. + +{% highlight json %} +{ + "request": "getTableTypes", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` The identifier of the connection to fetch the table types from. + +### TablesRequest + +This request is used to fetch the tables available in this database filtered by the provided criteria. + +{% highlight json %} +{ + "request": "getTables", + "connectionId": "000000-0000-0000-00000000", + "catalog": "catalog_name", + "schemaPattern": "schema_pattern.*", + "tableNamePattern": "table_name_pattern.*", + "typeList": [ "TABLE", "VIEW", ... ] +} +{% endhighlight %} + +`catalog` (optional string) The name of a catalog to restrict fetched tables. + +`connectionId` The identifier of the connection to fetch the tables from. + +`schemaPattern` (optional string) A Java Pattern representing schemas to include in fetched tables. + +`tableNamePattern` (optional string) A Java Pattern representing table names to include in fetched tables. + +`typeList` (optional array of string) A list of table types used to restrict fetched tables. + +### TypeInfoRequest + +This request is used to fetch the types available in this database. + +{% highlight json %} +{ + "request": "getTypeInfo", + "connectionId": "000000-0000-0000-00000000" +} +{% endhighlight %} + +`connectionId` The identifier of the connection to fetch the types from. + +## Responses + +The collection of all JSON objects returned as responses from Avatica. All Responses include a `response` attribute +which uniquely identifies the concrete Response from all other Responses. + +### CloseConnectionResponse + +A response to the <a href="#closeconnectionrequest">CloseConnectionRequest</a>. + +{% highlight json %} +{ + "response": "closeConnection", + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### CloseStatementResponse + +A response to the <a href="#closestatementrequest">CloseStatementRequest</a>. + +{% highlight json %} +{ + "response": "closeStatement", + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### CommitResponse + +A response to the <a href="#commitrequest">CommitRequest</a>. + +{% highlight json %} +{ + "response": "commit" +} +{% endhighlight %} + +There are no extra attributes on this Response. + +### ConnectionSyncResponse + +A response to the <a href="#connectionsyncrequest">ConnectionSyncRequest</a>. Properties included in the +response are those of the Connection in the Avatica server. + +{% highlight json %} +{ + "response": "connectionSync", + "connProps": ConnectionProperties, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`connProps` The <a href="#connectionproperties">ConnectionProperties</a> that were synchronized. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### CreateStatementResponse + +A response to the <a href="#createstatementrequest">CreateStatementRequest</a>. The ID of the statement +that was created is included in the response. Clients will use this `statementId` in subsequent calls. + +{% highlight json %} +{ + "response": "createStatement", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`connectionId` The identifier for the connection used to create the statement. + +`statementId` The identifier for the created statement. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### DatabasePropertyResponse + +A response to the <a href="#databasepropertyrequest">DatabasePropertyRequest</a>. See <a hred="#databaseproperty">DatabaseProperty</a> +for information on the available property keys. + +{% highlight json %} +{ + "response": "databaseProperties", + "map": { DatabaseProperty: Object, DatabaseProperty: Object, ... }, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`map` A map of <a href="#databaseproperty">DatabaseProperty</a> to value of that property. The value may be some +primitive type or an array of primitive types. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### ErrorResponse + +A response when an error was caught executing a request. Any request may return this response. + +{% highlight json %} +{ + "response": "error", + "exceptions": [ "stacktrace", "stacktrace", ... ], + "errorMessage": "The error message", + "errorCode": 42, + "sqlState": "ABC12", + "severity": AvaticaSeverity, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`exceptions` A list of stringified Java StackTraces. + +`errorMessage` A human-readable error message. + +`errorCode` A numeric code for this error. + +`sqlState` A five character alphanumeric code for this error. + +`severity` An <a href="#avaticaseverity">AvaticaSeverity</a> object which denotes how critical the error is. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### ExecuteResponse + +A response to the <a href="#executerequest">ExecuteRequest</a> which contains the results for a metadata query. + +{% highlight json %} +{ + "response": "executeResults", + "resultSets": [ ResultSetResponse, ResultSetResponse, ... ], + "missingStatement": false, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`resultSets` An array of <a href="#resultsetresponse">ResultSetResponse</a>s. + +`missingStatement` A boolean which denotes if the request failed due to a missing Statement. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### FetchResponse + +A response to the <a href="#fetchrequest">FetchRequest</a> which contains the request for the query. + +{% highlight json %} +{ + "response": "fetch", + "frame": Frame, + "missingStatement": false, + "missingResults": false, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`frame` A <a href="#frame">Frame</a> containing the results of the fetch. + +`missingStatement` A boolean which denotes if the request failed due to a missing Statement. + +`missingResults` A boolean which denotes if the request failed due to a missing ResultSet. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### OpenConnectionResponse + +A response to the <a href="#openconnectionrequest">OpenConnectionRequest</a>. The ID for the connection that +the client should use in subsequent calls was provided by the client in the request. + +{% highlight json %} +{ + "response": "openConnection", + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### PrepareResponse + +A response to the <a href="#preparerequest">PrepareRequest</a>. This response includes a <a href="#statementhandle">StatementHandle</a> +which clients must use to fetch the results from the Statement. + +{% highlight json %} +{ + "response": "prepare", + "statement": StatementHandle, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`statement` A <a href="#statementhandle">StatementHandle</a> object. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### ResultSetResponse + +A response which contains the results and type details from a query. + +{% highlight json %} +{ + "response": "resultSet", + "connectionId": "000000-0000-0000-00000000", + "statementId": 12345, + "ownStatement": true, + "signature": Signature, + "firstFrame": Frame, + "updateCount": 10, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`connectionId` The identifier for the connection used to generate this response. + +`statementId` The identifier for the statement used to generate this response. + +`ownStatement` Whether the result set has its own dedicated statement. If true, the server must automatically close the +statement when the result set is closed. This is used for JDBC metadata result sets, for instance. + +`signature` A non-optional nested object <a href="#signature">Signature</a> + +`firstFrame` A optional nested object <a href="#frame">Frame</a> + +`updateCount` A number which is always `-1` for normal result sets. Any other value denotes a "dummy" result set +that only contains this count and no additional data. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +### RollbackResponse + +A response to the <a href="#rollbackrequest">RollBackRequest</a>. + +{% highlight json %} +{ + "response": "rollback" +} +{% endhighlight %} + +There are no extra attributes on this Response. + +### SyncResultsResponse + +A response to the <a href="#syncresultsrequest">SyncResultsRequest</a>. When `moreResults` is true, a <a href="#fetchrequest">FetchRequest</a> +should be issued to get the next batch of records. When `missingStatement` is true, the statement must be re-created using <a href="#preparerequest">PrepareRequest</a> +or the appropriate Request for a DDL request (e.g. <a href="#catalogsrequest">CatalogsRequest</a> or <a href="#schemasrequest">SchemasRequest</a>). + +{% highlight json %} +{ + "response": "syncResults", + "moreResults": true, + "missingStatement": false, + "rpcMetadata": RpcMetadata +} +{% endhighlight %} + +`moreResults` A boolean which denotes if results exist for the ResultSet being "synced" per the request. + +`missingStatement` A boolean which denotes if the statement for the ResultSet still exists. + +`rpcMetadata` <a href="#rpcmetadata">Server metadata</a> about this call. + +## Miscellaneous + +### AvaticaParameter + +This object describes the "simple", or scalar, JDBC type representation of a column in a result. This does not include +complex types such as arrays. + +{% highlight json %} +{ + "signed": true, + "precision": 10, + "scale": 2, + "parameterType": 8, + "typeName": "integer", + "className": "java.lang.Integer", + "name": "number" +} +{% endhighlight %} + +`signed` A boolean denoting whether the column is a signed numeric. + +`precision` The maximum numeric precision supported by this column. + +`scale` The maximum numeric scale supported by this column. + +`parameterType` An integer corresponding to the JDBC Types class denoting the column's type. + +`typeName` The JDBC type name for this column. + +`className` The Java class backing the JDBC type for this column. + +`name` The name of the column. + +### AvaticaSeverity + +This enumeration describes the various levels of concern for an error in the Avatica server. + +One of: + +* `UNKNOWN` +* `FATAL` +* `ERROR` +* `WARNING` + +### AvaticaType + +This object describes a simple or complex type for a column. Complex types will contain +additional information in the `component` or `columns` attribute which describe the nested +types of the complex parent type. + +{% highlight json %} +{ + "type": "scalar", + "id": "identifier", + "name": "column", + "rep": Rep, + "columns": [ ColumnMetaData, ColumnMetaData, ... ], + "component": AvaticaType +} +{% endhighlight %} + +`type` One of: `scalar`, `array`, `struct`. + +`id` A numeric value corresponding to the type of the object per the JDBC Types class. + +`name` The readable name of the JDBC type. + +`rep` A nested <a href="#rep">Rep</a> object used by Avatica to hold additional type information. + +`columns` For `STRUCT` types, a list of the columns contained in that `STRUCT`. + +`component` For `ARRAY` types, the type of the elements contained in that `ARRAY`. + +### ColumnMetaData + +This object represents the JDBC ResultSetMetaData for a column. + +{% highlight json %} +{ + "ordinal": 0, + "autoIncrement": true, + "caseSensitive": true, + "searchable": false, + "currency": false, + "nullable": 0, + "signed": true, + "displaySize": 20, + "label": "Description", + "columnName": "col1", + "schemaName": "schema", + "precision": 10, + "scale": 2, + "tableName": "table", + "catalogName": "catalog", + "type": AvaticaType, + "readOnly": false, + "writable": true, + "definitelyWritable": true, + "columnClassName": "java.lang.String" +} +{% endhighlight %} + +`ordinal` A positional offset number. + +`autoIncrement` A boolean denoting whether the column is automatically incremented. + +`caseSensitive` A boolean denoting whether the column is case sensitive. + +`searchable` A boolean denoting whether this column supports all WHERE search clauses. + +`currency` A boolean denoting whether this column represents currency. + +`nullable` A number denoting whether this column supports null values. + +* 0 = No null values are allowed +* 1 = Null values are allowed +* 2 = It is unknown if null values are allowed + +`signed` A boolean denoting whether the column is a signed numeric. + +`displaySize` The character width of the column. + +`label` A description for this column. + +`columnName` The name of the column. + +`schemaName` The schema to which this column belongs. + +`precision` The maximum numeric precision supported by this column. + +`scale` The maximum numeric scale supported by this column. + +`tableName` The name of the table to which this column belongs. + +`catalogName` The name of the catalog to which this column belongs. + +`type` A nested <a href="#avaticatype">AvaticaType</a> representing the type of the column. + +`readOnly` A boolean denoting whether the column is read-only. + +`writable` A boolean denoting whether the column is possible to be updated. + +`definitelyWritable` A boolean denoting whether the column definitely can be updated. + +`columnClassName` The name of the Java class backing the column's type. + +### ConnectionProperties + +This object represents the properties for a given JDBC Connection. + +{% highlight json %} +{ + "connProps": "connPropsImpl", + "autoCommit": true, + "readOnly": true, + "transactionIsolation": 0, + "catalog": "catalog", + "schema": "schema" +} +{% endhighlight %} + +`autoCommit` (optional boolean) A boolean denoting if autoCommit is enabled for transactions. + +`readOnly` (optional boolean) A boolean denoting if a JDBC connection is read-only. + +`transactionIsolation` (optional integer) An integer which denotes the level of transactions isolation per the JDBC +specification. This value is analogous to the values defined in `java.sql.Connection`. + +* 0 = Transactions are not supported +* 1 = Dirty reads, non-repeatable reads and phantom reads may occur. +* 2 = Dirty reads are prevented, but non-repeatable reads and phantom reads may occur. +* 4 = Dirty reads and non-repeatable reads are prevented, but phantom reads may occur. +* 8 = Dirty reads, non-repeatable reads, and phantom reads are all prevented. + +`catalog` (optional string) The name of the catalog to include when fetching connection properties. + +`schema` (optional string) The name of the schema to include when fetching connection properties. + +### CursorFactory + +This object represents the information required to cast untyped objects into the necessary type for some results. + +{% highlight json %} +{ + "style": Style, + "clazz": "java.lang.String", + "fieldNames": [ "column1", "column2", ... ] +} +{% endhighlight %} + +`style` A string denoting the <a href="#style">Style</a> of the contained objects. + +### DatabaseProperty + +This object represents the exposed database properties for a Connection through the Avatica server. + +One of: + +* `GET_STRING_FUNCTIONS` +* `GET_NUMERIC_FUNCTIONS` +* `GET_SYSTEM_FUNCTIONS` +* `GET_TIME_DATE_FUNCTIONS` +* `GET_S_Q_L_KEYWORDS` +* `GET_DEFAULT_TRANSACTION_ISOLATION` + +### Frame + +This object represents a batch of results, tracking the offset into the results and whether more results still exist +to be fetched in the Avatica server. + +{% highlight json %} +{ + "offset": 100, + "done": true, + "rows": [ [ val1, val2, ... ], ... ] +} +{% endhighlight %} + +`offset` The starting position of these `rows` in the encompassing result set. + +`done` A boolean denoting whether more results exist for this result set. + +`rows` An array of arrays corresponding to the rows and columns for the result set. + +### QueryState + +This object represents the way a ResultSet was created in the Avatica server. A ResultSet could be created by a user-provided +SQL or by a DatabaseMetaData operation with arguments on that operation. + +{% highlight json %} +{ + "type": StateType, + "sql": "SELECT * FROM table", + "metaDataOperation": MetaDataOperation, + "operationArgs": ["arg0", "arg1", ... ] +} +{% endhighlight %} + +`type` A <a href="#statetype">StateType</a> object denoting what type of operation backs the ResultSet for this query. + +`sql` The SQL statement which created the ResultSet for this query. Required if the `type` is `SQL`. + +`metaDataOperation` The DML operation which created the ResultSet for this query. Required if the `type` is `METADATA`. + +`operationArgs` The arguments to the invoked DML operation. Required if the `type` is `METADATA`. + +### Rep + +This enumeration represents the concrete Java type for some value. + +One of: + +* `PRIMITIVE_BOOLEAN` +* `PRIMITIVE_BYTE` +* `PRIMITIVE_CHAR` +* `PRIMITIVE_SHORT` +* `PRIMITIVE_INT` +* `PRIMITIVE_LONG` +* `PRIMITIVE_FLOAT` +* `PRIMITIVE_DOUBLE` +* `BOOLEAN` +* `BYTE` +* `CHARACTER` +* `SHORT` +* `INTEGER` +* `LONG` +* `FLOAT` +* `DOUBLE` +* `JAVA_SQL_TIME` +* `JAVA_SQL_TIMESTAMP` +* `JAVA_SQL_DATE` +* `JAVA_UTIL_DATE` +* `BYTE_STRING` +* `STRING` +* `NUMBER` +* `OBJECT` + +### RpcMetadata + +This object contains assorted per-call/contextual metadata returned by the Avatica server. + +{% highlight json %} +{ + "serverAddress": "localhost:8765" +} +{% endhighlight %} + +`serverAddress` The `host:port` of the server which created this object. + +### Signature + +This object represents the result of preparing a Statement in the Avatica server. + +{% highlight json %} +{ + "columns": [ ColumnMetaData, ColumnMetaData, ... ], + "sql": "SELECT * FROM table", + "parameters": [ AvaticaParameter, AvaticaParameter, ... ], + "cursorFactory": CursorFactory, + "statementType": StatementType +} +{% endhighlight %} + +`columns` An array of <a href="#columnmetadata">ColumnMetaData</a> objects denoting the schema of the result set. + +`sql` The SQL executed. + +`parameters` An array of <a href="#avaticaparameter">AvaticaParameter</a> objects denoting type-specific details. + +`cursorFactory` An <a href="#cursorfactory">CursorFactory</a> object representing the Java representation of the frame. + +`statementType` An <a href="#statementtype">StatementType</a> object representing the type of Statement. + +### StateType + +This enumeration denotes whether user-provided SQL or a DatabaseMetaData operation was used to create some ResultSet. + +One of: + +* `SQL` +* `METADATA` + +### StatementHandle + +This object encapsulates all of the information of a Statement created in the Avatica server. + +{% highlight json %} +{ + "connectionId": "000000-0000-0000-00000000", + "id": 12345, + "signature": Signature +} +{% endhighlight %} + +`connectionId` The identifier of the connection to which this statement belongs. + +`id` The identifier of the statement. + +`signature` A <a href="#signature">Signature</a> object for the statement. + +### StatementType + +This enumeration represents what kind the Statement is. + +One of: + +* `SELECT` +* `INSERT` +* `UPDATE` +* `DELETE` +* `UPSERT` +* `MERGE` +* `OTHER_DML` +* `CREATE` +* `DROP` +* `ALTER` +* `OTHER_DDL` +* `CALL` + +### Style + +This enumeration represents the generic "class" of type for a value. + +One of: + +* `OBJECT` +* `RECORD` +* `RECORD_PROJECTION` +* `ARRAY` +* `LIST` +* `MAP` + +### TypedValue + +This object encapsulates the type and value for a column in a row. + +{% highlight json %} +{ + "type": "type_name", + "value": object +} +{% endhighlight %} + +`type` A name referring to the type of the object stored in `value`. + +`value` A JSON representation of a JDBC type. http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_docs/lattice.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/lattice.md b/avatica/site/_docs/lattice.md deleted file mode 100644 index 918261c..0000000 --- a/avatica/site/_docs/lattice.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -layout: docs -title: Lattices -permalink: /docs/lattice.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 %} ---> - -A lattice is a framework for creating and populating materialized views, -and for recognizing that a materialized view can be used to solve a -particular query. - -A lattice represents a star (or snowflake) schema, not a general -schema. In particular, all relationships must be many-to-one, heading -from a fact table at the center of the star. - -The name derives from the mathematics: a -<a href="http://en.wikipedia.org/wiki/Lattice_(order)">lattice</a> -is a -<a href="http://en.wikipedia.org/wiki/Partially_ordered_set";>partially -ordered set</a> where any two elements have a unique greatest lower -bound and least upper bound. - -[<a href="#ref-hru96">HRU96</a>] observed that the set of possible -materializations of a data cube forms a lattice, and presented an -algorithm to choose a good set of materializations. Calcite's -recommendation algorithm is derived from this. - -The lattice definition uses a SQL statement to represent the star. SQL -is a useful short-hand to represent several tables joined together, -and assigning aliases to the column names (it more convenient than -inventing a new language to represent relationships, join conditions -and cardinalities). - -Unlike regular SQL, order is important. If you put A before B in the -FROM clause, and make a join between A and B, you are saying that -there is a many-to-one foreign key relationship from A to B. (E.g. in -the example lattice, the Sales fact table occurs before the Time -dimension table, and before the Product dimension table. The Product -dimension table occurs before the ProductClass outer dimension table, -further down an arm of a snowflake.) - -A lattice implies constraints. In the A to B relationship, there is a -foreign key on A (i.e. every value of A's foreign key has a -corresponding value in B's key), and a unique key on B (i.e. no key -value occurs more than once). These constraints are really important, -because it allows the planner to remove joins to tables whose columns -are not being used, and know that the query results will not change. - -Calcite does not check these constraints. If they are violated, -Calcite will return wrong results. - -A lattice is a big, virtual join view. It is not materialized (it -would be several times larger than the star schema, because of -denormalization) and you probably wouldn't want to query it (far too -many columns). So what is it useful for? As we said above, (a) the -lattice declares some very useful primary and foreign key constraints, -(b) it helps the query planner map user queries onto -filter-join-aggregate materialized views (the most useful kind of -materialized view for DW queries), (c) gives Calcite a framework -within which to gather stats about data volumes and user queries, (d) -allows Calcite to automatically design and populate materialized -views. - -Most star schema models force you to choose whether a column is a -dimension or a measure. In a lattice, every column is a dimension -column. (That is, it can become one of the columns in the GROUP BY clause -to query the star schema at a particular dimensionality). Any column -can also be used in a measure; you define measures by giving the -column and an aggregate function. - -If "unit_sales" tends to be used much more often as a measure rather -than a dimension, that's fine. Calcite's algorithm should notice that -it is rarely aggregated, and not be inclined to create tiles that -aggregate on it. (By "should" I mean "could and one day will". The -algorithm does not currently take query history into account when -designing tiles.) - -But someone might want to know whether orders with fewer than 5 items -were more or less profitable than orders with more than 100. All of a -sudden, "unit_sales" has become a dimension. If there's virtually zero -cost to declaring a column a dimension column, I figured let's make -them all dimension columns. - -The model allows for a particular table to be used more than once, -with a different table alias. You could use this to model say -OrderDate and ShipDate, with two uses to the Time dimension table. - -Most SQL systems require that the column names in a view are unique. -This is hard to achieve in a lattice, because you often include -primary and foreign key columns in a join. So Calcite lets you refer -to columns in two ways. If the column is unique, you can use its name, -["unit_sales"]. Whether or not it is unique in the lattice, it will be -unique in its table, so you can use it qualified by its table alias. -Examples: - -* ["sales", "unit_sales"] -* ["ship_date", "time_id"] -* ["order_date", "time_id"] - -A "tile" is a materialized table in a lattice, with a particular -dimensionality. (What Kylin calls a "cuboid".) The "tiles" attribute -of the <a href="{{ site.baseurl }}/docs/model.html#lattice">lattice JSON element</a> -defines an initial set of tiles to materialize. - -If you run the algorithm, you can omit the tiles attribute. Calcite -will choose an initial set. If you include the tiles attribute, the -algorithm will start with that list and then start finding other tiles -that are complementary (i.e. "fill in the gaps" left by the initial -tiles). - -### References - -<ul> -<li>[<a name="ref-hru96">HRU96</a>] V. Harinarayan, A. Rajaraman and J. Ullman. - <a href="http://web.eecs.umich.edu/~jag/eecs584/papers/implementing_data_cube.pdf";>Implementing - data cubes efficiently</a>. - In <i>Proc. ACM SIGMOD Conf.</i>, Montreal, 1996.</li> -</ul> - http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_docs/model.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/model.md b/avatica/site/_docs/model.md deleted file mode 100644 index 2675453..0000000 --- a/avatica/site/_docs/model.md +++ /dev/null @@ -1,517 +0,0 @@ ---- -layout: docs -title: JSON models -permalink: /docs/model.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 %} ---> - -Calcite models can be represented as JSON files. -This page describes the structure of those files. - -Models can also be built programmatically using the `Schema` SPI. - -## Elements - -### Root - -{% highlight json %} -{ - version: '1.0', - defaultSchema: 'mongo', - schemas: [ Schema... ] -} -{% endhighlight %} - -`version` (required string) must have value `1.0`. - -`defaultSchema` (optional string). If specified, it is -the name (case-sensitive) of a schema defined in this model, and will -become the default schema for connections to Calcite that use this model. - -`schemas` (optional list of <a href="#schema">Schema</a> elements). - -### Schema - -Occurs within `root.schemas`. - -{% highlight json %} -{ - name: 'foodmart', - path: ['lib'], - cache: true, - materializations: [ Materialization... ] -} -{% endhighlight %} - -`name` (required string) is the name of the schema. - -`type` (optional string, default `map`) indicates sub-type. Values are: - -* `map` for <a href="#map-schema">Map Schema</a> -* `custom` for <a href="#custom-schema">Custom Schema</a> -* `jdbc` for <a href="#jdbc-schema">JDBC Schema</a> - -`path` (optional list) is the SQL path that is used to -resolve functions used in this schema. If specified it must be a list, -and each element of the list must be either a string or a list of -strings. For example, - -{% highlight json %} - path: [ ['usr', 'lib'], 'lib' ] -{% endhighlight %} - -declares a path with two elements: the schema '/usr/lib' and the -schema '/lib'. Most schemas are at the top level, and for these you can use a -string. - -`materializations` (optional list of -<a href="#materialization">Materialization</a>) defines the tables -in this schema that are materializations of queries. - -`cache` (optional boolean, default true) tells Calcite whether to -cache metadata (tables, functions and sub-schemas) generated -by this schema. - -* If `false`, Calcite will go back to the schema each time it needs - metadata, for example, each time it needs a list of tables in order to - validate a query against the schema. - -* If `true`, Calcite will cache the metadata the first time it reads - it. This can lead to better performance, especially if name-matching is - case-insensitive. - -However, it also leads to the problem of cache staleness. -A particular schema implementation can override the -`Schema.contentsHaveChangedSince` method to tell Calcite -when it should consider its cache to be out of date. - -Tables, functions and sub-schemas explicitly created in a schema are -not affected by this caching mechanism. They always appear in the schema -immediately, and are never flushed. - -### Map Schema - -Like base class <a href="#schema">Schema</a>, occurs within `root.schemas`. - -{% highlight json %} -{ - name: 'foodmart', - type: 'map', - tables: [ Table... ], - functions: [ Function... ] -} -{% endhighlight %} - -`name`, `type`, `path`, `cache`, `materializations` inherited from -<a href="#schema">Schema</a>. - -`tables` (optional list of <a href="#table">Table</a> elements) -defines the tables in this schema. - -`functions` (optional list of <a href="#function">Function</a> elements) -defines the functions in this schema. - -### Custom Schema - -Like base class <a href="#schema">Schema</a>, occurs within `root.schemas`. - -{% highlight json %} -{ - name: 'mongo', - type: 'custom', - factory: 'org.apache.calcite.adapter.mongodb.MongoSchemaFactory', - operand: { - host: 'localhost', - database: 'test' - } -} -{% endhighlight %} - -`name`, `type`, `path`, `cache`, `materializations` inherited from -<a href="#schema">Schema</a>. - -`factory` (required string) is the name of the factory class for this -schema. Must implement interface -[org.apache.calcite.schema.SchemaFactory]({{ site.apiRoot }}/org/apache/calcite/schema/SchemaFactory.html) -and have a public default constructor. - -`operand` (optional map) contains attributes to be passed to the -factory. - -### JDBC Schema - -Like base class <a href="#schema">Schema</a>, occurs within `root.schemas`. - -{% highlight json %} -{ - name: 'foodmart', - type: 'jdbc', - jdbcDriver: TODO, - jdbcUrl: TODO, - jdbcUser: TODO, - jdbcPassword: TODO, - jdbcCatalog: TODO, - jdbcSchema: TODO -} -{% endhighlight %} - -`name`, `type`, `path`, `cache`, `materializations` inherited from -<a href="#schema">Schema</a>. - -`jdbcDriver` (optional string) is the name of the JDBC driver class. If not -specified, uses whichever class the JDBC DriverManager chooses. - -`jdbcUrl` (optional string) is the JDBC connect string, for example -"jdbc:mysql://localhost/foodmart". - -`jdbcUser` (optional string) is the JDBC user name. - -`jdbcPassword` (optional string) is the JDBC password. - -`jdbcCatalog` (optional string) is the name of the initial catalog in the JDBC -data source. - -`jdbcSchema` (optional string) is the name of the initial schema in the JDBC -data source. - -### Materialization - -Occurs within `root.schemas.materializations`. - -{% highlight json %} -{ - view: 'V', - table: 'T', - sql: 'select deptno, count(*) as c, sum(sal) as s from emp group by deptno' -} -{% endhighlight %} - -`view` (optional string) is the name of the view; null means that the table -already exists and is populated with the correct data. - -`table` (required string) is the name of the table that materializes the data in -the query. If `view` is not null, the table might not exist, and if it does not, -Calcite will create and populate an in-memory table. - -`sql` (optional string, or list of strings that will be concatenated as a - multi-line string) is the SQL definition of the materialization. - -### Table - -Occurs within `root.schemas.tables`. - -{% highlight json %} -{ - name: 'sales_fact', - columns: [ Column... ] -} -{% endhighlight %} - -`name` (required string) is the name of this table. Must be unique within the schema. - -`type` (optional string, default `custom`) indicates sub-type. Values are: - -* `custom` for <a href="#custom-table">Custom Table</a> -* `view` for <a href="#view">View</a> - -`columns` (list of <a href="#column">Column</a> elements, required for -some kinds of table, optional for others such as View) - -### View - -Like base class <a href="#table">Table</a>, occurs within `root.schemas.tables`. - -{% highlight json %} -{ - name: 'female_emps', - type: 'view', - sql: "select * from emps where gender = 'F'", - modifiable: true -} -{% endhighlight %} - -`name`, `type`, `columns` inherited from <a href="#table">Table</a>. - -`sql` (required string, or list of strings that will be concatenated as a - multi-line string) is the SQL definition of the view. - -`path` (optional list) is the SQL path to resolve the query. If not -specified, defaults to the current schema. - -`modifiable` (optional boolean) is whether the view is modifiable. -If null or not specified, Calcite deduces whether the view is modifiable. - -A view is modifiable if contains only SELECT, FROM, WHERE (no JOIN, aggregation -or sub-queries) and every column: - -* is specified once in the SELECT clause; or -* occurs in the WHERE clause with a `column = literal` predicate; or -* is nullable. - -The second clause allows Calcite to automatically provide the correct value for -hidden columns. It is useful in multi-tenant environments, where the `tenantId` -column is hidden, mandatory (NOT NULL), and has a constant value for a -particular view. - -Errors regarding modifiable views: - -* If a view is marked `modifiable: true` and is not modifiable, Calcite throws - an error while reading the schema. -* If you submit an INSERT, UPDATE or UPSERT command to a non-modifiable view, - Calcite throws an error when validating the statement. -* If a DML statement creates a row that would not appear in the view - (for example, a row in `female_emps`, above, with `gender = 'M'`), - Calcite throws an error when executing the statement. - -### Custom Table - -Like base class <a href="#table">Table</a>, occurs within `root.schemas.tables`. - -{% highlight json %} -{ - name: 'female_emps', - type: 'custom', - factory: 'TODO', - operand: { - todo: 'TODO' - } -} -{% endhighlight %} - -`name`, `type`, `columns` inherited from <a href="#table">Table</a>. - -`factory` (required string) is the name of the factory class for this -table. Must implement interface -[org.apache.calcite.schema.TableFactory]({{ site.apiRoot }}/org/apache/calcite/schema/TableFactory.html) -and have a public default constructor. - -`operand` (optional map) contains attributes to be passed to the -factory. - -### Stream - -Information about whether a table allows streaming. - -Occurs within `root.schemas.tables.stream`. - -{% highlight json %} -{ - stream: true, - history: false -} -{% endhighlight %} - -`stream` (optional; default true) is whether the table allows streaming. - -`history` (optional; default false) is whether the history of the stream is -available. - -### Column - -Occurs within `root.schemas.tables.columns`. - -{% highlight json %} -{ - name: 'empno' -} -{% endhighlight %} - -`name` (required string) is the name of this column. - -### Function - -Occurs within `root.schemas.functions`. - -{% highlight json %} -{ - name: 'MY_PLUS', - className: 'com.example.functions.MyPlusFunction', - methodName: 'apply', - path: [] -} -{% endhighlight %} - -`name` (required string) is the name of this function. - -`className` (required string) is the name of the class that implements this -function. - -`methodName` (optional string) is the name of the method that implements this -function. - -If `methodName` is specified, the method must exist (case-sensitive) and Calcite -will create a scalar function. The method may be static or non-static, but -if non-static, the class must have a public constructor with no parameters. - -If `methodName` is "*", Calcite creates a function for every method -in the class. - -If `methodName` is not specified, Calcite looks for a method called "eval", and -if found, creates a a table macro or scalar function. -It also looks for methods "init", "add", "merge", "result", and -if found, creates an aggregate function. - -`path` (optional list of string) is the path for resolving this function. - -### Lattice - -Occurs within `root.schemas.lattices`. - -{% highlight json %} -{ - name: 'star', - sql: [ - 'select 1 from "foodmart"."sales_fact_1997" as "s"', - 'join "foodmart"."product" as "p" using ("product_id")', - 'join "foodmart"."time_by_day" as "t" using ("time_id")', - 'join "foodmart"."product_class" as "pc" on "p"."product_class_id" = "pc"."product_class_id"' - ], - auto: false, - algorithm: true, - algorithmMaxMillis: 10000, - rowCountEstimate: 86837, - defaultMeasures: [ { - agg: 'count' - } ], - tiles: [ { - dimensions: [ 'the_year', ['t', 'quarter'] ], - measures: [ { - agg: 'sum', - args: 'unit_sales' - }, { - agg: 'sum', - args: 'store_sales' - }, { - agg: 'count' - } ] - } ] -} -{% endhighlight %} - -`name` (required string) is the name of this lattice. - -`sql` (required string, or list of strings that will be concatenated as a -multi-line string) is the SQL statement that defines the fact table, dimension -tables, and join paths for this lattice. - -`auto` (optional boolean, default true) is whether to materialize tiles on need -as queries are executed. - -`algorithm` (optional boolean, default false) is whether to use an optimization -algorithm to suggest and populate an initial set of tiles. - -`algorithmMaxMillis` (optional long, default -1, meaning no limit) is the -maximum number of milliseconds for which to run the algorithm. After this point, -takes the best result the algorithm has come up with so far. - -`rowCountEstimate` (optional double, default 1000.0) estimated number of rows in -the lattice - -`tiles` (optional list of <a href="#tile">Tile</a> elements) is a list of -materialized aggregates to create up front. - -`defaultMeasures` (optional list of <a href="#measure">Measure</a> elements) -is a list of measures that a tile should have by default. -Any tile defined in `tiles` can still define its own measures, including -measures not on this list. If not specified, the default list of measures is -just 'count(*)': - -{% highlight json %} -[ { name: 'count' } ] -{% endhighlight %} - -`statisticProvider` (optional name of a class that implements -[org.apache.calcite.materialize.LatticeStatisticProvider]({{ site.apiRoot }}/org/apache/calcite/materialize/LatticeStatisticProvider.html)) -provides estimates of the number of distinct values in each column. - -You can use a class name, or a class plus a static field. Example: - -{% highlight json %} - "statisticProvider": "org.apache.calcite.materialize.Lattices#CACHING_SQL_STATISTIC_PROVIDER" -{% endhighlight %} - -If not set, Calcite will generate and execute a SQL query to find the real -value, and cache the results. - -See also: <a href="{{ site.baseurl }}/docs/lattice.html">Lattices</a>. - -### Tile - -Occurs within `root.schemas.lattices.tiles`. - -{% highlight json %} -{ - dimensions: [ 'the_year', ['t', 'quarter'] ], - measures: [ { - agg: 'sum', - args: 'unit_sales' - }, { - agg: 'sum', - args: 'store_sales' - }, { - agg: 'count' - } ] -} -{% endhighlight %} - -`dimensions` (list of strings or string lists, required, but may be empty) -defines the dimensionality of this tile. -Each dimension is a column from the lattice, like a `GROUP BY` clause. -Each element can be either a string -(the unique label of the column within the lattice) -or a string list (a pair consisting of a table alias and a column name). - -`measures` (optional list of <a href="#measure">Measure</a> elements) is a list -of aggregate functions applied to arguments. If not specified, uses the -lattice's default measure list. - -### Measure - -Occurs within `root.schemas.lattices.defaultMeasures` -and `root.schemas.lattices.tiles.measures`. - -{% highlight json %} -{ - agg: 'sum', - args: [ 'unit_sales' ] -} -{% endhighlight %} - -`agg` is the name of an aggregate function (usually 'count', 'sum', 'min', -'max'). - -`args` (optional) is a column label (string), or list of zero or more column -labels - -Valid values are: - -* Not specified: no arguments -* null: no arguments -* Empty list: no arguments -* String: single argument, the name of a lattice column -* List: multiple arguments, each a column label - -Unlike lattice dimensions, measures can not be specified in qualified -format, {@code ["table", "column"]}. When you define a lattice, make sure -that each column you intend to use as a measure has a unique label within -the lattice (using "{@code AS label}" if necessary), and use that label -when you want to pass the column as a measure argument. - -<!-- End model.md -->
