Source: https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/string/
Documentation version: v5.3.2

# 字符串函数

## 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()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/list/#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()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/list/#length)和[图函数`length()`](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/graph/#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](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/dql/for/) 和[列表函数](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/list/)。

返回：

````
+------+
| 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`：要查找的正则表达式模式。有关正则表达式语法的更多信息，请参见[正则表达式](https://www3.ntu.edu.sg/home/ehchua/programming/howto/Regexe.html)。
- 

`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](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/dql/for/) 和[列表函数](https://dev-docs.yueshu.com.cn/v5.3.2/database-gql-reference/fe/functions/list/)。

返回：

````
+-------+
| 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](https://zh.wikipedia.org/wiki/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`）的字符串字面量。