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/07/22 02:23:16 UTC
[1/2] incubator-calcite git commit: Document JSON model,
making javadoc consistent with the model reference
Repository: incubator-calcite
Updated Branches:
refs/heads/master b550ff887 -> 4b60b9bf4
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/master
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 -->
[2/2] incubator-calcite git commit: [CALCITE-761] Pre-populated
materializations (Maryann Xue)
Posted by jh...@apache.org.
[CALCITE-761] Pre-populated materializations (Maryann Xue)
Project: http://git-wip-us.apache.org/repos/asf/incubator-calcite/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-calcite/commit/4b60b9bf
Tree: http://git-wip-us.apache.org/repos/asf/incubator-calcite/tree/4b60b9bf
Diff: http://git-wip-us.apache.org/repos/asf/incubator-calcite/diff/4b60b9bf
Branch: refs/heads/master
Commit: 4b60b9bf46b88b4dc6af8279013cbb731d98a8d3
Parents: 629a56e
Author: maryannxue <we...@intel.com>
Authored: Fri Jun 26 15:32:02 2015 -0700
Committer: Julian Hyde <jh...@apache.org>
Committed: Tue Jul 21 16:51:15 2015 -0700
----------------------------------------------------------------------
.../materialize/MaterializationService.java | 19 +++++--
.../org/apache/calcite/model/ModelHandler.java | 17 +++++-
.../calcite/plan/RelOptMaterialization.java | 3 +-
.../schema/impl/MaterializedViewTable.java | 13 +++--
.../org/apache/calcite/test/CalciteAssert.java | 58 ++++++++++----------
.../calcite/test/MaterializationTest.java | 39 +++++++++++++
site/_docs/model.md | 7 ++-
7 files changed, 111 insertions(+), 45 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/4b60b9bf/core/src/main/java/org/apache/calcite/materialize/MaterializationService.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/materialize/MaterializationService.java b/core/src/main/java/org/apache/calcite/materialize/MaterializationService.java
index b594cca..615d185 100644
--- a/core/src/main/java/org/apache/calcite/materialize/MaterializationService.java
+++ b/core/src/main/java/org/apache/calcite/materialize/MaterializationService.java
@@ -95,15 +95,16 @@ public class MaterializationService {
/** Defines a new materialization. Returns its key. */
public MaterializationKey defineMaterialization(final CalciteSchema schema,
TileKey tileKey, String viewSql, List<String> viewSchemaPath,
- final String suggestedTableName, boolean create) {
+ final String suggestedTableName, boolean create, boolean existing) {
return defineMaterialization(schema, tileKey, viewSql, viewSchemaPath,
- suggestedTableName, tableFactory, create);
+ suggestedTableName, tableFactory, create, existing);
}
/** Defines a new materialization. Returns its key. */
public MaterializationKey defineMaterialization(final CalciteSchema schema,
TileKey tileKey, String viewSql, List<String> viewSchemaPath,
- String suggestedTableName, TableFactory tableFactory, boolean create) {
+ String suggestedTableName, TableFactory tableFactory, boolean create,
+ boolean existing) {
final MaterializationActor.QueryKey queryKey =
new MaterializationActor.QueryKey(viewSql, schema, viewSchemaPath);
final MaterializationKey existingKey = actor.keyBySql.get(queryKey);
@@ -116,7 +117,15 @@ public class MaterializationService {
final CalciteConnection connection =
CalciteMetaImpl.connect(schema.root(), null);
- CalciteSchema.TableEntry tableEntry = schema.getTableBySql(viewSql);
+ CalciteSchema.TableEntry tableEntry;
+ if (existing) {
+ tableEntry = schema.getTable(suggestedTableName, true);
+ } else {
+ tableEntry = null;
+ }
+ if (tableEntry == null) {
+ tableEntry = schema.getTableBySql(viewSql);
+ }
RelDataType rowType = null;
if (tableEntry == null) {
Table table = tableFactory.createTable(schema, viewSql, viewSchemaPath);
@@ -265,7 +274,7 @@ public class MaterializationService {
final String sql = lattice.sql(groupSet, newTileKey.measures);
materializationKey =
defineMaterialization(schema, newTileKey, sql, schema.path(null),
- suggestedTableName, tableFactory, true);
+ suggestedTableName, tableFactory, true, false);
if (materializationKey != null) {
final CalciteSchema.TableEntry tableEntry =
checkValid(materializationKey);
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/4b60b9bf/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 1afaf41..3faf446 100644
--- a/core/src/main/java/org/apache/calcite/model/ModelHandler.java
+++ b/core/src/main/java/org/apache/calcite/model/ModelHandler.java
@@ -265,9 +265,22 @@ public class ModelHandler {
+ "' is not a SemiMutableSchema");
}
CalciteSchema calciteSchema = CalciteSchema.from(schema);
- schema.add(jsonMaterialization.view,
+
+ final String viewName;
+ final boolean existing;
+ if (jsonMaterialization.view == null) {
+ // If the user did not supply a view name, that means the materialized
+ // view is pre-populated. Generate a synthetic view name.
+ viewName = "$" + schema.getTableNames().size();
+ existing = true;
+ } else {
+ viewName = jsonMaterialization.view;
+ existing = false;
+ }
+ schema.add(viewName,
MaterializedViewTable.create(calciteSchema,
- jsonMaterialization.getSql(), null, jsonMaterialization.table));
+ jsonMaterialization.getSql(), null, jsonMaterialization.table,
+ existing));
} catch (Exception e) {
throw new RuntimeException("Error instantiating " + jsonMaterialization,
e);
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/4b60b9bf/core/src/main/java/org/apache/calcite/plan/RelOptMaterialization.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/plan/RelOptMaterialization.java b/core/src/main/java/org/apache/calcite/plan/RelOptMaterialization.java
index f945e65..4108cff 100644
--- a/core/src/main/java/org/apache/calcite/plan/RelOptMaterialization.java
+++ b/core/src/main/java/org/apache/calcite/plan/RelOptMaterialization.java
@@ -62,7 +62,8 @@ public class RelOptMaterialization {
*/
public RelOptMaterialization(RelNode tableRel, RelNode queryRel,
RelOptTable starRelOptTable) {
- this.tableRel = tableRel;
+ this.tableRel =
+ RelOptUtil.createCastRel(tableRel, queryRel.getRowType(), false);
this.starRelOptTable = starRelOptTable;
if (starRelOptTable == null) {
this.starTable = null;
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/4b60b9bf/core/src/main/java/org/apache/calcite/schema/impl/MaterializedViewTable.java
----------------------------------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/schema/impl/MaterializedViewTable.java b/core/src/main/java/org/apache/calcite/schema/impl/MaterializedViewTable.java
index 27e873a..8d80465 100644
--- a/core/src/main/java/org/apache/calcite/schema/impl/MaterializedViewTable.java
+++ b/core/src/main/java/org/apache/calcite/schema/impl/MaterializedViewTable.java
@@ -75,11 +75,10 @@ public class MaterializedViewTable extends ViewTable {
/** Table macro that returns a materialized view. */
public static MaterializedViewTableMacro create(final CalciteSchema schema,
- final String viewSql,
- final List<String> viewSchemaPath,
- final String tableName) {
+ final String viewSql, final List<String> viewSchemaPath,
+ final String suggestedTableName, boolean existing) {
return new MaterializedViewTableMacro(schema, viewSql, viewSchemaPath,
- tableName);
+ suggestedTableName, existing);
}
@Override public RelNode toRel(RelOptTable.ToRelContext context,
@@ -102,11 +101,13 @@ public class MaterializedViewTable extends ViewTable {
private final MaterializationKey key;
private MaterializedViewTableMacro(CalciteSchema schema, String viewSql,
- List<String> viewSchemaPath, String suggestedTableName) {
+ List<String> viewSchemaPath, String suggestedTableName,
+ boolean existing) {
super(schema, viewSql, viewSchemaPath, Boolean.TRUE);
this.key = Preconditions.checkNotNull(
MaterializationService.instance().defineMaterialization(
- schema, null, viewSql, schemaPath, suggestedTableName, true));
+ schema, null, viewSql, schemaPath, suggestedTableName, true,
+ existing));
}
@Override public TranslatableTable apply(List<Object> arguments) {
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/4b60b9bf/core/src/test/java/org/apache/calcite/test/CalciteAssert.java
----------------------------------------------------------------------
diff --git a/core/src/test/java/org/apache/calcite/test/CalciteAssert.java b/core/src/test/java/org/apache/calcite/test/CalciteAssert.java
index 39ed982..3d0a0dc 100644
--- a/core/src/test/java/org/apache/calcite/test/CalciteAssert.java
+++ b/core/src/test/java/org/apache/calcite/test/CalciteAssert.java
@@ -405,7 +405,7 @@ public class CalciteAssert {
private static String typeString(ResultSetMetaData metaData)
throws SQLException {
- final List<String> list = new ArrayList<String>();
+ final List<String> list = new ArrayList<>();
for (int i = 0; i < metaData.getColumnCount(); i++) {
list.add(
metaData.getColumnName(i + 1)
@@ -452,13 +452,7 @@ public class CalciteAssert {
exceptionChecker.apply(null);
return;
}
- } catch (Exception e) {
- if (exceptionChecker != null) {
- exceptionChecker.apply(e);
- return;
- }
- throw e;
- } catch (Error e) {
+ } catch (Exception | Error e) {
if (exceptionChecker != null) {
exceptionChecker.apply(e);
return;
@@ -471,13 +465,11 @@ public class CalciteAssert {
resultSet.close();
statement.close();
connection.close();
- } catch (Error e) {
+ } catch (Error | RuntimeException e) {
// We ignore extended message for non-runtime exception, however
// it does not matter much since it is better to have AssertionError
// at the very top level of the exception stack.
throw e;
- } catch (RuntimeException e) {
- throw e;
} catch (Throwable e) {
throw new RuntimeException(message, e);
} finally {
@@ -840,21 +832,32 @@ public class CalciteAssert {
/** Adds materializations to the schema. */
public final AssertThat withMaterializations(String model,
- String... materializations) {
- assert materializations.length % 2 == 0;
+ final String... materializations) {
+ return withMaterializations(model,
+ new Function<JsonBuilder, List<Object>>() {
+ public List<Object> apply(JsonBuilder builder) {
+ assert materializations.length % 2 == 0;
+ final List<Object> list = builder.list();
+ for (int i = 0; i < materializations.length; i++) {
+ String table = materializations[i++];
+ final Map<String, Object> map = builder.map();
+ map.put("table", table);
+ map.put("view", table + "v");
+ String sql = materializations[i];
+ final String sql2 = sql.replaceAll("`", "\"");
+ map.put("sql", sql2);
+ list.add(map);
+ }
+ return list;
+ }
+ });
+ }
+
+ /** Adds materializations to the schema. */
+ public final AssertThat withMaterializations(String model,
+ Function<JsonBuilder, List<Object>> materializations) {
final JsonBuilder builder = new JsonBuilder();
- final List<Object> list = builder.list();
- for (int i = 0; i < materializations.length; i++) {
- String table = materializations[i++];
- final Map<String, Object> map = builder.map();
- map.put("table", table);
- map.put("view", table + "v");
- String sql = materializations[i];
- final String sql2 = sql
- .replaceAll("`", "\"");
- map.put("sql", sql2);
- list.add(map);
- }
+ final List<Object> list = materializations.apply(builder);
final String buf =
"materializations: " + builder.toJsonString(list);
final String model2;
@@ -908,13 +911,10 @@ public class CalciteAssert {
* and executes a callback. */
public <T> AssertThat doWithConnection(Function<CalciteConnection, T> fn)
throws Exception {
- Connection connection = connectionFactory.createConnection();
- try {
+ try (Connection connection = connectionFactory.createConnection()) {
T t = fn.apply((CalciteConnection) connection);
Util.discard(t);
return AssertThat.this;
- } finally {
- connection.close();
}
}
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/4b60b9bf/core/src/test/java/org/apache/calcite/test/MaterializationTest.java
----------------------------------------------------------------------
diff --git a/core/src/test/java/org/apache/calcite/test/MaterializationTest.java b/core/src/test/java/org/apache/calcite/test/MaterializationTest.java
index ae235ab..f132915 100644
--- a/core/src/test/java/org/apache/calcite/test/MaterializationTest.java
+++ b/core/src/test/java/org/apache/calcite/test/MaterializationTest.java
@@ -28,14 +28,18 @@ import org.apache.calcite.rex.RexLiteral;
import org.apache.calcite.rex.RexNode;
import org.apache.calcite.rex.RexUtil;
import org.apache.calcite.sql.fun.SqlStdOperatorTable;
+import org.apache.calcite.util.JsonBuilder;
import com.google.common.base.Function;
+import com.google.common.collect.ImmutableList;
import org.junit.Ignore;
import org.junit.Test;
import java.math.BigDecimal;
import java.sql.ResultSet;
+import java.util.List;
+import java.util.Map;
import static org.hamcrest.CoreMatchers.equalTo;
import static org.junit.Assert.assertEquals;
@@ -53,6 +57,10 @@ public class MaterializationTest {
CalciteAssert.checkResultContains(
"EnumerableTableScan(table=[[hr, m0]])");
+ private static final Function<ResultSet, Void> CONTAINS_LOCATIONS =
+ CalciteAssert.checkResultContains(
+ "EnumerableTableScan(table=[[hr, locations]])");
+
final JavaTypeFactoryImpl typeFactory =
new JavaTypeFactoryImpl(RelDataTypeSystem.DEFAULT);
final RexBuilder rexBuilder = new RexBuilder(typeFactory);
@@ -749,6 +757,37 @@ public class MaterializationTest {
+ "join \"depts\" using (\"deptno\")";
checkMaterialize("select * from \"emps\" where \"empid\" < 500", q);
}
+
+ /** Test case for
+ * <a href="https://issues.apache.org/jira/browse/CALCITE-761">[CALCITE-761]
+ * Pre-populated materializations</a>. */
+ @Test public void testPrePopulated() {
+ String q = "select \"deptno\" from \"emps\"";
+ try {
+ Prepare.THREAD_TRIM.set(true);
+ MaterializationService.setThreadLocal();
+ CalciteAssert.that()
+ .withMaterializations(
+ JdbcTest.HR_MODEL,
+ new Function<JsonBuilder, List<Object>>() {
+ public List<Object> apply(JsonBuilder builder) {
+ final Map<String, Object> map = builder.map();
+ map.put("table", "locations");
+ String sql = "select `deptno` as `empid`, '' as `name`\n"
+ + "from `emps`";
+ final String sql2 = sql.replaceAll("`", "\"");
+ map.put("sql", sql2);
+ return ImmutableList.<Object>of(map);
+ }
+ })
+ .query(q)
+ .enableMaterializations(true)
+ .explainMatches("", CONTAINS_LOCATIONS)
+ .sameResultWithMaterializationsDisabled();
+ } finally {
+ Prepare.THREAD_TRIM.set(false);
+ }
+ }
}
// End MaterializationTest.java
http://git-wip-us.apache.org/repos/asf/incubator-calcite/blob/4b60b9bf/site/_docs/model.md
----------------------------------------------------------------------
diff --git a/site/_docs/model.md b/site/_docs/model.md
index 0f9a548..cb8cc9c 100644
--- a/site/_docs/model.md
+++ b/site/_docs/model.md
@@ -204,9 +204,12 @@ Occurs within `root.schemas.materializations`.
}
{% endhighlight %}
-`view` (optional string) TODO
+`view` (optional string) is the name of the view; null means that the table
+already exists and is populated with the correct data.
-`table` (optional string) TODO
+`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.