Hi, > From my side, [1] is for introducing what features we have. So, for a new query feature, we need to update doc [1] to introduce when to use it, and how to use it. But we can omit some cases that are rarely used.
+1, [1] is mainly for users, most user would prefer [1] than [2]. > Another choice is removing the document [1], but currently I do not think it is the time because they are more friendly for readers now. >From my side, never remove the document [1]. If we do this, users will get lost. ============================== I recommended reconstructing the document [1] like this [3], all functional SQL should be included here: ## set storage group // Function name According to the storage model we can set up the corresponding storage group. // Function introduction ### Syntax // here we only put the top-level syntax, not each part. If you want to see each part, go to the SQL reference SET STORAGE GROUP TO <FullPath> CREATE STORAGE GROUP TO <FullPath> Note: FullPath can not include `*` ### Example IoTDB > set storage group to root.ln IoTDB > create storage group root.sgcc ============================== Then the SQL reference is a transformation of sql.g4 [4] [3] https://docs.influxdata.com/influxdb/v1.8/query_language/explore-schema/ [4] https://docs.influxdata.com/influxdb/v1.8/query_language/spec/#query-representation Thanks, ————————————————— Jialin Qiao School of Software, Tsinghua University 乔嘉林 清华大学 软件学院 Xiangdong Huang <[email protected]> 于2021年8月17日周二 下午2:23写道： > Hi, > > When I review a PR for introducing a new SQL grammar into IoTDB, I > realize that our SQL documents are confusing contributors. > > 1. we have several documents under IoTDB-SQL-Language folder, like > [1], which introduces some important and frequent grammar. > > 2. we have a complete SQL reference document [2]. > > It is definitely that we need to update the document [2] when > introducing new SQL grammar. However, when should we update document > [1]? > > I think we need to make a convention. > > From my side, [1] is for introducing what features we have. So, for a > new query feature, we need to update doc [1] to introduce when to use > it, and how to use it. But we can omit some cases that are rarely > used. > > Another choice is removing the document [1], but currently I do not > think it is the time because they are more friendly for readers now. > > [1] > https://iotdb.apache.org/UserGuide/Master/IoTDB-SQL-Language/DML-Data-Manipulation-Language.html > [2] https://iotdb.apache.org/UserGuide/Master/Appendix/SQL-Reference.html > > Best, > ----------------------------------- > Xiangdong Huang > School of Software, Tsinghua University > > 黄向东 > 清华大学 软件学院 >
