Skip to content

docs: update numeric type aliases aligned with PostgreSQL and MySQL #2231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
+74 −36
Open

docs: update numeric type aliases aligned with PostgreSQL and MySQL #2231

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
f333954
Initial plan
Copilot Nov 21, 2025
57348f7
Update numeric type aliases in documentation
Copilot Nov 21, 2025
e8da1c7
Add breaking change warning for INT8 alias
Copilot Nov 21, 2025
52da90d
Improve breaking change warning with detailed explanation
Copilot Nov 21, 2025
03427d9
Fix trailing whitespace in warning
Copilot Nov 21, 2025
667fce0
Update Chinese documentation for numeric type aliases
Copilot Nov 21, 2025
aeffba4
Improve Chinese translation clarity
Copilot Nov 21, 2025
69d11a0
Clarify distinction between bit-based and byte-based naming
Copilot Nov 21, 2025
16973fc
chore: add note for native types
killme2008 Nov 21, 2025
6bb378e
chore: revert the table columns order
killme2008 Nov 21, 2025
cebf256
chore: remove breaking change
killme2008 Nov 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 38 additions & 18 deletions docs/reference/sql/data-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,12 @@ The maximum capacities of `String` and `Binary` are determined by their encoding
| `Float32` | 32-bit IEEE754 floating point values | 4 Bytes |
| `Float64` | Double precision IEEE 754 floating point values | 8 Bytes |

:::tip NOTE
The descriptions here refer to **GreptimeDB native type information**, which are measured in **bits**.
However, when using **SQL**, follow the conventions of **PostgreSQL** and **MySQL**, where types like `INT2`, `INT4`, `INT8`, `FLOAT4` and `FLOAT8` are defined in **bytes**.
For example, in an SQL statement, `INT8` actually corresponds to **BigInt** (8 bytes, 64 bits).
:::

## Decimal Type

GreptimeDB supports the `decimal` type, a fixed-point type represented as `decimal(precision, scale)`, where `precision` is the total number of digits, and `scale` is the number of digits in the fractional part. For example, `123.45` has a precision of 5 and a scale of 2.
Expand Down Expand Up @@ -303,24 +309,38 @@ INSERT INTO bools(b) VALUES (TRUE), (FALSE);

For users migrating from MySQL or PostgreSQL to GreptimeDB, GreptimeDB supports the following alias types.

| Data Type | Alias Types |
| ---------------------- | --------------------------------------------------------------- |
| `String` | `Text`, `TinyText`, `MediumText`, `LongText`, `Varchar`, `Char` |
| `Binary` | `Varbinary` |
| `Int8` | `TinyInt` |
| `Int16` | `SmallInt` |
| `Int32` | `Int` |
| `Int64` | `BigInt` |
| `UInt8` | `UnsignedTinyInt` |
| `UInt16` | `UnsignedSmallInt` |
| `UInt32` | `UnsignedInt` |
| `UInt64` | `UnsignedBigInt` |
| `Float32` | `Float` |
| `Float64` | `Double` |
| `TimestampSecond` | `Timestamp_s`, `Timestamp_sec`, `Timestamp(0)` |
| `TimestampMillisecond` | `Timestamp`, `Timestamp_ms`, `Timestamp(3)` |
| `TimestampMicroSecond` | `Timestamp_us`, `Timestamp(6)` |
| `TimestampNanosecond` | `Timestamp_ns`, `Timestamp(9)` |

| SQL Datatype Alias | Native Datatype |
| --------------------------------------------------------------- | ---------------------- |
| `Text`, `TinyText`, `MediumText`, `LongText`, `Varchar`, `Char` | `String` |
| `Varbinary` | `Binary` |
| `TinyInt` | `Int8` |
| `SmallInt`, `Int2` | `Int16` |
| `Int`, `Int4` | `Int32` |
| `BigInt`, `Int8` | `Int64` |
| `UnsignedTinyInt` | `UInt8` |
| `UnsignedSmallInt` | `UInt16` |
| `UnsignedInt` | `UInt32` |
| `UnsignedBigInt` | `UInt64` |
| `Float`, `Float4` | `Float32` |
| `Double`, `Float8` | `Float64` |
| `Timestamp_s`, `Timestamp_sec`, `Timestamp(0)` | `TimestampSecond` |
| `Timestamp`, `Timestamp_ms`, `Timestamp(3)` | `TimestampMillisecond` |
| `Timestamp_us`, `Timestamp(6)` | `TimestampMicroSecond` |
| `Timestamp_ns`, `Timestamp(9)` | `TimestampNanosecond` |

:::warning Note
The type aliases `Int2`, `Int4`, `Int8`, `Float4`, and `Float8` follow the PostgreSQL and MySQL convention where these identifiers refer to the number of **bytes** (not bits) in the type.

Specifically:
- `Int2` = 2 bytes = `SmallInt` (16-bit)
- `Int4` = 4 bytes = `Int` (32-bit)
- `Int8` = 8 bytes = `BigInt` (64-bit)
- `Float4` = 4 bytes = `Float` (32-bit)
- `Float8` = 8 bytes = `Double` (64-bit)

