SchemaPlus rootSchema = Frameworks.createRootSchema(true);
rootSchema.add("USERS", new AbstractTable() { //note: add a table
    @Override
    public RelDataType getRowType(final RelDataTypeFactory typeFactory) {
        RelDataTypeFactory.Builder builder = typeFactory.builder();

        builder.add("ID", new BasicSqlType(new RelDataTypeSystemImpl() {}, SqlTypeName.INTEGER));
        builder.add("NAME", new BasicSqlType(new RelDataTypeSystemImpl() {}, SqlTypeName.CHAR));
        builder.add("AGE", new BasicSqlType(new RelDataTypeSystemImpl() {}, SqlTypeName.INTEGER));
        return builder.build();
    }
});

rootSchema.add("JOBS", new AbstractTable() {
    @Override
    public RelDataType getRowType(final RelDataTypeFactory typeFactory) {
        RelDataTypeFactory.Builder builder = typeFactory.builder();

        builder.add("ID", new BasicSqlType(new RelDataTypeSystemImpl() {}, SqlTypeName.INTEGER));
        builder.add("NAME", new BasicSqlType(new RelDataTypeSystemImpl() {}, SqlTypeName.CHAR));
        builder.add("COMPANY", new BasicSqlType(new RelDataTypeSystemImpl() {}, SqlTypeName.CHAR));
        return builder.build();
    }
});

SqlParser parser = SqlParser.create(sql, SqlParser.Config.DEFAULT);
SqlNode sqlNode = parser.parseStmt();

// org.apache.calcite.sql.parser.SqlParser
public SqlNode parseStmt() throws SqlParseException {
  return parseQuery();
}

public SqlNode parseQuery() throws SqlParseException {
  try {
    return parser.parseSqlStmtEof(); //note: 解析sql语句
  } catch (Throwable ex) {
    if (ex instanceof CalciteContextException) {
      final String originalSql = parser.getOriginalSql();
      if (originalSql != null) {
        ((CalciteContextException) ex).setOriginalStatement(originalSql);
      }
    }
    throw parser.normalizeException(ex);
  }
}

//org.apache.calcite.sql.parser.impl.SqlParserImpl
public SqlNode parseSqlStmtEof() throws Exception
{
  return SqlStmtEof();
}

/**
 * Parses an SQL statement followed by the end-of-file symbol.
 * note:解析SQL语句(后面有文件结束符号)
 */
final public SqlNode SqlStmtEof() throws ParseException {
  SqlNode stmt;
  stmt = SqlStmt();
  jj_consume_token(0);
      {if (true) return stmt;}
  throw new Error("Missing return statement in function");
}

 //note: 解析 SQL statement
final public SqlNode SqlStmt() throws ParseException {
  SqlNode stmt;
  if (jj_2_34(2)) {
    stmt = SqlSetOption(Span.of(), null);
  } else if (jj_2_35(2)) {
    stmt = SqlAlter();
  } else if (jj_2_36(2)) {
    stmt = OrderedQueryOrExpr(ExprContext.ACCEPT_QUERY);
  } else if (jj_2_37(2)) {
    stmt = SqlExplain();
  } else if (jj_2_38(2)) {
    stmt = SqlDescribe();
  } else if (jj_2_39(2)) {
    stmt = SqlInsert();
  } else if (jj_2_40(2)) {
    stmt = SqlDelete();
  } else if (jj_2_41(2)) {
    stmt = SqlUpdate();
  } else if (jj_2_42(2)) {
    stmt = SqlMerge();
  } else if (jj_2_43(2)) {
    stmt = SqlProcedureCall();
  } else {
    jj_consume_token(-1);
    throw new ParseException();
  }
      {if (true) return stmt;}
  throw new Error("Missing return statement in function");
}

//note: 二、sql validate（会先通过Catalog读取获取相应的metadata和namespace）
//note: get metadata and namespace
SqlTypeFactoryImpl factory = new SqlTypeFactoryImpl(RelDataTypeSystem.DEFAULT);
CalciteCatalogReader calciteCatalogReader = new CalciteCatalogReader(
    CalciteSchema.from(rootScheme),
    CalciteSchema.from(rootScheme).path(null),
    factory,
    new CalciteConnectionConfigImpl(new Properties()));

