diff --git a/src/UserGuide/Master/Table/Basic-Concept/Delete-Data.md b/src/UserGuide/Master/Table/Basic-Concept/Delete-Data.md new file mode 100644 index 000000000..f2016dd7f --- /dev/null +++ b/src/UserGuide/Master/Table/Basic-Concept/Delete-Data.md @@ -0,0 +1,116 @@ + + +# Data Deletion + +## 1. Data Deletion + +Data deletion in IoTDB can be achieved using the DELETE statement. You can specify filters based on tags and time to delete specific subsets of data. + +### 1.1 Syntax Overview + +```SQL +DELETE FROM [WHERE_CLAUSE]? + +WHERE_CLAUSE: + WHERE DELETE_CONDITION + +DELETE_CONDITION: + SINGLE_CONDITION + | DELETE_CONDITION AND DELETE_CONDITION + | DELETE_CONDITION OR DELETE_CONDITION + +SINGLE_CODITION: + TIME_CONDITION | ID_CONDITION + +TIME_CONDITION: + time TIME_OPERATOR LONG_LITERAL + +TIME_OPERATOR: + < | > | <= | >= | = + +ID_CONDITION: + identifier = STRING_LITERAL +``` + +**Note:** + +- The `DELETE_CONDITION` can include single conditions or be a combination of conditions (logical operators like `AND` and `OR` are used). Currently, only **time conditions** and **tag conditions** are supported. +- For **time conditions**, operators include standard comparison symbols (`<`, `>`, etc.). +- For **tag conditions**, only equality (=) is allowed. + +### 1.2 Examples + +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. + +#### 1.2.1 Delet All Data from a Table + +```SQL +# Whole table deletion +DELETE FROM table1 +``` + +#### 1.2.2 Delete Data within a Specific Time Range + +```SQL +# Single time interval deletion +DELETE FROM table1 WHERE time <= 2024-11-29 00:00:00 + +# Multi time interval deletion +DELETE FROM table1 WHERE time >= 2024-11-27 00:00:00 and time <= 2024-11-29 00:00:00 +``` + +#### 1.2.3 Deleting Data for a Specific Device + +```SQL +# Device-specific deletion +# Identifier conditions only support the '=' operator +DELETE FROM table1 WHERE device_id='101' and model_id = 'B' + +# Device-specific deletion with time interval +DELETE FROM table1 + WHERE time >= 2024-11-27 16:39:00 and time <= 2024-11-29 16:42:00 + AND device_id='101' and model_id = 'B' + +# Device-type-specific deletion +DELETE FROM table1 WHERE model_id = 'B' +``` + +## 2. Device Deletion + +When a device is written to IoTDB, its metadata is retained even if data is deleted. To remove both the data and metadata of a device, you can use the `DELETE DEVICES` statement. + +### 2.1 Syntax Overview + +```SQL +DELETE DEVICES FROM tableName=qualifiedName (WHERE booleanExpression)? +``` + +**Notes:** + +- The `WHERE` clause supports only equality filters on tags. Conditions can be combined using `AND` and `OR` operators. +- Time conditions are **not** supported in the `DELETE DEVICES` statement. + +### 2.2 Example + +```SQL +DELETE DEVICES FROM table1 WHERE device_id = '101' +``` \ No newline at end of file diff --git a/src/UserGuide/Master/Table/Basic-Concept/Query-Data.md b/src/UserGuide/Master/Table/Basic-Concept/Query-Data.md new file mode 100644 index 000000000..4a5c51a95 --- /dev/null +++ b/src/UserGuide/Master/Table/Basic-Concept/Query-Data.md @@ -0,0 +1,277 @@ + + +# Data Query + +## 1. Syntax Overview + +```SQL +SELECT ⟨select_list⟩ + FROM ⟨tables⟩ + [WHERE ⟨condition⟩] + [GROUP BY ⟨groups⟩] + [HAVING ⟨group_filter⟩] + [FILL ⟨fill_methods⟩] + [ORDER BY ⟨order_expression⟩] + [OFFSET ⟨n⟩] + [LIMIT ⟨n⟩]; +``` + +The IoTDB table model query syntax supports the following clauses: + +- **SELECT Clause**: Specifies the columns to be included in the result. Details: [SELECT Clause](../SQL-Manual/Select-Clause.md) +- **FROM Clause**: Indicates the data source for the query, which can be a single table, multiple tables joined using the `JOIN` clause, or a subquery. Details: [FROM & JOIN Clause](../SQL-Manual/From-Join-Clause.md) +- **WHERE Clause**: Filters rows based on specific conditions. Logically executed immediately after the `FROM` clause. Details: [WHERE Clause](../SQL-Manual/Where-Clause.md) +- **GROUP BY Clause**: Used for aggregating data, specifying the columns for grouping. Details: [GROUP BY Clause](../SQL-Manual/GroupBy-Clause.md) +- **HAVING Clause**: Applied after the `GROUP BY` clause to filter grouped data, similar to `WHERE` but operates after grouping. Details:[HAVING Clause](../SQL-Manual/Having-Clause.md) +- **FILL Clause**: Handles missing values in query results by specifying fill methods (e.g., previous non-null value or linear interpolation) for better visualization and analysis. Details:[FILL Clause](../SQL-Manual/Fill-Clause.md) +- **ORDER BY Clause**: Sorts query results in ascending (`ASC`) or descending (`DESC`) order, with optional handling for null values (`NULLS FIRST` or `NULLS LAST`). Details: [ORDER BY Clause](../SQL-Manual/OrderBy-Clause.md) +- **OFFSET Clause**: Specifies the starting position for the query result, skipping the first `OFFSET` rows. Often used with the `LIMIT` clause. Details: [LIMIT and OFFSET Clause](../SQL-Manual/Limit-Offset-Clause.md) +- **LIMIT Clause**: Limits the number of rows in the query result. Typically used in conjunction with the `OFFSET` clause for pagination. Details: [LIMIT and OFFSET Clause](../SQL-Manual/Limit-Offset-Clause.md) + +## 2. Clause Execution Order + +![](/img/%E5%AD%90%E5%8F%A5%E6%89%A7%E8%A1%8C%E9%A1%BA%E5%BA%8F01.png) + + +## 3. Common Query Examples + +### 3.1 Sample Dataset + +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. + +### 3.2 Basic Data Query + +**Example 1: Filter by Time** + +```SQL +IoTDB> SELECT time, temperature, humidity + FROM table1 + WHERE time >= 2024-11-27 00:00:00 and time <= 2024-11-29 00:00:00; +``` + +**Result**: + +```SQL ++-----------------------------+-----------+--------+ +| time|temperature|humidity| ++-----------------------------+-----------+--------+ +|2024-11-28T08:00:00.000+08:00| 85.0| null| +|2024-11-28T09:00:00.000+08:00| null| 40.9| +|2024-11-28T10:00:00.000+08:00| 85.0| 35.2| +|2024-11-28T11:00:00.000+08:00| 88.0| 45.1| +|2024-11-27T16:38:00.000+08:00| null| 35.1| +|2024-11-27T16:39:00.000+08:00| 85.0| 35.3| +|2024-11-27T16:40:00.000+08:00| 85.0| null| +|2024-11-27T16:41:00.000+08:00| 85.0| null| +|2024-11-27T16:42:00.000+08:00| null| 35.2| +|2024-11-27T16:43:00.000+08:00| null| null| +|2024-11-27T16:44:00.000+08:00| null| null| ++-----------------------------+-----------+--------+ +Total line number = 11 +It costs 0.075s +``` + +**Example 2: Filter by** **Value** + +```SQL +IoTDB> SELECT time, temperature, humidity + FROM table1 + WHERE temperature > 89.0; +``` + +**Result**: + +```SQL ++-----------------------------+-----------+--------+ +| time|temperature|humidity| ++-----------------------------+-----------+--------+ +|2024-11-29T18:30:00.000+08:00| 90.0| 35.4| +|2024-11-26T13:37:00.000+08:00| 90.0| 35.1| +|2024-11-26T13:38:00.000+08:00| 90.0| 35.1| +|2024-11-30T09:30:00.000+08:00| 90.0| 35.2| +|2024-11-30T14:30:00.000+08:00| 90.0| 34.8| ++-----------------------------+-----------+--------+ +Total line number = 5 +It costs 0.156s +``` + +**Example 3: Filter by Attribute** + +```SQL +IoTDB> SELECT time, temperature, humidity + FROM table1 + WHERE model_id ='B'; +``` + +**Result**: + +```SQL ++-----------------------------+-----------+--------+ +| time|temperature|humidity| ++-----------------------------+-----------+--------+ +|2024-11-27T16:38:00.000+08:00| null| 35.1| +|2024-11-27T16:39:00.000+08:00| 85.0| 35.3| +|2024-11-27T16:40:00.000+08:00| 85.0| null| +|2024-11-27T16:41:00.000+08:00| 85.0| null| +|2024-11-27T16:42:00.000+08:00| null| 35.2| +|2024-11-27T16:43:00.000+08:00| null| null| +|2024-11-27T16:44:00.000+08:00| null| null| ++-----------------------------+-----------+--------+ +Total line number = 7 +It costs 0.106s +``` + +### 3.3 Aggregation Query + +**Example**: Calculate the average, maximum, and minimum temperature for each `device_id` within a specific time range. + +```SQL +IoTDB> SELECT device_id, AVG(temperature) as avg_temp, MAX(temperature) as max_temp, MIN(temperature) as min_temp + FROM table1 + WHERE time >= 2024-11-26 00:00:00 AND time <= 2024-11-29 00:00:00 + GROUP BY device_id; +``` + +**Result**: + +```SQL ++---------+--------+--------+--------+ +|device_id|avg_temp|max_temp|min_temp| ++---------+--------+--------+--------+ +| 100| 87.6| 90.0| 85.0| +| 101| 85.0| 85.0| 85.0| ++---------+--------+--------+--------+ +Total line number = 2 +It costs 0.278s +``` + +### 3.4 Latest Point Query + +**Example**: Retrieve the latest record for each `device_id`, including the temperature value and the timestamp of the last record. + +```SQL +IoTDB> SELECT device_id,last(temperature),last_by(time,temperature) + FROM table1 + GROUP BY device_id; +``` + +**Result**: + +```SQL ++---------+-----+-----------------------------+ +|device_id|_col1| _col2| ++---------+-----+-----------------------------+ +| 100| 90.0|2024-11-29T18:30:00.000+08:00| +| 101| 90.0|2024-11-30T14:30:00.000+08:00| ++---------+-----+-----------------------------+ +Total line number = 2 +It costs 0.090s +``` + +### 3.5 Downsampling Query + +**Example**: Group data by day and calculate the average temperature using `date_bin_gapfill` function. + +```SQL +IoTDB> SELECT date_bin(1d ,time) as day_time, AVG(temperature) as avg_temp + FROM table1 + WHERE time >= 2024-11-26 00:00:00 AND time <= 2024-11-30 00:00:00 + GROUP BY date_bin(1d ,time); +``` + +**Result**: + +```SQL ++-----------------------------+--------+ +| day_time|avg_temp| ++-----------------------------+--------+ +|2024-11-29T08:00:00.000+08:00| 87.5| +|2024-11-28T08:00:00.000+08:00| 86.0| +|2024-11-26T08:00:00.000+08:00| 90.0| +|2024-11-27T08:00:00.000+08:00| 85.0| ++-----------------------------+--------+ +Total line number = 4 +It costs 0.110s +``` + +### 3.6 Missing Data Filling + +**Example**: Query the records within a specified time range where `device_id` is '100'. If there are missing data points, fill them using the previous non-null value. + +```SQL +IoTDB> SELECT time, temperature, humidity + FROM table1 + WHERE time >= 2024-11-26 00:00:00 and time <= 2024-11-30 11:00:00 + AND region='East' AND plant_id='1001' AND device_id='101' + FILL METHOD PREVIOUS; +``` + +**Result**: + +```SQL ++-----------------------------+-----------+--------+ +| time|temperature|humidity| ++-----------------------------+-----------+--------+ +|2024-11-27T16:38:00.000+08:00| null| 35.1| +|2024-11-27T16:39:00.000+08:00| 85.0| 35.3| +|2024-11-27T16:40:00.000+08:00| 85.0| 35.3| +|2024-11-27T16:41:00.000+08:00| 85.0| 35.3| +|2024-11-27T16:42:00.000+08:00| 85.0| 35.2| +|2024-11-27T16:43:00.000+08:00| 85.0| 35.2| +|2024-11-27T16:44:00.000+08:00| 85.0| 35.2| ++-----------------------------+-----------+--------+ +Total line number = 7 +It costs 0.101s +``` + +### 3.7 Sorting & Pagination + +**Example**: Query records from the table, sorting by `humidity` in descending order and placing null values (NULL) at the end. Skip the first 2 rows and return the next 8 rows. + +```SQL +IoTDB> SELECT time, temperature, humidity + FROM table1 + ORDER BY humidity desc NULLS LAST + OFFSET 2 + LIMIT 10; +``` + +**Result**: + +```SQL ++-----------------------------+-----------+--------+ +| time|temperature|humidity| ++-----------------------------+-----------+--------+ +|2024-11-28T09:00:00.000+08:00| null| 40.9| +|2024-11-29T18:30:00.000+08:00| 90.0| 35.4| +|2024-11-27T16:39:00.000+08:00| 85.0| 35.3| +|2024-11-28T10:00:00.000+08:00| 85.0| 35.2| +|2024-11-30T09:30:00.000+08:00| 90.0| 35.2| +|2024-11-27T16:42:00.000+08:00| null| 35.2| +|2024-11-26T13:38:00.000+08:00| 90.0| 35.1| +|2024-11-26T13:37:00.000+08:00| 90.0| 35.1| +|2024-11-27T16:38:00.000+08:00| null| 35.1| +|2024-11-30T14:30:00.000+08:00| 90.0| 34.8| ++-----------------------------+-----------+--------+ +Total line number = 10 +It costs 0.093s +``` diff --git a/src/UserGuide/Master/Table/Basic-Concept/TTL-Delete-Data.md b/src/UserGuide/Master/Table/Basic-Concept/TTL-Delete-Data.md new file mode 100644 index 000000000..df19a8596 --- /dev/null +++ b/src/UserGuide/Master/Table/Basic-Concept/TTL-Delete-Data.md @@ -0,0 +1,144 @@ + + +# Automatic Data Expiration (TTL) + +## 1. Overview + +Time-to-Live (TTL) is a mechanism for defining the lifespan of data in a database. In IoTDB, TTL allows setting table-level expiration policies, enabling the system to automatically delete outdated data periodically. This helps manage disk space efficiently, maintain high query performance, and reduce memory usage. + +TTL values are specified in milliseconds, and once data exceeds its defined lifespan, it becomes unavailable for queries and cannot be written to. However, the physical deletion of expired data occurs later during the compaction process. Note that changes to TTL settings can briefly impact the accessibility of data. + +**Notes:** + +1. TTL defines the expiration time of data in milliseconds, independent of the time precision configuration file. +2. Modifying TTL settings can cause temporary variations in data accessibility. +3. The system eventually removes expired data, though this process may involve some delay.。 + +## 2. Set TTL + +In the table model, IoTDB’s TTL operates at the granularity of individual tables. You can set TTL directly on a table or at the database level. When TTL is configured at the database level, it serves as the default for new tables created within the database. However, each table can still have its own independent TTL settings. + +**Note:** Modifying the database-level TTL does not retroactively affect the TTL settings of existing tables. + +### 2.1 Set TTL for Tables + +If TTL is specified when creating a table using SQL, the table’s TTL takes precedence. Refer to [Table-Management](../Basic-Concept/Table-Management.md)for details. + +Example 1: Setting TTL during table creation: + +```SQL +CREATE TABLE test3 ("site" string id, "temperature" int32) with (TTL=3600) +``` + +Example 2: Changing TTL for an existing table: + +```SQL +ALTER TABLE tableB SET PROPERTIES TTL=3600; +``` + +**Example 3:** If TTL is not specified or set to the default value, it will inherit the database's TTL. By default, the database TTL is `'INF'` (infinite): + +```SQL +CREATE TABLE test3 ("site" string id, "temperature" int32) with (TTL=DEFAULT) +CREATE TABLE test3 ("site" string id, "temperature" int32) +ALTER TABLE tableB set properties TTL=DEFAULT +``` + +### 2.2 Set TTL for Databases + +Tables without explicit TTL settings inherit the TTL of their database. Refer to [Database-Management](../Basic-Concept/Database-Management.md)for details. + +Example 4: A database with TTL=3600000 creates tables inheriting this TTL: + +```SQL +CREATE DATABASE db WITH (ttl=3600000) +use db +CREATE TABLE test3 ("site" string id, "temperature" int32) +``` + +Example 5: A database without a TTL setting creates tables without TTL: + +```SQL +CREATE DATABASE db +use db +CREATE TABLE test3 ("site" string id, "temperature" int32) +``` + +Example 6: Setting a table with no TTL explicitly (TTL=INF) in a database with a configured TTL: + +```SQL +CREATE DATABASE db WITH (ttl=3600000) +use db +CREATE TABLE test3 ("site" string id, "temperature" int32) with (ttl='INF') +``` + +## 3. Remove TTL + +To cancel a TTL setting, modify the table's TTL to 'INF'. Note that IoTDB does not currently support modifying the TTL of a database. + +```SQL +ALTER TABLE tableB set properties TTL='INF' +``` + +## 4. View TTL Information + +Use the SHOW DATABASES and SHOW TABLES commands to view TTL details for databases and tables. Refer to [Database-Management](../Basic-Concept/Database-Management.md)、 [Table-Management](../Basic-Concept/Table-Management.md)for details. + +> Note: TTL settings in tree-model will also be shown. + +Example Output: + +```SQL +IoTDB> show databases ++---------+-------+-----------------------+---------------------+---------------------+ +| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval| ++---------+-------+-----------------------+---------------------+---------------------+ +|test_prop| 300| 1| 3| 100000| +| test2| 300| 1| 1| 604800000| ++---------+-------+-----------------------+---------------------+---------------------+ + +IoTDB> show databases details ++---------+-------+-----------------------+---------------------+---------------------+-----+ +| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|Model| ++---------+-------+-----------------------+---------------------+---------------------+-----+ +|test_prop| 300| 1| 3| 100000|TABLE| +| test2| 300| 1| 1| 604800000| TREE| ++---------+-------+-----------------------+---------------------+---------------------+-----+ +IoTDB> show tables ++---------+-------+ +|TableName|TTL(ms)| ++---------+-------+ +| grass| 1000| +| bamboo| 300| +| flower| INF| ++---------+-------+ + +IoTDB> show tables details ++---------+-------+----------+ +|TableName|TTL(ms)| Status| ++---------+-------+----------+ +| bean| 300|PRE_CREATE| +| grass| 1000| USING| +| bamboo| 300| USING| +| flower| INF| USING| ++---------+-------+----------+ +``` \ No newline at end of file diff --git a/src/UserGuide/Master/Table/Basic-Concept/Sample-Data.md b/src/UserGuide/Master/Table/Reference/Sample-Data.md similarity index 100% rename from src/UserGuide/Master/Table/Basic-Concept/Sample-Data.md rename to src/UserGuide/Master/Table/Reference/Sample-Data.md diff --git a/src/UserGuide/Master/Table/SQL-Manual/Fill-Clause.md b/src/UserGuide/Master/Table/SQL-Manual/Fill-Clause.md index d761f4f94..a708cc763 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/Fill-Clause.md +++ b/src/UserGuide/Master/Table/SQL-Manual/Fill-Clause.md @@ -24,9 +24,10 @@ ## 1 Function Introduction -When performing data queries, you may encounter situations where certain columns lack data in some rows, resulting in NULL values in the result set. These NULL values are not conducive to data visualization and analysis, so IoTDB provides the FILL clause to fill in these NULL values. +During data queries, you may encounter scenarios where certain columns have missing data in some rows, resulting in NULL values in the result set. These NULL values can hinder data visualization and analysis. To address this, IoTDB provides the FILL clause to populate these NULL values. -When the query includes an ORDER BY clause, the FILL clause will be executed before the ORDER BY. If there is a GAPFILL (date_bin_gapfill function) operation, the FILL clause will be executed after the GAPFILL. +- If the query includes an `ORDER BY` clause, the FILL clause is executed before `ORDER BY`. +- If a `GAPFILL` (e.g., `date_bin_gapfill` function) operation exists, the FILL clause is executed after `GAPFILL`. ## 2 Syntax Overview @@ -62,18 +63,18 @@ intervalField ; ``` -### 2.1 Filling Methods +### 2.1 ### Filling Methods -IoTDB supports the following three methods for filling null values: +IoTDB supports the following three methods to fill NULL values: -1. __`PREVIOUS` Filling__：Fills with the previous non-null value of the column. -2. __`LINEAR` Filling__：Fills with the linear interpolation between the previous and next non-null values of the column. -3. __`Constant` Filling__：Fills with a specified constant value. +1. **PREVIOUS Fill:** Uses the most recent non-NULL value from the same column to fill NULL values. +2. **LINEAR Fill:** Applies linear interpolation using the nearest previous and next non-NULL values in the same column. +3. **CONSTANT Fill:** Fills NULL values with a specified constant. -Only one filling method can be specified, and this method will be applied to all columns in the result set. +Only one filling method can be specified, and it applies to all columns in the result set. -### 2.2 Data Types and Supported Filling Methods +### 2.2 Supported Data Types for Filling Methods | Data Type | Previous | Linear | Constant | | :-------- | :------- | :----- | :------- | @@ -88,26 +89,26 @@ Only one filling method can be specified, and this method will be applied to all | timestamp | √ | √ | √ | | date | √ | √ | √ | -Note: For columns whose data types do not support the specified filling method, neither filling is performed nor exceptions are thrown; the original state is simply maintained. +**Note:** Columns with data types not supporting the specified filling method will remain unchanged without errors. -## 3 Example Data +## 3 Sample Dataset -In the [Example Data page](../Basic-Concept/Sample-Data.md), there are SQL statements for building the table structure and inserting data. By downloading and executing these statements in the IoTDB CLI, you can import data into IoTDB. You can use this data to test and execute the SQL statements in the examples and obtain the corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. -### 3.1 PREVIOUS Filling： +### 3.1 PREVIOUS Fill -For null values in the query result set, fill with the previous non-null value of the column. +`PREVIOUS FILL` fills NULL values with the most recent non-NULL value in the same column. -#### 3.1.1 Parameter Introduction： +#### 3.1.1 Parameters -- TIME_BOUND（optional）：The time threshold to look forward. If the time interval between the current null value's timestamp and the previous non-null value's timestamp exceeds this threshold, filling will not be performed. By default, the first TIMESTAMP type column in the query result is used to determine whether the time threshold has been exceeded. - - The format of the time threshold parameter is a time interval, where the numerical part must be an integer, and the unit part y represents years, mo represents months, w represents weeks, d represents days, h represents hours, m represents minutes, s represents seconds, ms represents milliseconds, µs represents microseconds, and ns represents nanoseconds, such as 1d1h. -- TIME_COLUMN（optional）：If you need to manually specify the TIMESTAMP column used to judge the time threshold, you can determine the order of the column by specifying a number (starting from 1) after the `TIME_COLUMN`parameter. This number represents the specific position of the TIMESTAMP column in the original table. +- **TIME_BOUND (optional):** Defines a forward-looking time threshold. If the time difference between the current NULL value and the previous non-NULL value exceeds this threshold, the value will not be filled. By default, the system uses the first `TIMESTAMP` column in the query result to determine the threshold. + - Format: A time interval specified with integer values and units, e.g., `1d1h` (1 day and 1 hour). +- **TIME_COLUMN (optional):** Allows specifying the `TIMESTAMP` column used to determine the time threshold. The column is specified using its positional index (starting from 1) in the original table. -#### 3.1.2 Example +#### 3.1.2 Examples -Without using any filling method: +- Without FILL Clause: ```sql SELECT time, temperature, status @@ -116,7 +117,7 @@ SELECT time, temperature, status AND plant_id='1001' and device_id='101'; ``` -Query results: +Results: ```sql +-----------------------------+-----------+------+ @@ -134,7 +135,7 @@ Total line number = 7 It costs 0.088s ``` -Use the PREVIOUS padding method (the result will be filled with the previous non null value to fill the NULL value): +- Using `PREVIOUS Fill`: ```sql SELECT time, temperature, status @@ -144,7 +145,7 @@ SELECT time, temperature, status FILL METHOD PREVIOUS; ``` -Query results: +Results: ```sql +-----------------------------+-----------+------+ @@ -162,7 +163,7 @@ Total line number = 7 It costs 0.091s ``` -Use the PREVIOUS padding method (specify time threshold): +- Using `PREVIOUS Fill` with a Specified Time Threshold: ```sql # Do not specify a time column @@ -180,7 +181,7 @@ SELECT time, temperature, status FILL METHOD PREVIOUS 1m TIME_COLUMN 1; ``` -Query results: +Results: ```sql +-----------------------------+-----------+------+ @@ -198,24 +199,23 @@ Total line number = 7 It costs 0.075s ``` -### 3.2 LINEAR Filling +### 3.2 LINEAR Fill -For null values in the query result set, fill with the linear interpolation between the previous and next non-null values of the column. +`LINEAR Fill` fills NULL values using linear interpolation based on the nearest previous and next non-NULL values in the same column. -#### 3.2.1 Linear Filling Rules: +#### 3.2.1 Linear Fill Rules -- If all previous values are null, or all subsequent values are null, no filling is performed. -- If the column's data type is boolean/string/blob/text, no filling is performed, and no exceptions are thrown. -- If no time column is specified, the system defaults to selecting the first column with a data type of TIMESTAMP in the SELECT clause as the auxiliary time column for linear interpolation. If no column with a TIMESTAMP data type exists, the system will throw an exception. +1. If all previous or all subsequent values are NULL, no filling is performed. +2. Columns with data types such as `boolean`, `string`, `blob`, or `text` are not filled, and no error is returned. +3. If no auxiliary time column is specified, the first `TIMESTAMP`-type column in the `SELECT` clause is used by default for interpolation. If no `TIMESTAMP` column exists, an error will be returned. -#### 3.2.2 Parameter Introduction: +#### 3.2.2 Parameters -- TIME_COLUMN（optional）：You can manually specify the `TIMESTAMP` column used to determine the time threshold as an auxiliary column for linear interpolation by specifying a number (starting from 1) after the `TIME_COLUMN` parameter. This number represents the specific position of the `TIMESTAMP` column in the original table. +- **TIME_COLUMN (optional):** Specifies the `TIMESTAMP` column to be used as an auxiliary column for linear interpolation. The column is identified by its positional index (starting from 1) in the original table. -Note: It is not mandatory that the auxiliary column for linear interpolation must be a time column; any expression with a TIMESTAMP type is acceptable. However, since linear interpolation only makes sense when the auxiliary column is in ascending or descending order, users need to ensure that the result set is ordered by that column in ascending or descending order if they specify other columns. +**Note:** The auxiliary column used for linear interpolation is not required to be the `time` column. However, the auxiliary column must be sorted in ascending or descending order for meaningful interpolation. If another column is specified, the user must ensure the result set is ordered correctly. - -#### 3.2.3 Example +#### 3.2.3 Examples ```sql @@ -226,7 +226,7 @@ SELECT time, temperature, status FILL METHOD LINEAR; ``` -Query results: +Result: ```sql +-----------------------------+-----------+------+ @@ -244,19 +244,19 @@ Total line number = 7 It costs 0.053s ``` -### 3.3 Constant Filling: +### 3.3 ### CONSTANT Fill -For null values in the query result set, fill with a specified constant. +`CONSTANT Fill` fills NULL values with a specified constant value. -#### 3.3.1 Constant Filling Rules: +#### 3.3.1 Constant Fill Rules -- If the data type does not match the input constant, IoTDB will not fill the query result and will not throw an exception. -- If the inserted constant value exceeds the maximum value that its data type can represent, IoTDB will not fill the query result and will not throw an exception. +1. If the data type of the constant does not match the column's data type, IoTDB does not fill the result set and no error is returned. +2. If the constant value exceeds the column's allowable range, IoTDB does not fill the result set and no error is returned. -#### 3.3.2 Example +#### 3.3.2 Examples -When using a `FLOAT` constant for filling, the SQL statement is as follows: +- Using a `FLOAT` constant: ```sql @@ -267,7 +267,7 @@ SELECT time, temperature, status FILL METHOD CONSTANT 80.0; ``` -Query results: +Results: ```sql +-----------------------------+-----------+------+ @@ -285,8 +285,7 @@ Total line number = 7 It costs 0.242s ``` -When using the constant `BOOLEAN` to fill in, the SQL statement is as follows: - +W- Using a `BOOLEAN` constant: ```sql SELECT time, temperature, status @@ -296,7 +295,7 @@ SELECT time, temperature, status FILL METHOD CONSTANT true; ``` -Query results: +Results: ```sql +-----------------------------+-----------+------+ @@ -316,12 +315,13 @@ It costs 0.073s ## 4 Advanced Usage -When using `PREVIOUS` and `LINEAR` FILL, an additional `FILL_GROUP` parameter is also supported for filling within groups. +When using the `PREVIOUS` or `LINEAR` FILL methods, the `FILL_GROUP` parameter allows filling within specific groups without being influenced by other groups. -When using a group by clause with fill, you may want to fill within groups without being affected by other groups. +#### Examples -For example: Fill the null values within each `device_id` without using values from other devices: +- **Filling Missing Values Within `device_id`** +The following query demonstrates how to fill missing values for each `device_id` group independently, without using values from other devices: ```sql SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) AS avg_temp FROM table1 @@ -329,7 +329,7 @@ SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) A group by 1, plant_id, device_id; ``` -Query results: +Results： ```sql +-----------------------------+--------+---------+--------+ @@ -348,7 +348,9 @@ Total line number = 8 It costs 0.110s ``` -If the FILL_GROUP parameter is not specified, the null value for `100` will be filled with the value of `101`: +- **Without Specifying `FILL_GROUP`** + +If the `FILL_GROUP` parameter is not specified, missing values in `device_id = 100` will be filled using values from `device_id = 101`: ```sql SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) AS avg_temp @@ -358,7 +360,7 @@ SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) A FILL METHOD PREVIOUS; ``` -Query results: +Results： ```sql +-----------------------------+--------+---------+--------+ @@ -377,7 +379,9 @@ Total line number = 8 It costs 0.066s ``` -After specifying FILL_GROUP as the second column, the filling will only occur within the group that uses the second column `device_id` as the group key. The null value for `100` will not be filled with the value of `101` because they belong to different groups. +- **Specifying `FILL_GROUP` for Grouped Filling** + +By specifying `FILL_GROUP 2`, the filling is restricted to groups based on the second column (`device_id`). As a result, missing values in `device_id = 100` will not be filled using values from `device_id = 101`: ```sql SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) AS avg_temp @@ -387,7 +391,7 @@ SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) A FILL METHOD PREVIOUS FILL_GROUP 2; ``` -Query results: +Results: ```sql +-----------------------------+--------+---------+--------+ @@ -408,12 +412,14 @@ It costs 0.089s ## 5 Special Notes -When using `LINEAR FILL` or `PREVIOUS FILL`, if there are NULL values in the auxiliary time column (the column used to determine the filling logic), IoTDB will follow these rules: +When using `LINEAR` or `PREVIOUS` FILL methods, if the auxiliary time column (used to determine filling logic) contains NULL values, IoTDB follows these rules: -- Do not fill rows where the auxiliary time column is NULL. -- These rows will also not participate in the filling logic calculation. +- Rows with NULL values in the auxiliary column will not be filled. +- These rows are also excluded from the filling logic calculations. -Taking `PREVIOUS FILL` as an example, the original data is as follows: +**Example of `PREVIOUS Fill`** + +- Query original data: @@ -424,7 +430,7 @@ SELECT time, plant_id, device_id, humidity, arrival_time AND plant_id='1001' and device_id='101'; ``` -Query results: +Results: ```sql +-----------------------------+--------+---------+--------+-----------------------------+ @@ -442,7 +448,7 @@ Total line number = 7 It costs 0.119s ``` -Use the arrival_time column as the auxiliary time column and set the time interval (TIME_SOUND) to 2 ms (if the previous value is more than 2ms away from the current value, it will not be filled in): +- Using `arrival_time` as the auxiliary column with a time interval (`TIME_BOUND`) of 2 seconds ```sql SELECT time, plant_id, device_id, humidity, arrival_time @@ -452,7 +458,7 @@ SELECT time, plant_id, device_id, humidity, arrival_time FILL METHOD PREVIOUS TIME_BOUND 2s TIME_COLUMN 5; ``` -Query results: +Results: ```sql +-----------------------------+--------+---------+--------+-----------------------------+ @@ -469,9 +475,15 @@ Query results: Total line number = 7 It costs 0.049s ``` - -Filling results details: - -- For the humidity column at 16:39, 16:42, and 16:43, filling is not performed because the auxiliary column arrival_time is NULL. -- For the humidity column at 16:40, since the auxiliary column arrival_time is not NULL and is `1970-01-01T08:00:00.003+08:00`, which is within a 2ms time difference from the previous non-NULL value `1970-01-01T08:00:00.001+08:00`, it is filled with the value 1 from the first row (s1). -- For the humidity column at 16:41, although arrival_time is not NULL, the time difference from the previous non-NULL value exceeds 2ms, so no filling is performed. The same applies to the seventh row. \ No newline at end of file +**Filling Details** + +1. For `humidity` at `16:39`, `16:42`, and `16:43`: + 1. Since the auxiliary column `arrival_time` is NULL, no filling is performed. +2. For `humidity` at `16:40`: + 1. The auxiliary column `arrival_time` is not NULL and has a value of `1970-01-01T08:00:00.003+08:00`. + 2. The time difference from the previous non-NULL value (`1970-01-01T08:00:00.001+08:00`) is less than 2 seconds (`TIME_BOUND`) + 3. So the value `35.1` from the first row is used for filling. +3. For `humidity` at `16:41`: + 1. Although the auxiliary column `arrival_time` is not NULL, the time difference from the previous non-NULL value exceeds 2 seconds, so no filling is performed. +4. For `humidity` at `16:44`: + 1. Similarly, the time difference exceeds 2 seconds, so no filling is performed. \ No newline at end of file diff --git a/src/UserGuide/Master/Table/SQL-Manual/From-Join-Clause.md b/src/UserGuide/Master/Table/SQL-Manual/From-Join-Clause.md index b6d67780b..e561a9e03 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/From-Join-Clause.md +++ b/src/UserGuide/Master/Table/SQL-Manual/From-Join-Clause.md @@ -81,9 +81,7 @@ In the current version of IoTDB, the following joins are supported: #### 3.1.1 Explicit Join (Recommended) -Explicit joins use the syntax `JOIN + ON` or `JOIN + USING` to specify join conditions. - -The SQL syntax is as follows: +Explicit joins use the syntax JOIN + ON or JOIN + USING to specify join conditions: ```sql // Explicit join: Specify the join condition after the ON keyword or the join column(s) after the USING keyword. @@ -107,8 +105,6 @@ joinCriteria Implicit joins do not use `JOIN`, `ON`, or `USING` keywords. Instead, conditions are specified in the `WHERE` clause: -The SQL syntax is as follows: - ```sql // Implicit join: Specify the join condition in the WHERE clause. SELECT selectExpr [, selectExpr] ... FROM [, ] ... [WHERE whereCondition] @@ -126,7 +122,7 @@ IoTDB currently supports only `FULL [OUTER] JOIN`. This type returns all records ## 4 Example Queries -The [Example Data page](../Basic-Concept/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results.corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. ### 4.1 FROM Examples @@ -218,7 +214,9 @@ It costs 0.072s #### 4.2.1 Inner Join -**Example 1: Explicit Join using** **`ON`** This query retrieves records where `table1` and `table2` share the same `time` values. +**Example 1: Explicit Join using `ON`** + +This query retrieves records where `table1` and `table2` share the same `time` values. ```sql SELECT @@ -246,7 +244,9 @@ Total line number = 3 It costs 0.076s ``` -**Example 2: Explicit Join using** **`USING`** This query retrieves records from `table1` and `table2`, joining on the `time` column. +**Example 2: Explicit Join using `USING`** + +This query retrieves records from `table1` and `table2`, joining on the `time` column. ```sql SELECT time, @@ -273,7 +273,9 @@ Total line number = 3 It costs 0.081s ``` -**Example 3: Implicit Join using** **`WHERE`** This query joins `table1` and `table2` by specifying the condition in the `WHERE` clause. +**Example 3: Implicit Join using `WHERE`** + +This query joins `table1` and `table2` by specifying the condition in the `WHERE` clause. ```sql SELECT t1.time, @@ -303,7 +305,9 @@ It costs 0.082s #### 4.2.2 Outer Join -**Example 1: Full Outer Join using** **`ON`** This query retrieves all records from `table1` and `table2`, including unmatched rows with `NULL` values. +**Example 1: Full Outer Join using `ON`** + +This query retrieves all records from `table1` and `table2`, including unmatched rows with `NULL` values. ```sql SELECT @@ -349,7 +353,7 @@ Total line number = 21 It costs 0.071s ``` -**Example 2: Explicit Join using** **`USING`** +**Example 2: Explicit Join using `USING`** This query retrieves all records from `table1` and `table2`, combining them based on the `time` column. Rows with no matches in one of the tables will include `NULL` values for the missing fields. diff --git a/src/UserGuide/Master/Table/SQL-Manual/GroupBy-Clause.md b/src/UserGuide/Master/Table/SQL-Manual/GroupBy-Clause.md index 95c9795e1..6522f34eb 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/GroupBy-Clause.md +++ b/src/UserGuide/Master/Table/SQL-Manual/GroupBy-Clause.md @@ -34,7 +34,9 @@ GROUP BY expression (',' expression)* ## 2 Notes -- Items in the `SELECT` clause must either include aggregate functions or consist of columns specified in the `GROUP BY` clause. +#### 2.1 Items in the `SELECT` Clause + +Items in the `SELECT` clause must either include aggregate functions or consist of columns specified in the `GROUP BY` clause. Valid Example: @@ -91,13 +93,15 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Column 'model' cannot be resolved ``` -- If there is no `GROUP BY` clause, all items in the `SELECT` clause must either include aggregate functions or exclude them entirely. +#### 2.2 Without a `GROUP BY` Clause + +If there is no `GROUP BY` clause, all items in the `SELECT` clause must either include aggregate functions or exclude them entirely. Valid Example: ```sql SELECT COUNT(*), avg(temperature) - FROM table1; -- 合法 + FROM table1; -- valid ``` Result: @@ -125,9 +129,11 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: 'humidity' must be an aggregate expression or appear in GROUP BY clause ``` -- The `GROUP BY` clause supports referencing `SELECT` items using constant integers starting from 1. If the constant is less than 1 or exceeds the size of the `SELECT` item list, an error will occur. +#### 2.3 Using Constant Integers in `GROUP BY` Clause + +The `GROUP BY` clause supports referencing `SELECT` items using constant integers starting from 1. If the constant is less than 1 or exceeds the size of the `SELECT` item list, an error will occur. - **Example:** +Example: ```sql SELECT date_bin(1h, time), device_id, avg(temperature) @@ -152,9 +158,11 @@ Total line number = 5 It costs 0.092s ``` -- Aliases from `SELECT` items cannot be used in the `GROUP BY` clause. Use the original expression instead. +#### 2.4 Alias Restrictions in `GROUP BY` Clause - **Example:** +Aliases from `SELECT` items cannot be used in the `GROUP BY` clause. Use the original expression instead. + +Example: ```sql SELECT date_bin(1h, time) AS hour_time, device_id, avg(temperature) @@ -179,9 +187,11 @@ Total line number = 5 It costs 0.092s ``` -- Only the `COUNT` function can be used with `*` to calculate the total number of rows. Using `*` with other aggregate functions will result in an error. +#### 2.5 Using Aggregate Functions with `\*` + +Only the `COUNT` function can be used with `*` to calculate the total number of rows. Using `*` with other aggregate functions will result in an error. - **Example:** +Example: ```sql SELECT count(*) FROM table1; @@ -201,7 +211,7 @@ It costs 0.047s ## 3 Sample Data and Usage Examples -The [Example Data page](../Basic-Concept/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results.corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. #### Example 1: Downsampling Time-Series Data @@ -256,8 +266,8 @@ Total line number = 8 It costs 0.081s ``` -有关date_bin函数的更多详细信息可以参见 date_bin （时间分桶规整）函数功能定义 - For more details on the `date_bin` function, refer to the **Definition of Date Bin** **(Time Bucketing)** feature documentation. + +For more details on the `date_bin` function, refer to the **Definition of Date Bin (Time Bucketing)** feature documentation. #### Example 2: Query the Latest Data Point for Each Device diff --git a/src/UserGuide/Master/Table/SQL-Manual/Having-Clause.md b/src/UserGuide/Master/Table/SQL-Manual/Having-Clause.md index b0952623d..8b2b68afe 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/Having-Clause.md +++ b/src/UserGuide/Master/Table/SQL-Manual/Having-Clause.md @@ -34,11 +34,11 @@ The `HAVING` clause is used to filter aggregated results after a `GROUP BY` oper #### Notes -- 就语法而言，`HAVING`子句与`WHERE`子句相同，WHERE子句在分组聚合之前对数据进行过滤，HAVING子句是对分组聚合后的结果进行过滤。 +In terms of syntax, the `HAVING` clause is similar to the `WHERE` clause. However, while `WHERE` filters rows before grouping and aggregation, `HAVING` filters the results after grouping and aggregation. ## 2 Sample Data and Usage Examples -The [Example Data page](../Basic-Concept/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results.corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. #### Example 1: Filtering Devices with Entry Counts Below a Certain Threshold diff --git a/src/UserGuide/Master/Table/SQL-Manual/Identifier.md b/src/UserGuide/Master/Table/SQL-Manual/Identifier.md index f8604e678..782fecf47 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/Identifier.md +++ b/src/UserGuide/Master/Table/SQL-Manual/Identifier.md @@ -21,18 +21,18 @@ # Identifiers -In IoTDB, identifiers are used to identify database, table, column, function, or other object names. +In IoTDB, identifiers are used to represent the names of databases, tables, columns, functions, and other objects. ## 1 Naming Rules -- __First Character__：Identifiers must begin with a letter. -- __Subsequent Characters__：Can include letters, numbers, and underscores. -- __Special Characters__：If an identifier contains characters other than letters, numbers, and underscores, it must be enclosed in double quotes (`"`). -- __Escape Character__：Within double-quoted identifiers, two consecutive double quotes (`""`) are used to represent a single double quote character. +1. **Starting Character**: An identifier must begin with a letter. +2. **Subsequent Characters**: Identifiers can include letters, digits, and underscores. +3. **Special Characters**: If an identifier contains characters other than letters, digits, and underscores, it must be enclosed in double quotes (`"`). +4. **Escape Characters**: In double-quoted identifiers, a double quote character can be represented using two consecutive double quotes (`""`). ### 1.1 Examples -Here are some valid identifier examples: +Here are some examples of valid identifiers: ```sql test @@ -42,7 +42,7 @@ test "quotes" ``` -Invalid identifier examples that must be quoted with double quotes: +The following are examples of invalid identifiers that must be enclosed in double quotes to be used: ```sql table-name // contains a hyphen @@ -52,13 +52,13 @@ colum$name@field // contains special characters and is not enclosed in double q ## 2 Case Sensitivity -Identifiers are not case-sensitive, and the system does not retain the original case when storing identifiers. The column names in the query results will be displayed based on the case specified by the user in the SELECT clause. +Identifiers in IoTDB are case-insensitive. The system does not preserve the original case of identifiers during storage, but query results display column names in the same case as specified in the SELECT clause of the query. -> Identifiers enclosed in double quotes are also not case-sensitive. +> Identifiers enclosed in double quotes are also case-insensitive. ### 2.1 Example -When a column named `Device_id` is created, it is seen as `device_id` when viewing the table, but the returned result column matches the format specified by the user in the query as `Device_ID`: +Suppose a column named `Device_id` is created. When inspecting the table schema, it appears as `device_id`, but query results reflect the column name in the format specified by the user during the query (e.g., `Device_ID`). ```sql IoTDB> create table table1(Device_id STRING TAG, Model STRING ATTRIBUTE, TemPerature FLOAT FIELD, Humidity DOUBLE FIELD) diff --git a/src/UserGuide/Master/Table/SQL-Manual/Keywords.md b/src/UserGuide/Master/Table/SQL-Manual/Keywords.md index d387f6c63..0bb31d769 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/Keywords.md +++ b/src/UserGuide/Master/Table/SQL-Manual/Keywords.md @@ -21,7 +21,7 @@ # Reserved Words & Keywords -Reserved keywords must be quoted in double quotes (`"`) to be used as identifiers. The following are all reserved words in the IoTDB table model: +Reserved keywords must be enclosed in double quotes (" ") to be used as identifiers. Below is a list of all reserved keywords in the IoTDB table model. - ALTER - AND diff --git a/src/UserGuide/Master/Table/SQL-Manual/Limit-Offset-Clause.md b/src/UserGuide/Master/Table/SQL-Manual/Limit-Offset-Clause.md index 81d9d5ce7..9a321e361 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/Limit-Offset-Clause.md +++ b/src/UserGuide/Master/Table/SQL-Manual/Limit-Offset-Clause.md @@ -34,7 +34,7 @@ The `LIMIT` clause is applied in the final stage of a query to restrict the numb #### Notes - When `LIMIT` is used without an `ORDER BY` clause, the result order may not be deterministic. -- The `LIMIT` clause requires a non-negative integer.。 +- The `LIMIT` clause requires a non-negative integer. ### 1.2 OFFSET Clause @@ -48,7 +48,7 @@ The `OFFSET` clause works in conjunction with the `LIMIT` clause to skip a speci ## 2 Sample Data and Usage Examples -The [Example Data page](../Basic-Concept/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results.corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. #### Example 1: Retrieve the Latest Row for a Device diff --git a/src/UserGuide/Master/Table/SQL-Manual/OrderBy-Clause.md b/src/UserGuide/Master/Table/SQL-Manual/OrderBy-Clause.md index f60aaf9c3..347e4cfab 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/OrderBy-Clause.md +++ b/src/UserGuide/Master/Table/SQL-Manual/OrderBy-Clause.md @@ -21,6 +21,8 @@ # ORDER BY Clauses +The `ORDER BY` clause is used to sort the result set of a query at its final stage based on specified sorting conditions. + ## 1 Syntax Overview ```sql @@ -33,17 +35,17 @@ sortItem ### 1.1 ORDER BY Clauses -- The ORDER BY clause is used in the final stage of a query to sort the result set. It arranges the rows in the query result in ascending (ASC) or descending (DESC) order based on the specified sorting conditions. -- It provides control over the position of NULL values in the排序, allowing users to specify whether NULL values should be placed at the beginning (NULLS FIRST) or the end (NULLS LAST) of the sorted results. -- By default, ASC NULLS LAST sorting is used, meaning values are sorted in ascending order with NULLs placed at the end. You can change the default sorting order by manually specifying other parameters. -- The execution order of the ORDER BY clause is before the LIMIT or OFFSET clauses. +- Allows sorting query result rows based on specified conditions in ascending order (`ASC`) or descending order (`DESC`). +- Provides control over the position of `NULL` values, enabling users to specify whether `NULL` values appear at the beginning (`NULLS FIRST`) or the end (`NULLS LAST`). +- By default, sorting is applied as `ASC NULLS LAST`, meaning values are sorted in ascending order and `NULL` values are placed at the end. Users can manually specify other parameters to override the default behavior. +- The `ORDER BY` clause is executed before the `LIMIT` or `OFFSET` clauses. ## 2 Example Data -In the [Example Data page](../Basic-Concept/Sample-Data.md), there are SQL statements for building the table structure and inserting data. By downloading and executing these statements in the IoTDB CLI, you can import data into IoTDB. You can use this data to test and execute the SQL statements in the examples and obtain the corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. -#### Example 1: Retrieve data from the past hour in descending order of time +#### Example 1: Query data from the past hour in descending order of time ```sql SELECT * @@ -52,7 +54,7 @@ SELECT * ORDER BY time DESC; ``` -The execution results are as follows:： +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -74,7 +76,7 @@ Total line number = 11 It costs 0.148s ``` -#### Example 2: Query the data of all devices in the past hour in ascending order and descending order of time based on ' `device_id`', with `temperature` being prioritized for display +#### Example 2: Query data sorted by device_id in ascending order and time in descending order, with NULL temperatures displayed first ```sql SELECT * @@ -83,7 +85,7 @@ SELECT * ORDER BY temperature NULLS FIRST, time DESC; ``` -The execution results are as follows:： +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -105,7 +107,7 @@ Total line number = 11 It costs 0.060s ``` -#### Example 3: Querying the top 10 rows of data with the highest temperature +#### Example 3: Query the top 10 rows with the highest temperature values ```sql SELECT * @@ -114,7 +116,7 @@ SELECT * LIMIT 10; ``` -The execution results are as follows:： +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ diff --git a/src/UserGuide/Master/Table/SQL-Manual/Select-Clause.md b/src/UserGuide/Master/Table/SQL-Manual/Select-Clause.md index 8f467b23a..32018c2ad 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/Select-Clause.md +++ b/src/UserGuide/Master/Table/SQL-Manual/Select-Clause.md @@ -21,6 +21,8 @@ # SELECT Clauses +**SELECT Clause** specifies the columns included in the query results. + ## 1 Syntax Overview ```sql @@ -33,36 +35,36 @@ selectItem ; ``` -- __SELECT Clause__: SELECT Clause: Specifies the columns to be included in the query results, including aggregate functions (such as SUM, AVG, COUNT, etc.) and window functions, which are logically executed last. +- It supports aggregate functions (e.g., `SUM`, `AVG`, `COUNT`) and window functions, logically executed last in the query process. ## 2 Detailed Syntax: -Each `selectItem` can be one of the following forms: +Each `selectItem` can take one of the following forms: -- __Expression__: `expression [ [ AS ] column_alias ]` defines a single output column, and a column alias can be specified. -- __Selecting all columns of a relation__: `relation.*` selects all columns of a certain relation, and column aliases are not allowed. -- __Selecting all columns in the result set__: `*` selects all columns of the query, and column aliases are not allowed. +1. **Expression**: `expression [[AS] column_alias]` defines a single output column and optionally assigns an alias. +2. **All Columns from a Relation**: `relation.*` selects all columns from a specified relation. Column aliases are not allowed in this case. +3. **All Columns in the Result Set**: `*` selects all columns returned by the query. Column aliases are not allowed. ## 3 Example Data -In the [Example Data page](../Basic-Concept/Sample-Data.md), there are SQL statements for building the table structure and inserting data. By downloading and executing these statements in the IoTDB CLI, you can import data into IoTDB. You can use this data to test and execute the SQL statements in the examples and obtain the corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. -### 3.1 Select List +### 3.1 Selection List #### 3.1.1 Star Expression -The asterisk (*) can be used to select all columns from a table. __Note__, the star expression cannot be transformed by most functions, except in the case of `count(*)`. +The asterisk (`*`) selects all columns in a table. Note that it cannot be used with most functions, except for cases like `COUNT(*)`. -Example: Select all columns from a table +**Example**: Selecting all columns from a table. ```sql SELECT * FROM table1; ``` -The execution result is as follows: +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -93,15 +95,15 @@ It costs 0.653s #### 3.1.2 Aggregate Functions -Aggregate functions summarize multiple rows of data into a single value. When the SELECT clause contains aggregate functions, the query is considered an aggregate query. In aggregate queries, all expressions must be part of an aggregate function or specified by the [GROUP BY clause](../SQL-Manual/GroupBy-Clause.md) for grouping. +Aggregate functions summarize multiple rows into a single value. When aggregate functions are present in the `SELECT` clause, the query is treated as an **aggregate query**. All expressions in the query must either be part of an aggregate function or specified in the [GROUP BY clause](../SQL-Manual/GroupBy-Clause.md). -Example 1: Return the total number of rows in the address table: +**Example 1**: Total number of rows in a table. ```sql SELECT count(*) FROM table1; ``` -The execution result is as follows: +Results: ```sql +-----+ @@ -113,8 +115,7 @@ Total line number = 1 It costs 0.091s ``` -Example 2: Return the total number of rows in the address table grouped by city: - +**Example 2**: Total rows grouped by region. ```sql SELECT region, count(*) @@ -122,7 +123,7 @@ SELECT region, count(*) GROUP BY region; ``` -The execution result is as follows: +Results: ```sql +------+-----+ @@ -137,16 +138,16 @@ It costs 0.071s #### 3.1.3 Aliases -The keyword `AS` is used to specify an alias for the selected column, which overrides the existing column name to improve the readability of the query results. +The `AS` keyword assigns an alias to selected columns, improving readability by overriding existing column names. -Example 1: Original Table: +**Example 1**: Original table. ```sql IoTDB> SELECT * FROM table1; ``` -The execution result is as follows: +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -175,7 +176,7 @@ Total line number = 18 It costs 0.653s ``` -Example 2: Single column alias setting: +**Example 2**: Assigning an alias to a single column. ```sql IoTDB> SELECT device_id @@ -183,7 +184,7 @@ IoTDB> SELECT device_id FROM table1; ``` -The execution result is as follows: +Results: ```sql +------+ @@ -212,7 +213,7 @@ Total line number = 18 It costs 0.053s ``` -Example 3: Aliases for all columns: +**Example 3:** Assigning aliases to all columns. ```sql IoTDB> SELECT table1.* @@ -220,7 +221,7 @@ IoTDB> SELECT table1.* FROM table1; ``` -The execution result is as follows: +Results: ```sql +-----------------------------+----+----+-----+---+---+----+----+-----+-----------------------------+ @@ -249,7 +250,7 @@ Total line number = 18 It costs 0.189s ``` -## 4 Result Set Column Order +## 4 Column Order in the Result Set -- __Column order__: The column order in the result set is the same as the order specified in the SELECT clause. -- __Multi column sorting__: If an expression is selected to return multiple columns, their sorting method is the same as the sorting method in the source relationship. \ No newline at end of file +- **Column Order**: The order of columns in the result set matches the order specified in the `SELECT` clause. +- **Multi-column Expressions**: If a selection expression produces multiple columns, their order follows the order in the source relation.p. \ No newline at end of file diff --git a/src/UserGuide/Master/Table/SQL-Manual/Where-Clause.md b/src/UserGuide/Master/Table/SQL-Manual/Where-Clause.md index 88fef659f..630f36277 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/Where-Clause.md +++ b/src/UserGuide/Master/Table/SQL-Manual/Where-Clause.md @@ -27,20 +27,20 @@ WHERE booleanExpression ``` -__WHERE clause __: Used to specify filtering conditions in SQL queries, the WHERE clause is executed immediately after the FROM clause. +The `WHERE` clause is used to specify filter conditions in an SQL query. It is executed immediately after the `FROM` clause. ## 2 Example Data +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. -In the [Example Data page](../Basic-Concept/Sample-Data.md), there are SQL statements for building the table structure and inserting data. By downloading and executing these statements in the IoTDB CLI, you can import data into IoTDB. You can use this data to test and execute the SQL statements in the examples and obtain the corresponding results. -#### Example 1: Select a row with a specific ID +#### Example 1: Selecting Rows with a Specific ID ```sql SELECT * FROM table1 WHERE plant_id = '1001'; ``` -The execution result is as follows: +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -60,13 +60,13 @@ Total line number = 9 It costs 0.091s ``` -#### Example 2: Choose to use LIKE expression for matching +#### Example 2: Using the `LIKE` Expression for Matching ```sql SELECT * FROM table1 WHERE plant_id LIKE '300%'; ``` -The execution result is as follows: +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -86,13 +86,13 @@ Total line number = 9 It costs 0.261s ``` -#### Example 3: Choose to use composite expression filtering +#### Example 3: Filtering with a Compound Expression ```sql SELECT * FROM table1 WHERE time >= 2024-11-28 00:00:00 and (plant_id = '3001' OR plant_id = '3002'); ``` -The execution result is as follows: +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ diff --git a/src/UserGuide/Master/Table/SQL-Manual/overview.md b/src/UserGuide/Master/Table/SQL-Manual/overview.md index 00b4434be..89bc8cd65 100644 --- a/src/UserGuide/Master/Table/SQL-Manual/overview.md +++ b/src/UserGuide/Master/Table/SQL-Manual/overview.md @@ -35,26 +35,18 @@ SELECT ⟨select_list⟩ [LIMIT ⟨n⟩]; ``` -IoTDB query syntax provides the following clauses: - -- SELECT Clause: The columns to include in the query results. For detailed syntax, see: [SELECTClauses](../SQL-Manual/Select-Clause.md) -- FROM Clause: Specifies the data source of the query, which can be a single table, multiple tables joined using the JOIN clause, or a subquery. For detailed syntax, see: [FROM & JOIN Clauses](../SQL-Manual/From-Join-Clause.md) -- WHERE Clause: Used to filter data, selecting only rows that meet specific conditions. This clause is logically executed immediately after the FROM clause. For detailed syntax, see:[WHERE Clauses](../SQL-Manual/Where-Clause.md) -- GROUP BY Clause: Used when data aggregation is needed, specifying the columns used for grouping. For detailed syntax, see: [GROUP BY Clauses](../SQL-Manual/GroupBy-Clause.md) -- HAVING Clause: Used after the GROUP BY clause to filter data that has already been grouped. Similar to the WHERE clause, but the HAVING clause is executed after grouping. For detailed syntax, see: [HAVING Clauses](../SQL-Manual/Having-Clause.md) -- FILL Clause: Used to handle null values in the query results. Users can specify filling modes (such as the previous non-null value or linear interpolation) to fill null values with the FILL clause, facilitating data visualization and analysis. For detailed syntax, see: [FILL Clauses](../SQL-Manual/Fill-Clause.md) -- ORDER BY Clause: Sorts the query results, specifying ascending (ASC) or descending (DESC) order, as well as handling of NULL values (NULLS FIRST or NULLS LAST). For detailed syntax, see: [ORDER BY Clauses](../SQL-Manual/OrderBy-Clause.md) -- OFFSET Clause: Used to specify the starting position of the query results, that is, skipping the first OFFSET rows. Used in conjunction with the LIMIT clause. For detailed syntax, see: [LIMIT and OFFSET Clauses](../SQL-Manual/Limit-Offset-Clause.md) -- LIMIT Clause: Limits the number of rows in the query results, often used with the OFFSET clause to implement pagination. For detailed syntax, see: [LIMIT and OFFSET Clauses](../SQL-Manual/Limit-Offset-Clause.md) - -## 2 Clause Execution Order - -1. FROM (table name) -2. WHERE (condition filtering) -3. SELECT (column names/expressions) -4. GROUP BY (grouping) -5. HAVING (condition filtering after grouping) -6. FILL(null value filling) -7. ORDER BY (sorting) -8. OFFSET (offset amount) -9. LIMIT (limit amount) \ No newline at end of file +The IoTDB table model query syntax supports the following clauses: + +- **SELECT Clause**: Specifies the columns to be included in the result. Details: [SELECT Clause](../SQL-Manual/Select-Clause.md) +- **FROM Clause**: Indicates the data source for the query, which can be a single table, multiple tables joined using the `JOIN` clause, or a subquery. Details: [FROM & JOIN Clause](../SQL-Manual/From-Join-Clause.md) +- **WHERE Clause**: Filters rows based on specific conditions. Logically executed immediately after the `FROM` clause. Details: [WHERE Clause](../SQL-Manual/Where-Clause.md) +- **GROUP BY Clause**: Used for aggregating data, specifying the columns for grouping. Details: [GROUP BY Clause](../SQL-Manual/GroupBy-Clause.md) +- **HAVING Clause**: Applied after the `GROUP BY` clause to filter grouped data, similar to `WHERE` but operates after grouping. Details:[HAVING Clause](../SQL-Manual/Having-Clause.md) +- **FILL Clause**: Handles missing values in query results by specifying fill methods (e.g., previous non-null value or linear interpolation) for better visualization and analysis. Details:[FILL Clause](../SQL-Manual/Fill-Clause.md) +- **ORDER BY Clause**: Sorts query results in ascending (`ASC`) or descending (`DESC`) order, with optional handling for null values (`NULLS FIRST` or `NULLS LAST`). Details: [ORDER BY Clause](../SQL-Manual/OrderBy-Clause.md) +- **OFFSET Clause**: Specifies the starting position for the query result, skipping the first `OFFSET` rows. Often used with the `LIMIT` clause. Details: [LIMIT and OFFSET Clause](../SQL-Manual/Limit-Offset-Clause.md) +- **LIMIT Clause**: Limits the number of rows in the query result. Typically used in conjunction with the `OFFSET` clause for pagination. Details: [LIMIT and OFFSET Clause](../SQL-Manual/Limit-Offset-Clause.md) + +## 2. Clause Execution Order + +![](/img/%E5%AD%90%E5%8F%A5%E6%89%A7%E8%A1%8C%E9%A1%BA%E5%BA%8F01.png) \ No newline at end of file diff --git a/src/UserGuide/latest-Table/Basic-Concept/Delete-Data.md b/src/UserGuide/latest-Table/Basic-Concept/Delete-Data.md new file mode 100644 index 000000000..f2016dd7f --- /dev/null +++ b/src/UserGuide/latest-Table/Basic-Concept/Delete-Data.md @@ -0,0 +1,116 @@ + + +# Data Deletion + +## 1. Data Deletion + +Data deletion in IoTDB can be achieved using the DELETE statement. You can specify filters based on tags and time to delete specific subsets of data. + +### 1.1 Syntax Overview + +```SQL +DELETE FROM [WHERE_CLAUSE]? + +WHERE_CLAUSE: + WHERE DELETE_CONDITION + +DELETE_CONDITION: + SINGLE_CONDITION + | DELETE_CONDITION AND DELETE_CONDITION + | DELETE_CONDITION OR DELETE_CONDITION + +SINGLE_CODITION: + TIME_CONDITION | ID_CONDITION + +TIME_CONDITION: + time TIME_OPERATOR LONG_LITERAL + +TIME_OPERATOR: + < | > | <= | >= | = + +ID_CONDITION: + identifier = STRING_LITERAL +``` + +**Note:** + +- The `DELETE_CONDITION` can include single conditions or be a combination of conditions (logical operators like `AND` and `OR` are used). Currently, only **time conditions** and **tag conditions** are supported. +- For **time conditions**, operators include standard comparison symbols (`<`, `>`, etc.). +- For **tag conditions**, only equality (=) is allowed. + +### 1.2 Examples + +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. + +#### 1.2.1 Delet All Data from a Table + +```SQL +# Whole table deletion +DELETE FROM table1 +``` + +#### 1.2.2 Delete Data within a Specific Time Range + +```SQL +# Single time interval deletion +DELETE FROM table1 WHERE time <= 2024-11-29 00:00:00 + +# Multi time interval deletion +DELETE FROM table1 WHERE time >= 2024-11-27 00:00:00 and time <= 2024-11-29 00:00:00 +``` + +#### 1.2.3 Deleting Data for a Specific Device + +```SQL +# Device-specific deletion +# Identifier conditions only support the '=' operator +DELETE FROM table1 WHERE device_id='101' and model_id = 'B' + +# Device-specific deletion with time interval +DELETE FROM table1 + WHERE time >= 2024-11-27 16:39:00 and time <= 2024-11-29 16:42:00 + AND device_id='101' and model_id = 'B' + +# Device-type-specific deletion +DELETE FROM table1 WHERE model_id = 'B' +``` + +## 2. Device Deletion + +When a device is written to IoTDB, its metadata is retained even if data is deleted. To remove both the data and metadata of a device, you can use the `DELETE DEVICES` statement. + +### 2.1 Syntax Overview + +```SQL +DELETE DEVICES FROM tableName=qualifiedName (WHERE booleanExpression)? +``` + +**Notes:** + +- The `WHERE` clause supports only equality filters on tags. Conditions can be combined using `AND` and `OR` operators. +- Time conditions are **not** supported in the `DELETE DEVICES` statement. + +### 2.2 Example + +```SQL +DELETE DEVICES FROM table1 WHERE device_id = '101' +``` \ No newline at end of file diff --git a/src/UserGuide/latest-Table/Basic-Concept/Query-Data.md b/src/UserGuide/latest-Table/Basic-Concept/Query-Data.md new file mode 100644 index 000000000..4a5c51a95 --- /dev/null +++ b/src/UserGuide/latest-Table/Basic-Concept/Query-Data.md @@ -0,0 +1,277 @@ + + +# Data Query + +## 1. Syntax Overview + +```SQL +SELECT ⟨select_list⟩ + FROM ⟨tables⟩ + [WHERE ⟨condition⟩] + [GROUP BY ⟨groups⟩] + [HAVING ⟨group_filter⟩] + [FILL ⟨fill_methods⟩] + [ORDER BY ⟨order_expression⟩] + [OFFSET ⟨n⟩] + [LIMIT ⟨n⟩]; +``` + +The IoTDB table model query syntax supports the following clauses: + +- **SELECT Clause**: Specifies the columns to be included in the result. Details: [SELECT Clause](../SQL-Manual/Select-Clause.md) +- **FROM Clause**: Indicates the data source for the query, which can be a single table, multiple tables joined using the `JOIN` clause, or a subquery. Details: [FROM & JOIN Clause](../SQL-Manual/From-Join-Clause.md) +- **WHERE Clause**: Filters rows based on specific conditions. Logically executed immediately after the `FROM` clause. Details: [WHERE Clause](../SQL-Manual/Where-Clause.md) +- **GROUP BY Clause**: Used for aggregating data, specifying the columns for grouping. Details: [GROUP BY Clause](../SQL-Manual/GroupBy-Clause.md) +- **HAVING Clause**: Applied after the `GROUP BY` clause to filter grouped data, similar to `WHERE` but operates after grouping. Details:[HAVING Clause](../SQL-Manual/Having-Clause.md) +- **FILL Clause**: Handles missing values in query results by specifying fill methods (e.g., previous non-null value or linear interpolation) for better visualization and analysis. Details:[FILL Clause](../SQL-Manual/Fill-Clause.md) +- **ORDER BY Clause**: Sorts query results in ascending (`ASC`) or descending (`DESC`) order, with optional handling for null values (`NULLS FIRST` or `NULLS LAST`). Details: [ORDER BY Clause](../SQL-Manual/OrderBy-Clause.md) +- **OFFSET Clause**: Specifies the starting position for the query result, skipping the first `OFFSET` rows. Often used with the `LIMIT` clause. Details: [LIMIT and OFFSET Clause](../SQL-Manual/Limit-Offset-Clause.md) +- **LIMIT Clause**: Limits the number of rows in the query result. Typically used in conjunction with the `OFFSET` clause for pagination. Details: [LIMIT and OFFSET Clause](../SQL-Manual/Limit-Offset-Clause.md) + +## 2. Clause Execution Order + +![](/img/%E5%AD%90%E5%8F%A5%E6%89%A7%E8%A1%8C%E9%A1%BA%E5%BA%8F01.png) + + +## 3. Common Query Examples + +### 3.1 Sample Dataset + +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. + +### 3.2 Basic Data Query + +**Example 1: Filter by Time** + +```SQL +IoTDB> SELECT time, temperature, humidity + FROM table1 + WHERE time >= 2024-11-27 00:00:00 and time <= 2024-11-29 00:00:00; +``` + +**Result**: + +```SQL ++-----------------------------+-----------+--------+ +| time|temperature|humidity| ++-----------------------------+-----------+--------+ +|2024-11-28T08:00:00.000+08:00| 85.0| null| +|2024-11-28T09:00:00.000+08:00| null| 40.9| +|2024-11-28T10:00:00.000+08:00| 85.0| 35.2| +|2024-11-28T11:00:00.000+08:00| 88.0| 45.1| +|2024-11-27T16:38:00.000+08:00| null| 35.1| +|2024-11-27T16:39:00.000+08:00| 85.0| 35.3| +|2024-11-27T16:40:00.000+08:00| 85.0| null| +|2024-11-27T16:41:00.000+08:00| 85.0| null| +|2024-11-27T16:42:00.000+08:00| null| 35.2| +|2024-11-27T16:43:00.000+08:00| null| null| +|2024-11-27T16:44:00.000+08:00| null| null| ++-----------------------------+-----------+--------+ +Total line number = 11 +It costs 0.075s +``` + +**Example 2: Filter by** **Value** + +```SQL +IoTDB> SELECT time, temperature, humidity + FROM table1 + WHERE temperature > 89.0; +``` + +**Result**: + +```SQL ++-----------------------------+-----------+--------+ +| time|temperature|humidity| ++-----------------------------+-----------+--------+ +|2024-11-29T18:30:00.000+08:00| 90.0| 35.4| +|2024-11-26T13:37:00.000+08:00| 90.0| 35.1| +|2024-11-26T13:38:00.000+08:00| 90.0| 35.1| +|2024-11-30T09:30:00.000+08:00| 90.0| 35.2| +|2024-11-30T14:30:00.000+08:00| 90.0| 34.8| ++-----------------------------+-----------+--------+ +Total line number = 5 +It costs 0.156s +``` + +**Example 3: Filter by Attribute** + +```SQL +IoTDB> SELECT time, temperature, humidity + FROM table1 + WHERE model_id ='B'; +``` + +**Result**: + +```SQL ++-----------------------------+-----------+--------+ +| time|temperature|humidity| ++-----------------------------+-----------+--------+ +|2024-11-27T16:38:00.000+08:00| null| 35.1| +|2024-11-27T16:39:00.000+08:00| 85.0| 35.3| +|2024-11-27T16:40:00.000+08:00| 85.0| null| +|2024-11-27T16:41:00.000+08:00| 85.0| null| +|2024-11-27T16:42:00.000+08:00| null| 35.2| +|2024-11-27T16:43:00.000+08:00| null| null| +|2024-11-27T16:44:00.000+08:00| null| null| ++-----------------------------+-----------+--------+ +Total line number = 7 +It costs 0.106s +``` + +### 3.3 Aggregation Query + +**Example**: Calculate the average, maximum, and minimum temperature for each `device_id` within a specific time range. + +```SQL +IoTDB> SELECT device_id, AVG(temperature) as avg_temp, MAX(temperature) as max_temp, MIN(temperature) as min_temp + FROM table1 + WHERE time >= 2024-11-26 00:00:00 AND time <= 2024-11-29 00:00:00 + GROUP BY device_id; +``` + +**Result**: + +```SQL ++---------+--------+--------+--------+ +|device_id|avg_temp|max_temp|min_temp| ++---------+--------+--------+--------+ +| 100| 87.6| 90.0| 85.0| +| 101| 85.0| 85.0| 85.0| ++---------+--------+--------+--------+ +Total line number = 2 +It costs 0.278s +``` + +### 3.4 Latest Point Query + +**Example**: Retrieve the latest record for each `device_id`, including the temperature value and the timestamp of the last record. + +```SQL +IoTDB> SELECT device_id,last(temperature),last_by(time,temperature) + FROM table1 + GROUP BY device_id; +``` + +**Result**: + +```SQL ++---------+-----+-----------------------------+ +|device_id|_col1| _col2| ++---------+-----+-----------------------------+ +| 100| 90.0|2024-11-29T18:30:00.000+08:00| +| 101| 90.0|2024-11-30T14:30:00.000+08:00| ++---------+-----+-----------------------------+ +Total line number = 2 +It costs 0.090s +``` + +### 3.5 Downsampling Query + +**Example**: Group data by day and calculate the average temperature using `date_bin_gapfill` function. + +```SQL +IoTDB> SELECT date_bin(1d ,time) as day_time, AVG(temperature) as avg_temp + FROM table1 + WHERE time >= 2024-11-26 00:00:00 AND time <= 2024-11-30 00:00:00 + GROUP BY date_bin(1d ,time); +``` + +**Result**: + +```SQL ++-----------------------------+--------+ +| day_time|avg_temp| ++-----------------------------+--------+ +|2024-11-29T08:00:00.000+08:00| 87.5| +|2024-11-28T08:00:00.000+08:00| 86.0| +|2024-11-26T08:00:00.000+08:00| 90.0| +|2024-11-27T08:00:00.000+08:00| 85.0| ++-----------------------------+--------+ +Total line number = 4 +It costs 0.110s +``` + +### 3.6 Missing Data Filling + +**Example**: Query the records within a specified time range where `device_id` is '100'. If there are missing data points, fill them using the previous non-null value. + +```SQL +IoTDB> SELECT time, temperature, humidity + FROM table1 + WHERE time >= 2024-11-26 00:00:00 and time <= 2024-11-30 11:00:00 + AND region='East' AND plant_id='1001' AND device_id='101' + FILL METHOD PREVIOUS; +``` + +**Result**: + +```SQL ++-----------------------------+-----------+--------+ +| time|temperature|humidity| ++-----------------------------+-----------+--------+ +|2024-11-27T16:38:00.000+08:00| null| 35.1| +|2024-11-27T16:39:00.000+08:00| 85.0| 35.3| +|2024-11-27T16:40:00.000+08:00| 85.0| 35.3| +|2024-11-27T16:41:00.000+08:00| 85.0| 35.3| +|2024-11-27T16:42:00.000+08:00| 85.0| 35.2| +|2024-11-27T16:43:00.000+08:00| 85.0| 35.2| +|2024-11-27T16:44:00.000+08:00| 85.0| 35.2| ++-----------------------------+-----------+--------+ +Total line number = 7 +It costs 0.101s +``` + +### 3.7 Sorting & Pagination + +**Example**: Query records from the table, sorting by `humidity` in descending order and placing null values (NULL) at the end. Skip the first 2 rows and return the next 8 rows. + +```SQL +IoTDB> SELECT time, temperature, humidity + FROM table1 + ORDER BY humidity desc NULLS LAST + OFFSET 2 + LIMIT 10; +``` + +**Result**: + +```SQL ++-----------------------------+-----------+--------+ +| time|temperature|humidity| ++-----------------------------+-----------+--------+ +|2024-11-28T09:00:00.000+08:00| null| 40.9| +|2024-11-29T18:30:00.000+08:00| 90.0| 35.4| +|2024-11-27T16:39:00.000+08:00| 85.0| 35.3| +|2024-11-28T10:00:00.000+08:00| 85.0| 35.2| +|2024-11-30T09:30:00.000+08:00| 90.0| 35.2| +|2024-11-27T16:42:00.000+08:00| null| 35.2| +|2024-11-26T13:38:00.000+08:00| 90.0| 35.1| +|2024-11-26T13:37:00.000+08:00| 90.0| 35.1| +|2024-11-27T16:38:00.000+08:00| null| 35.1| +|2024-11-30T14:30:00.000+08:00| 90.0| 34.8| ++-----------------------------+-----------+--------+ +Total line number = 10 +It costs 0.093s +``` diff --git a/src/UserGuide/latest-Table/Basic-Concept/TTL-Delete-Data.md b/src/UserGuide/latest-Table/Basic-Concept/TTL-Delete-Data.md new file mode 100644 index 000000000..df19a8596 --- /dev/null +++ b/src/UserGuide/latest-Table/Basic-Concept/TTL-Delete-Data.md @@ -0,0 +1,144 @@ + + +# Automatic Data Expiration (TTL) + +## 1. Overview + +Time-to-Live (TTL) is a mechanism for defining the lifespan of data in a database. In IoTDB, TTL allows setting table-level expiration policies, enabling the system to automatically delete outdated data periodically. This helps manage disk space efficiently, maintain high query performance, and reduce memory usage. + +TTL values are specified in milliseconds, and once data exceeds its defined lifespan, it becomes unavailable for queries and cannot be written to. However, the physical deletion of expired data occurs later during the compaction process. Note that changes to TTL settings can briefly impact the accessibility of data. + +**Notes:** + +1. TTL defines the expiration time of data in milliseconds, independent of the time precision configuration file. +2. Modifying TTL settings can cause temporary variations in data accessibility. +3. The system eventually removes expired data, though this process may involve some delay.。 + +## 2. Set TTL + +In the table model, IoTDB’s TTL operates at the granularity of individual tables. You can set TTL directly on a table or at the database level. When TTL is configured at the database level, it serves as the default for new tables created within the database. However, each table can still have its own independent TTL settings. + +**Note:** Modifying the database-level TTL does not retroactively affect the TTL settings of existing tables. + +### 2.1 Set TTL for Tables + +If TTL is specified when creating a table using SQL, the table’s TTL takes precedence. Refer to [Table-Management](../Basic-Concept/Table-Management.md)for details. + +Example 1: Setting TTL during table creation: + +```SQL +CREATE TABLE test3 ("site" string id, "temperature" int32) with (TTL=3600) +``` + +Example 2: Changing TTL for an existing table: + +```SQL +ALTER TABLE tableB SET PROPERTIES TTL=3600; +``` + +**Example 3:** If TTL is not specified or set to the default value, it will inherit the database's TTL. By default, the database TTL is `'INF'` (infinite): + +```SQL +CREATE TABLE test3 ("site" string id, "temperature" int32) with (TTL=DEFAULT) +CREATE TABLE test3 ("site" string id, "temperature" int32) +ALTER TABLE tableB set properties TTL=DEFAULT +``` + +### 2.2 Set TTL for Databases + +Tables without explicit TTL settings inherit the TTL of their database. Refer to [Database-Management](../Basic-Concept/Database-Management.md)for details. + +Example 4: A database with TTL=3600000 creates tables inheriting this TTL: + +```SQL +CREATE DATABASE db WITH (ttl=3600000) +use db +CREATE TABLE test3 ("site" string id, "temperature" int32) +``` + +Example 5: A database without a TTL setting creates tables without TTL: + +```SQL +CREATE DATABASE db +use db +CREATE TABLE test3 ("site" string id, "temperature" int32) +``` + +Example 6: Setting a table with no TTL explicitly (TTL=INF) in a database with a configured TTL: + +```SQL +CREATE DATABASE db WITH (ttl=3600000) +use db +CREATE TABLE test3 ("site" string id, "temperature" int32) with (ttl='INF') +``` + +## 3. Remove TTL + +To cancel a TTL setting, modify the table's TTL to 'INF'. Note that IoTDB does not currently support modifying the TTL of a database. + +```SQL +ALTER TABLE tableB set properties TTL='INF' +``` + +## 4. View TTL Information + +Use the SHOW DATABASES and SHOW TABLES commands to view TTL details for databases and tables. Refer to [Database-Management](../Basic-Concept/Database-Management.md)、 [Table-Management](../Basic-Concept/Table-Management.md)for details. + +> Note: TTL settings in tree-model will also be shown. + +Example Output: + +```SQL +IoTDB> show databases ++---------+-------+-----------------------+---------------------+---------------------+ +| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval| ++---------+-------+-----------------------+---------------------+---------------------+ +|test_prop| 300| 1| 3| 100000| +| test2| 300| 1| 1| 604800000| ++---------+-------+-----------------------+---------------------+---------------------+ + +IoTDB> show databases details ++---------+-------+-----------------------+---------------------+---------------------+-----+ +| Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|Model| ++---------+-------+-----------------------+---------------------+---------------------+-----+ +|test_prop| 300| 1| 3| 100000|TABLE| +| test2| 300| 1| 1| 604800000| TREE| ++---------+-------+-----------------------+---------------------+---------------------+-----+ +IoTDB> show tables ++---------+-------+ +|TableName|TTL(ms)| ++---------+-------+ +| grass| 1000| +| bamboo| 300| +| flower| INF| ++---------+-------+ + +IoTDB> show tables details ++---------+-------+----------+ +|TableName|TTL(ms)| Status| ++---------+-------+----------+ +| bean| 300|PRE_CREATE| +| grass| 1000| USING| +| bamboo| 300| USING| +| flower| INF| USING| ++---------+-------+----------+ +``` \ No newline at end of file diff --git a/src/UserGuide/latest-Table/Basic-Concept/Sample-Data.md b/src/UserGuide/latest-Table/Reference/Sample-Data.md similarity index 100% rename from src/UserGuide/latest-Table/Basic-Concept/Sample-Data.md rename to src/UserGuide/latest-Table/Reference/Sample-Data.md diff --git a/src/UserGuide/latest-Table/SQL-Manual/Fill-Clause.md b/src/UserGuide/latest-Table/SQL-Manual/Fill-Clause.md index d761f4f94..a708cc763 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/Fill-Clause.md +++ b/src/UserGuide/latest-Table/SQL-Manual/Fill-Clause.md @@ -24,9 +24,10 @@ ## 1 Function Introduction -When performing data queries, you may encounter situations where certain columns lack data in some rows, resulting in NULL values in the result set. These NULL values are not conducive to data visualization and analysis, so IoTDB provides the FILL clause to fill in these NULL values. +During data queries, you may encounter scenarios where certain columns have missing data in some rows, resulting in NULL values in the result set. These NULL values can hinder data visualization and analysis. To address this, IoTDB provides the FILL clause to populate these NULL values. -When the query includes an ORDER BY clause, the FILL clause will be executed before the ORDER BY. If there is a GAPFILL (date_bin_gapfill function) operation, the FILL clause will be executed after the GAPFILL. +- If the query includes an `ORDER BY` clause, the FILL clause is executed before `ORDER BY`. +- If a `GAPFILL` (e.g., `date_bin_gapfill` function) operation exists, the FILL clause is executed after `GAPFILL`. ## 2 Syntax Overview @@ -62,18 +63,18 @@ intervalField ; ``` -### 2.1 Filling Methods +### 2.1 ### Filling Methods -IoTDB supports the following three methods for filling null values: +IoTDB supports the following three methods to fill NULL values: -1. __`PREVIOUS` Filling__：Fills with the previous non-null value of the column. -2. __`LINEAR` Filling__：Fills with the linear interpolation between the previous and next non-null values of the column. -3. __`Constant` Filling__：Fills with a specified constant value. +1. **PREVIOUS Fill:** Uses the most recent non-NULL value from the same column to fill NULL values. +2. **LINEAR Fill:** Applies linear interpolation using the nearest previous and next non-NULL values in the same column. +3. **CONSTANT Fill:** Fills NULL values with a specified constant. -Only one filling method can be specified, and this method will be applied to all columns in the result set. +Only one filling method can be specified, and it applies to all columns in the result set. -### 2.2 Data Types and Supported Filling Methods +### 2.2 Supported Data Types for Filling Methods | Data Type | Previous | Linear | Constant | | :-------- | :------- | :----- | :------- | @@ -88,26 +89,26 @@ Only one filling method can be specified, and this method will be applied to all | timestamp | √ | √ | √ | | date | √ | √ | √ | -Note: For columns whose data types do not support the specified filling method, neither filling is performed nor exceptions are thrown; the original state is simply maintained. +**Note:** Columns with data types not supporting the specified filling method will remain unchanged without errors. -## 3 Example Data +## 3 Sample Dataset -In the [Example Data page](../Basic-Concept/Sample-Data.md), there are SQL statements for building the table structure and inserting data. By downloading and executing these statements in the IoTDB CLI, you can import data into IoTDB. You can use this data to test and execute the SQL statements in the examples and obtain the corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. -### 3.1 PREVIOUS Filling： +### 3.1 PREVIOUS Fill -For null values in the query result set, fill with the previous non-null value of the column. +`PREVIOUS FILL` fills NULL values with the most recent non-NULL value in the same column. -#### 3.1.1 Parameter Introduction： +#### 3.1.1 Parameters -- TIME_BOUND（optional）：The time threshold to look forward. If the time interval between the current null value's timestamp and the previous non-null value's timestamp exceeds this threshold, filling will not be performed. By default, the first TIMESTAMP type column in the query result is used to determine whether the time threshold has been exceeded. - - The format of the time threshold parameter is a time interval, where the numerical part must be an integer, and the unit part y represents years, mo represents months, w represents weeks, d represents days, h represents hours, m represents minutes, s represents seconds, ms represents milliseconds, µs represents microseconds, and ns represents nanoseconds, such as 1d1h. -- TIME_COLUMN（optional）：If you need to manually specify the TIMESTAMP column used to judge the time threshold, you can determine the order of the column by specifying a number (starting from 1) after the `TIME_COLUMN`parameter. This number represents the specific position of the TIMESTAMP column in the original table. +- **TIME_BOUND (optional):** Defines a forward-looking time threshold. If the time difference between the current NULL value and the previous non-NULL value exceeds this threshold, the value will not be filled. By default, the system uses the first `TIMESTAMP` column in the query result to determine the threshold. + - Format: A time interval specified with integer values and units, e.g., `1d1h` (1 day and 1 hour). +- **TIME_COLUMN (optional):** Allows specifying the `TIMESTAMP` column used to determine the time threshold. The column is specified using its positional index (starting from 1) in the original table. -#### 3.1.2 Example +#### 3.1.2 Examples -Without using any filling method: +- Without FILL Clause: ```sql SELECT time, temperature, status @@ -116,7 +117,7 @@ SELECT time, temperature, status AND plant_id='1001' and device_id='101'; ``` -Query results: +Results: ```sql +-----------------------------+-----------+------+ @@ -134,7 +135,7 @@ Total line number = 7 It costs 0.088s ``` -Use the PREVIOUS padding method (the result will be filled with the previous non null value to fill the NULL value): +- Using `PREVIOUS Fill`: ```sql SELECT time, temperature, status @@ -144,7 +145,7 @@ SELECT time, temperature, status FILL METHOD PREVIOUS; ``` -Query results: +Results: ```sql +-----------------------------+-----------+------+ @@ -162,7 +163,7 @@ Total line number = 7 It costs 0.091s ``` -Use the PREVIOUS padding method (specify time threshold): +- Using `PREVIOUS Fill` with a Specified Time Threshold: ```sql # Do not specify a time column @@ -180,7 +181,7 @@ SELECT time, temperature, status FILL METHOD PREVIOUS 1m TIME_COLUMN 1; ``` -Query results: +Results: ```sql +-----------------------------+-----------+------+ @@ -198,24 +199,23 @@ Total line number = 7 It costs 0.075s ``` -### 3.2 LINEAR Filling +### 3.2 LINEAR Fill -For null values in the query result set, fill with the linear interpolation between the previous and next non-null values of the column. +`LINEAR Fill` fills NULL values using linear interpolation based on the nearest previous and next non-NULL values in the same column. -#### 3.2.1 Linear Filling Rules: +#### 3.2.1 Linear Fill Rules -- If all previous values are null, or all subsequent values are null, no filling is performed. -- If the column's data type is boolean/string/blob/text, no filling is performed, and no exceptions are thrown. -- If no time column is specified, the system defaults to selecting the first column with a data type of TIMESTAMP in the SELECT clause as the auxiliary time column for linear interpolation. If no column with a TIMESTAMP data type exists, the system will throw an exception. +1. If all previous or all subsequent values are NULL, no filling is performed. +2. Columns with data types such as `boolean`, `string`, `blob`, or `text` are not filled, and no error is returned. +3. If no auxiliary time column is specified, the first `TIMESTAMP`-type column in the `SELECT` clause is used by default for interpolation. If no `TIMESTAMP` column exists, an error will be returned. -#### 3.2.2 Parameter Introduction: +#### 3.2.2 Parameters -- TIME_COLUMN（optional）：You can manually specify the `TIMESTAMP` column used to determine the time threshold as an auxiliary column for linear interpolation by specifying a number (starting from 1) after the `TIME_COLUMN` parameter. This number represents the specific position of the `TIMESTAMP` column in the original table. +- **TIME_COLUMN (optional):** Specifies the `TIMESTAMP` column to be used as an auxiliary column for linear interpolation. The column is identified by its positional index (starting from 1) in the original table. -Note: It is not mandatory that the auxiliary column for linear interpolation must be a time column; any expression with a TIMESTAMP type is acceptable. However, since linear interpolation only makes sense when the auxiliary column is in ascending or descending order, users need to ensure that the result set is ordered by that column in ascending or descending order if they specify other columns. +**Note:** The auxiliary column used for linear interpolation is not required to be the `time` column. However, the auxiliary column must be sorted in ascending or descending order for meaningful interpolation. If another column is specified, the user must ensure the result set is ordered correctly. - -#### 3.2.3 Example +#### 3.2.3 Examples ```sql @@ -226,7 +226,7 @@ SELECT time, temperature, status FILL METHOD LINEAR; ``` -Query results: +Result: ```sql +-----------------------------+-----------+------+ @@ -244,19 +244,19 @@ Total line number = 7 It costs 0.053s ``` -### 3.3 Constant Filling: +### 3.3 ### CONSTANT Fill -For null values in the query result set, fill with a specified constant. +`CONSTANT Fill` fills NULL values with a specified constant value. -#### 3.3.1 Constant Filling Rules: +#### 3.3.1 Constant Fill Rules -- If the data type does not match the input constant, IoTDB will not fill the query result and will not throw an exception. -- If the inserted constant value exceeds the maximum value that its data type can represent, IoTDB will not fill the query result and will not throw an exception. +1. If the data type of the constant does not match the column's data type, IoTDB does not fill the result set and no error is returned. +2. If the constant value exceeds the column's allowable range, IoTDB does not fill the result set and no error is returned. -#### 3.3.2 Example +#### 3.3.2 Examples -When using a `FLOAT` constant for filling, the SQL statement is as follows: +- Using a `FLOAT` constant: ```sql @@ -267,7 +267,7 @@ SELECT time, temperature, status FILL METHOD CONSTANT 80.0; ``` -Query results: +Results: ```sql +-----------------------------+-----------+------+ @@ -285,8 +285,7 @@ Total line number = 7 It costs 0.242s ``` -When using the constant `BOOLEAN` to fill in, the SQL statement is as follows: - +W- Using a `BOOLEAN` constant: ```sql SELECT time, temperature, status @@ -296,7 +295,7 @@ SELECT time, temperature, status FILL METHOD CONSTANT true; ``` -Query results: +Results: ```sql +-----------------------------+-----------+------+ @@ -316,12 +315,13 @@ It costs 0.073s ## 4 Advanced Usage -When using `PREVIOUS` and `LINEAR` FILL, an additional `FILL_GROUP` parameter is also supported for filling within groups. +When using the `PREVIOUS` or `LINEAR` FILL methods, the `FILL_GROUP` parameter allows filling within specific groups without being influenced by other groups. -When using a group by clause with fill, you may want to fill within groups without being affected by other groups. +#### Examples -For example: Fill the null values within each `device_id` without using values from other devices: +- **Filling Missing Values Within `device_id`** +The following query demonstrates how to fill missing values for each `device_id` group independently, without using values from other devices: ```sql SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) AS avg_temp FROM table1 @@ -329,7 +329,7 @@ SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) A group by 1, plant_id, device_id; ``` -Query results: +Results： ```sql +-----------------------------+--------+---------+--------+ @@ -348,7 +348,9 @@ Total line number = 8 It costs 0.110s ``` -If the FILL_GROUP parameter is not specified, the null value for `100` will be filled with the value of `101`: +- **Without Specifying `FILL_GROUP`** + +If the `FILL_GROUP` parameter is not specified, missing values in `device_id = 100` will be filled using values from `device_id = 101`: ```sql SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) AS avg_temp @@ -358,7 +360,7 @@ SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) A FILL METHOD PREVIOUS; ``` -Query results: +Results： ```sql +-----------------------------+--------+---------+--------+ @@ -377,7 +379,9 @@ Total line number = 8 It costs 0.066s ``` -After specifying FILL_GROUP as the second column, the filling will only occur within the group that uses the second column `device_id` as the group key. The null value for `100` will not be filled with the value of `101` because they belong to different groups. +- **Specifying `FILL_GROUP` for Grouped Filling** + +By specifying `FILL_GROUP 2`, the filling is restricted to groups based on the second column (`device_id`). As a result, missing values in `device_id = 100` will not be filled using values from `device_id = 101`: ```sql SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) AS avg_temp @@ -387,7 +391,7 @@ SELECT date_bin(1h, time) AS hour_time, plant_id, device_id, avg(temperature) A FILL METHOD PREVIOUS FILL_GROUP 2; ``` -Query results: +Results: ```sql +-----------------------------+--------+---------+--------+ @@ -408,12 +412,14 @@ It costs 0.089s ## 5 Special Notes -When using `LINEAR FILL` or `PREVIOUS FILL`, if there are NULL values in the auxiliary time column (the column used to determine the filling logic), IoTDB will follow these rules: +When using `LINEAR` or `PREVIOUS` FILL methods, if the auxiliary time column (used to determine filling logic) contains NULL values, IoTDB follows these rules: -- Do not fill rows where the auxiliary time column is NULL. -- These rows will also not participate in the filling logic calculation. +- Rows with NULL values in the auxiliary column will not be filled. +- These rows are also excluded from the filling logic calculations. -Taking `PREVIOUS FILL` as an example, the original data is as follows: +**Example of `PREVIOUS Fill`** + +- Query original data: @@ -424,7 +430,7 @@ SELECT time, plant_id, device_id, humidity, arrival_time AND plant_id='1001' and device_id='101'; ``` -Query results: +Results: ```sql +-----------------------------+--------+---------+--------+-----------------------------+ @@ -442,7 +448,7 @@ Total line number = 7 It costs 0.119s ``` -Use the arrival_time column as the auxiliary time column and set the time interval (TIME_SOUND) to 2 ms (if the previous value is more than 2ms away from the current value, it will not be filled in): +- Using `arrival_time` as the auxiliary column with a time interval (`TIME_BOUND`) of 2 seconds ```sql SELECT time, plant_id, device_id, humidity, arrival_time @@ -452,7 +458,7 @@ SELECT time, plant_id, device_id, humidity, arrival_time FILL METHOD PREVIOUS TIME_BOUND 2s TIME_COLUMN 5; ``` -Query results: +Results: ```sql +-----------------------------+--------+---------+--------+-----------------------------+ @@ -469,9 +475,15 @@ Query results: Total line number = 7 It costs 0.049s ``` - -Filling results details: - -- For the humidity column at 16:39, 16:42, and 16:43, filling is not performed because the auxiliary column arrival_time is NULL. -- For the humidity column at 16:40, since the auxiliary column arrival_time is not NULL and is `1970-01-01T08:00:00.003+08:00`, which is within a 2ms time difference from the previous non-NULL value `1970-01-01T08:00:00.001+08:00`, it is filled with the value 1 from the first row (s1). -- For the humidity column at 16:41, although arrival_time is not NULL, the time difference from the previous non-NULL value exceeds 2ms, so no filling is performed. The same applies to the seventh row. \ No newline at end of file +**Filling Details** + +1. For `humidity` at `16:39`, `16:42`, and `16:43`: + 1. Since the auxiliary column `arrival_time` is NULL, no filling is performed. +2. For `humidity` at `16:40`: + 1. The auxiliary column `arrival_time` is not NULL and has a value of `1970-01-01T08:00:00.003+08:00`. + 2. The time difference from the previous non-NULL value (`1970-01-01T08:00:00.001+08:00`) is less than 2 seconds (`TIME_BOUND`) + 3. So the value `35.1` from the first row is used for filling. +3. For `humidity` at `16:41`: + 1. Although the auxiliary column `arrival_time` is not NULL, the time difference from the previous non-NULL value exceeds 2 seconds, so no filling is performed. +4. For `humidity` at `16:44`: + 1. Similarly, the time difference exceeds 2 seconds, so no filling is performed. \ No newline at end of file diff --git a/src/UserGuide/latest-Table/SQL-Manual/From-Join-Clause.md b/src/UserGuide/latest-Table/SQL-Manual/From-Join-Clause.md index b6d67780b..e561a9e03 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/From-Join-Clause.md +++ b/src/UserGuide/latest-Table/SQL-Manual/From-Join-Clause.md @@ -81,9 +81,7 @@ In the current version of IoTDB, the following joins are supported: #### 3.1.1 Explicit Join (Recommended) -Explicit joins use the syntax `JOIN + ON` or `JOIN + USING` to specify join conditions. - -The SQL syntax is as follows: +Explicit joins use the syntax JOIN + ON or JOIN + USING to specify join conditions: ```sql // Explicit join: Specify the join condition after the ON keyword or the join column(s) after the USING keyword. @@ -107,8 +105,6 @@ joinCriteria Implicit joins do not use `JOIN`, `ON`, or `USING` keywords. Instead, conditions are specified in the `WHERE` clause: -The SQL syntax is as follows: - ```sql // Implicit join: Specify the join condition in the WHERE clause. SELECT selectExpr [, selectExpr] ... FROM [, ] ... [WHERE whereCondition] @@ -126,7 +122,7 @@ IoTDB currently supports only `FULL [OUTER] JOIN`. This type returns all records ## 4 Example Queries -The [Example Data page](../Basic-Concept/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results.corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. ### 4.1 FROM Examples @@ -218,7 +214,9 @@ It costs 0.072s #### 4.2.1 Inner Join -**Example 1: Explicit Join using** **`ON`** This query retrieves records where `table1` and `table2` share the same `time` values. +**Example 1: Explicit Join using `ON`** + +This query retrieves records where `table1` and `table2` share the same `time` values. ```sql SELECT @@ -246,7 +244,9 @@ Total line number = 3 It costs 0.076s ``` -**Example 2: Explicit Join using** **`USING`** This query retrieves records from `table1` and `table2`, joining on the `time` column. +**Example 2: Explicit Join using `USING`** + +This query retrieves records from `table1` and `table2`, joining on the `time` column. ```sql SELECT time, @@ -273,7 +273,9 @@ Total line number = 3 It costs 0.081s ``` -**Example 3: Implicit Join using** **`WHERE`** This query joins `table1` and `table2` by specifying the condition in the `WHERE` clause. +**Example 3: Implicit Join using `WHERE`** + +This query joins `table1` and `table2` by specifying the condition in the `WHERE` clause. ```sql SELECT t1.time, @@ -303,7 +305,9 @@ It costs 0.082s #### 4.2.2 Outer Join -**Example 1: Full Outer Join using** **`ON`** This query retrieves all records from `table1` and `table2`, including unmatched rows with `NULL` values. +**Example 1: Full Outer Join using `ON`** + +This query retrieves all records from `table1` and `table2`, including unmatched rows with `NULL` values. ```sql SELECT @@ -349,7 +353,7 @@ Total line number = 21 It costs 0.071s ``` -**Example 2: Explicit Join using** **`USING`** +**Example 2: Explicit Join using `USING`** This query retrieves all records from `table1` and `table2`, combining them based on the `time` column. Rows with no matches in one of the tables will include `NULL` values for the missing fields. diff --git a/src/UserGuide/latest-Table/SQL-Manual/GroupBy-Clause.md b/src/UserGuide/latest-Table/SQL-Manual/GroupBy-Clause.md index 95c9795e1..6522f34eb 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/GroupBy-Clause.md +++ b/src/UserGuide/latest-Table/SQL-Manual/GroupBy-Clause.md @@ -34,7 +34,9 @@ GROUP BY expression (',' expression)* ## 2 Notes -- Items in the `SELECT` clause must either include aggregate functions or consist of columns specified in the `GROUP BY` clause. +#### 2.1 Items in the `SELECT` Clause + +Items in the `SELECT` clause must either include aggregate functions or consist of columns specified in the `GROUP BY` clause. Valid Example: @@ -91,13 +93,15 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Column 'model' cannot be resolved ``` -- If there is no `GROUP BY` clause, all items in the `SELECT` clause must either include aggregate functions or exclude them entirely. +#### 2.2 Without a `GROUP BY` Clause + +If there is no `GROUP BY` clause, all items in the `SELECT` clause must either include aggregate functions or exclude them entirely. Valid Example: ```sql SELECT COUNT(*), avg(temperature) - FROM table1; -- 合法 + FROM table1; -- valid ``` Result: @@ -125,9 +129,11 @@ Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: 'humidity' must be an aggregate expression or appear in GROUP BY clause ``` -- The `GROUP BY` clause supports referencing `SELECT` items using constant integers starting from 1. If the constant is less than 1 or exceeds the size of the `SELECT` item list, an error will occur. +#### 2.3 Using Constant Integers in `GROUP BY` Clause + +The `GROUP BY` clause supports referencing `SELECT` items using constant integers starting from 1. If the constant is less than 1 or exceeds the size of the `SELECT` item list, an error will occur. - **Example:** +Example: ```sql SELECT date_bin(1h, time), device_id, avg(temperature) @@ -152,9 +158,11 @@ Total line number = 5 It costs 0.092s ``` -- Aliases from `SELECT` items cannot be used in the `GROUP BY` clause. Use the original expression instead. +#### 2.4 Alias Restrictions in `GROUP BY` Clause - **Example:** +Aliases from `SELECT` items cannot be used in the `GROUP BY` clause. Use the original expression instead. + +Example: ```sql SELECT date_bin(1h, time) AS hour_time, device_id, avg(temperature) @@ -179,9 +187,11 @@ Total line number = 5 It costs 0.092s ``` -- Only the `COUNT` function can be used with `*` to calculate the total number of rows. Using `*` with other aggregate functions will result in an error. +#### 2.5 Using Aggregate Functions with `\*` + +Only the `COUNT` function can be used with `*` to calculate the total number of rows. Using `*` with other aggregate functions will result in an error. - **Example:** +Example: ```sql SELECT count(*) FROM table1; @@ -201,7 +211,7 @@ It costs 0.047s ## 3 Sample Data and Usage Examples -The [Example Data page](../Basic-Concept/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results.corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. #### Example 1: Downsampling Time-Series Data @@ -256,8 +266,8 @@ Total line number = 8 It costs 0.081s ``` -有关date_bin函数的更多详细信息可以参见 date_bin （时间分桶规整）函数功能定义 - For more details on the `date_bin` function, refer to the **Definition of Date Bin** **(Time Bucketing)** feature documentation. + +For more details on the `date_bin` function, refer to the **Definition of Date Bin (Time Bucketing)** feature documentation. #### Example 2: Query the Latest Data Point for Each Device diff --git a/src/UserGuide/latest-Table/SQL-Manual/Having-Clause.md b/src/UserGuide/latest-Table/SQL-Manual/Having-Clause.md index b0952623d..8b2b68afe 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/Having-Clause.md +++ b/src/UserGuide/latest-Table/SQL-Manual/Having-Clause.md @@ -34,11 +34,11 @@ The `HAVING` clause is used to filter aggregated results after a `GROUP BY` oper #### Notes -- 就语法而言，`HAVING`子句与`WHERE`子句相同，WHERE子句在分组聚合之前对数据进行过滤，HAVING子句是对分组聚合后的结果进行过滤。 +In terms of syntax, the `HAVING` clause is similar to the `WHERE` clause. However, while `WHERE` filters rows before grouping and aggregation, `HAVING` filters the results after grouping and aggregation. ## 2 Sample Data and Usage Examples -The [Example Data page](../Basic-Concept/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results.corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. #### Example 1: Filtering Devices with Entry Counts Below a Certain Threshold diff --git a/src/UserGuide/latest-Table/SQL-Manual/Identifier.md b/src/UserGuide/latest-Table/SQL-Manual/Identifier.md index f8604e678..782fecf47 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/Identifier.md +++ b/src/UserGuide/latest-Table/SQL-Manual/Identifier.md @@ -21,18 +21,18 @@ # Identifiers -In IoTDB, identifiers are used to identify database, table, column, function, or other object names. +In IoTDB, identifiers are used to represent the names of databases, tables, columns, functions, and other objects. ## 1 Naming Rules -- __First Character__：Identifiers must begin with a letter. -- __Subsequent Characters__：Can include letters, numbers, and underscores. -- __Special Characters__：If an identifier contains characters other than letters, numbers, and underscores, it must be enclosed in double quotes (`"`). -- __Escape Character__：Within double-quoted identifiers, two consecutive double quotes (`""`) are used to represent a single double quote character. +1. **Starting Character**: An identifier must begin with a letter. +2. **Subsequent Characters**: Identifiers can include letters, digits, and underscores. +3. **Special Characters**: If an identifier contains characters other than letters, digits, and underscores, it must be enclosed in double quotes (`"`). +4. **Escape Characters**: In double-quoted identifiers, a double quote character can be represented using two consecutive double quotes (`""`). ### 1.1 Examples -Here are some valid identifier examples: +Here are some examples of valid identifiers: ```sql test @@ -42,7 +42,7 @@ test "quotes" ``` -Invalid identifier examples that must be quoted with double quotes: +The following are examples of invalid identifiers that must be enclosed in double quotes to be used: ```sql table-name // contains a hyphen @@ -52,13 +52,13 @@ colum$name@field // contains special characters and is not enclosed in double q ## 2 Case Sensitivity -Identifiers are not case-sensitive, and the system does not retain the original case when storing identifiers. The column names in the query results will be displayed based on the case specified by the user in the SELECT clause. +Identifiers in IoTDB are case-insensitive. The system does not preserve the original case of identifiers during storage, but query results display column names in the same case as specified in the SELECT clause of the query. -> Identifiers enclosed in double quotes are also not case-sensitive. +> Identifiers enclosed in double quotes are also case-insensitive. ### 2.1 Example -When a column named `Device_id` is created, it is seen as `device_id` when viewing the table, but the returned result column matches the format specified by the user in the query as `Device_ID`: +Suppose a column named `Device_id` is created. When inspecting the table schema, it appears as `device_id`, but query results reflect the column name in the format specified by the user during the query (e.g., `Device_ID`). ```sql IoTDB> create table table1(Device_id STRING TAG, Model STRING ATTRIBUTE, TemPerature FLOAT FIELD, Humidity DOUBLE FIELD) diff --git a/src/UserGuide/latest-Table/SQL-Manual/Keywords.md b/src/UserGuide/latest-Table/SQL-Manual/Keywords.md index d387f6c63..0bb31d769 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/Keywords.md +++ b/src/UserGuide/latest-Table/SQL-Manual/Keywords.md @@ -21,7 +21,7 @@ # Reserved Words & Keywords -Reserved keywords must be quoted in double quotes (`"`) to be used as identifiers. The following are all reserved words in the IoTDB table model: +Reserved keywords must be enclosed in double quotes (" ") to be used as identifiers. Below is a list of all reserved keywords in the IoTDB table model. - ALTER - AND diff --git a/src/UserGuide/latest-Table/SQL-Manual/Limit-Offset-Clause.md b/src/UserGuide/latest-Table/SQL-Manual/Limit-Offset-Clause.md index 81d9d5ce7..9a321e361 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/Limit-Offset-Clause.md +++ b/src/UserGuide/latest-Table/SQL-Manual/Limit-Offset-Clause.md @@ -34,7 +34,7 @@ The `LIMIT` clause is applied in the final stage of a query to restrict the numb #### Notes - When `LIMIT` is used without an `ORDER BY` clause, the result order may not be deterministic. -- The `LIMIT` clause requires a non-negative integer.。 +- The `LIMIT` clause requires a non-negative integer. ### 1.2 OFFSET Clause @@ -48,7 +48,7 @@ The `OFFSET` clause works in conjunction with the `LIMIT` clause to skip a speci ## 2 Sample Data and Usage Examples -The [Example Data page](../Basic-Concept/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results.corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. #### Example 1: Retrieve the Latest Row for a Device diff --git a/src/UserGuide/latest-Table/SQL-Manual/OrderBy-Clause.md b/src/UserGuide/latest-Table/SQL-Manual/OrderBy-Clause.md index f60aaf9c3..347e4cfab 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/OrderBy-Clause.md +++ b/src/UserGuide/latest-Table/SQL-Manual/OrderBy-Clause.md @@ -21,6 +21,8 @@ # ORDER BY Clauses +The `ORDER BY` clause is used to sort the result set of a query at its final stage based on specified sorting conditions. + ## 1 Syntax Overview ```sql @@ -33,17 +35,17 @@ sortItem ### 1.1 ORDER BY Clauses -- The ORDER BY clause is used in the final stage of a query to sort the result set. It arranges the rows in the query result in ascending (ASC) or descending (DESC) order based on the specified sorting conditions. -- It provides control over the position of NULL values in the排序, allowing users to specify whether NULL values should be placed at the beginning (NULLS FIRST) or the end (NULLS LAST) of the sorted results. -- By default, ASC NULLS LAST sorting is used, meaning values are sorted in ascending order with NULLs placed at the end. You can change the default sorting order by manually specifying other parameters. -- The execution order of the ORDER BY clause is before the LIMIT or OFFSET clauses. +- Allows sorting query result rows based on specified conditions in ascending order (`ASC`) or descending order (`DESC`). +- Provides control over the position of `NULL` values, enabling users to specify whether `NULL` values appear at the beginning (`NULLS FIRST`) or the end (`NULLS LAST`). +- By default, sorting is applied as `ASC NULLS LAST`, meaning values are sorted in ascending order and `NULL` values are placed at the end. Users can manually specify other parameters to override the default behavior. +- The `ORDER BY` clause is executed before the `LIMIT` or `OFFSET` clauses. ## 2 Example Data -In the [Example Data page](../Basic-Concept/Sample-Data.md), there are SQL statements for building the table structure and inserting data. By downloading and executing these statements in the IoTDB CLI, you can import data into IoTDB. You can use this data to test and execute the SQL statements in the examples and obtain the corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. -#### Example 1: Retrieve data from the past hour in descending order of time +#### Example 1: Query data from the past hour in descending order of time ```sql SELECT * @@ -52,7 +54,7 @@ SELECT * ORDER BY time DESC; ``` -The execution results are as follows:： +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -74,7 +76,7 @@ Total line number = 11 It costs 0.148s ``` -#### Example 2: Query the data of all devices in the past hour in ascending order and descending order of time based on ' `device_id`', with `temperature` being prioritized for display +#### Example 2: Query data sorted by device_id in ascending order and time in descending order, with NULL temperatures displayed first ```sql SELECT * @@ -83,7 +85,7 @@ SELECT * ORDER BY temperature NULLS FIRST, time DESC; ``` -The execution results are as follows:： +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -105,7 +107,7 @@ Total line number = 11 It costs 0.060s ``` -#### Example 3: Querying the top 10 rows of data with the highest temperature +#### Example 3: Query the top 10 rows with the highest temperature values ```sql SELECT * @@ -114,7 +116,7 @@ SELECT * LIMIT 10; ``` -The execution results are as follows:： +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ diff --git a/src/UserGuide/latest-Table/SQL-Manual/Select-Clause.md b/src/UserGuide/latest-Table/SQL-Manual/Select-Clause.md index 8f467b23a..32018c2ad 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/Select-Clause.md +++ b/src/UserGuide/latest-Table/SQL-Manual/Select-Clause.md @@ -21,6 +21,8 @@ # SELECT Clauses +**SELECT Clause** specifies the columns included in the query results. + ## 1 Syntax Overview ```sql @@ -33,36 +35,36 @@ selectItem ; ``` -- __SELECT Clause__: SELECT Clause: Specifies the columns to be included in the query results, including aggregate functions (such as SUM, AVG, COUNT, etc.) and window functions, which are logically executed last. +- It supports aggregate functions (e.g., `SUM`, `AVG`, `COUNT`) and window functions, logically executed last in the query process. ## 2 Detailed Syntax: -Each `selectItem` can be one of the following forms: +Each `selectItem` can take one of the following forms: -- __Expression__: `expression [ [ AS ] column_alias ]` defines a single output column, and a column alias can be specified. -- __Selecting all columns of a relation__: `relation.*` selects all columns of a certain relation, and column aliases are not allowed. -- __Selecting all columns in the result set__: `*` selects all columns of the query, and column aliases are not allowed. +1. **Expression**: `expression [[AS] column_alias]` defines a single output column and optionally assigns an alias. +2. **All Columns from a Relation**: `relation.*` selects all columns from a specified relation. Column aliases are not allowed in this case. +3. **All Columns in the Result Set**: `*` selects all columns returned by the query. Column aliases are not allowed. ## 3 Example Data -In the [Example Data page](../Basic-Concept/Sample-Data.md), there are SQL statements for building the table structure and inserting data. By downloading and executing these statements in the IoTDB CLI, you can import data into IoTDB. You can use this data to test and execute the SQL statements in the examples and obtain the corresponding results. +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. -### 3.1 Select List +### 3.1 Selection List #### 3.1.1 Star Expression -The asterisk (*) can be used to select all columns from a table. __Note__, the star expression cannot be transformed by most functions, except in the case of `count(*)`. +The asterisk (`*`) selects all columns in a table. Note that it cannot be used with most functions, except for cases like `COUNT(*)`. -Example: Select all columns from a table +**Example**: Selecting all columns from a table. ```sql SELECT * FROM table1; ``` -The execution result is as follows: +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -93,15 +95,15 @@ It costs 0.653s #### 3.1.2 Aggregate Functions -Aggregate functions summarize multiple rows of data into a single value. When the SELECT clause contains aggregate functions, the query is considered an aggregate query. In aggregate queries, all expressions must be part of an aggregate function or specified by the [GROUP BY clause](../SQL-Manual/GroupBy-Clause.md) for grouping. +Aggregate functions summarize multiple rows into a single value. When aggregate functions are present in the `SELECT` clause, the query is treated as an **aggregate query**. All expressions in the query must either be part of an aggregate function or specified in the [GROUP BY clause](../SQL-Manual/GroupBy-Clause.md). -Example 1: Return the total number of rows in the address table: +**Example 1**: Total number of rows in a table. ```sql SELECT count(*) FROM table1; ``` -The execution result is as follows: +Results: ```sql +-----+ @@ -113,8 +115,7 @@ Total line number = 1 It costs 0.091s ``` -Example 2: Return the total number of rows in the address table grouped by city: - +**Example 2**: Total rows grouped by region. ```sql SELECT region, count(*) @@ -122,7 +123,7 @@ SELECT region, count(*) GROUP BY region; ``` -The execution result is as follows: +Results: ```sql +------+-----+ @@ -137,16 +138,16 @@ It costs 0.071s #### 3.1.3 Aliases -The keyword `AS` is used to specify an alias for the selected column, which overrides the existing column name to improve the readability of the query results. +The `AS` keyword assigns an alias to selected columns, improving readability by overriding existing column names. -Example 1: Original Table: +**Example 1**: Original table. ```sql IoTDB> SELECT * FROM table1; ``` -The execution result is as follows: +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -175,7 +176,7 @@ Total line number = 18 It costs 0.653s ``` -Example 2: Single column alias setting: +**Example 2**: Assigning an alias to a single column. ```sql IoTDB> SELECT device_id @@ -183,7 +184,7 @@ IoTDB> SELECT device_id FROM table1; ``` -The execution result is as follows: +Results: ```sql +------+ @@ -212,7 +213,7 @@ Total line number = 18 It costs 0.053s ``` -Example 3: Aliases for all columns: +**Example 3:** Assigning aliases to all columns. ```sql IoTDB> SELECT table1.* @@ -220,7 +221,7 @@ IoTDB> SELECT table1.* FROM table1; ``` -The execution result is as follows: +Results: ```sql +-----------------------------+----+----+-----+---+---+----+----+-----+-----------------------------+ @@ -249,7 +250,7 @@ Total line number = 18 It costs 0.189s ``` -## 4 Result Set Column Order +## 4 Column Order in the Result Set -- __Column order__: The column order in the result set is the same as the order specified in the SELECT clause. -- __Multi column sorting__: If an expression is selected to return multiple columns, their sorting method is the same as the sorting method in the source relationship. \ No newline at end of file +- **Column Order**: The order of columns in the result set matches the order specified in the `SELECT` clause. +- **Multi-column Expressions**: If a selection expression produces multiple columns, their order follows the order in the source relation.p. \ No newline at end of file diff --git a/src/UserGuide/latest-Table/SQL-Manual/Where-Clause.md b/src/UserGuide/latest-Table/SQL-Manual/Where-Clause.md index 88fef659f..630f36277 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/Where-Clause.md +++ b/src/UserGuide/latest-Table/SQL-Manual/Where-Clause.md @@ -27,20 +27,20 @@ WHERE booleanExpression ``` -__WHERE clause __: Used to specify filtering conditions in SQL queries, the WHERE clause is executed immediately after the FROM clause. +The `WHERE` clause is used to specify filter conditions in an SQL query. It is executed immediately after the `FROM` clause. ## 2 Example Data +The [Example Data page](../Reference/Sample-Data.md)page provides SQL statements to construct table schemas and insert data. By downloading and executing these statements in the IoTDB CLI, you can import the data into IoTDB. This data can be used to test and run the example SQL queries included in this documentation, allowing you to reproduce the described results. -In the [Example Data page](../Basic-Concept/Sample-Data.md), there are SQL statements for building the table structure and inserting data. By downloading and executing these statements in the IoTDB CLI, you can import data into IoTDB. You can use this data to test and execute the SQL statements in the examples and obtain the corresponding results. -#### Example 1: Select a row with a specific ID +#### Example 1: Selecting Rows with a Specific ID ```sql SELECT * FROM table1 WHERE plant_id = '1001'; ``` -The execution result is as follows: +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -60,13 +60,13 @@ Total line number = 9 It costs 0.091s ``` -#### Example 2: Choose to use LIKE expression for matching +#### Example 2: Using the `LIKE` Expression for Matching ```sql SELECT * FROM table1 WHERE plant_id LIKE '300%'; ``` -The execution result is as follows: +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ @@ -86,13 +86,13 @@ Total line number = 9 It costs 0.261s ``` -#### Example 3: Choose to use composite expression filtering +#### Example 3: Filtering with a Compound Expression ```sql SELECT * FROM table1 WHERE time >= 2024-11-28 00:00:00 and (plant_id = '3001' OR plant_id = '3002'); ``` -The execution result is as follows: +Results: ```sql +-----------------------------+------+--------+---------+--------+-----------+-----------+--------+------+-----------------------------+ diff --git a/src/UserGuide/latest-Table/SQL-Manual/overview.md b/src/UserGuide/latest-Table/SQL-Manual/overview.md index 00b4434be..89bc8cd65 100644 --- a/src/UserGuide/latest-Table/SQL-Manual/overview.md +++ b/src/UserGuide/latest-Table/SQL-Manual/overview.md @@ -35,26 +35,18 @@ SELECT ⟨select_list⟩ [LIMIT ⟨n⟩]; ``` -IoTDB query syntax provides the following clauses: - -- SELECT Clause: The columns to include in the query results. For detailed syntax, see: [SELECTClauses](../SQL-Manual/Select-Clause.md) -- FROM Clause: Specifies the data source of the query, which can be a single table, multiple tables joined using the JOIN clause, or a subquery. For detailed syntax, see: [FROM & JOIN Clauses](../SQL-Manual/From-Join-Clause.md) -- WHERE Clause: Used to filter data, selecting only rows that meet specific conditions. This clause is logically executed immediately after the FROM clause. For detailed syntax, see:[WHERE Clauses](../SQL-Manual/Where-Clause.md) -- GROUP BY Clause: Used when data aggregation is needed, specifying the columns used for grouping. For detailed syntax, see: [GROUP BY Clauses](../SQL-Manual/GroupBy-Clause.md) -- HAVING Clause: Used after the GROUP BY clause to filter data that has already been grouped. Similar to the WHERE clause, but the HAVING clause is executed after grouping. For detailed syntax, see: [HAVING Clauses](../SQL-Manual/Having-Clause.md) -- FILL Clause: Used to handle null values in the query results. Users can specify filling modes (such as the previous non-null value or linear interpolation) to fill null values with the FILL clause, facilitating data visualization and analysis. For detailed syntax, see: [FILL Clauses](../SQL-Manual/Fill-Clause.md) -- ORDER BY Clause: Sorts the query results, specifying ascending (ASC) or descending (DESC) order, as well as handling of NULL values (NULLS FIRST or NULLS LAST). For detailed syntax, see: [ORDER BY Clauses](../SQL-Manual/OrderBy-Clause.md) -- OFFSET Clause: Used to specify the starting position of the query results, that is, skipping the first OFFSET rows. Used in conjunction with the LIMIT clause. For detailed syntax, see: [LIMIT and OFFSET Clauses](../SQL-Manual/Limit-Offset-Clause.md) -- LIMIT Clause: Limits the number of rows in the query results, often used with the OFFSET clause to implement pagination. For detailed syntax, see: [LIMIT and OFFSET Clauses](../SQL-Manual/Limit-Offset-Clause.md) - -## 2 Clause Execution Order - -1. FROM (table name) -2. WHERE (condition filtering) -3. SELECT (column names/expressions) -4. GROUP BY (grouping) -5. HAVING (condition filtering after grouping) -6. FILL(null value filling) -7. ORDER BY (sorting) -8. OFFSET (offset amount) -9. LIMIT (limit amount) \ No newline at end of file +The IoTDB table model query syntax supports the following clauses: + +- **SELECT Clause**: Specifies the columns to be included in the result. Details: [SELECT Clause](../SQL-Manual/Select-Clause.md) +- **FROM Clause**: Indicates the data source for the query, which can be a single table, multiple tables joined using the `JOIN` clause, or a subquery. Details: [FROM & JOIN Clause](../SQL-Manual/From-Join-Clause.md) +- **WHERE Clause**: Filters rows based on specific conditions. Logically executed immediately after the `FROM` clause. Details: [WHERE Clause](../SQL-Manual/Where-Clause.md) +- **GROUP BY Clause**: Used for aggregating data, specifying the columns for grouping. Details: [GROUP BY Clause](../SQL-Manual/GroupBy-Clause.md) +- **HAVING Clause**: Applied after the `GROUP BY` clause to filter grouped data, similar to `WHERE` but operates after grouping. Details:[HAVING Clause](../SQL-Manual/Having-Clause.md) +- **FILL Clause**: Handles missing values in query results by specifying fill methods (e.g., previous non-null value or linear interpolation) for better visualization and analysis. Details:[FILL Clause](../SQL-Manual/Fill-Clause.md) +- **ORDER BY Clause**: Sorts query results in ascending (`ASC`) or descending (`DESC`) order, with optional handling for null values (`NULLS FIRST` or `NULLS LAST`). Details: [ORDER BY Clause](../SQL-Manual/OrderBy-Clause.md) +- **OFFSET Clause**: Specifies the starting position for the query result, skipping the first `OFFSET` rows. Often used with the `LIMIT` clause. Details: [LIMIT and OFFSET Clause](../SQL-Manual/Limit-Offset-Clause.md) +- **LIMIT Clause**: Limits the number of rows in the query result. Typically used in conjunction with the `OFFSET` clause for pagination. Details: [LIMIT and OFFSET Clause](../SQL-Manual/Limit-Offset-Clause.md) + +## 2. Clause Execution Order + +![](/img/%E5%AD%90%E5%8F%A5%E6%89%A7%E8%A1%8C%E9%A1%BA%E5%BA%8F01.png) \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Table/Basic-Concept/Delete-Data.md b/src/zh/UserGuide/Master/Table/Basic-Concept/Delete-Data.md index 444f4e971..dce9c095c 100644 --- a/src/zh/UserGuide/Master/Table/Basic-Concept/Delete-Data.md +++ b/src/zh/UserGuide/Master/Table/Basic-Concept/Delete-Data.md @@ -63,7 +63,6 @@ ID_CONDITION: ```SQL # 全表删除 -# Whole table deletion DELETE FROM table1 ``` @@ -71,11 +70,9 @@ DELETE FROM table1 ```SQL # 单时间段删除 -# Single time interval deletion DELETE FROM table1 WHERE time <= 2024-11-29 00:00:00 # 多时间段删除 -# Multi time interval deletion DELETE FROM table1 WHERE time >= 2024-11-27 00:00:00 and time <= 2024-11-29 00:00:00 ``` @@ -84,17 +81,14 @@ DELETE FROM table1 WHERE time >= 2024-11-27 00:00:00 and time <= 2024-11-29 00 ```SQL # 删除指定设备 # 标识条件只支持 = 运算符 -# Device-specific deletion DELETE FROM table1 WHERE device_id='101' and model_id = 'B' # 删除指定设备的时间段 -# Device-specific deletion with time interval DELETE FROM table1 WHERE time >= 2024-11-27 16:39:00 and time <= 2024-11-29 16:42:00 AND device_id='101' and model_id = 'B' # 删除指定类型的设备 -# Device-type-specific deletion DELETE FROM table1 WHERE model_id = 'B' ``` diff --git a/src/zh/UserGuide/latest-Table/Basic-Concept/Delete-Data.md b/src/zh/UserGuide/latest-Table/Basic-Concept/Delete-Data.md index 444f4e971..dce9c095c 100644 --- a/src/zh/UserGuide/latest-Table/Basic-Concept/Delete-Data.md +++ b/src/zh/UserGuide/latest-Table/Basic-Concept/Delete-Data.md @@ -63,7 +63,6 @@ ID_CONDITION: ```SQL # 全表删除 -# Whole table deletion DELETE FROM table1 ``` @@ -71,11 +70,9 @@ DELETE FROM table1 ```SQL # 单时间段删除 -# Single time interval deletion DELETE FROM table1 WHERE time <= 2024-11-29 00:00:00 # 多时间段删除 -# Multi time interval deletion DELETE FROM table1 WHERE time >= 2024-11-27 00:00:00 and time <= 2024-11-29 00:00:00 ``` @@ -84,17 +81,14 @@ DELETE FROM table1 WHERE time >= 2024-11-27 00:00:00 and time <= 2024-11-29 00 ```SQL # 删除指定设备 # 标识条件只支持 = 运算符 -# Device-specific deletion DELETE FROM table1 WHERE device_id='101' and model_id = 'B' # 删除指定设备的时间段 -# Device-specific deletion with time interval DELETE FROM table1 WHERE time >= 2024-11-27 16:39:00 and time <= 2024-11-29 16:42:00 AND device_id='101' and model_id = 'B' # 删除指定类型的设备 -# Device-type-specific deletion DELETE FROM table1 WHERE model_id = 'B' ```