CAST 函数
CAST 函数用于在 NeuG 中不同数据类型之间转换值。它支持字面值、动态参数、变量和节点/关系属性的类型转换。
语法
CAST(expression, 'TARGET_TYPE')参数：
expression：要转换的值或表达式。可以是字面值、变量、属性或任何有效的 Cypher 表达式。'TARGET_TYPE'：指定目标数据类型的字符串字面值（如'INT32'、'DOUBLE'、'STRING'、'DATE')。
返回值： 转换为指定目标类型的值。
使用示例
基本类型转换
以下示例演示使用字面值进行基本类型转换：
# 将整数转换为双精度浮点数（向上转型）
RETURN CAST(123, 'DOUBLE');
# 将双精度浮点数转换为整数（向下转型，截断小数部分）
RETURN CAST(123.7, 'INT32');
# 将字符串转换为整数（解析）
RETURN CAST('123', 'INT32');
# 将整数转换为字符串
RETURN CAST(123, 'STRING');
# 将字符串转换为时间类型
RETURN CAST('2012-01-02', 'DATE');列表与数组值
LIST (T[]) 和固定大小的 ARRAY (T[N]) 是不同的复合类型。
CAST 并非通用的 LIST/ARRAY 兼容层。写入节点和关系属性的值必须与编译器选定的模式类型相匹配。请使用模式声明或其他类型化上下文来生成固定大小的数组值。
转换属性值
CAST 函数也可应用于节点和关系属性：
# 将节点属性从 INT32 转换为 DOUBLE
MATCH (n:person)
RETURN CAST(n.age, 'DOUBLE');
# 将关系属性从 DOUBLE 转换为 INT32
MATCH (n:person)-[k:knows]->(m:person)
RETURN CAST(k.weight, 'INT32');转换变量和表达式
您可以转换任何有效的表达式，包括变量和计算值：
# 转换变量
MATCH (n:person)
WITH n.age AS age
RETURN CAST(age, 'DOUBLE') AS age_double;
# 转换计算表达式
MATCH (n:person)
RETURN CAST(n.age * 2.5, 'INT32') AS rounded_age;支持的类型类别
NeuG 的类型系统包含四大类别：
| 类别 | 描述 | CAST 支持 |
|---|---|---|
| 数值 | INT32、INT64、UINT32、UINT64、FLOAT、DOUBLE | ✅（包含溢出规则） |
| 字符串 | STRING | ✅ |
| 时间 | DATE、DATETIME | ✅（受限，详见下方转换表） |
| 复合 | LIST、ARRAY | ✅ 仅限同一种复合类型内部；不支持 LIST ↔ ARRAY 转换 |
类型转换规则
数值到数值转换
在数值类型之间转换时，可能发生精度丢失或溢出（如 INT64 → INT32)。转换行为取决于源类型和目标类型，以及构建模式。
换矩阵
下表显示数值类型转换的安全性和溢出行为：
| 从 \ 到 | INT32 | UINT32 | INT64 | UINT64 | FLOAT | DOUBLE |
|---|---|---|---|---|---|---|
| INT32 | ✅ 安全 | ⚠️ 可能溢出（如果值 < 0） | ✅ 安全 | ⚠️ 可能溢出（如果值 < 0） | ✅ 安全 | ✅ 安全 |
| UINT32 | ⚠️ 可能溢出（如果值 > INT32_MAX） | ✅ 安全 | ✅ 安全 | ✅ 安全 | ✅ 安全 | ✅ 安全 |
| INT64 | ⚠️ 可能溢出（如果值 < INT32_MIN 或 > INT32_MAX） | ⚠️ 可能溢出（如果值 < 0 或 > UINT32_MAX） | ✅ 安全 | ⚠️ 可能溢出（如果值 < 0） | ✅ 安全 | ✅ 安全 |
| UINT64 | ⚠️ 可能溢出（如果值 > INT32_MAX） | ⚠️ 可能溢出（如果值 > UINT32_MAX） | ⚠️ 可能溢出（如果值 > INT64_MAX） | ✅ 安全 | ✅ 安全 | ✅ 安全 |
| FLOAT | ⚠️ 可能溢出（如果值 < INT32_MIN 或 > INT32_MAX） | ⚠️ 可能溢出（如果值 < 0 或 > UINT32_MAX） | ⚠️ 可能溢出（如果值 < INT64_MIN 或 > INT64_MAX） | ⚠️ 可能溢出（如果值 < 0 或 > UINT64_MAX） | ✅ 安全 | ✅ 安全 |
| DOUBLE | ⚠️ 可能溢出（如果值 < INT32_MIN 或 > INT32_MAX） | ⚠️ 可能溢出（如果值 < 0 或 > UINT32_MAX） | ⚠️ 可能溢出（如果值 < INT64_MIN 或 > INT64_MAX） | ⚠️ 可能溢出（如果值 < 0 或 > UINT64_MAX） | ⚠️ 可能溢出（如果值 < -FLT_MAX 或 > FLT_MAX） | ✅ 安全 |
图例说明：
- ✅ 安全：转换始终安全并保留值
- ⚠️ 可能溢出：如果值超出目标类型范围，转换可能失败或产生意外结果
溢出处理
溢出时的行为取决于构建模式：
| 模式 | 行为 |
|---|---|
| 发布版 | 静默返回未定义/溢出值（如回绕或最大可表示值）。出于性能原因，不抛出异常。 |
| 调试版 | 抛出明确的 OverflowError，消息指示源类型、目标类型和导致溢出的值。 |
示例：
# 在发布模式下，这可能静默回绕或返回最大值
# 在调试模式下，这会抛出 OverflowError
RETURN CAST(999999999999, 'INT32');跨类别转换
下表总结不同类型类别之间允许的转换：
| 从 \ 到 | 数值 | 字符串 | 时间 |
|---|---|---|---|
| 数值 | ✅（见上文数值转换表） | ✅（如 123 → "123") | ❌（目前不支持） |
| 字符串 | ✅（如果可解析，如 "42" → 42) | ✅（身份转换） | ✅（如果符合 ISO 格式，如 "2025-01-01" → DATE) |
| 时间 | ❌（目前不支持） | ✅（转换为 ISO 字符串格式） | ✅（在兼容的时间类型之间，如 DATE ↔ DATETIME) |
字符串到数值转换
从 STRING 转换为数值类型时，字符串必须可解析为目标数值类型：
# 有效转换
RETURN CAST('42', 'INT32'); # 返回 42
RETURN CAST('3.14', 'DOUBLE'); # 返回 3.14
RETURN CAST('-100', 'INT64'); # 返回 -100
# 无效转换会导致错误
# RETURN CAST('abc', 'INT32'); # 错误：无法将 'abc' 解析为 INT32字符串到时间转换
从 STRING 转换为时间类型时，字符串必须符合 ISO 格式：
# 有效 DATE 转换
RETURN CAST('2012-01-02', 'DATE');
# 有效 DATETIME 转换
RETURN CAST('2012-01-02 10:30:00', 'TIMESTAMP');时间到字符串转换
时间类型转换为 ISO 字符串格式：
# DATE 到 STRING
RETURN CAST(DATE('2012-01-02'), 'STRING'); # 返回 '2012-01-02'
# DATETIME 到 STRING
RETURN CAST(DATETIME('2012-01-02 10:30:00'), 'STRING'); # 返回 '2012-01-02 10:30:00'LIST 和 ARRAY 类型
T[] 声明一个可变长度的 LIST，而 T[N] 则声明一个包含恰好 N 个元素的固定大小 ARRAY。编译器会在执行前根据模式对属性值进行验证，因此运行时不会将 LIST 值规范化为 ARRAY 值，反之亦然。
错误处理
CAST 函数可能在以下情况下失败：
- 无效的类型转换：尝试在不兼容的类型之间进行转换（例如，将
LIST转换为ARRAY或将ARRAY转换为INT32） - 解析错误：转换无法解析为目标类型的字符串（例如，
CAST('abc', 'INT32')） - 溢出错误（仅限调试模式）：转换的值超出目标类型的范围
Last updated on