Skip to content

Latest commit

 

History

History
393 lines (294 loc) · 9.82 KB

MODEL.md

File metadata and controls

393 lines (294 loc) · 9.82 KB
Raw

Calcite JSON model reference

Elements

Root

{
  version: '1.0',
  defaultSchema: 'mongo',
  schemas: [ Schema... ]
}

version (required string) must have value 1.0.

defaultSchema (optional string). If specified, it is the name (case-sensitive) of a schema defined in this model, and will become the default schema for connections to Calcite that use this model.

schemas (optional list of Schema elements).

Schema

Occurs within root.schemas.

{
  name: 'foodmart',
  path: ['lib'],
  cache: true,
  materializations: [ Materialization... ]
}

name (required string) is the name of the schema.

type (optional string, default map) indicates sub-type. Values are:

path (optional list) is the SQL path that is used to resolve functions used in this schema. If specified it must be a list, and each element of the list must be either a string or a list of strings. For example,

  path: [ ['usr', 'lib'], 'lib' ]

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 string.

materializations (optional list of Materialization) defines the tables in this schema that are materializations of queries.

cache (optional boolean, default true) tells Calcite whether to cache metadata (tables, functions and sub-schemas) generated by this schema.

  • If false, Calcite will go back to the schema each time it needs metadata, for example, each time it needs a list of tables in order to validate a query against the schema.

  • If true, Calcite will cache the metadata the first time it reads it. This can lead to better performance, especially if name-matching is case-insensitive.

However, it also leads to the problem of cache staleness. A particular schema implementation can override the Schema.contentsHaveChangedSince method to tell Calcite when it should consider its cache to be out of date.

Tables, functions and sub-schemas explicitly created in a schema are not affected by this caching mechanism. They always appear in the schema immediately, and are never flushed.

Map Schema

Like base class Schema, occurs within root.schemas.

{
  name: 'foodmart',
  type: 'map',
  tables: [ Table... ],
  functions: [ Function... ]
}

name, type, path, cache, materializations inherited from Schema.

tables (optional list of Table elements) defines the tables in this schema.

functions (optional list of Function elements) defines the functions in this schema.

Custom Schema

Like base class Schema, occurs within root.schemas.

{
  name: 'mongo',
  type: 'custom',
  factory: 'org.apache.calcite.adapter.mongodb.MongoSchemaFactory',
  operand: {
    host: 'localhost',
    database: 'test'
  }
}

name, type, path, cache, materializations inherited from Schema.

factory (required string) is the name of the factory class for this schema. Must implement interface org.apache.calcite.schema.SchemaFactory and have a public default constructor.

operand (optional map) contains attributes to be passed to the factory.

JDBC Schema

Like base class Schema, occurs within root.schemas.

{
  name: 'foodmart',
  type: 'jdbc',
  jdbcDriver: TODO,
  jdbcUrl: TODO,
  jdbcUser: TODO,
  jdbcPassword: TODO,
  jdbcCatalog: TODO,
  jdbcSchema: TODO
}

name, type, path, cache, materializations inherited from Schema.

jdbcDriver (optional string) is the name of the JDBC driver class. It not specified, uses whichever class the JDBC DriverManager chooses.

jdbcUrl (optional string) is the JDBC connect string, for example "jdbc:mysql://localhost/foodmart".

jdbcUser (optional string) is the JDBC user name.

jdbcPassword (optional string) is the JDBC password.

jdbcCatalog (optional string) is the name of the initial catalog in the JDBC data source.

jdbcSchema (optional string) is the name of the initial schema in the JDBC data source.

Materialization

Occurs within root.schemas.materializations.

{
  view: 'V',
  table: 'T',
  sql: 'select deptno, count(*) as c, sum(sal) as s from emp group by deptno'
}

view (optional string) TODO

table (optional string) TODO

sql (optional string, or list of strings that will be concatenated as a multi-line string) is the SQL definition of the materialization.

Table

Occurs within root.schemas.tables.

