You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@calcite.apache.org by jh...@apache.org on 2015/09/03 00:16:09 UTC
[21/50] incubator-calcite git commit: Document JSON model,
making javadoc consistent with the model reference
Document JSON model, making javadoc consistent with the model reference
Project: http://git-wip-us.apache.org/repos/asf/incubator-calcite/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-calcite/commit/629a56e5
Tree: http://git-wip-us.apache.org/repos/asf/incubator-calcite/tree/629a56e5
Diff: http://git-wip-us.apache.org/repos/asf/incubator-calcite/diff/629a56e5
Branch: refs/heads/branch-release
Commit: 629a56e5ed93d1493af508773075a8c0ffc9e486
Parents: b550ff8
Author: Julian Hyde <jh...@apache.org>
Authored: Fri Jun 26 12:39:45 2015 -0700
Committer: Julian Hyde <jh...@apache.org>
Committed: Tue Jul 21 13:00:15 2015 -0700
----------------------------------------------------------------------
.../org/apache/calcite/model/JsonColumn.java | 6 ++
.../apache/calcite/model/JsonCustomSchema.java | 15 ++++-
.../apache/calcite/model/JsonCustomTable.java | 15 ++++-
.../org/apache/calcite/model/JsonFunction.java | 31 +++++++++
.../apache/calcite/model/JsonJdbcSchema.java | 33 ++++++++++
.../org/apache/calcite/model/JsonLattice.java | 41 ++++++++----
.../org/apache/calcite/model/JsonMapSchema.java | 16 ++++-
.../calcite/model/JsonMaterialization.java | 8 +++
.../org/apache/calcite/model/JsonMeasure.java | 6 ++
.../java/org/apache/calcite/model/JsonRoot.java | 18 ++++-
.../org/apache/calcite/model/JsonSchema.java | 35 ++++++++--
.../org/apache/calcite/model/JsonStream.java | 12 +++-
.../org/apache/calcite/model/JsonTable.java | 16 ++++-
.../java/org/apache/calcite/model/JsonTile.java | 18 +++--
.../java/org/apache/calcite/model/JsonView.java | 43 +++++++++++-
.../org/apache/calcite/model/ModelHandler.java | 3 +-
site/_docs/model.md | 69 +++++++++++++++++---
17 files changed, 334 insertions(+), 51 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonColumn.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonColumn.java b/core/src/main/java/org/apache/calcite/model/JsonColumn.java
index 2b9a361..843610f 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonColumn.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonColumn.java
@@ -19,9 +19,15 @@ package org.apache.calcite.model;
/**
* JSON object representing a column.
*
+ * <p>Occurs within {@link JsonTable#columns}.
+ *
* @see JsonRoot Description of JSON schema elements
*/
public class JsonColumn {
+ /** Column name.
+ *
+ * Required, and must be unique within the table.
+ */
public String name;
}
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonCustomSchema.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonCustomSchema.java b/core/src/main/java/org/apache/calcite/model/JsonCustomSchema.java
index 3144d38..0e656cd 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonCustomSchema.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonCustomSchema.java
@@ -21,15 +21,24 @@ import java.util.Map;
/**
* JSON schema element that represents a custom schema.
*
+ * <p>Like the base class {@link JsonSchema},
+ * occurs within {@link JsonRoot#schemas}.
+ *
* @see org.apache.calcite.model.JsonRoot Description of schema elements
*/
public class JsonCustomSchema extends JsonMapSchema {
- /** Name of the factory class for this schema. Must implement interface
+ /** Name of the factory class for this schema.
+ *
+ * <p>Required. Must implement interface
* {@link org.apache.calcite.schema.SchemaFactory} and have a public default
- * constructor. */
+ * constructor.
+ */
public String factory;
- /** Operand. May be a JSON object (represented as Map) or null. */
+ /** Contains attributes to be passed to the factory.
+ *
+ * <p>May be a JSON object (represented as Map) or null.
+ */
public Map<String, Object> operand;
public void accept(ModelHandler handler) {
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonCustomTable.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonCustomTable.java b/core/src/main/java/org/apache/calcite/model/JsonCustomTable.java
index 07a73d9..1619f7f 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonCustomTable.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonCustomTable.java
@@ -21,15 +21,24 @@ import java.util.Map;
/**
* Custom table schema element.
*
+ * <p>Like base class {@link JsonTable},
+ * occurs within {@link JsonMapSchema#tables}.
+ *
* @see JsonRoot Description of schema elements
*/
public class JsonCustomTable extends JsonTable {
- /** Name of the factory class for this table. Must implement interface
+ /** Name of the factory class for this table.
+ *
+ * <p>Required. Must implement interface
* {@link org.apache.calcite.schema.TableFactory} and have a public default
- * constructor. */
+ * constructor.
+ */
public String factory;
- /** Operand. May be a JSON object (represented as Map) or null. */
+ /** Contains attributes to be passed to the factory.
+ *
+ * <p>May be a JSON object (represented as Map) or null.
+ */
public Map<String, Object> operand;
public void accept(ModelHandler handler) {
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonFunction.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonFunction.java b/core/src/main/java/org/apache/calcite/model/JsonFunction.java
index 5c24ec9..e7a2bec 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonFunction.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonFunction.java
@@ -24,9 +24,40 @@ import java.util.List;
* @see JsonRoot Description of schema elements
*/
public class JsonFunction {
+ /** Name of this function.
+ *
+ * <p>Required.
+ */
public String name;
+
+ /** Name of the class that implements this function.
+ *
+ * <p>Required.
+ */
public String className;
+
+ /** Name of the method that implements this function.
+ *
+ * <p>Optional.
+ *
+ * <p>If 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.
+ *
+ * <p>If "*", Calcite creates a function for every method
+ * in this class.
+ *
+ * <p>If 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.
+ */
public String methodName;
+
+ /** Path for resolving this function.
+ *
+ * <p>Optional.
+ */
public List<String> path;
public void accept(ModelHandler handler) {
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonJdbcSchema.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonJdbcSchema.java b/core/src/main/java/org/apache/calcite/model/JsonJdbcSchema.java
index 61923d9..5eb203b 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonJdbcSchema.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonJdbcSchema.java
@@ -19,14 +19,47 @@ package org.apache.calcite.model;
/**
* JSON object representing a schema that maps to a JDBC database.
*
+ * <p>Like the base class {@link JsonSchema},
+ * occurs within {@link JsonRoot#schemas}.
+ *
* @see JsonRoot Description of JSON schema elements
*/
public class JsonJdbcSchema extends JsonSchema {
+ /** The name of the JDBC driver class.
+ *
+ * <p>Optional. If not specified, uses whichever class the JDBC
+ * {@link java.sql.DriverManager} chooses.
+ */
public String jdbcDriver;
+
+ /** JDBC connect string, for example “jdbc:mysql://localhost/foodmart”.
+ *
+ * <p>Optional.
+ */
public String jdbcUrl;
+
+ /** JDBC user name.
+ *
+ * <p>Optional.
+ */
public String jdbcUser;
+
+ /** JDBC connect string, for example “jdbc:mysql://localhost/foodmart”.
+ *
+ * <p>Optional.
+ */
public String jdbcPassword;
+
+ /** Name of the initial catalog in the JDBC data source.
+ *
+ * <p>Optional.
+ */
public String jdbcCatalog;
+
+ /** Name of the initial schema in the JDBC data source.
+ *
+ * <p>Optional.
+ */
public String jdbcSchema;
@Override public void accept(ModelHandler handler) {
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonLattice.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonLattice.java b/core/src/main/java/org/apache/calcite/model/JsonLattice.java
index d96eb06..15f1fcd 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonLattice.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonLattice.java
@@ -16,8 +16,7 @@
*/
package org.apache.calcite.model;
-import com.google.common.collect.Lists;
-
+import java.util.ArrayList;
import java.util.List;
/**
@@ -25,29 +24,48 @@ import java.util.List;
* recognizing, and recommending materialized views at various levels of
* aggregation.
*
+ * <p>Occurs within {@link JsonSchema#lattices}.
+ *
* @see JsonRoot Description of schema elements
*/
public class JsonLattice {
+ /** The name of this lattice.
+ *
+ * <p>Required.
+ */
public String name;
/** SQL query that defines the lattice.
*
- * <p>Must be a string or a list of strings (which are concatenated separated
- * by newlines).
+ * <p>Must be a string or a list of strings (which are concatenated into a
+ * multi-line SQL string, separated by newlines).
+ *
+ * <p>The structure of the SQL statement, and in particular the order of
+ * items in the FROM clause, defines the fact table, dimension tables, and
+ * join paths for this lattice.
*/
public Object sql;
- /** Whether to create in-memory materialized aggregates on demand.
+ /** Whether to materialize tiles on demand as queries are executed.
*
- * <p>Default is true. */
+ * <p>Optional; default is true.
+ */
public boolean auto = true;
- /** Whether to use an algorithm to suggest aggregates.
+ /** Whether to use an optimization algorithm to suggest and populate an
+ * initial set of tiles.
*
- * <p>Default is false. */
+ * <p>Optional; default is false.
+ */
public boolean algorithm = false;
- /** Maximum time to run the algorithm. Default is -1, meaning no timeout. */
+ /** Maximum time (in milliseconds) to run the algorithm.
+ *
+ * <p>Optional; default is -1, meaning no timeout.
+ *
+ * <p>When the timeout is reached, Calcite uses the best result that has
+ * been obtained so far.
+ */
public long algorithmMaxMillis = -1;
/** Estimated number of rows.
@@ -69,13 +87,14 @@ public class JsonLattice {
public String statisticProvider;
/** List of materialized aggregates to create up front. */
- public final List<JsonTile> tiles = Lists.newArrayList();
+ public final List<JsonTile> tiles = new ArrayList<>();
/** List of measures that a tile should have by default.
*
* <p>A tile can define its own measures, including measures not in this list.
*
- * <p>The default list is just count. */
+ * <p>Optional. The default list is just "count(*)".
+ */
public List<JsonMeasure> defaultMeasures;
public void accept(ModelHandler handler) {
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonMapSchema.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonMapSchema.java b/core/src/main/java/org/apache/calcite/model/JsonMapSchema.java
index e65a211..a7e8783 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonMapSchema.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonMapSchema.java
@@ -22,11 +22,23 @@ import java.util.List;
/**
* JSON object representing a schema whose tables are explicitly specified.
*
+ * <p>Like the base class {@link JsonSchema},
+ * occurs within {@link JsonRoot#schemas}.
+ *
* @see JsonRoot Description of JSON schema elements
*/
public class JsonMapSchema extends JsonSchema {
- public final List<JsonTable> tables = new ArrayList<JsonTable>();
- public final List<JsonFunction> functions = new ArrayList<JsonFunction>();
+ /** Tables in this schema.
+ *
+ * <p>The list may be empty.
+ */
+ public final List<JsonTable> tables = new ArrayList<>();
+
+ /** Functions in this schema.
+ *
+ * <p>The list may be empty.
+ */
+ public final List<JsonFunction> functions = new ArrayList<>();
@Override public void accept(ModelHandler handler) {
handler.visit(this);
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonMaterialization.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonMaterialization.java b/core/src/main/java/org/apache/calcite/model/JsonMaterialization.java
index 59b4828..e8165c8 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonMaterialization.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonMaterialization.java
@@ -19,11 +19,19 @@ package org.apache.calcite.model;
/**
* Element that describes how a table is a materialization of a query.
*
+ * <p>Occurs within {@link JsonSchema#materializations}.
+ *
* @see JsonRoot Description of schema elements
*/
public class JsonMaterialization {
public String view;
public String table;
+
+ /** SQL query that defines the materialization.
+ *
+ * <p>Must be a string or a list of strings (which are concatenated into a
+ * multi-line SQL string, separated by newlines).
+ */
public Object sql;
public void accept(ModelHandler handler) {
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonMeasure.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonMeasure.java b/core/src/main/java/org/apache/calcite/model/JsonMeasure.java
index e813c22..3071b00 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonMeasure.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonMeasure.java
@@ -26,7 +26,13 @@ package org.apache.calcite.model;
* @see JsonRoot Description of schema elements
*/
public class JsonMeasure {
+ /** The name of an aggregate function.
+ *
+ * <p>Required. Usually {@code count}, {@code sum},
+ * {@code min}, {@code max}.
+ */
public String agg;
+
/** Arguments to the measure.
*
* <p>Valid values are:
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonRoot.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonRoot.java b/core/src/main/java/org/apache/calcite/model/JsonRoot.java
index 44703aa..d85d8e6 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonRoot.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonRoot.java
@@ -43,11 +43,27 @@ import java.util.List;
* {@link JsonMaterialization} (in collection {@link JsonSchema#materializations materializations})
* </pre>
* <!-- CHECKSTYLE: ON -->
+ *
+ * <p>See the <a href="http://calcite.incubator.apache.org/docs/model.html">JSON
+ * model reference</a>.
*/
public class JsonRoot {
+ /** Schema model version number. Required, must have value "1.0". */
public String version;
+
+ /** Name of the schema that will become the default schema for connections
+ * to Calcite that use this model.
+ *
+ * <p>Optional, case-sensitive. If specified, there must be a schema in this
+ * model with this name.
+ */
public String defaultSchema;
- public final List<JsonSchema> schemas = new ArrayList<JsonSchema>();
+
+ /** List of schema elements.
+ *
+ * <p>The list may be empty.
+ */
+ public final List<JsonSchema> schemas = new ArrayList<>();
}
// End JsonRoot.java
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonSchema.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonSchema.java b/core/src/main/java/org/apache/calcite/model/JsonSchema.java
index 07e326f..d1c46f1 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonSchema.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonSchema.java
@@ -18,13 +18,15 @@ package org.apache.calcite.model;
import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
-import com.google.common.collect.Lists;
+import java.util.ArrayList;
import java.util.List;
/**
* Schema schema element.
*
+ * <p>Occurs within {@link JsonRoot#schemas}.
+ *
* @see JsonRoot Description of schema elements
*/
@JsonTypeInfo(
@@ -36,16 +38,37 @@ import java.util.List;
@JsonSubTypes.Type(value = JsonJdbcSchema.class, name = "jdbc"),
@JsonSubTypes.Type(value = JsonCustomSchema.class, name = "custom") })
public abstract class JsonSchema {
+ /** Name of the schema.
+ *
+ * <p>Required.
+ *
+ * @see JsonRoot#defaultSchema
+ */
public String name;
- /** SQL-path. May be null, or a list, each element of which is a string or a
- * string-list. */
+ /** SQL path that is used to resolve functions used in this schema.
+ *
+ * <p>May be null, or a list, each element of which is a string or a
+ * string-list.
+ *
+ * <p>For example,
+ *
+ * <blockquote><pre>path: [ ['usr', 'lib'], 'lib' ]</pre></blockquote>
+ *
+ * <p>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.
+ */
public List<Object> path;
- public final List<JsonMaterialization> materializations =
- Lists.newArrayList();
+ /**
+ * List of tables in this schema that are materializations of queries.
+ *
+ * <p>The list may be empty.
+ */
+ public final List<JsonMaterialization> materializations = new ArrayList<>();
- public final List<JsonLattice> lattices = Lists.newArrayList();
+ public final List<JsonLattice> lattices = new ArrayList<>();
/** Whether to cache metadata (tables, functions and sub-schemas) generated
* by this schema. Default value is {@code true}.
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonStream.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonStream.java b/core/src/main/java/org/apache/calcite/model/JsonStream.java
index f8d728a..714af5f 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonStream.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonStream.java
@@ -19,14 +19,22 @@ package org.apache.calcite.model;
/**
* Information about whether a table allows streaming.
*
+ * <p>Occurs within {@link JsonTable#stream}.
+ *
* @see org.apache.calcite.model.JsonRoot Description of schema elements
* @see org.apache.calcite.model.JsonTable#stream
*/
public class JsonStream {
- /** Whether the table allows streaming. */
+ /** Whether the table allows streaming.
+ *
+ * <p>Optional; default true.
+ */
public boolean stream = true;
- /** Whether the history of the table is available. */
+ /** Whether the history of the table is available.
+ *
+ * <p>Optional; default false.
+ */
public boolean history = false;
}
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonTable.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonTable.java b/core/src/main/java/org/apache/calcite/model/JsonTable.java
index 806405b..9673667 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonTable.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonTable.java
@@ -18,13 +18,15 @@ package org.apache.calcite.model;
import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
-import com.google.common.collect.Lists;
+import java.util.ArrayList;
import java.util.List;
/**
* Table schema element.
*
+ * <p>Occurs within {@link JsonMapSchema#tables}.
+ *
* @see JsonRoot Description of schema elements
*/
@JsonTypeInfo(
@@ -35,8 +37,18 @@ import java.util.List;
@JsonSubTypes.Type(value = JsonCustomTable.class, name = "custom"),
@JsonSubTypes.Type(value = JsonView.class, name = "view") })
public abstract class JsonTable {
+ /** Name of this table.
+ *
+ * <p>Required. Must be unique within the schema.
+ */
public String name;
- public final List<JsonColumn> columns = Lists.newArrayList();
+
+ /** Definition of the columns of this table.
+ *
+ * <p>Required for some kinds of type,
+ * optional for others (such as {@link JsonView}).
+ */
+ public final List<JsonColumn> columns = new ArrayList<>();
/** Information about whether the table can be streamed, and if so, whether
* the history of the table is also available. */
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonTile.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonTile.java b/core/src/main/java/org/apache/calcite/model/JsonTile.java
index aef1d2e..f718777 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonTile.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonTile.java
@@ -16,8 +16,7 @@
*/
package org.apache.calcite.model;
-import com.google.common.collect.Lists;
-
+import java.util.ArrayList;
import java.util.List;
/**
@@ -27,14 +26,21 @@ import java.util.List;
* drawn from the lattice) and measures (aggregate functions applied to
* lattice columns).
*
+ * <p>Occurs within {@link JsonLattice#tiles}.
+ *
* @see JsonRoot Description of schema elements
*/
public class JsonTile {
- /** List of grouping columns that define this tile.
+ /** List of dimensions that define this tile.
*
- * <p>Elements are either strings (column names unique within the lattice)
- * or string lists (pairs of table alias and column name). */
- public final List dimensions = Lists.newArrayList();
+ * <p>Each dimension is a column from the lattice. The list of dimensions
+ * defines the level of aggregation, like a {@code GROUP BY} clause.
+ *
+ * <p>Required, but may be empty. Each element is 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).
+ */
+ public final List dimensions = new ArrayList();
/** List of measures in this tile.
*
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/JsonView.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/JsonView.java b/core/src/main/java/org/apache/calcite/model/JsonView.java
index 48e1cf3..ccacc11 100644
--- a/core/src/main/java/org/apache/calcite/model/JsonView.java
+++ b/core/src/main/java/org/apache/calcite/model/JsonView.java
@@ -21,14 +21,51 @@ import java.util.List;
/**
* View schema element.
*
+ * <p>Like base class {@link JsonTable},
+ * occurs within {@link JsonMapSchema#tables}.
+ *
+ * <h2>Modifiable views</h2>
+ *
+ * <p>A view is modifiable if contains only SELECT, FROM, WHERE (no JOIN,
+ * aggregation or sub-queries) and every column:
+ *
+ * <ul>
+ * <li>is specified once in the SELECT clause; or
+ * <li>occurs in the WHERE clause with a column = literal predicate; or
+ * <li>is nullable.
+ * </ul>
+ *
+ * <p>The second clause allows Calcite to automatically provide the correct
+ * value for hidden columns. It is useful in, say, a multi-tenant environment,
+ * where the {@code tenantId} column is hidden, mandatory (NOT NULL), and has a
+ * constant value for a particular view.
+ *
+ * <p>Errors regarding modifiable views:
+ *
+ * <ul>
+ * <li>If a view is marked modifiable: true and is not modifiable, Calcite
+ * throws an error while reading the schema.
+ * <li>If you submit an INSERT, UPDATE or UPSERT command to a non-modifiable
+ * view, Calcite throws an error when validating the statement.
+ * <li>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.
+ * </ul>
+ *
* @see JsonRoot Description of schema elements
*/
public class JsonView extends JsonTable {
- /** SQL query that is the definition of the view. */
+ /** SQL query that is the definition of the view.
+ *
+ * <p>Must be a string or a list of strings (which are concatenated into a
+ * multi-line SQL string, separated by newlines).
+ */
public Object sql;
- /** Schema name(s) to use when resolving query. If not specified, defaults
- * to current schema. */
+ /** Schema name(s) to use when resolving query.
+ *
+ * <p>If not specified, defaults to current schema.
+ */
public List<String> path;
/** Whether this view should allow INSERT requests.
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/core/src/main/java/org/apache/calcite/model/ModelHandler.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/model/ModelHandler.java b/core/src/main/java/org/apache/calcite/model/ModelHandler.java
index 0c0efa8..1afaf41 100644
--- a/core/src/main/java/org/apache/calcite/model/ModelHandler.java
+++ b/core/src/main/java/org/apache/calcite/model/ModelHandler.java
@@ -62,8 +62,7 @@ import static org.apache.calcite.util.Stacks.push;
*/
public class ModelHandler {
private final CalciteConnection connection;
- private final List<Pair<String, SchemaPlus>> schemaStack =
- new ArrayList<Pair<String, SchemaPlus>>();
+ private final List<Pair<String, SchemaPlus>> schemaStack = new ArrayList<>();
private final String modelUri;
Lattice.Builder latticeBuilder;
Lattice.TileBuilder tileBuilder;
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/629a56e5/site/_docs/model.md
----------------------------------------------------------------------
diff --git a/site/_docs/model.md b/site/_docs/model.md
index a6514a3..0f9a548 100644
--- a/site/_docs/model.md
+++ b/site/_docs/model.md
@@ -79,7 +79,7 @@ strings. For example,
{% endhighlight %}
declares a path with two elements: the schema '/usr/lib' and the
-schema '/lib'. Most schemas are at the top level, so you can use a
+schema '/lib'. Most schemas are at the top level, and for these you can use a
string.
`materializations` (optional list of
@@ -176,7 +176,7 @@ Like base class <a href="#schema">Schema</a>, occurs within `root.schemas`.
`name`, `type`, `path`, `cache`, `materializations` inherited from
<a href="#schema">Schema</a>.
-`jdbcDriver` (optional string) is the name of the JDBC driver class. It not
+`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
@@ -229,7 +229,8 @@ Occurs within `root.schemas.tables`.
* `custom` for <a href="#custom-table">Custom Table</a>
* `view` for <a href="#view">View</a>
-`columns` (optional list of <a href="#column">Column</a> elements)
+`columns` (list of <a href="#column">Column</a> elements, required for
+some kinds of table, optional for others such as View)
### View
@@ -302,6 +303,24 @@ 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`.
@@ -335,6 +354,18 @@ 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
@@ -389,7 +420,7 @@ 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 star
+the lattice
`tiles` (optional list of <a href="#tile">Tile</a> elements) is a list of
materialized aggregates to create up front.
@@ -435,9 +466,12 @@ Occurs within `root.schemas.lattices.tiles`.
}
{% endhighlight %}
-`dimensions` is a list of dimensions (columns from the star), like a `GROUP BY`
-clause. Each element is either a string (the unique label of the column within
-the star) or a string list (a column name qualified by a table name).
+`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
@@ -458,6 +492,21 @@ and `root.schemas.lattices.tiles.measures`.
`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 columns.
-If a list, each element is either a string (the unique label of the column
-within the star) or a string list (a column name qualified by a table name).
+`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 -->