字符串函数

substring()

用于从一个字符串中提取指定长度的子串。子串的长度为len，从位置idx开始。需要注意的是，字符串的位置索引从 1 开始，而不是从 0 开始的。len必须为正数。

NULL 行为：默认

函数签名

substring(str: STRING, idx: INT32, len: INT32) -> STRING

示例

RETURN substring("abcdef", 1, 2) AS substr

返回：

+--------+
| substr |
+--------+
| ab     |
+--------+

repeat()

返回将字符串str重复count次并拼接得到的新字符串。

NULL 行为：默认

函数签名

repeat(str: STRING, count: INT32) -> STRING

• 当count小于或等于0时返回空字符串。
• 若结果字符串的字节数超过2³²−1 (4,294,967,295)字节，则报错。

示例

重复字符串两次

RETURN repeat("hello ", 2) AS s

返回：

+--------------+
| s            |
+--------------+
| hello hello  |
+--------------+

当count为负数时返回空字符串

RETURN repeat("hello", -1) AS s

返回：

+---+
| s |
+---+
|   |
+---+

当结果超过长度限制时出错

RETURN length(repeat("xxxxxxxxx", 1000000000))

返回：

Error: [NR016]: String should be no more than 4294967295 bytes...

fmt()

格式化指定的值并插入字符串的占位符中。

NULL 行为：通用

函数签名

fmt(str: STRING, value: STRING | Numeric | BOOLEAN [, value...]) -> STRING

Numeric数据类型中不包括DECIMAL。

参数

• str: STRING：含有占位符的源字符串。占位符必须与要插入参数的数据类型匹配才能生效。支持的占位符及对应数据类型如下：
  • %s: STRING
  • %d: UINT8、UINT16、UINT32、UINT64、INT8、INT16、INT32、INT64
  • %f: FLOAT、DOUBLE
  • %b: BOOLEAN

• value: STRING | Numeric | BOOLEAN [, value...]：要插入至源字符串占位符中的一个或多个值。确保单次调用该函数时，value参数的数据类型一致，系统根据value参数的数据类型和填写顺序，匹配源字符串中的占位符并替换为对应的值。

示例

在字符串中插入多组字符串

RETURN fmt('hello %s %s', 'my', 'world') AS a

返回：

+----------------+
| a              |
+----------------+
| hello my world |
+----------------+

在字符串中插入布尔值

RETURN fmt("a:%b", true) AS a

返回：

+--------+
| a      |
+--------+
| a:true |
+--------+

在字符串中插入不同类型的值

RETURN fmt(fmt(fmt("12%d%s,%d5%d%b,%d%d%b", 3,4,6,78,9),"xyz"),false,true) AS a

返回：

+-------------------------+
| a                       |
+-------------------------+
| 123xyz,456false,789true |
+-------------------------+

left()

返回字符串左侧指定长度的字符。

NULL 行为：默认

函数签名

left(str: STRING, len: INT32) -> STRING

示例

RETURN left("abcdef", 3) AS substr

返回：

+--------+
| substr |
+--------+
| abc    |
+--------+

right()

返回字符串右侧指定长度的字符。

NULL 行为：默认

函数签名

right(str: STRING, len: INT32) -> STRING

示例

RETURN right("abcdef", 3) AS substr

返回：

+--------+
| substr |
+--------+
| def    |
+--------+

upper()

用于将字符串中的所有字符转换为大写形式。

NULL 行为：默认

函数签名

upper(str: STRING) -> STRING

示例

RETURN upper("abCDef") AS a

返回：

+--------+
| a      |
+--------+
| ABCDEF |
+--------+

lower()

用于将字符串中的所有字符转换为小写形式。

NULL 行为：默认

函数签名

lower(str: STRING) -> STRING

示例

RETURN lower("abCDef") AS a

返回：

+--------+
| a      |
+--------+
| abcdef |
+--------+

trim()

返回去除左侧、右侧或两侧的指定字符串后的字符串。

该函数还可用于移除列表末尾指定数量的元素。更多信息，请参见列表函数trim()。

