答复: 【可能伪造邮件 POSSIBLY SPOOFED 】Re: The relationship among SQL documents

[程建云 <ch...@360.cn>]

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 <qi...@apache.org>
发送时间: 2021年8月17日 15:12:09
收件人: dev@iotdb.apache.org
主题: 【可能伪造邮件 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 <sa...@gmail.com> 于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
>
>  黄向东
> 清华大学 软件学院
>

Re: Re: The relationship among SQL documents

[Xiangdong Huang <sa...@gmail.com>]

ideally,  it should contain all features in [1].
[2] is grammar syntax description.

-----------------------------------
Xiangdong Huang
School of Software, Tsinghua University

 黄向东
清华大学 软件学院

程建云 <ch...@360.cn> 于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 <qi...@apache.org>
> 发送时间: 2021年8月17日 15:12:09
> 收件人: dev@iotdb.apache.org
> 主题: 【可能伪造邮件 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 <sa...@gmail.com> 于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
> >
> >  黄向东
> > 清华大学 软件学院
> >