Note: GreptimeDB's native type names (like `UInt8`, `Int32`, `Int64`) refer to the number of **bits**, while the SQL aliases `Int2`, `Int4`, and `Int8` refer to the number of **bytes** following PostgreSQL/MySQL conventions. For example, the native type `Int8` is an 8-**bit** integer (`TinyInt`, 1 byte), while the SQL alias `INT8` maps to an 8-**byte** integer (`BigInt`, 64-bit).
:::

You can use these alias types when creating tables.
For example, use `Varchar` instead of `String`, `Double` instead of `Float64`, and `Timestamp(0)` instead of `TimestampSecond`.
Expand Down
54 changes: 36 additions & 18 deletions i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/data-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,11 @@ SQL 数据类型定义了列可以存储的数据类型。当您运行 `DESC TAB
| `Float32` | 32 位 IEEE 754 浮点数 | 4 字节 |
| `Float64` | 双精度 IEEE 754 浮点数 | 8 字节 |

:::tip 注意
这里的描述指的是 GreptimeDB 原生类型信息，这些类型都是以 位（bits） 为单位的。但是，在使用 SQL 时，请遵循 PostgreSQL 和 MySQL 的惯例，其中 `INT2`、`INT4`、`INT8`、`FLOAT4` 和 `FLOAT8` 等类型都是以 字节（bytes） 为单位定义的。
例如，在 SQL 语句中，`INT8` 实际上对应 `BigInt`（8 个字节，64 位）。
:::

## Decimal 类型

GreptimeDB 支持 `decimal` 类型，这是一种定点类型，表示为 `decimal(precision, scale)`，其中 `precision` 是总位数，`scale` 是小数部分的位数。例如，`123.45` 的总位数为 5，小数位数为 2。
Expand Down Expand Up @@ -303,24 +308,37 @@ INSERT INTO bools(b) VALUES (TRUE), (FALSE);

对于从 MySQL 或 PostgreSQL 迁移到 GreptimeDB 的用户，GreptimeDB 支持以下类型别名。

| 数据类型 | 别名 |
| ---------------------- | --------------------------------------------------------------- |
| `String` | `Text`, `TinyText`, `MediumText`, `LongText`, `Varchar`, `Char` |
| `Binary` | `Varbinary` |
| `Int8` | `TinyInt` |
| `Int16` | `SmallInt` |
| `Int32` | `Int` |
| `Int64` | `BigInt` |
| `UInt8` | `UnsignedTinyInt` |
| `UInt16` | `UnsignedSmallInt` |
| `UInt32` | `UnsignedInt` |
| `UInt64` | `UnsignedBigInt` |
| `Float32` | `Float` |
| `Float64` | `Double` |
| `TimestampSecond` | `Timestamp_s`, `Timestamp_sec`, `Timestamp(0)` |
| `TimestampMillisecond` | `Timestamp`, `Timestamp_ms` , `Timestamp(3)` |
| `TimestampMicroSecond` | `Timestamp_us`, `Timestamp(6)` |
| `TimestampNanosecond` | `Timestamp_ns`, `Timestamp(9)` |
| SQL 类型别名 | Native 数据类型 |
| --------------------------------------------------------------- | ---------------------- |
| `Text`, `TinyText`, `MediumText`, `LongText`, `Varchar`, `Char` | `String` |
| `Varbinary` | `Binary` |
| `TinyInt` | `Int8` |
| `SmallInt`, `Int2` | `Int16` |
| `Int`, `Int4` | `Int32` |
| `BigInt`, `Int8` | `Int64` |
| `UnsignedTinyInt` | `UInt8` |
| `UnsignedSmallInt` | `UInt16` |
| `UnsignedInt` | `UInt32` |
| `UnsignedBigInt` | `UInt64` |
| `Float`, `Float4` | `Float32` |
| `Double`, `Float8` | `Float64` |
| `Timestamp_s`, `Timestamp_sec`, `Timestamp(0)` | `TimestampSecond` |
| `Timestamp`, `Timestamp_ms`, `Timestamp(3)` | `TimestampMillisecond` |
| `Timestamp_us`, `Timestamp(6)` | `TimestampMicroSecond` |
| `Timestamp_ns`, `Timestamp(9)` | `TimestampNanosecond` |

:::warning 注意
类型别名 `Int2`、`Int4`、`Int8`、`Float4` 和 `Float8` 遵循 PostgreSQL 和 MySQL 的约定，这些标识符表示类型中的**字节**数（而非位数）。

具体来说：
- `Int2` = 2 字节 = `SmallInt`（16 位）
- `Int4` = 4 字节 = `Int`（32 位）
- `Int8` = 8 字节 = `BigInt`（64 位）
- `Float4` = 4 字节 = `Float`（32 位）
- `Float8` = 8 字节 = `Double`（64 位）

注意：GreptimeDB 的原生类型名称（如 `UInt8`、`Int32`、`Int64`）表示**位**数，而 SQL 类型别名 `Int2`、`Int4` 和 `Int8` 遵循 PostgreSQL/MySQL 约定表示**字节**数。例如，原生类型 `Int8` 是 8 **位**整数（`TinyInt`, 1 字节），而 SQL 别名 `INT8` 映射到 8 **字节**整数（`BigInt`，64 位）。
:::

在创建表时也可以使用这些别名类型。
例如，使用 `Varchar` 代替 `String`，使用 `Double` 代替 `Float64`，使用 `Timestamp(0)` 代替 `TimestampSecond`。
Expand Down