NULL 行为：默认

函数签名

trim( [ [ LEADING | TRAILING | BOTH ] [ trim_char: STRING ] FROM ] source_str: STRING ) -> STRING

参数

• LEADING | TRAILING | BOTH：要修剪字符串的哪一侧。如果省略，默认是BOTH。
• trim_char: STRING：要从源字符串中删除的字符。如果省略，默认是空格（）字符。
• FROM：如果指定了此关键字，则必须指定至少一个可选参数：要修剪字符串的哪一侧或要删除的字符。
• source_str: STRING：源字符串。

示例

去除左侧和右侧空格字符

RETURN trim("   abc   ") AS a

返回：

+-----+
| a   |
+-----+
| abc |
+-----+

去除左侧和右侧下划线

RETURN trim('_' FROM "__abc__") AS a

返回：

+-----+
| a   |
+-----+
| abc |
+-----+

去除左侧下划线

RETURN trim(LEADING '_' FROM "__abc__") AS a

返回：

+-------+
| a     |
+-------+
| abc__ |
+-------+

去除右侧下划线

RETURN trim(TRAILING '_' FROM "__abc__") AS a

返回：

+-------+
| a     |
+-------+
| __abc |
+-------+

ltrim()

返回去除左侧指定字符后的字符串。

NULL 行为：默认

函数签名

ltrim( source_str: STRING [ , trim_str: STRING ] ) -> STRING

参数

• source_str: STRING：源字符串。
• trim_str: STRING：要从源字符串左侧删除的字符。如果省略，默认是空格（）字符。

示例

去除左侧空格字符

RETURN ltrim('  abc   ') AS a

返回：

+--------+
| a      |
+--------+
| abc    |
+--------+

去除源字符串中的左侧字符abc

RETURN ltrim('aabbccdd' , 'abc') AS a

返回：

+----+
| a  |
+----+
| dd |
+----+

rtrim()

返回去除右侧字符后的字符串。

NULL 行为：默认

函数签名

rtrim( source_str: STRING [, trim_str: STRING] ) -> STRING

参数

• source_str: STRING：源字符串。
• trim_str: STRING：要从源字符串右侧删除的字符。如果省略，默认是空格（）字符。

示例

去除右侧空格字符

RETURN rtrim('  abc   ') AS a

返回：

+-------+
| a     |
+-------+
|   abc |
+-------+

去除源字符串中的右侧字符cd

RETURN rtrim('aabbccdd' , 'cd') AS a

返回：

+------+
| a    |
+------+
| aabb |
+------+

length()

返回字符串中的字符数。

length()还可用于返回列表中的元素数量或返回路径的长度。更多信息，请参见列表函数length()和图函数length()。

NULL 行为：默认

函数签名

length(str: STRING) -> INT32

示例

RETURN length('nebula graph') AS l

返回：

+----+
| l  |
+----+
| 12 |
+----+

contains()

如果在字符串中找到指定的子串，则返回true。

NULL 行为：默认

函数签名

contains(str: STRING, substr: STRING) -> BOOL

参数

• str: STRING：要匹配的源字符串。
• substr: STRING：要查找的子串。

str和substr都可以是返回字符串的表达式。

示例

RETURN contains('nebula graph', 'nebula') AS c

返回：

+------+
| c    |
+------+
| true |
+------+

like()

返回true或false，表示字符串是否匹配指定的模式。用于对字符串类型的数据进行模式匹配。模式可以包含两个通配符：

• 百分号（%）：匹配零个或多个字符。
• 下划线（_）：匹配任意单个字符。

要将百分号（%）和下划线（_）作为普通字符而不是通配符匹配，需要在百分号（%）和下划线（_）前添加反斜杠（\）。由于反斜杠（\）本身是一个转义字符，因此要匹配它，请使用\\。例如，使用\\%匹配%字符，使用\\_匹配_字符。如果模式无效，则返回错误。

NULL 行为：默认

函数签名

like(str: STRING, pattern: STRING) -> BOOLEAN

或

str: STRING LIKE pattern: STRING -> BOOLEAN