//note: 校验（包括对表名，字段名，函数名，字段类型的校验。）
SqlValidator validator = SqlValidatorUtil.newValidator(SqlStdOperatorTable.instance(), calciteCatalogReader, factory,
    conformance(frameworkConfig));
SqlNode validateSqlNode = validator.validate(sqlNode);

//org.apache.calcite.schema.impl.AbstractSchema
/**
 * Returns a map of tables in this schema by name.
 *
 * <p>The implementations of {@link #getTableNames()}
 * and {@link #getTable(String)} depend on this map.
 * The default implementation of this method returns the empty map.
 * Override this method to change their behavior.</p>
 *
 * @return Map of tables in this schema by name
 */
protected Map<String, Table> getTableMap() {
  return ImmutableMap.of();
}

//org.apache.calcite.adapter.csvorg.apache.calcite.adapter.csv.CsvSchemasvSchema
//note: 创建表
@Override protected Map<String, Table> getTableMap() {
  if (tableMap == null) {
    tableMap = createTableMap();
  }
  return tableMap;
}

org.apache.calcite.sql.validate.SqlValidatorImpl
//note: 做相应的语法树校验
public SqlNode validate(SqlNode topNode) {
  //note: root 对应的 Scope
  SqlValidatorScope scope = new EmptyScope(this);
  scope = new CatalogScope(scope, ImmutableList.of("CATALOG"));
  //note: 1.rewrite expression
  //note: 2.做相应的语法检查
  final SqlNode topNode2 = validateScopedExpression(topNode, scope); //note: 验证
  final RelDataType type = getValidatedNodeType(topNode2);
  Util.discard(type);
  return topNode2;
}

private SqlNode validateScopedExpression(
    SqlNode topNode,
    SqlValidatorScope scope) {
  //note: 1. rewrite expression，将其标准化，便于后面的逻辑计划优化
  SqlNode outermostNode = performUnconditionalRewrites(topNode, false);
  cursorSet.add(outermostNode);
  top = outermostNode;
  TRACER.trace("After unconditional rewrite: {}", outermostNode);
  //note: 2. Registers a query in a parent scope.
  //note: register scopes and namespaces implied a relational expression
  if (outermostNode.isA(SqlKind.TOP_LEVEL)) {
    registerQuery(scope, null, outermostNode, outermostNode, null, false);
  }
  //note: 3. catalog 验证，调用 SqlNode 的 validate 方法，
  outermostNode.validate(this, scope);
  if (!outermostNode.isA(SqlKind.TOP_LEVEL)) {
    // force type derivation so that we can provide it to the
    // caller later without needing the scope
    deriveType(scope, outermostNode);
  }
  TRACER.trace("After validation: {}", outermostNode);
  return outermostNode;
}

/**
 * Parse tree node that represents an {@code ORDER BY} on a query other than a
 * {@code SELECT} (e.g. {@code VALUES} or {@code UNION}).
 *
 * <p>It is a purely syntactic operator, and is eliminated by
 * {@link org.apache.calcite.sql.validate.SqlValidatorImpl#performUnconditionalRewrites}
 * and replaced with the ORDER_OPERAND of SqlSelect.</p>
 */
