calcite-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From els...@apache.org
Subject [55/59] calcite git commit: [CALCITE-1079] Split out an Avatica website, made to slot into the Calcite site at /avatica
Date Mon, 07 Mar 2016 18:28:33 GMT
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.
+![Avatica Architecture](https://raw.githubusercontent.com/julianhyde/share/master/slides/avatica-architecture.png)
 
-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 -->


Mime
View raw message