[CALCITE-1079] Split out an Avatica website, made to slot into the Calcite site at /avatica
Project: http://git-wip-us.apache.org/repos/asf/calcite/repo Commit: http://git-wip-us.apache.org/repos/asf/calcite/commit/65f2afa7 Tree: http://git-wip-us.apache.org/repos/asf/calcite/tree/65f2afa7 Diff: http://git-wip-us.apache.org/repos/asf/calcite/diff/65f2afa7 Branch: refs/heads/master Commit: 65f2afa7add341c614cb59fb80f93da5e575e96a Parents: 5cee486 Author: Josh Elser <[email protected]> Authored: Fri Mar 4 00:40:43 2016 -0500 Committer: Josh Elser <[email protected]> Committed: Mon Mar 7 10:50:09 2016 -0500 ---------------------------------------------------------------------- avatica/site/_config.yml | 4 +- avatica/site/_data/contributors.yml | 96 - avatica/site/_data/docs.yml | 20 +- avatica/site/_docs/adapter.md | 38 - avatica/site/_docs/algebra.md | 369 --- avatica/site/_docs/avatica_json_reference.md | 1086 --------- avatica/site/_docs/avatica_overview.md | 130 - .../site/_docs/avatica_protobuf_reference.md | 1181 --------- avatica/site/_docs/avatica_roadmap.md | 51 - avatica/site/_docs/history.md | 2301 +----------------- avatica/site/_docs/index.md | 185 +- avatica/site/_docs/json_reference.md | 1086 +++++++++ avatica/site/_docs/lattice.md | 136 -- avatica/site/_docs/model.md | 517 ---- avatica/site/_docs/protobuf_reference.md | 1181 +++++++++ avatica/site/_docs/reference.md | 1248 ---------- avatica/site/_docs/roadmap.md | 51 + avatica/site/_docs/stream.md | 1023 -------- avatica/site/_docs/tutorial.md | 760 ------ avatica/site/_includes/header.html | 2 +- avatica/site/_includes/news_contents.html | 2 +- .../2014-06-27-release-0.8.0-incubating.md | 31 - .../2014-08-19-release-0.9.0-incubating.md | 30 - .../2014-10-02-release-0.9.1-incubating.md | 29 - .../2014-11-05-release-0.9.2-incubating.md | 32 - .../2015-01-31-release-1.0.0-incubating.md | 42 - .../2015-03-13-release-1.1.0-incubating.md | 41 - .../2015-04-07-release-1.2.0-incubating.md | 41 - .../site/_posts/2015-04-24-new-committers.md | 34 - .../2015-05-30-release-1.3.0-incubating.md | 33 - .../site/_posts/2015-06-05-algebra-builder.md | 87 - .../2015-07-31-xldb-best-lightning-talk.md | 41 - .../2015-09-02-release-1.4.0-incubating.md | 39 - .../site/_posts/2015-10-22-calcite-graduates.md | 63 - .../site/_posts/2015-11-08-new-committers.md | 31 - avatica/site/_posts/2015-11-10-release-1.5.0.md | 33 - avatica/site/_posts/2016-01-22-release-1.6.0.md | 59 - avatica/site/_posts/2016-02-17-elser-pmc.md | 33 - .../_posts/2016-02-17-streaming-sql-talk.md | 40 - .../site/_posts/2016-03-03-separate-project.md | 32 + avatica/site/_posts/2016-03-03-tbd-release.md | 30 + avatica/site/community/index.md | 48 +- avatica/site/develop/index.md | 5 +- avatica/site/doap_calcite.rdf | 59 - avatica/site/downloads/index.md | 8 +- avatica/site/index.html | 23 +- site/index.html | 8 + 47 files changed, 2493 insertions(+), 9926 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_config.yml ---------------------------------------------------------------------- diff --git a/avatica/site/_config.yml b/avatica/site/_config.yml index 9b8de85..c765da2 100644 --- a/avatica/site/_config.yml +++ b/avatica/site/_config.yml @@ -27,7 +27,7 @@ collections: output: true # The URL where the code can be found -sourceRoot: https://github.com/apache/calcite/blob/master +sourceRoot: https://github.com/apache/calcite/tree/master/avatica # The URL where Javadocs are located apiRoot: /apidocs @@ -38,6 +38,6 @@ testApiRoot: /testapidocs # testApiRoot: http://calcite.apache.org/testapidocs # The base path where the website is deployed -baseurl: +baseurl: /avatica # End _config.yml http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_data/contributors.yml ---------------------------------------------------------------------- diff --git a/avatica/site/_data/contributors.yml b/avatica/site/_data/contributors.yml deleted file mode 100644 index 98f8bf9..0000000 --- a/avatica/site/_data/contributors.yml +++ /dev/null @@ -1,96 +0,0 @@ -# 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. -# -# Database of contributors to Apache Calcite. -# Pages such as developer.md use this data. -# -- name: Alan Gates - apacheId: gates - githubId: alanfgates - org: Hortonworks - role: PMC -- name: Aman Sinha - apacheId: amansinha - githubId: amansinha100 - org: MapR - role: PMC -- name: Ashutosh Chauhan - apacheId: hashutosh - githubId: ashutoshc - org: Hortonworks - role: PMC -- name: James R. Taylor - apacheId: jamestaylor - githubId: JamesRTaylor - org: Salesforce - role: PMC -- name: Jacques Nadeau - apacheId: jacques - githubId: jacques-n - org: Dremio - role: PMC -- name: Jesús Camacho RodrÃguez - apacheId: jcamacho - githubId: jcamachor - org: Hortonworks - role: PMC -- name: Jinfeng Ni - apacheId: jni - githubId: jinfengni - org: MapR - role: PMC -- name: John Pullokkaran - apacheId: jpullokk - githubId: jpullokkaran - org: Hortonworks - role: PMC -- name: Josh Elser - apacheId: elserj - githubId: joshelser - org: Hortonworks - role: PMC -- name: Julian Hyde - apacheId: jhyde - githubId: julianhyde - org: Hortonworks - role: PMC Chair - homepage: http://people.apache.org/~jhyde -- name: Maryann Xue - apacheId: maryannxue - githubId: maryannxue - org: Intel - role: Committer -- name: Nick Dimiduk - apacheId: ndimiduk - githubId: ndimiduk - org: Hortonworks - role: PMC -- name: Steven Noels - apacheId: stevenn - githubId: stevenn - org: NGData - role: PMC -- name: Ted Dunning - apacheId: tdunning - githubId: tdunning - org: MapR - role: PMC - avatar: https://www.mapr.com/sites/default/files/otherpageimages/ted-circle-80.png -- name: Vladimir Sitnikov - apacheId: vladimirsitnikov - githubId: vlsi - org: NetCracker - role: PMC -# End contributors.yml http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_data/docs.yml ---------------------------------------------------------------------- diff --git a/avatica/site/_data/docs.yml b/avatica/site/_data/docs.yml index a996097..8b1af11 100644 --- a/avatica/site/_data/docs.yml +++ b/avatica/site/_data/docs.yml @@ -18,26 +18,12 @@ - title: Overview docs: - index - - tutorial - - algebra - -- title: Advanced - docs: - - adapter - - stream - - lattice - -- title: Avatica - docs: - - avatica_overview - - avatica_roadmap - - avatica_json_reference - - avatica_protobuf_reference + - roadmap - title: Reference docs: - - reference - - model + - json_reference + - protobuf_reference - howto - title: Meta http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_docs/adapter.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/adapter.md b/avatica/site/_docs/adapter.md deleted file mode 100644 index fa8eb21..0000000 --- a/avatica/site/_docs/adapter.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: docs -title: Adapters -permalink: /docs/adapter.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 href="https://github.com/apache/drill";>Apache Drill adapter</a> -* Cascading adapter (<a href="https://github.com/Cascading/lingual";>Lingual</a>) -* Cassandra adapter (<a href="{{ site.apiRoot }}/org/apache/calcite/adapter/cassandra/package-summary.html">calcite-cassandra</a>) -* CSV adapter (<a href="{{ site.apiRoot }}/org/apache/calcite/adapter/csv/package-summary.html">example/csv</a>) -* JDBC adapter (part of <a href="{{ site.apiRoot }}/org/apache/calcite/adapter/jdbc/package-summary.html">calcite-core</a>) -* MongoDB adapter (<a href="{{ site.apiRoot }}/org/apache/calcite/adapter/mongodb/package-summary.html">calcite-mongodb</a>) -* Spark adapter (<a href="{{ site.apiRoot }}/org/apache/calcite/adapter/spark/package-summary.html">calcite-spark</a>) -* Splunk adapter (<a href="{{ site.apiRoot }}/org/apache/calcite/adapter/splunk/package-summary.html">calcite-splunk</a>) -* Eclipse Memory Analyzer (MAT) adapter (<a href="https://github.com/vlsi/mat-calcite-plugin";>mat-calcite-plugin</a>) - -## Drivers - -* <a href="{{ site.apiRoot }}/org/apache/calcite/jdbc/package-summary.html">JDBC driver</a> - http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_docs/algebra.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/algebra.md b/avatica/site/_docs/algebra.md deleted file mode 100644 index e651dd0..0000000 --- a/avatica/site/_docs/algebra.md +++ /dev/null @@ -1,369 +0,0 @@ ---- -layout: docs -title: Algebra -permalink: /docs/algebra.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 %} ---> - -Relational algebra is at the heart of Calcite. Every query is -represented as a tree of relational operators. You can translate from -SQL to relational algebra, or you can build the tree directly. - -Planner rules transform expression trees using mathematical identities -that preserve semantics. For example, it is valid to push a filter -into an input of an inner join if the filter does not reference -columns from the other input. - -Calcite optimizes queries by repeatedly applying planner rules to a -relational expression. A cost model guides the process, and the -planner engine generates an alternative expression that has the same -semantics as the original but a lower cost. - -The planning process is extensible. You can add your own relational -operators, planner rules, cost model, and statistics. - -## Algebra builder - -The simplest way to build a relational expression is to use the algebra builder, -[RelBuilder]({{ site.apiRoot }}/org/apache/calcite/tools/RelBuilder.html). -Here is an example: - -### TableScan - -{% highlight java %} -final FrameworkConfig config; -final RelBuilder builder = RelBuilder.create(config); -final RelNode node = builder - .scan("EMP") - .build(); -System.out.println(RelOptUtil.toString(node)); -{% endhighlight %} - -(You can find the full code for this and other examples in -[RelBuilderExample.java]({{ site.sourceRoot }}/core/src/test/java/org/apache/calcite/examples/RelBuilderExample.java).) - -The code prints - -{% highlight text %} -LogicalTableScan(table=[[scott, EMP]]) -{% endhighlight %} - -It has created a scan of the `EMP` table; equivalent to the SQL - -{% highlight sql %} -SELECT * -FROM scott.EMP; -{% endhighlight %} - -### Adding a Project - -Now, let's add a Project, the equivalent of - -{% highlight sql %} -SELECT ename, deptno -FROM scott.EMP; -{% endhighlight %} - -We just add a call to the `project` method before calling -`build`: - -{% highlight java %} -final RelNode node = builder - .scan("EMP") - .project(builder.field("DEPTNO"), builder.field("ENAME")) - .build(); -System.out.println(RelOptUtil.toString(node)); -{% endhighlight %} - -and the output is - -{% highlight text %} -LogicalProject(DEPTNO=[$7], ENAME=[$1]) - LogicalTableScan(table=[[scott, EMP]]) -{% endhighlight %} - -The two calls to `builder.field` create simple expressions -that return the fields from the input relational expression, -namely the TableScan created by the `scan` call. - -Calcite has converted them to field references by ordinal, -`$7` and `$1`. - -### Adding a Filter and Aggregate - -A query with an Aggregate, and a Filter: - -{% highlight java %} -final RelNode node = builder - .scan("EMP") - .aggregate(builder.groupKey("DEPTNO"), - builder.count(false, "C"), - builder.sum(false, "S", builder.field("SAL"))) - .filter( - builder.call(SqlStdOperatorTable.GREATER_THAN, - builder.field("C"), - builder.literal(10))) - .build(); -System.out.println(RelOptUtil.toString(node)); -{% endhighlight %} - -is equivalent to SQL - -{% highlight sql %} -SELECT deptno, count(*) AS c, sum(sal) AS s -FROM emp -GROUP BY deptno -HAVING count(*) > 10 -{% endhighlight %} - -and produces - -{% highlight text %} -LogicalFilter(condition=[>($1, 10)]) - LogicalAggregate(group=[{7}], C=[COUNT()], S=[SUM($5)]) - LogicalTableScan(table=[[scott, EMP]]) -{% endhighlight %} - -### Push and pop - -The builder uses a stack to store the relational expression produced by -one step and pass it as an input to the next step. This allows the -methods that produce relational expressions to produce a builder. - -Most of the time, the only stack method you will use is `build()`, to get the -last relational expression, namely the root of the tree. - -Sometimes the stack becomes so deeply nested it gets confusing. To keep things -straight, you can remove expressions from the stack. For example, here we are -building a bushy join: - -{% highlight text %} -. - join - / \ - join join - / \ / \ -CUSTOMERS ORDERS LINE_ITEMS PRODUCTS -{% endhighlight %} - -We build it in three stages. Store the intermediate results in variables -`left` and `right`, and use `push()` to put them back on the stack when it is -time to create the final `Join`: - -{% highlight java %} -final RelNode left = builder - .scan("CUSTOMERS") - .scan("ORDERS") - .join(JoinRelType.INNER, "ORDER_ID") - .build(); - -final RelNode right = builder - .scan("LINE_ITEMS") - .scan("PRODUCTS") - .join(JoinRelType.INNER, "PRODUCT_ID") - .build(); - -final RelNode result = builder - .push(left) - .push(right) - .join(JoinRelType.INNER, "ORDER_ID") - .build(); -{% endhighlight %} - -### Field names and ordinals - -You can reference a field by name or ordinal. - -Ordinals are zero-based. Each operator guarantees the order in which its output -fields occur. For example, `Project` returns the fields in the generated by -each of the scalar expressions. - -The field names of an operator are guaranteed to be unique, but sometimes that -means that the names are not exactly what you expect. For example, when you -join EMP to DEPT, one of the output fields will be called DEPTNO and another -will be called something like DEPTNO_1. - -Some relational expression methods give you more control over field names: - -* `project` lets you wrap expressions using `alias(expr, fieldName)`. It - removes the wrapper but keeps the suggested name (as long as it is unique). -* `values(String[] fieldNames, Object... values)` accepts an array of field - names. If any element of the array is null, the builder will generate a unique - name. - -If an expression projects an input field, or a cast of an input field, it will -use the name of that input field. - -Once the unique field names have been assigned, the names are immutable. -If you have a particular `RelNode` instance, you can rely on the field names not -changing. In fact, the whole relational expression is immutable. - -But if a relational expression has passed through several rewrite rules (see -([RelOptRule]({{ site.apiRoot }}/org/apache/calcite/plan/RelOptRule.html)), the field -names of the resulting expression might not look much like the originals. -At that point it is better to reference fields by ordinal. - -When you are building a relational expression that accepts multiple inputs, -you need to build field references that take that into account. This occurs -most often when building join conditions. - -Suppose you are building a join on EMP, -which has 8 fields [EMPNO, ENAME, JOB, MGR, HIREDATE, SAL, COMM, DEPTNO] -and DEPT, -which has 3 fields [DEPTNO, DNAME, LOC]. -Internally, Calcite represents those fields as offsets into -a combined input row with 11 fields: the first field of the left input is -field #0 (0-based, remember), and the first field of the right input is -field #8. - -But through the builder API, you specify which field of which input. -To reference "SAL", internal field #5, -write `builder.field(2, 0, "SAL")` -or `builder.field(2, 0, 5)`. -This means "the field #5 of input #0 of two inputs". -(Why does it need to know that there are two inputs? Because they are stored on -the stack; input #1 is at the top of the stack, and input #0 is below it. -If we did not tell the builder that were two inputs, it would not know how deep -to go for input #0.) - -Similarly, to reference "DNAME", internal field #9 (8 + 1), -write `builder.field(2, 1, "DNAME")` -or `builder.field(2, 1, 1)`. - -### API summary - -#### Relational operators - -The following methods create a relational expression -([RelNode]({{ site.apiRoot }}/org/apache/calcite/rel/RelNode.html)), -push it onto the stack, and -return the `RelBuilder`. - -| Method | Description -|:------------------- |:----------- -| `scan(tableName)` | Creates a [TableScan]({{ site.apiRoot }}/org/apache/calcite/rel/core/TableScan.html). -| `values(fieldNames, value...)`<br/>`values(rowType, tupleList)` | Creates a [Values]({{ site.apiRoot }}/org/apache/calcite/rel/core/Values.html). -| `filter(expr...)`<br/>`filter(exprList)` | Creates a [Filter]({{ site.apiRoot }}/org/apache/calcite/rel/core/Filter.html) over the AND of the given predicates. -| `project(expr...)`<br/>`project(exprList [, fieldNames])` | Creates a [Project]({{ site.apiRoot }}/org/apache/calcite/rel/core/Project.html). To override the default name, wrap expressions using `alias`, or specify the `fieldNames` argument. -| `permute(mapping)` | Creates a [Project]({{ site.apiRoot }}/org/apache/calcite/rel/core/Project.html) that permutes the fields using `mapping`. -| `convert(rowType [, rename])` | Creates a [Project]({{ site.apiRoot }}/org/apache/calcite/rel/core/Project.html) that converts the fields to the given types, optionally also renaming them. -| `aggregate(groupKey, aggCall...)`<br/>`aggregate(groupKey, aggCallList)` | Creates an [Aggregate]({{ site.apiRoot }}/org/apache/calcite/rel/core/Aggregate.html). -| `distinct()` | Creates an [Aggregate]({{ site.apiRoot }}/org/apache/calcite/rel/core/Aggregate.html) that eliminates duplicate records. -| `sort(fieldOrdinal...)`<br/>`sort(expr...)`<br/>`sort(exprList)` | Creates a [Sort]({{ site.apiRoot }}/org/apache/calcite/rel/core/Sort.html).<br/><br/>In the first form, field ordinals are 0-based, and a negative ordinal indicates descending; for example, -2 means field 1 descending.<br/><br/>In the other forms, you can wrap expressions in `as`, `nullsFirst` or `nullsLast`. -| `sortLimit(offset, fetch, expr...)`<br/>`sortLimit(offset, fetch, exprList)` | Creates a [Sort]({{ site.apiRoot }}/org/apache/calcite/rel/core/Sort.html) with offset and limit. -| `limit(offset, fetch)` | Creates a [Sort]({{ site.apiRoot }}/org/apache/calcite/rel/core/Sort.html) that does not sort, only applies with offset and limit. -| `join(joinType, expr...)`<br/>`join(joinType, exprList)`<br/>`join(joinType, fieldName...)` | Creates a [Join]({{ site.apiRoot }}/org/apache/calcite/rel/core/Join.html) of the two most recent relational expressions.<br/><br/>The first form joins on a boolean expression (multiple conditions are combined using AND).<br/><br/>The last form joins on named fields; each side must have a field of each name. -| `semiJoin(expr)` | Creates a [SemiJoin]({{ site.apiRoot }}/org/apache/calcite/rel/core/SemiJoin.html) of the two most recent relational expressions. -| `union(all [, n])` | Creates a [Union]({{ site.apiRoot }}/org/apache/calcite/rel/core/Union.html) of the `n` (default two) most recent relational expressions. -| `intersect(all [, n])` | Creates an [Intersect]({{ site.apiRoot }}/org/apache/calcite/rel/core/Intersect.html) of the `n` (default two) most recent relational expressions. -| `minus(all)` | Creates a [Minus]({{ site.apiRoot }}/org/apache/calcite/rel/core/Minus.html) of the two most recent relational expressions. - -Argument types: - -* `expr` [RexNode]({{ site.apiRoot }}/org/apache/calcite/rex/RexNode.html) -* `expr...` Array of [RexNode]({{ site.apiRoot }}/org/apache/calcite/rex/RexNode.html) -* `exprList` Iterable of [RexNode]({{ site.apiRoot }}/org/apache/calcite/rex/RexNode.html) -* `fieldOrdinal` Ordinal of a field within its row (starting from 0) -* `fieldName` Name of a field, unique within its row -* `fieldName...` Array of String -* `fieldNames` Iterable of String -* `rowType` [RelDataType]({{ site.apiRoot }}/org/apache/calcite/rel/type/RelDataType.html) -* `groupKey` [RelBuilder.GroupKey]({{ site.apiRoot }}/org/apache/calcite/tools/RelBuilder.GroupKey.html) -* `aggCall...` Array of [RelBuilder.AggCall]({{ site.apiRoot }}/org/apache/calcite/tools/RelBuilder.AggCall.html) -* `aggCallList` Iterable of [RelBuilder.AggCall]({{ site.apiRoot }}/org/apache/calcite/tools/RelBuilder.AggCall.html) -* `value...` Array of Object -* `value` Object -* `tupleList` Iterable of List of [RexLiteral]({{ site.apiRoot }}/org/apache/calcite/rex/RexLiteral.html) -* `all` boolean -* `distinct` boolean -* `alias` String - -The builder methods perform various optimizations, including: -* `project` returns its input if asked to project all columns in order -* `filter` flattens the condition (so an `AND` and `OR` may have more than 2 children), - simplifies (converting say `x = 1 AND TRUE` to `x = 1`) -* If you apply `sort` then `limit`, the effect is as if you had called `sortLimit` - -### Stack methods - - -| Method | Description -|:------------------- |:----------- -| `build()` | Pops the most recently created relational expression off the stack -| `push(rel)` | Pushes a relational expression onto the stack. Relational methods such as `scan`, above, call this method, but user code generally does not -| `pushAll(collection)` | Pushes a collection of relational expressions onto the stack -| `peek()` | Returns the relational expression most recently put onto the stack, but does not remove it - -#### Scalar expression methods - -The following methods return a scalar expression -([RexNode]({{ site.apiRoot }}/org/apache/calcite/rex/RexNode.html)). - -Many of them use the contents of the stack. For example, `field("DEPTNO")` -returns a reference to the "DEPTNO" field of the relational expression just -added to the stack. - -| Method | Description -|:------------------- |:----------- -| `literal(value)` | Constant -| `field(fieldName)` | Reference, by name, to a field of the top-most relational expression -| `field(fieldOrdinal)` | Reference, by ordinal, to a field of the top-most relational expression -| `field(inputCount, inputOrdinal, fieldName)` | Reference, by name, to a field of the (`inputCount` - `inputOrdinal`)th relational expression -| `field(inputCount, inputOrdinal, fieldOrdinal)` | Reference, by ordinal, to a field of the (`inputCount` - `inputOrdinal`)th relational expression -| `fields(fieldOrdinalList)` | List of expressions referencing input fields by ordinal -| `fields(mapping)` | List of expressions referencing input fields by a given mapping -| `fields(collation)` | List of expressions, `exprList`, such that `sort(exprList)` would replicate collation -| `call(op, expr...)`<br/>`call(op, exprList)` | Call to a function or operator -| `and(expr...)`<br/>`and(exprList)` | Logical AND. Flattens nested ANDs, and optimizes cases involving TRUE and FALSE. -| `or(expr...)`<br/>`or(exprList)` | Logical OR. Flattens nested ORs, and optimizes cases involving TRUE and FALSE. -| `not(expr)` | Logical NOT -| `equals(expr, expr)` | Equals -| `isNull(expr)` | Checks whether an expression is null -| `isNotNull(expr)` | Checks whether an expression is not null -| `alias(expr, fieldName)` | Renames an expression (only valid as an argument to `project`) -| `cast(expr, typeName)`<br/>`cast(expr, typeName, precision)`<br/>`cast(expr, typeName, precision, scale)`<br/> | Converts an expression to a given type -| `desc(expr)` | Changes sort direction to descending (only valid as an argument to `sort` or `sortLimit`) -| `nullsFirst(expr)` | Changes sort order to nulls first (only valid as an argument to `sort` or `sortLimit`) -| `nullsLast(expr)` | Changes sort order to nulls last (only valid as an argument to `sort` or `sortLimit`) - -### Group key methods - -The following methods return a -[RelBuilder.GroupKey]({{ site.apiRoot }}/org/apache/calcite/tools/RelBuilder.GroupKey.html). - -| Method | Description -|:------------------- |:----------- -| `groupKey(fieldName...)`<br/>`groupKey(fieldOrdinal...)`<br/>`groupKey(expr...)`<br/>`groupKey(exprList)` | Creates a group key of the given expressions -| `groupKey(exprList, exprListList)` | Creates a group key of the given expressions with grouping sets -| `groupKey(bitSet, bitSets)` | Creates a group key of the given input columns with grouping sets - -### Aggregate call methods - -The following methods return an -[RelBuilder.AggCall]({{ site.apiRoot }}/org/apache/calcite/tools/RelBuilder.AggCall.html). - -| Method | Description -|:------------------- |:----------- -| `aggregateCall(op, distinct, filter, alias, expr...)`<br/>`aggregateCall(op, distinct, filter, alias, exprList)` | Creates a call to a given aggregate function, with an optional filter expression -| `count(distinct, alias, expr...)` | Creates a call to the COUNT aggregate function -| `countStar(alias)` | Creates a call to the COUNT(*) aggregate function -| `sum(distinct, alias, expr)` | Creates a call to the SUM aggregate function -| `min(alias, expr)` | Creates a call to the MIN aggregate function -| `max(alias, expr)` | Creates a call to the MAX aggregate function http://git-wip-us.apache.org/repos/asf/calcite/blob/65f2afa7/avatica/site/_docs/avatica_json_reference.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/avatica_json_reference.md b/avatica/site/_docs/avatica_json_reference.md deleted file mode 100644 index d49be7c..0000000 --- a/avatica/site/_docs/avatica_json_reference.md +++ /dev/null @@ -1,1086 +0,0 @@ ---- -layout: docs -title: Avatica JSON Reference -sidebar_title: JSON Reference -permalink: /docs/avatica_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/avatica_overview.md ---------------------------------------------------------------------- diff --git a/avatica/site/_docs/avatica_overview.md b/avatica/site/_docs/avatica_overview.md deleted file mode 100644 index 6c77eb9..0000000 --- a/avatica/site/_docs/avatica_overview.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -layout: docs -title: Avatica Overview -sidebar_title: Overview -permalink: /docs/avatica_overview.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 %} ---> - -Avatica is a framework for building JDBC and ODBC drivers for databases, -and an RPC wire protocol. - - - -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. - -Avatica's wire protocol is JSON over HTTP. -The Java implementation uses Jackson to convert request/response command -objects to/from JSON. - -Avatica-Server is a Java implementation of Avatica RPC. - -Core concepts: - -* 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 - -## JDBC - -Avatica implements JDBC by means of Factory. -Factory creates implementations of the JDBC classes (Driver, Connection, -Statement, PreparedStatement, ResultSet) on top of a Meta. - -## ODBC - -Work has not started on Avatica ODBC. - -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++. - -Since the Avatica protocol abstracts many of the differences between providers, -the same ODBC client could be used for different databases. - -## HTTP Server - -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. - -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: - -{% 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 %} - -## Project structure - -We know that it is important that client libraries have minimal dependencies. - -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