public class SqlOrderBy extends SqlCall {

/**
 * <h3>Scopes</h3>
 *
 * <p>In the query</p>
 *
 * <blockquote>
 * <pre>
 * SELECT expr1
 * FROM t1,
 *     t2,
 *     (SELECT expr2 FROM t3) AS q3
 * WHERE c1 IN (SELECT expr3 FROM t4)
 * ORDER BY expr4</pre>
 * </blockquote>
 *
 * <p>The scopes available at various points of the query are as follows:</p>
 *
 * <ul>
 * <li>expr1 can see t1, t2, q3</li>
 * <li>expr2 can see t3</li>
 * <li>expr3 can see t4, t1, t2</li>
 * <li>expr4 can see t1, t2, q3, plus (depending upon the dialect) any aliases
 * defined in the SELECT clause</li>
 * </ul>
 *
 * <h3>Namespaces</h3>
 *
 * <p>In the above query, there are 4 namespaces:</p>
 *
 * <ul>
 * <li>t1</li>
 * <li>t2</li>
 * <li>(SELECT expr2 FROM t3) AS q3</li>
 * <li>(SELECT expr3 FROM t4)</li>
 */

public void validate(SqlValidator validator, SqlValidatorScope scope) {
  validator.validateQuery(this, scope, validator.getUnknownType());
}

public void validateQuery(SqlNode node, SqlValidatorScope scope,
    RelDataType targetRowType) {
  final SqlValidatorNamespace ns = getNamespace(node, scope);
  if (node.getKind() == SqlKind.TABLESAMPLE) {
    List<SqlNode> operands = ((SqlCall) node).getOperandList();
    SqlSampleSpec sampleSpec = SqlLiteral.sampleValue(operands.get(1));
    if (sampleSpec instanceof SqlSampleSpec.SqlTableSampleSpec) {
      validateFeature(RESOURCE.sQLFeature_T613(), node.getParserPosition());
    } else if (sampleSpec
        instanceof SqlSampleSpec.SqlSubstitutionSampleSpec) {
      validateFeature(RESOURCE.sQLFeatureExt_T613_Substitution(),
          node.getParserPosition());
    }
  }

  validateNamespace(ns, targetRowType);//note: 检查
  switch (node.getKind()) {
  case EXTEND:
    // Until we have a dedicated namespace for EXTEND
    deriveType(scope, node);
  }
  if (node == top) {
    validateModality(node);
  }
  validateAccess(
      node,
      ns.getTable(),
      SqlAccessEnum.SELECT);
}

/**
 * Validates a namespace.
 *
 * @param namespace Namespace
 * @param targetRowType Desired row type, must not be null, may be the data
 *                      type 'unknown'.
 */
protected void validateNamespace(final SqlValidatorNamespace namespace,
    RelDataType targetRowType) {
  namespace.validate(targetRowType);//note: 验证
  if (namespace.getNode() != null) {
    setValidatedNodeType(namespace.getNode(), namespace.getType());
  }
}

//org.apache.calcite.sql.validate.AbstractNamespace
public final void validate(RelDataType targetRowType) {
  switch (status) {
  case UNVALIDATED: //note: 还没开始 check
    try {
      status = SqlValidatorImpl.Status.IN_PROGRESS; //note: 更新当前 namespace 的状态
      Preconditions.checkArgument(rowType == null,
          "Namespace.rowType must be null before validate has been called");
      RelDataType type = validateImpl(targetRowType); //note: 检查验证
      Preconditions.checkArgument(type != null,
          "validateImpl() returned null");
      setType(type);
    } finally {
      status = SqlValidatorImpl.Status.VALID;
    }
    break;
  case IN_PROGRESS: //note: 已经开始 check 了，死循环了
    throw new AssertionError("Cycle detected during type-checking");
  case VALID://note: 检查结束
    break;
  default:
    throw Util.unexpected(status);
  }
}

//org.apache.calcite.sql.validate.SelectNamespace
//note: 检查，还是调用 SqlValidatorImpl 的方法
public RelDataType validateImpl(RelDataType targetRowType) {
  validator.validateSelect(select, targetRowType);
  return rowType;
}

// create the rexBuilder
final RexBuilder rexBuilder =  new RexBuilder(factory);
// init the planner
// 这里也可以注册 VolcanoPlanner，这一步 planner 并没有使用
HepProgramBuilder builder = new HepProgramBuilder();
RelOptPlanner planner = new HepPlanner(builder.build());

//note: init cluster: An environment for related relational expressions during the optimization of a query.
final RelOptCluster cluster = RelOptCluster.create(planner, rexBuilder);
//note: init SqlToRelConverter
final SqlToRelConverter.Config config = SqlToRelConverter.configBuilder()
    .withConfig(frameworkConfig.getSqlToRelConverterConfig())
    .withTrimUnusedFields(false)
    .withConvertTableAccess(false)
    .build(); //note: config
// 创建 SqlToRelConverter 实例，cluster、calciteCatalogReader、validator 都传进去了，SqlToRelConverter 会缓存这些对象
final SqlToRelConverter sqlToRelConverter = new SqlToRelConverter(new DogView(), validator, calciteCatalogReader, cluster, StandardConvertletTable.INSTANCE, config);
// convert to RelNode
RelRoot root = sqlToRelConverter.convertQuery(validateSqlNode, false, true);

root = root.withRel(sqlToRelConverter.flattenTypes(root.rel, true));
final RelBuilder relBuilder = config.getRelBuilderFactory().create(cluster, null);
root = root.withRel(RelDecorrelator.decorrelateQuery(root.rel, relBuilder));

RelNode relNode = root.rel;

//DogView 的实现
private static class DogView implements RelOptTable.ViewExpander {
    public DogView() {
    }

