ideally, it should contain all features in [1]. [2] is grammar syntax description.
----------------------------------- Xiangdong Huang School of Software, Tsinghua University 黄向东 清华大学 软件学院 程建云 <[email protected]> 于2021年8月18日周三 下午2:43写道： > > 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 > > > > 黄向东 > > 清华大学 软件学院 > >
