Skip to content

Commit 4b71ed1

Browse files
W1y1rW1y1r
committed
Table model writing&updating English PR
1 parent cc77e84 commit 4b71ed1

File tree

2 files changed

+420
-0
lines changed

2 files changed

+420
-0
lines changed

‎src/UserGuide/Master/Table/Basic-Concept/Write-Updata-Data.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
<!--
2+
3+
Licensed to the Apache Software Foundation (ASF) under one
4+
or more contributor license agreements. See the NOTICE file
5+
distributed with this work for additional information
6+
regarding copyright ownership. The ASF licenses this file
7+
to you under the Apache License, Version 2.0 (the
8+
"License"); you may not use this file except in compliance
9+
with the License. You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing,
14+
software distributed under the License is distributed on an
15+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16+
KIND, either express or implied. See the License for the
17+
specific language governing permissions and limitations
18+
under the License.
19+
20+
-->
21+
22+
# Data Insertion & Update
23+
24+
## 1. Data Insertion
25+
26+
### 1.1 Syntax
27+
28+
In IoTDB, data insertion follows the general syntax:
29+
30+
```SQL
31+
INSERT INTO <TABLE_NAME> [(COLUMN_NAME[, COLUMN_NAME]*)]? VALUES (COLUMN_VALUE[, COLUMN_VALUE]*)
32+
```
33+
34+
**Basic Constraints**:
35+
36+
1. Tables cannot be automatically created using `INSERT` statements.
37+
2. Columns not specified in the `INSERT` statement will automatically be filled with `null`.
38+
3. If no timestamp is provided, the system will use the current time (`now()`).
39+
4. If a column value does not exist for the identified device, the insertion will overwrite any existing `null` values with the new data.
40+
5. If a column value already exists for the identified device, a new insertion will update the column with the new value.
41+
6. For duplicate timestamps:
42+
1. Columns with `null` values at the original timestamp will be updated.
43+
2. Columns with non-`null` values at the original timestamp will retain their original values.
44+
45+
Since attributes generally do not change over time, it is recommended to update attribute values using the `UPDATE` statement described below，Please refer to the following [Data Update](#2-data-updates).
46+
47+
<div style="text-align: center;">
48+
<img src="/img/WriteData01.png" alt="" style="width: 70%;"/>
49+
</div>
50+
51+
52+
### 1.2 Automatically Create Tables via Session Insertion
53+
54+
When inserting data via the Session API, IoTDB can automatically create table structures based on the data insertion request, eliminating the need for manual table creation.
55+
56+
**Example:**
57+
58+
```Java
59+
try (ITableSession session =
60+
new TableSessionBuilder()
61+
.nodeUrls(Collections.singletonList("127.0.0.1:6667"))
62+
.username("root")
63+
.password("root")
64+
.build()) {
65+
66+
session.executeNonQueryStatement("CREATE DATABASE db1");
67+
session.executeNonQueryStatement("use db1");
68+
69+
// Insert data without manually creating the table
70+
List<String> columnNameList =
71+
Arrays.asList("region_id", "plant_id", "device_id", "model", "temperature", "humidity");
72+
List<TSDataType> dataTypeList =
73+
Arrays.asList(
74+
TSDataType.STRING,
75+
TSDataType.STRING,
76+
TSDataType.STRING,
77+
TSDataType.STRING,
78+
TSDataType.FLOAT,
79+
TSDataType.DOUBLE);
80+
List<Tablet.ColumnCategory> columnTypeList =
81+
new ArrayList<>(
82+
Arrays.asList(
83+
Tablet.ColumnCategory.TAG,
84+
Tablet.ColumnCategory.TAG,
85+
Tablet.ColumnCategory.TAG,
86+
Tablet.ColumnCategory.ATTRIBUTE,
87+
Tablet.ColumnCategory.FIELD,
88+
Tablet.ColumnCategory.FIELD));
89+
Tablet tablet = new Tablet("table1", columnNameList, dataTypeList, columnTypeList, 100);
90+
for (long timestamp = 0; timestamp < 100; timestamp++) {
91+
int rowIndex = tablet.getRowSize();
92+
tablet.addTimestamp(rowIndex, timestamp);
93+
tablet.addValue("region_id", rowIndex, "1");
94+
tablet.addValue("plant_id", rowIndex, "5");
95+
tablet.addValue("device_id", rowIndex, "3");
96+
tablet.addValue("model", rowIndex, "A");
97+
tablet.addValue("temperature", rowIndex, 37.6F);
98+
tablet.addValue("humidity", rowIndex, 111.1);
99+
if (tablet.getRowSize() == tablet.getMaxRowNumber()) {
100+
session.insert(tablet);
101+
tablet.reset();
102+
}
103+
}
104+
if (tablet.getRowSize() != 0) {
105+
session.insert(tablet);
106+
tablet.reset();
107+
}
108+
}
109+
```
110+
111+
After execution, you can verify the table creation using the following command:
112+
113+
```SQL
114+
IoTDB> desc table1
115+
+-----------+---------+-----------+
116+
| ColumnName| DataType| Category|
117+
+-----------+---------+-----------+
118+
| time|TIMESTAMP| TIME|
119+
| region_id| STRING| TAG|
120+
| plant_id| STRING| TAG|
121+
| device_id| STRING| TAG|
122+
| model| STRING| ATTRIBUTE|
123+
|temperature| FLOAT| FIELD|
124+
| humidity| DOUBLE| FIELD|
125+
+-----------+---------+-----------+
126+
```
127+
128+
### 1.3 Specified Column Insertion
129+
130+
It is possible to insert data for specific columns. Columns not specified will remain `null`.
131+
132+
**Example:**
133+
134+
```SQL
135+
insert into table1("region", "plant_id", "device_id", Time, "temperature", "displacement") values ('Hamburg', '3001', '3', 4, 90.0, 1200.0)
136+
137+
138+
insert into table1("region", "plant_id", "device_id", Time, "temperature") values ('Hamburg, '3001', '3', 5, 90.0)
139+
```
140+
141+
### 1.4 Null Value Insertion
142+
143+
You can explicitly set `null` values for tag columns, attribute columns, and field columns.
144+
145+
**Example**:
146+
147+
Equivalent to the above partial column insertion.
148+
149+
```SQL
150+
# Equivalent to the example above
151+
insert into table1("region", "plant_id", "device_id", "model", "maintenance_cycle", Time, "temperature", "displacement") values ('Hamburg', '3001', '3', null, null, 4, 90.0, 1200.0)
152+
153+
insert into table1("region", "plant_id", "device_id", "model", "maintenance_cycle", Time, "temperature", "displacement") values ('Hamburg', '3001', '3', null, null, 5, 90.0, null)
154+
```
155+
156+
If no tag columns are included, the system will automatically create a device with all tag column values set to `null`.
157+
158+
> **Note:** This operation will not only automatically populate existing tag columns in the table with `null` values but will also populate any newly added tag columns with `null` values in the future.
159+
160+
### 1.5 Multi-Row Insertion
161+
162+
IoTDB supports inserting multiple rows of data in a single statement to improve efficiency.
163+
164+
**Example**:
165+
166+
```SQL
167+
insert into table1
168+
values
169+
('Frankfurt', '3001', '3', '1', '10', 4, 90.0, 1200.0)
170+
('Frankfurt', '3001', '3', '1', '10', 5, 90.0, 1200.0)
171+
172+
173+
insert into table1
174+
("region", "plant_id", "device_id", Time, "temperature", "displacement")
175+
values
176+
('Frankfurt', '3001', '3', 4, 90.0, 1200.0)
177+
('Frankfurt', '3001', '3', 5, 90.0, 1200.0)
178+
```
179+
180+
#### Notes
181+
182+
- Referencing non-existent columns in SQL will result in an error code `COLUMN_NOT_EXIST(616)`.
183+
- Data type mismatches between the insertion data and the column's data type will result in an error code `DATA_TYPE_MISMATCH(614)`.
184+
185+
186+
## 2. Data Updates
187+
188+
### 2.1 Syntax
189+
190+
```SQL
191+
UPDATE <TABLE_NAME> SET updateAssignment (',' updateAssignment)* (WHERE where=booleanExpression)?
192+
193+
updateAssignment
194+
: identifier EQ expression
195+
;
196+
```
197+
198+
**Note:**
199+
200+
- Updates are allowed only on `ATTRIBUTE` columns.
201+
- `WHERE` conditions:
202+
- Can only include `TAG` and `ATTRIBUTE` columns; `FIELD` and `TIME` columns are not allowed.
203+
- Aggregation functions are not supported.
204+
- The result of the `SET` assignment expression must be a `string` type and follow the same constraints as the `WHERE` clause.
205+
206+
**Example**:
207+
208+
```SQL
209+
update table1 set b = a where substring(a, 1, 1) like '%'
210+
```

0 commit comments

Comments
 (0)