str和pattern可以是返回字符串的表达式。

示例

使用简单模式匹配

RETURN like("a", "a%%") AS v

返回：

+------+
| v    |
+------+
| true |
+------+

使用%通配符匹配

RETURN "hello, world" LIKE "hello, wo%" AS v

返回：

+------+
| v    |
+------+
| true |
+------+

使用_通配符匹配

RETURN "hello, world" LIKE "hello, _orl_" AS v

返回：

+------+
| v    |
+------+
| true |
+------+

使用转义字符匹配

RETURN '%' LIKE '\\%' AS v, '_' LIKE '\\_' AS t

返回：

+------+------+
| v    | t    |
+------+------+
| true | true |
+------+------+

使用表达式匹配

'''
LET input = "hello, world", patterns = LIST[ 
  "%ello, _orl%",
  "hello, _orld%",
  "%hello, world%%"]
FOR i in RANGE(1, LENGTH(patterns))
RETURN input LIKE  patterns[i-1] AS v
'''

上面的示例使用like()函数将输入字符串与列表中的模式匹配。i-1索引用于访问列表中的元素。FOR语句用于遍历列表。length()函数用于获取列表的长度。range()函数用于生成始于 1、止于列表长度值的整数序列。有关更多信息，请参见 FOR 和列表函数。

返回：

+------+
| v    |
+------+
| true |
| true |
| true |
+------+

无效模式

RETURN 'a' LIKE '\\a'

返回：

[ERROR]: Invalid function argument `\a` of `like`

regexp_like()

如果字符串匹配指定的正则表达式，则返回true。regexp_like()类似于like()，但使用正则表达式模式进行匹配。如果正则表达式模式无效，则返回错误。

NULL 行为：默认

函数签名

regexp_like(str: STRING, pattern: STRING [, options: STRING]) -> BOOLEAN

参数

• str: STRING：要匹配的源字符串。
• pattern: STRING：要查找的正则表达式模式。有关正则表达式语法的更多信息，请参见正则表达式。

• options: STRING：正则表达式匹配的选项。支持以下选项：

  • i：不区分大小写匹配
  • c：区分大小写匹配
  • n：多行匹配
  • m：与n同义

  options参数是可选的。如果省略，默认是区分大小写和单行匹配。如果指定，它必须是包含一个或多个选项的字符串，任何其他字符将被忽略。选项可以以任意顺序组合。

str和pattern可以是返回字符串的表达式。

示例

使用简单正则表达式匹配

RETURN regexp_like("hello", "he..o") AS v

返回：

+------+
| v    |
+------+
| true |
+------+

使用正则表达式选项匹配

RETURN regexp_like("hello\n, world", "HELLO.*", 'inx') AS v

上面的示例使用i选项不区分大小写匹配，使用n选项进行多行匹配。x选项被忽略，因为它不是有效选项。

返回：

+------+
| v    |
+------+
| true |
+------+

使用str和pattern表达式匹配

'''
LET words = LIST["hello, world"] 
LET patterns = LIST["hel{2}o, .(or).*", ".*", "^hello.*", "hello"] 
FOR w IN words 
FOR p IN patterns 
RETURN regexp_like(w, p) AS v
'''

上面的示例使用regexp_like函数将列表中的单词与列表中的模式匹配。w和p变量用于访问列表中的元素。FOR语句用于遍历列表。有关更多信息，请参见 FOR 和列表函数。

返回：

+-------+
| v     |
+-------+
| true  |
| true  |
| true  |
| false |
+-------+

无效正则表达式

RETURN regexp_like("a", "(a") AS v

返回：

[ERROR]: Invalid function argument `(a` of `regexp_like`

split()

使用指定的正则表达式作为分隔符，将字符串拆分成子字符串列表。

NULL 行为：默认

函数签名

split(str: STRING, regex: STRING[, limit: UINT]) -> LIST<STRING>

参数

• str: STRING：要拆分的源字符串。
• regex: STRING：作为分隔符的正则表达式。
• limit: UINT：可选的非负整数（负整数值将被视为0），用于指定返回的分割结果的最大数量。若省略（默认值为0）或者值大于所有可能的分割结果数，则返回所有可能的分割结果。