{
  name: 'sales_fact',
  columns: [ Column... ]
}

name (required string) is the name of this table. Must be unique within the schema.

type (optional string, default custom) indicates sub-type. Values are:

columns (optional list of Column elements)

View

Like base class Table, occurs within root.schemas.tables.

{
  name: 'female_emps',
  type: 'view',
  sql: "select * from emps where gender = 'F'"
}

name, type, columns inherited from Table.

sql (required string, or list of strings that will be concatenated as a multi-line string) is the SQL definition of the view.

path (optional list) is the SQL path to resolve the query. If not specified, defaults to the current schema.

Custom Table

Like base class Table, occurs within root.schemas.tables.

{
  name: 'female_emps',
  type: 'custom',
  factory: 'TODO',
  operand: {
    todo: 'TODO'
  }
}

name, type, columns inherited from Table.

factory (required string) is the name of the factory class for this table. Must implement interface org.apache.calcite.schema.TableFactory and have a public default constructor.

operand (optional map) contains attributes to be passed to the factory.

Column

Occurs within root.schemas.tables.columns.

{
  name: 'empno'
}

name (required string) is the name of this column.

Function

Occurs within root.schemas.functions.

{
  name: 'MY_PLUS',
  className: 'com.example.functions.MyPlusFunction',
  methodName: 'apply',
  path: []
}

name (required string) is the name of this function.

className (required string) is the name of the class that implements this function.

methodName (optional string) is the name of the method that implements this function.

path (optional list of string) is the path for resolving this function.

Lattice

Occurs within root.schemas.lattices.

{
  name: 'star',
  sql: [
    'select 1 from "foodmart"."sales_fact_1997" as "s"',
    'join "foodmart"."product" as "p" using ("product_id")',
    'join "foodmart"."time_by_day" as "t" using ("time_id")',
    'join "foodmart"."product_class" as "pc" on "p"."product_class_id" = "pc"."product_class_id"'
  ],
  auto: false,
  algorithm: true,
  algorithmMaxMillis: 10000,
  rowCountEstimate: 86837,
  defaultMeasures: [ {
    agg: 'count'
  } ],
  tiles: [ {
    dimensions: [ 'the_year', ['t', 'quarter'] ],
    measures: [ {
      agg: 'sum',
      args: 'unit_sales'
    }, {
      agg: 'sum',
      args: 'store_sales'
    }, {
      agg: 'count'
    } ]
  } ]
}

name (required string) is the name of this lattice.

sql (required string, or list of strings that will be concatenated as a multi-line string) is the SQL statement that defines the fact table, dimension tables, and join paths for this lattice.

auto (optional boolean, default true) is whether to materialize tiles on need as queries are executed.

algorithm (optional boolean, default false) is whether to use an optimization algorithm to suggest and populate an initial set of tiles.

algorithmMaxMillis (optional long, default -1, meaning no limit) is the maximum number of milliseconds for which to run the algorithm. After this point, takes the best result the algorithm has come up with so far.

rowCountEstimate (optional double, default 1000.0) estimated number of rows in the star

tiles (optional list of Tile elements) is a list of materialized aggregates to create up front.

defaultMeasures (optional list of Measure elements) is a list of measures that a tile should have by default. Any tile defined in tiles can still define its own measures, including measures not on this list. If not specified, the default list of measures is just 'count(*)':

[ { name: 'count' } ]

Tile

Occurs within root.schemas.lattices.tiles.

{
  dimensions: [ 'the_year', ['t', 'quarter'] ],
  measures: [ {
    agg: 'sum',
    args: 'unit_sales'
  }, {
    agg: 'sum',
    args: 'store_sales'
  }, {
    agg: 'count'
  } ]
}

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).

measures (optional list of Measure elements) is a list of aggregate functions applied to arguments. If not specified, uses the lattice's default measure list.

Measure

Occurs within root.schemas.lattices.defaultMeasures and root.schemas.lattices.tiles.measures.

{
  agg: 'sum',
  args: [ 'unit_sales' ]
}

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).