doc(decimal): decimal docs (#30295)
This commit is contained in:
wangjiaming
GitHub
parent
f7beaeebfe
commit
a41ba830ce
|
|
@ -43,6 +43,7 @@ In TDengine, the following data types can be used in the data model of basic tab
|
|||
| 16 | VARCHAR | Custom | Alias for BINARY type |
|
||||
| 17 | GEOMETRY | Custom | Geometry type, supported starting from version 3.1.0.0 |
|
||||
| 18 | VARBINARY | Custom | Variable-length binary data, supported starting from version 3.1.1.0 |
|
||||
| 19 | DECIMAL | 8 or 16 | High-precision numeric type. The range of values depends on the precision and scale specified in the type. Supported starting from version 3.3.6. See the description below. |
|
||||
|
||||
:::note
|
||||
|
||||
|
|
@ -61,6 +62,18 @@ In TDengine, the following data types can be used in the data model of basic tab
|
|||
- VARBINARY is a data type for storing binary data, with a maximum length of 65,517 bytes for data columns and 16,382 bytes for label columns. Binary data can be written via SQL or schemaless methods (needs to be converted to a string starting with \x), or through stmt methods (can use binary directly). Displayed as hexadecimal starting with \x.
|
||||
|
||||
:::
|
||||
### DECIMAL Data Type
|
||||
|
||||
The `DECIMAL` data type is used for high-precision numeric storage and is supported starting from version 3.3.6. The definition syntax is: `DECIMAL(18, 2)`, `DECIMAL(38, 10)`, where two parameters must be specified: `precision` and `scale`. `Precision` refers to the maximum number of significant digits supported, and `scale` refers to the maximum number of decimal places. For example, `DECIMAL(8, 4)` represents a range of `[-9999.9999, 9999.9999]`. When defining the `DECIMAL` data type, the range of `precision` is `[1, 38]`, and the range of `scale` is `[0, precision]`. If `scale` is 0, it represents integers only. You can also omit `scale`, in which case it defaults to 0. For example, `DECIMAL(18)` is equivalent to `DECIMAL(18, 0)`.
|
||||
|
||||
When the `precision` value is less than or equal to 18, 8 bytes of storage (DECIMAL64) are used internally. When the `precision` is in the range `(18, 38]`, 16 bytes of storage (DECIMAL) are used. When writing `DECIMAL` type data in SQL, numeric values can be written directly. If the value exceeds the maximum representable value for the type, a `DECIMAL_OVERFLOW` error will be reported. If the value does not exceed the maximum representable value but the number of decimal places exceeds the `scale`, it will be automatically rounded. For example, if the type is defined as `DECIMAL(10, 2)` and the value `10.987` is written, the actual stored value will be `10.99`.
|
||||
|
||||
The `DECIMAL` type only supports regular columns and does not currently support tag columns. The `DECIMAL` type supports SQL-based writes only and does not currently support `stmt` or schemaless writes.
|
||||
|
||||
When performing operations between integer types and the `DECIMAL` type, the integer type is converted to the `DECIMAL` type before the calculation. When the `DECIMAL` type is involved in calculations with `DOUBLE`, `FLOAT`, `VARCHAR`, or `NCHAR` types, it is converted to `DOUBLE` type for computation.
|
||||
|
||||
When querying `DECIMAL` type expressions, if the intermediate result of the calculation exceeds the maximum value that the current type can represent, a `DECIMAL_OVERFLOW` error is reported.
|
||||
|
||||
|
||||
## Constants
|
||||
|
||||
|
|
|
|||
|
|
@ -1186,6 +1186,7 @@ CAST(expr AS type_name)
|
|||
1) Invalid character situations when converting string types to numeric types, e.g., "a" might convert to 0, but will not throw an error.
|
||||
2) When converting to numeric types, if the value exceeds the range that `type_name` can represent, it will overflow, but will not throw an error.
|
||||
3) When converting to string types, if the converted length exceeds the length specified in `type_name`, it will be truncated, but will not throw an error.
|
||||
- The DECIMAL type does not support conversion to or from JSON, VARBINARY, or GEOMETRY types.
|
||||
|
||||
#### TO_ISO8601
|
||||
|
||||
|
|
@ -1691,12 +1692,14 @@ AVG(expr)
|
|||
|
||||
**Function Description**: Calculates the average value of the specified field.
|
||||
|
||||
**Return Data Type**: DOUBLE.
|
||||
**Return Data Type**: DOUBLE, DECIMAL.
|
||||
|
||||
**Applicable Data Types**: Numeric types.
|
||||
|
||||
**Applicable to**: Tables and supertables.
|
||||
|
||||
**Description**: When the input type is DECIMAL, the output type is also DECIMAL. The precision and scale of the output conform to the rules described in the data type section. The result type is obtained by dividing the SUM type by UINT64. If the SUM result causes a DECIMAL type overflow, a DECIMAL OVERFLOW error is reported.
|
||||
|
||||
### COUNT
|
||||
|
||||
```sql
|
||||
|
|
@ -1847,12 +1850,14 @@ SUM(expr)
|
|||
|
||||
**Function Description**: Calculates the sum of a column in a table/supertable.
|
||||
|
||||
**Return Data Type**: DOUBLE, BIGINT.
|
||||
**Return Data Type**: DOUBLE, BIGINT,DECIMAL.
|
||||
|
||||
**Applicable Data Types**: Numeric types.
|
||||
|
||||
**Applicable to**: Tables and supertables.
|
||||
|
||||
**Description**: When the input type is DECIMAL, the output type is DECIMAL(38, scale), where precision is the maximum value currently supported, and scale is the scale of the input type. If the SUM result overflows, a DECIMAL OVERFLOW error is reported.
|
||||
|
||||
### HYPERLOGLOG
|
||||
|
||||
```sql
|
||||
|
|
@ -2254,6 +2259,7 @@ ignore_null_values: {
|
|||
- INTERP is used to obtain the record value of a specified column at the specified time slice. It has a dedicated syntax (interp_clause) when used. For syntax introduction, see [reference link](../query-data/#interp).
|
||||
- When there is no row data that meets the conditions at the specified time slice, the INTERP function will interpolate according to the settings of the [FILL](../time-series-extensions/#fill-clause) parameter.
|
||||
- When INTERP is applied to a supertable, it will sort all the subtable data under that supertable by primary key column and perform interpolation calculations, and can also be used with PARTITION BY tbname to force the results to a single timeline.
|
||||
- When using INTERP with FILL PREV/NEXT/NEAR modes, its behavior differs from window queries. If data exists at the slice, no FILL operation will be performed, even if the current value is NULL.
|
||||
- INTERP can be used with the pseudocolumn _irowts to return the timestamp corresponding to the interpolation point (supported from version 3.0.2.0).
|
||||
- INTERP can be used with the pseudocolumn _isfilled to display whether the return result is from the original record or generated by the interpolation algorithm (supported from version 3.0.3.0).
|
||||
- INTERP can only use the pseudocolumn `_irowts_origin` when using FILL PREV/NEXT/NEAR modes. `_irowts_origin` is supported from version 3.3.4.9.
|
||||
|
|
|
|||
|
|
@ -84,10 +84,10 @@ The FILL statement specifies the filling mode when data is missing in a window i
|
|||
|
||||
1. No filling: NONE (default filling mode).
|
||||
2. VALUE filling: Fixed value filling, where the fill value must be specified. For example: FILL(VALUE, 1.23). Note that the final fill value is determined by the type of the corresponding column, such as FILL(VALUE, 1.23), if the corresponding column is of INT type, then the fill value is 1. If multiple columns in the query list need FILL, then each FILL column must specify a VALUE, such as `SELECT _wstart, min(c1), max(c1) FROM ... FILL(VALUE, 0, 0)`. Note, only ordinary columns in the SELECT expression need to specify FILL VALUE, such as `_wstart`, `_wstart+1a`, `now`, `1+1` and the partition key (like tbname) used with partition by do not need to specify VALUE, like `timediff(last(ts), _wstart)` needs to specify VALUE.
|
||||
3. PREV filling: Fill data using the previous non-NULL value. For example: FILL(PREV).
|
||||
3. PREV filling: Fill data using the previous value. For example: FILL(PREV).
|
||||
4. NULL filling: Fill data with NULL. For example: FILL(NULL).
|
||||
5. LINEAR filling: Perform linear interpolation filling based on the nearest non-NULL values before and after. For example: FILL(LINEAR).
|
||||
6. NEXT filling: Fill data using the next non-NULL value. For example: FILL(NEXT).
|
||||
6. NEXT filling: Fill data using the next value. For example: FILL(NEXT).
|
||||
|
||||
Among these filling modes, except for the NONE mode which does not fill by default, other modes will be ignored if there is no data in the entire query time range, resulting in no fill data and an empty query result. This behavior is reasonable under some modes (PREV, NEXT, LINEAR) because no data means no fill value can be generated. For other modes (NULL, VALUE), theoretically, fill values can be generated, and whether to output fill values depends on the application's needs. To meet the needs of applications that require forced filling of data or NULL, without breaking the compatibility of existing filling modes, two new filling modes have been added starting from version 3.0.3.0:
|
||||
|
||||
|
|
|
|||
|
|
@ -36,6 +36,7 @@ In this document, it specifically refers to the internal levels of the second-le
|
|||
| float/double | disabled/delta-d | delta-d | lz4/zlib/zstd/xz/tsz | lz4 | medium |
|
||||
| binary/nchar | disabled | disabled | lz4/zlib/zstd/xz | zstd | medium |
|
||||
| bool | disabled/bit-packing | bit-packing | lz4/zlib/zstd/xz | zstd | medium |
|
||||
| decimal | disabled | disabled | lz4/zlib/zstd/xz | zstd | medium |
|
||||
|
||||
## SQL Syntax
|
||||
|
||||
|
|
|
|||
|
|
@ -830,6 +830,12 @@ This section introduces APIs that are all synchronous interfaces. After being ca
|
|||
- res: [Input] Result set.
|
||||
- **Return Value**: Non-`NULL`: successful, returns a pointer to a TAOS_FIELD structure, each element representing the metadata of a column. `NULL`: failure.
|
||||
|
||||
- `TAOS_FIELD_E *taos_fetch_fields_e(TAOS_RES *res)`
|
||||
- **Interface Description**: Retrieves the attributes of each column in the query result set (column name, data type, column length). Used in conjunction with `taos_num_fields()`, it can be used to parse the data of a tuple (a row) returned by `taos_fetch_row()`. In addition to the basic information provided by TAOS_FIELD, TAOS_FIELD_E also includes `precision` and `scale` information for the data type.
|
||||
- **Parameter Description**:
|
||||
- res: [Input] Result set.
|
||||
- **Return Value**: Non-`NULL`: Success, returns a pointer to a TAOS_FIELD_E structure, where each element represents the metadata of a column. `NULL`: Failure.
|
||||
|
||||
- `void taos_stop_query(TAOS_RES *res)`
|
||||
- **Interface Description**: Stops the execution of the current query.
|
||||
- **Parameter Description**:
|
||||
|
|
|
|||
|
|
@ -44,6 +44,7 @@ CREATE DATABASE db_name PRECISION 'ns';
|
|||
| 16 | VARCHAR | 自定义 | BINARY 类型的别名 |
|
||||
| 17 | GEOMETRY | 自定义 | 几何类型，3.1.0.0 版本开始支持
|
||||
| 18 | VARBINARY | 自定义 | 可变长的二进制数据， 3.1.1.0 版本开始支持|
|
||||
| 19 | DECIMAL | 8或16 | 高精度数值类型, 取值范围取决于类型中指定的precision和scale, 自3.3.6开始支持, 见下文描述|
|
||||
|
||||
:::note
|
||||
|
||||
|
|
@ -63,6 +64,18 @@ CREATE DATABASE db_name PRECISION 'ns';
|
|||
|
||||
:::
|
||||
|
||||
### DECIMAL数据类型
|
||||
`DECIMAL`数据类型用于高精度数值存储, 自版本3.3.6开始支持, 定义语法: DECIMAL(18, 2), DECIMAL(38, 10), 其中需要指定两个参数, 分别为`precision`和`scale`. `precision`是指最大支持的有效数字个数, `scale`是指最大支持的小数位数. 如DECIMAL(8, 4), 可表示范围即[-9999.9999, 9999.9999]. 定义DECIMAL数据类型时, `precision`范围为: [1,38], scale的范围为: [0,precision], scale为0时, 仅表示整数. 也可以不指定scale, 默认为0, 如DECIMAL(18), 与DECIMAL(18,0)相同。
|
||||
|
||||
当`precision`值不大于18时, 内部使用8字节存储(DECIMAL64), 当precision范围为(18, 38]时, 使用16字节存储(DECIMAL). SQL中写入DECIMAL类型数据时, 可直接使用数值写入, 当写入值大于类型可表示的最大值时会报DECIMAL_OVERFLOW错误, 当未大于类型表示的最大值, 但小数位数超过SCALE时, 会自动四舍五入处理, 如定义类型DECIMAL(10, 2), 写入10.987, 则实际存储值为10.99。
|
||||
|
||||
DECIMAL类型仅支持普通列, 暂不支持tag列. DECIMAL类型只支持SQL写入， 暂不支持stmt写入和schemeless写入。
|
||||
|
||||
整数类型和DECIMAL类型操作时, 会将整数类型转换为DECIMAL类型再进行计算. DECIMAL类型与DOUBLE/FLOAT/VARCHAR/NCHAR等类型计算时, 转换为DOUBLE类型进行计算.
|
||||
|
||||
查询DECIMAL类型表达式时, 若计算的中间结果超出当前类型可表示的最大值时, 报DECIMAL OVERFLOW错误.
|
||||
|
||||
|
||||
## 常量
|
||||
|
||||
TDengine 支持多个类型的常量，细节如下表：
|
||||
|
|
|
|||
|
|
@ -1137,6 +1137,7 @@ CAST(expr AS type_name)
|
|||
- 字符串类型转换数值类型时可能出现的无效字符情况，例如 "a" 可能转为 0，但不会报错。
|
||||
- 转换到数值类型时，数值大于 type_name 可表示的范围时，则会溢出，但不会报错。
|
||||
- 转换到字符串类型时，如果转换后长度超过 type_name 中指定的长度，则会截断，但不会报错。
|
||||
- DECIMAL类型不支持与JSON,VARBINARY,GEOMERTY类型的互转.
|
||||
|
||||
#### TO_CHAR
|
||||
|
||||
|
|
@ -1618,12 +1619,14 @@ AVG(expr)
|
|||
|
||||
**功能说明**：统计指定字段的平均值。
|
||||
|
||||
**返回数据类型**：DOUBLE。
|
||||
**返回数据类型**：DOUBLE, DECIMAL。
|
||||
|
||||
**适用数据类型**：数值类型。
|
||||
|
||||
**适用于**：表和超级表。
|
||||
|
||||
**说明**: 当输入类型为DECIMAL类型时, 输出类型也为DECIMAL类型, 输出的precision和scale大小符合数据类型章节中的描述规则, 通过计算SUM类型和UINT64的除法得到结果类型, 若SUM的结果导致DECIMAL类型溢出, 则报DECIMAL OVERFLOW错误。
|
||||
|
||||
### COUNT
|
||||
|
||||
```sql
|
||||
|
|
@ -1805,12 +1808,14 @@ SUM(expr)
|
|||
|
||||
**功能说明**：统计表/超级表中某列的和。
|
||||
|
||||
**返回数据类型**：DOUBLE、BIGINT。
|
||||
**返回数据类型**：DOUBLE、BIGINT,DECIMAL。
|
||||
|
||||
**适用数据类型**：数值类型。
|
||||
|
||||
**适用于**：表和超级表。
|
||||
|
||||
**说明**: 输入类型为DECIMAL类型时, 输出类型为DECIMAL(38, scale), precision为当前支持的最大值, scale为输入类型的scale, 若SUM的结果溢出时, 报DECIMAL OVERFLOW错误.
|
||||
|
||||
### VAR_POP
|
||||
|
||||
```sql
|
||||
|
|
@ -2174,6 +2179,7 @@ ignore_null_values: {
|
|||
- INTERP 用于在指定时间断面获取指定列的记录值，使用时有专用语法(interp_clause)，语法介绍[参考链接](../select/#interp) 。
|
||||
- 当指定时间断面不存在符合条件的行数据时，INTERP 函数会根据 [FILL](../distinguished/#fill-子句) 参数的设定进行插值。
|
||||
- INTERP 作用于超级表时，会将该超级表下的所有子表数据按照主键列排序后进行插值计算，也可以搭配 PARTITION BY tbname 使用，将结果强制规约到单个时间线。
|
||||
- INTERP在FILL PREV/NEXT/NEAR时, 行为与窗口查询有所区别, 当截面存在数据时, 不会进行FILL, 即便当前值为NULL.
|
||||
- INTERP 可以与伪列 `_irowts` 一起使用，返回插值点所对应的时间戳(v3.0.2.0 以后支持)。
|
||||
- INTERP 可以与伪列 `_isfilled` 一起使用，显示返回结果是否为原始记录或插值算法产生的数据(v3.0.3.0 以后支持)。
|
||||
- 只有在使用 FILL PREV/NEXT/NEAR 模式时才可以使用伪列 `_irowts_origin`, 用于返回 `interp` 函数所使用的原始数据的时间戳列。若范围内无值, 则返回 NULL。`_irowts_origin` 在 v3.3.4.9 以后支持。
|
||||
|
|
|
|||
|
|
@ -77,10 +77,10 @@ FILL 语句指定某一窗口区间数据缺失的情况下的填充模式。填
|
|||
|
||||
1. 不进行填充：NONE（默认填充模式）。
|
||||
2. VALUE 填充：固定值填充，此时需要指定填充的数值。例如 `FILL(VALUE, 1.23)`。这里需要注意，最终填充的值受由相应列的类型决定，如 `FILL(VALUE, 1.23)`，相应列为 INT 类型，则填充值为 1，若查询列表中有多列需要 FILL，则需要给每一个 FILL 列指定 VALUE，如 `SELECT _wstart, min(c1), max(c1) FROM ... FILL(VALUE, 0, 0)`，注意，SELECT 表达式中只有包含普通列时才需要指定 FILL VALUE，如 `_wstart`、`_wstart+1a`、`now`、`1+1` 以及使用 `partition by` 时的 `partition key` (如 tbname)都不需要指定 VALUE，如 `timediff(last(ts), _wstart)` 则需要指定 VALUE。
|
||||
3. PREV 填充：使用前一个非 NULL 值填充数据。例如 FILL(PREV)。
|
||||
3. PREV 填充：使用前一个值填充数据。例如 FILL(PREV)。
|
||||
4. NULL 填充：使用 NULL 填充数据。例如 FILL(NULL)。
|
||||
5. LINEAR 填充：根据前后距离最近的非 NULL 值做线性插值填充。例如 FILL(LINEAR)。
|
||||
6. NEXT 填充：使用下一个非 NULL 值填充数据。例如 FILL(NEXT)。
|
||||
6. NEXT 填充：使用下一个值填充数据。例如 FILL(NEXT)。
|
||||
|
||||
以上填充模式中，除了 NONE 模式默认不填充值之外，其他模式在查询的整个时间范围内如果没有数据 FILL 子句将被忽略，即不产生填充数据，查询结果为空。这种行为在部分模式（PREV、NEXT、LINEAR）下具有合理性，因为在这些模式下没有数据意味着无法产生填充数值。而对另外一些模式（NULL、VALUE）来说，理论上是可以产生填充数值的，至于需不需要输出填充数值，取决于应用的需求。所以为了满足这类需要强制填充数据或 NULL 的应用的需求，同时不破坏现有填充模式的行为兼容性，从 v3.0.3.0 开始，增加了两种新的填充模式：
|
||||
|
||||
|
|
|
|||
|
|
@ -37,6 +37,7 @@ description: 可配置压缩算法
|
|||
| float/double | disabled/delta-d | delta-d | lz4/zlib/zstd/xz/tsz | lz4 | medium |
|
||||
| binary/nchar | disabled | disabled | lz4/zlib/zstd/xz | zstd | medium |
|
||||
| bool | disabled/bit-packing | bit-packing | lz4/zlib/zstd/xz | zstd | medium |
|
||||
| decimal | disabled | disabled | lz4/zlib/zstd/xz | zstd | medium |
|
||||
|
||||
|
||||
## SQL 语法
|
||||
|
|
|
|||
|
|
@ -826,6 +826,12 @@ TDengine 客户端驱动的版本号与 TDengine 服务端的版本号是一一
|
|||
- res：[入参] 结果集。
|
||||
- **返回值**：非 `NULL`：成功，返回一个指向 TAOS_FIELD 结构体的指针，每个元素代表一列的元数据。`NULL`：失败。
|
||||
|
||||
- `TAOS_FIELD_E *taos_fetch_fields_e(TAOS_RES *res)`
|
||||
- **接口说明**：获取查询结果集每列数据的属性（列的名称、列的数据类型、列的长度），与 `taos_num_fields()` 配合使用，可用来解析 `taos_fetch_row()` 返回的一个元组(一行)的数据。TAOS_FIELD_E中除了TAOS_FIELD的基本信息外, 还包括了类型的`precision`和`scale`信息。
|
||||
- **参数说明**：
|
||||
- res：[入参] 结果集。
|
||||
- **返回值**：非 `NULL`：成功，返回一个指向 TAOS_FIELD_E 结构体的指针，每个元素代表一列的元数据。`NULL`：失败。
|
||||
|
||||
- `void taos_stop_query(TAOS_RES *res)`
|
||||
- **接口说明**：停止当前查询的执行。
|
||||
- **参数说明**：
|
||||
|
|
|
|||
Loading…
Reference in New Issue