示例

使用逗号作为分隔符拆分字符串

RETURN split("a,b,c", ",") AS result

返回：

+---------+
| result  |
+---------+
| [a,b,c] |
+---------+

使用逗号作为分隔符拆分字符串，限制返回的子字符串数量为2

RETURN split("a,b,c", ",", 2) AS result

返回：

+-----------+
| result    |
+-----------+
| [a,"b,c"] |
+-----------+

使用正则表达式作为分隔符拆分字符串

RETURN split("a.txt,.txtb .txt,dfdc.txt, .txt ","[a-z]+\\.txt") AS result

返回：

+-----------------------------+
| result                      |
+-----------------------------+
| [,",.txtb .txt,",", .txt "] |
+-----------------------------+

md5()

返回字符串或字符串列表的 MD5 哈希值。

NULL 行为：默认

函数签名

md5(str: STRING | l: LIST<STRING>) -> STRING

参数

• str: STRING：计算哈希值的源字符串。
• l: LIST<STRING>：计算哈希值的源字符串列表。列表中的元素将拼接成一个字符串，然后计算哈希值。

示例

返回字符串的 MD5 哈希值

RETURN md5("Hello World") AS hash

返回：

+----------------------------------+
| hash                             |
+----------------------------------+
| b10a8db164e0754105b7a99be72e3fe5 |
+----------------------------------+

返回字符串列表的 MD5 哈希值

RETURN md5(["The","is","not","real"]) AS hash

返回：

+----------------------------------+
| hash                             |
+----------------------------------+
| 2959ae045f5aecdf022770443d6a85d8 |
+----------------------------------+

比较两个字符串列表的 MD5 哈希值

LET a = md5(["ThisIs", "Apple"]), b = md5(["This", "IsApple"]) RETURN a, b, a=b AS c

返回：

+----------------------------------+----------------------------------+------+
| a                                | b                                | c    |
+----------------------------------+----------------------------------+------+
| 40a699aa16fce58504ca8a4c277f3f4c | 40a699aa16fce58504ca8a4c277f3f4c | true |
+----------------------------------+----------------------------------+------+

index_of()

返回指定子字符串在目标字符串中第一次出现的起始位置，如果没有找到则返回-1。可以通过指定起始和结束位置来限定搜索范围。搜索范围为左闭右开区间[from, to)。

NULL 行为：默认

函数签名

index_of(str: STRING, substr: STRING[, from: INT, to: INT]) -> INT

参数

• str: STRING：给定的目标字符串，在其中搜索子字符串。
• substr: STRING：在目标字符串str中搜索的子字符串。
• from: INT（可选）：搜索的起始位置。从0开始计算位置，默认为0。如果为负数，视为0。
• to: INT（可选）：搜索范围的结束位置（不含）。从0开始计算位置，默认为-1，代表搜索至字符串末尾。如果为负数或者大于str的长度，视为str的长度。

示例

查找子字符串首次出现的起始位置

RETURN index_of("a数据库✅bcadabad书ad", "ad") AS res

返回：

+-----+
| res |
+-----+
| 7   |
+-----+

在指定范围内查找子字符串首次出现的起始位置

RETURN index_of("a数据库✅bcadabad书ad", "ad", 12) AS res

返回：

+-----+
| res |
+-----+
| 14  |
+-----+

上述语句从目标字符串的第12位开始查找第一次出现的子字符串ad。

未找到子字符串时返回-1

RETURN index_of("a数据库✅bcadabad书ad", "ad", 12, 13) AS res

返回：

+-----+
| res |
+-----+
| -1  |
+-----+

indexes_of()

返回目标字符串中指定子字符串的所有起始位置列表。如果未找到，则返回空列表。可以通过指定起始和结束位置来限定搜索范围。

NULL 行为：默认

函数签名

indexes_of(str: STRING, substr: STRING[, from: INT, to: INT]) -> LIST<INT>

参数