    @Override
    public RelRoot expandView(RelDataType rowType, String queryString, List<String> schemaPath,
                              List<String> viewPath) {
        return null;
    }
}

org.apache.calcite.plan.RelOptCluster

/** Creates a cluster. */
public static RelOptCluster create(RelOptPlanner planner,
    RexBuilder rexBuilder) {
  return new RelOptCluster(planner, rexBuilder.getTypeFactory(),
      rexBuilder, new AtomicInteger(0), new HashMap<>());
}

/**
 * Creates a cluster.
 *
 * <p>For use only from {@link #create} and {@link RelOptQuery}.
 */
RelOptCluster(RelOptPlanner planner, RelDataTypeFactory typeFactory,
    RexBuilder rexBuilder, AtomicInteger nextCorrel,
    Map<String, RelNode> mapCorrelToRel) {
  this.nextCorrel = nextCorrel;
  this.mapCorrelToRel = mapCorrelToRel;
  this.planner = Objects.requireNonNull(planner);
  this.typeFactory = Objects.requireNonNull(typeFactory);
  this.rexBuilder = rexBuilder;
  this.originalExpression = rexBuilder.makeLiteral("?");

  // set up a default rel metadata provider,
  // giving the planner first crack at everything
  //note: 默认的 metadata provider
  setMetadataProvider(DefaultRelMetadataProvider.INSTANCE);
  //note: trait（对于 HepPlaner 和 VolcanoPlanner 不一样)
  this.emptyTraitSet = planner.emptyTraitSet();
  assert emptyTraitSet.size() == planner.getRelTraitDefs().size();
}

/**
 * Converts an unvalidated query's parse tree into a relational expression.
 * note：把一个 parser tree 转换为 relational expression
 * @param query           Query to convert
 * @param needsValidation Whether to validate the query before converting;
 *                        <code>false</code> if the query has already been
 *                        validated.
 * @param top             Whether the query is top-level, say if its result
 *                        will become a JDBC result set; <code>false</code> if
 *                        the query will be part of a view.
 */
public RelRoot convertQuery(
    SqlNode query,
    final boolean needsValidation,
    final boolean top) {
  if (needsValidation) { //note: 是否需要做相应的校验（如果校验过了，这里就不需要了）
    query = validator.validate(query);
  }

  //note: 设置 MetadataProvider
  RelMetadataQuery.THREAD_PROVIDERS.set(
      JaninoRelMetadataProvider.of(cluster.getMetadataProvider()));
  //note: 得到 RelNode(relational expression)
  RelNode result = convertQueryRecursive(query, top, null).rel;
  if (top) {
    if (isStream(query)) {//note: 如果 stream 的话
      result = new LogicalDelta(cluster, result.getTraitSet(), result);
    }
  }
  RelCollation collation = RelCollations.EMPTY;
  if (!query.isA(SqlKind.DML)) { //note: 如果是 DML 语句
    if (isOrdered(query)) { //note: 如果需要做排序的话
      collation = requiredCollation(result);
    }
  }
  //note: 对转换前后的 RelDataType 做验证
  checkConvertedType(query, result);

  if (SQL2REL_LOGGER.isDebugEnabled()) {
    SQL2REL_LOGGER.debug(
        RelOptUtil.dumpPlan("Plan after converting SqlNode to RelNode",
            result, SqlExplainFormat.TEXT,
            SqlExplainLevel.EXPPLAN_ATTRIBUTES));
  }

  final RelDataType validatedRowType = validator.getValidatedNodeType(query);
  return RelRoot.of(result, validatedRowType, query.getKind())
      .withCollation(collation);
}

/**
 * Recursively converts a query to a relational expression.
 * note：递归地讲一个 query 转换为 relational expression
 *
 * @param query         Query
 * @param top           Whether this query is the top-level query of the
 *                      statement
 * @param targetRowType Target row type, or null
 * @return Relational expression
 */
protected RelRoot convertQueryRecursive(SqlNode query, boolean top,
    RelDataType targetRowType) {
  final SqlKind kind = query.getKind();
  switch (kind) {
  case SELECT:
    return RelRoot.of(convertSelect((SqlSelect) query, top), kind);
  case INSERT:
    return RelRoot.of(convertInsert((SqlInsert) query), kind);
  case DELETE:
    return RelRoot.of(convertDelete((SqlDelete) query), kind);
  case UPDATE:
    return RelRoot.of(convertUpdate((SqlUpdate) query), kind);
  case MERGE:
    return RelRoot.of(convertMerge((SqlMerge) query), kind);
  case UNION:
  case INTERSECT:
  case EXCEPT:
    return RelRoot.of(convertSetOp((SqlCall) query), kind);
  case WITH:
    return convertWith((SqlWith) query, top);
  case VALUES:
    return RelRoot.of(convertValues((SqlCall) query, targetRowType), kind);
  default:
    throw new AssertionError("not a query: " + query);
  }
}

/**
 * Converts a SELECT statement's parse tree into a relational expression.
 * note：将一个 Select parse tree 转换成一个关系表达式
 */
public RelNode convertSelect(SqlSelect select, boolean top) {
  final SqlValidatorScope selectScope = validator.getWhereScope(select);
  final Blackboard bb = createBlackboard(selectScope, null, top);
  convertSelectImpl(bb, select);//note: 做相应的转换
  return bb.root;
}

/**
 * Implementation of {@link #convertSelect(SqlSelect, boolean)};
 * derived class may override.
 */
protected void convertSelectImpl(
    final Blackboard bb,
    SqlSelect select) {
  //note: convertFrom
  convertFrom(
      bb,
      select.getFrom());
  //note: convertWhere
  convertWhere(
      bb,
      select.getWhere());

  final List<SqlNode> orderExprList = new ArrayList<>();
  final List<RelFieldCollation> collationList = new ArrayList<>();
  //note: 有 order by 操作时
  gatherOrderExprs(
      bb,
      select,
      select.getOrderList(),
      orderExprList,
      collationList);
  final RelCollation collation =
      cluster.traitSet().canonize(RelCollations.of(collationList));

  if (validator.isAggregate(select)) {
    //note: 当有聚合操作时，也就是含有 group by、having 或者 Select 和 order by 中含有聚合函数
    convertAgg(
        bb,
        select,
        orderExprList);
  } else { //note: 对 select list 部分的处理
    convertSelectList(
        bb,
        select,
        orderExprList);
  }

  if (select.isDistinct()) { //note: select 后面含有 DISTINCT 关键字时（去重）
    distinctify(bb, true);
  }
  //note: Converts a query's ORDER BY clause, if any.
  convertOrder(
      select, bb, collation, orderExprList, select.getOffset(),
      select.getFetch());
  bb.setRoot(bb.root, true);
}

HepProgramBuilder builder = new HepProgramBuilder();
builder.addRuleInstance(FilterJoinRule.FilterIntoJoinRule.FILTER_ON_JOIN); //note: 添加 rule
HepPlanner hepPlanner = new HepPlanner(builder.build());
hepPlanner.setRoot(relNode);
relNode = hepPlanner.findBestExp();