Hi, - insertRecord - insertDeviceTablet (or insertTablet) - insertMultiDeviceTables (or insertTablets) - insertRecords
I prefer DeviceTablet. insertRecord and insertRecords are both ok. Thanks, -- Jialin Qiao School of Software, Tsinghua University 乔嘉林 清华大学 软件学院 > -----原始邮件----- > 发件人: "Xiangdong Huang" <[email protected]> > 发送时间: 2020-04-23 17:17:15 (星期四) > 收件人: [email protected] > 抄送: > 主题: Re: [Discuss] Method names in Session > > Hi, > > (A little long and you can skip the content to just read the conclusion.) > > Initially, I agreed with Daiwei's naming solution. But after reviewing > these APIs, > I find the "insertMutiDevicesRecord" (or, insertMutiDevicesSingleRecord) is > not good. > It is because users can write several records that belong to the same > device using this API. > > OK, let's rethink the APIs we mentioned. > > Suppose we have 2 devices (d1, d2) and each device has 3 measurements (s1, > s2, s3). > > 1. The first API. > We can insert one data point, e.g., `insert into d1(time, s1) values > (now(), 1)`. > Also, we can insert a set of data points that belong to the same device > with a specific timestamp, > e.g., `insert into d1(time, s1, s2, s3) values (now(), 1, 2, 3)`. > > Let's consider it as the basic insert method or the unit operation of IoTDB. > > We can call the point pairs "d1, now(), (s1, 1), (s2, 2), (s3, 3)" as a > RECORD. > > So, I'd like to call the first API as "insertRecord()"; > > 2. The second API. > Ok, now we want to insert some points that belong to the same device. > Consider the following data: > > device1 > time, s1, s2, s3 > 1 1 2 3 > 2 1 2 3 > 3 1 2 3 > > In v0.9, we call such data as "RowBatch". I asked Jialin why it is called > "rowBatch", he said the name > is from ORC file... > > If let me name it, I think "Tablet" is suitable. > > If so, naming the API as "insertDeviceTablet()" is fine. > > Notice that the in this API, we do not allow "null" cell in the Tablet. > > As the first API is a unit operation, the second API is equally to calling > the first API several times. > The difference is, the second API is more efficient for this case. > > > 3. The third API > > Ok, considering another scenario, the IoT gateway packs several devices' > data into one packet and sends it > to the server. On the server-side, after unpacking, IoTDB receives data > like: > > device1 > time, s1, s2, s3 > 1 1 2 3 > 2 1 2 3 > 3 1 2 3 > device2 > time, s1, s2 > 1 1 2 > 3 1 2 > 4 1 2 > > Ok... The difference between it and the second API is this one can write > data of several devices. > > So, the name can be "insertMultiDeviceTablets()". > > The constraint is, for each device's Tablet, there is no "null" cell. > But, two devices can have different columns. > > This API is equally to calling the second API several times. > But, hope the implementation of this API more efficient. > > 4.The fourth API. > > Well, API 1 is unit but can insert a few data for each call. > API 2 and 3 can write more data for each call, but have some constraint. > So, can we have a API that can write data in batch and have no constraint? > > Yes, that is why we have the fourth API. > > Considering the batch data is: > > device1 > time, s1, s2, s3 > 1 1 2 3 > 2 1 null 3 > 3 1 null null > device2 > time, s1, s2 > 1 1 2 > 3 null 2 > 4 1 null > > In this case, you can not consider the data that belong to a device as a > tablet, > because we consider there is no null cell in a tablet. > > Then, for the above data example, we can consider the data as 6 Records. > > So, I'd like to name the API as insertRecords(). > > Conclusion, > > The four API suits for 4 scenarios, and the name can be: > > - insertRecord > - insertDeviceTablet (or insertTablet) > - insertMultiDeviceTables (or insertTablets) > - insertRecords > > How do you think about that? > > Best, > ----------------------------------- > Xiangdong Huang > School of Software, Tsinghua University > > 黄向东 > 清华大学 软件学院 > > > > > >