• str: STRING：给定的目标字符串，在其中搜索子字符串。
• substr: STRING：在目标字符串str中搜索的子字符串。
• from: INT（可选）：搜索的起始位置。从0开始计算位置，默认为0。如果为负数，视为0。
• to: INT（可选）：搜索的结束位置。从0开始计算位置，默认为目标字符串的长度。如果为负数或者大于str的长度，视为str的长度。

示例

查找子字符串出现的所有起始位置

RETURN indexes_of("a数据库✅bcadabad书ad", "ad") AS res

返回：

+----------------+
| res            |
+----------------+
| LIST [7,11,14] |
+----------------+

在指定范围内查找子字符串出现的所有起始位置

RETURN indexes_of("a数据库✅bcadabad书ad", "ad", 12) AS res

返回：

+------+
| res  |
+------+
| [14] |
+------+

子字符串未找到时返回空列表

RETURN indexes_of("a数据库✅bcadabad书ad", "ad", 12, 13) AS res

返回：

+-----+
| res |
+-----+
| []  |
+-----+

to_literal()

返回输入值的字符串表示形式。

NULL 行为：通用

函数签名

to_literal(input: E) -> STRING

E代表除DURATION和PATH之外的任意数据类型，以及表类型。

示例

将预定义数据类型转换为字符串字面量

'''
RETURN to_literal(-12) AS a, 
    to_literal(12.34f) AS b, 
    to_literal(null) AS c, 
    to_literal(true) AS d,
    to_literal(CAST(1.5 AS UINT64)) AS e, 
    to_literal(DATE '2022-12-31') AS f,
    to_literal(VECTOR<3,float>([1.1,2.1,3.1])) AS g,
    to_literal("hello world") AS h
'''

返回：

+-----+--------+------+------+---+------------------------------------+------------------------+---------------+
| a   | b      | c    | d    | e | f                                  | g                      | h             |
+-----+--------+------+------+---+------------------------------------+------------------------+---------------+
| -12 | 12.34f | NULL | true | 2 | date(\"2022-12-31\", \"%Y-%m-%d\") | VECTOR(1.1f,2.1f,3.1f) | 'hello world' |
+-----+--------+------+------+---+------------------------------------+------------------------+---------------+

将复合数据类型转换为字符串字面量

'''
RETURN to_literal([1,2,3,4.5]) AS a, 
    to_literal({a:1, b:true}) AS b,
    to_literal(SET {"a", "b", "c"}) AS c,
    to_literal(MAP{"a":1, "b":2}) AS d
'''

返回：

+---------------------+--------------------+------------------+------------------+
| a                   | b                  | c                | d                |
+---------------------+--------------------+------------------+------------------+
| LIST[1M,2M,3M,4.5M] | RECORD{a:1,b:true} | SET{'a','b','c'} | MAP{'a':1,'b':2} |
+---------------------+--------------------+------------------+------------------+

将表类型转换为字符串字面量

'''
TABLE t TYPED TABLE { id INT64, name STRING } =  
    { id: 10001, name: 'Alice' },  
    { id: 10002, name: 'Bob' }
RETURN to_literal(t) AS tableLiteral
'''

返回：

+-------------------------------+
| tableLiteral                  |
+-------------------------------+
| (10001,'Alice'),(10002,'Bob') |
+-------------------------------+

将特殊值转换为字符串字面量

'''
RETURN to_literal(1.0d/0.0) AS inf_0, 
       to_literal(-1.0f/0.0) AS inf_1,
       to_literal(CAST('NaN' AS DECIMAL)) AS `nan`
'''

返回：

+-----------------------------+------------------------------+------------------------+
| inf_0                       | inf_1                        | nan                    |
+-----------------------------+------------------------------+------------------------+
| CAST('Infinity' AS FLOAT64) | CAST('-Infinity' AS FLOAT32) | CAST('NaN' AS DECIMAL) |
+-----------------------------+------------------------------+------------------------+

上述示例返回正无穷（1.0d/0.0）、负无穷（-1.0d/0.0）和非数值（NaN）的字符串字面量。