As a new user of IoTDB, I didn't realize that [1] is for new supported feature until the @Xiangdong Huang pointed it out, lol. As [1] is much more user friendly, why not include all supported SQL in [1] and reconstruct the page as @Jialin Qiao side, so that everyone can refer it easily. IMHO, SQL is so important that worth a main page to introduce it. [2] is much more like an archive document.
It's better to have a new feature page for general purpose instead of only for SQL. The new SQL grammar could be introduced there and link detail to [1]. Thanks Jianyun Cheng ________________________________ 发件人: Jialin Qiao <[email protected]> 发送时间: 2021年8月17日 15:12:09 收件人: [email protected] 主题: 【可能伪造邮件 POSSIBLY SPOOFED 】Re: The relationship among SQL documents 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 > > 黄向东 > 清华大学 软件学院 >
