现已推出与 MongoDB 兼容的 Cloud Firestore 企业版！了解详情。

字符串函数

名称	说明
`BYTE_LENGTH`	返回 `STRING` 或 `BYTES` 值中 `BYTES` 的数量
`CHAR_LENGTH`	返回 `STRING` 值中的 Unicode 字符数
`STARTS_WITH`	如果 `STRING` 以指定前缀开头，则返回 `TRUE`
`ENDS_WITH`	如果 `STRING` 以给定的后缀结尾，则返回 `TRUE`
`LIKE`	如果 `STRING` 与某种模式匹配，则返回 `TRUE`
`REGEX_CONTAINS`	如果某个值与正则表达式部分或完全匹配，则返回 `TRUE`
`REGEX_MATCH`	如果该值的任何部分与正则表达式匹配，则返回 `TRUE`
`STRING_CONCAT`	将多个 `STRING` 连接成一个 `STRING`
`STRING_CONTAINS`	如果值包含 `STRING`，则返回 `TRUE`
`TO_UPPER`	将 `STRING` 或 `BYTES` 值转换为大写。
`TO_LOWER`	将 `STRING` 或 `BYTES` 值转换为小写。
`SUBSTRING`	获取 `STRING` 或 `BYTES` 值的子字符串。
`STRING_REVERSE`	反转 `STRING` 或 `BYTES` 值。
`TRIM`	从 `STRING` 或 `BYTES` 值中去除前导和尾随字符。
`SPLIT`	将 `STRING` 或 `BYTES` 值拆分为数组。

BYTE_LENGTH

语法：

byte_length[T <: STRING | BYTES](value: T) -> INT64

说明：

返回 STRING 或 BYTES 值中 BYTES 的出现次数。

示例：

值	`byte_length(value)`
"abc"	3
"xyzabc"	6
b"abc"	3

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("title").byteLength().as("titleByteLength")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").byteLength().as("titleByteLength")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("title").byteLength().alias("titleByteLength")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").byteLength().alias("titleByteLength")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("title").byte_length().as_("titleByteLength"))
    .execute()
)firestore_pipelines.py

CHAR_LENGTH

语法：

char_length(value: STRING) -> INT64

说明：

返回 STRING 值中的 Unicode 码位数量。

示例：

值	`char_length(value)`
"abc"	3
"hello"	5
"world"	5

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("title").charLength().as("titleCharLength")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").charLength().as("titleCharLength")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("title").charLength().alias("titleCharLength")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").charLength().alias("titleCharLength")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("title").char_length().as_("titleCharLength"))
    .execute()
)firestore_pipelines.py

STARTS_WITH

语法：

starts_with(value: STRING, prefix: STRING) -> BOOLEAN

说明：

如果 value 以 prefix 开头，则返回 TRUE。

示例：

值	前缀	`starts_with(value, prefix)`
"abc"	"a"	true
"abc"	"b"	false
"abc"	""	true

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("title").startsWith("The")
      .as("needsSpecialAlphabeticalSort")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").startsWith("The")
      .as("needsSpecialAlphabeticalSort")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("title").startsWith("The")
            .alias("needsSpecialAlphabeticalSort")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").startsWith("The")
            .alias("needsSpecialAlphabeticalSort")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("title").starts_with("The").as_("needsSpecialAlphabeticalSort")
    )
    .execute()
)firestore_pipelines.py

ENDS_WITH

语法：

ends_with(value: STRING, postfix: STRING) -> BOOLEAN

说明：

如果 value 以 postfix 结尾，则返回 TRUE。

示例：

值	postfix	`ends_with(value, postfix)`
"abc"	"c"	true
"abc"	"b"	false
"abc"	""	true

Swift

let result = try await db.pipeline()
  .collection("inventory/devices/laptops")
  .select([
    Field("name").endsWith("16 inch")
      .as("16InLaptops")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("inventory/devices/laptops")
    .select(
        field("name").endsWith("16 inch")
            .alias("16InLaptops")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("inventory/devices/laptops")
    .select(
        field("name").endsWith("16 inch")
            .alias("16InLaptops")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("inventory/devices/laptops")
    .select(Field.of("name").ends_with("16 inch").as_("16InLaptops"))
    .execute()
)firestore_pipelines.py

LIKE

语法：

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

说明：

如果 value 与 pattern 匹配，则返回 TRUE。

示例：

值	模式	`like(value, pattern)`
"Firestore"	"Fire%"	true
"Firestore"	"%store"	true
"Datastore"	"Data_tore"	true
"100%"	"100\%"	true

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre").like("%Fiction")
      .as("anyFiction")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre").like("%Fiction")
      .as("anyFiction")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("genre").like("%Fiction")
            .alias("anyFiction")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre").like("%Fiction")
            .alias("anyFiction")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").like("%Fiction").as_("anyFiction"))
    .execute()
)firestore_pipelines.py

REGEX_CONTAINS

语法：

regex_contains(value: STRING, pattern: STRING) -> BOOLEAN

说明：

如果 value 的某一部分与 pattern 匹配，则返回 TRUE。如果 pattern 不是有效的正则表达式，此函数会返回 error。

正则表达式遵循 re2 库的语法。

示例：

值	模式	`regex_contains(value, pattern)`
"Firestore"	"Fire"	true
"Firestore"	"store$"	true
"Firestore"	"data"	false

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("title").regexContains("Firestore (Enterprise|Standard)")
      .as("isFirestoreRelated")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("title").regexContains("Firestore (Enterprise|Standard)")
      .as("isFirestoreRelated")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("title").regexContains("Firestore (Enterprise|Standard)")
            .alias("isFirestoreRelated")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("title").regexContains("Firestore (Enterprise|Standard)")
            .alias("isFirestoreRelated")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("title")
        .regex_contains("Firestore (Enterprise|Standard)")
        .as_("isFirestoreRelated")
    )
    .execute()
)firestore_pipelines.py

REGEX_MATCH

语法：

regex_match(value: STRING, pattern: STRING) -> BOOLEAN

说明：

如果 value 完全匹配 pattern，则返回 TRUE。如果 pattern 不是有效的正则表达式，此函数会返回 error。

正则表达式遵循 re2 库的语法。

示例：

值	模式	`regex_match(value, pattern)`
"Firestore"	"F.*store"	true
"Firestore"	"Fire"	false
"Firestore"	"^F.*e$"	true

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("title").regexMatch("Firestore (Enterprise|Standard)")
      .as("isFirestoreExactly")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("title").regexMatch("Firestore (Enterprise|Standard)")
      .as("isFirestoreExactly")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("title").regexMatch("Firestore (Enterprise|Standard)")
            .alias("isFirestoreExactly")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("title").regexMatch("Firestore (Enterprise|Standard)")
            .alias("isFirestoreExactly")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("title")
        .regex_match("Firestore (Enterprise|Standard)")
        .as_("isFirestoreExactly")
    )
    .execute()
)firestore_pipelines.py

STRING_CONCAT

语法：

string_concat(values: STRING...) -> STRING

说明：

将两个或多个 STRING 值串联成一个结果。

示例：

参数	`string_concat(values...)`
`()`	错误
`("a")`	"a"
`("abc", "def")`	"abcdef"
`("a", "", "c")`	"ac"

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("title").stringConcat(" by ", field("author"))
      .as("fullyQualifiedTitle")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").concat([" by ", Field("author")])
      .as("fullyQualifiedTitle")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("title").concat(" by ", field("author"))
            .alias("fullyQualifiedTitle")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").concat(" by ", field("author"))
            .alias("fullyQualifiedTitle")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("title")
        .concat(" by ", Field.of("author"))
        .as_("fullyQualifiedTitle")
    )
    .execute()
)firestore_pipelines.py

STRING_CONTAINS

语法：

string_contains(value: STRING, substring: STRING) -> BOOLEAN

说明：

检查 value 是否包含字面值字符串 substring。

示例：

值	substring	`string_contains(value, substring)`
"abc"	"b"	true
"abc"	"d"	false
"abc"	""	true
"a.c"	"."	true
"☃☃☃"	"☃"	true

Web

const result = await execute(db.pipeline()
  .collection("articles")
  .select(
    field("body").stringContains("Firestore")
      .as("isFirestoreRelated")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("articles")
  .select([
    Field("body").stringContains("Firestore")
      .as("isFirestoreRelated")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("articles")
    .select(
        field("body").stringContains("Firestore")
            .alias("isFirestoreRelated")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("articles")
    .select(
        field("body").stringContains("Firestore")
            .alias("isFirestoreRelated")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("articles")
    .select(Field.of("body").string_contains("Firestore").as_("isFirestoreRelated"))
    .execute()
)firestore_pipelines.py

TO_UPPER

语法：

to_upper[T <: STRING | BYTES](value: T) -> T

说明：

将 STRING 或 BYTES 值转换为大写。

如果某个字节或字符不属于 UTF-8 小写字母字符，则该字节或字符将保持原样，不作改动。

示例：

值	`to_upper(value)`
"abc"	"ABC"
"AbC"	"ABC"
b"abc"	b"ABC"
b"a1c"	b"A1C"

Web

const result = await execute(db.pipeline()
  .collection("authors")
  .select(
    field("name").toUpper()
      .as("uppercaseName")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("authors")
  .select([
    Field("name").toUpper()
      .as("uppercaseName")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("authors")
    .select(
        field("name").toUpper()
            .alias("uppercaseName")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("authors")
    .select(
        field("name").toUpper()
            .alias("uppercaseName")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("authors")
    .select(Field.of("name").to_upper().as_("uppercaseName"))
    .execute()
)firestore_pipelines.py

TO_LOWER

语法：

to_lower[T <: STRING | BYTES](value: T) -> T

说明：

将 STRING 或 BYTES 值转换为小写。

如果某个字节或字符不属于 UTF-8 大写字母字符，则该字节或字符将保持原样，不作改动。

示例：

值	`to_lower(value)`
"ABC"	"abc"
"AbC"	"abc"
"A1C"	"a1c"
b"ABC"	b"abc"

Web

const result = await execute(db.pipeline()
  .collection("authors")
  .select(
    field("genre").toLower().equal("fantasy")
      .as("isFantasy")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("authors")
  .select([
    Field("genre").toLower().equal("fantasy")
      .as("isFantasy")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("authors")
    .select(
        field("genre").toLower().equal("fantasy")
            .alias("isFantasy")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("authors")
    .select(
        field("genre").toLower().equal("fantasy")
            .alias("isFantasy")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("authors")
    .select(Field.of("genre").to_lower().equal("fantasy").as_("isFantasy"))
    .execute()
)firestore_pipelines.py

SUBSTRING

语法：

substring[T <: STRING | BYTES](input: T, position: INT64) -> T
substring[T <: STRING | BYTES](input: T, position: INT64, length: INT64) -> T

说明：

返回 input 的子字符串，从 position（从零开始的索引）开始，最多包含 length 个条目。如果未提供 length，则返回从 position 到 input 结尾的子字符串。

如果 input 是 STRING 类型的值，则 position 和 length 的计量单位是 Unicode 码位。如果它是 BYTES 类型的值，则计量单位是字节。
如果 position 大于 input 的长度，则返回空子字符串。如果 position 与 length 之和大于 input 的长度，则子字符串将从起始位置截取到 input 的末尾。
如果 position 为负数，则位置从输入的末尾开始计算。如果负的 position 大于输入大小，则位置将被设置为零。length 必须为非负数。

示例：

未提供 length 时：

输入	position	`substring(input, position)`
"abc"	0	"abc"
"abc"	1	"bc"
"abc"	3	""
"abc"	-1	"c"
b"abc"	1	b"bc"

当提供 length 时：

输入	position	长度	`substring(input, position, length)`
"abc"	0	1	"a"
"abc"	1	2	"bc"
"abc"	-1	1	"c"
b"abc"	0	1	b"a"

Web

const result = await execute(db.pipeline()
  .collection("books")
  .where(field("title").startsWith("The "))
  .select(
    field("title").substring(4)
      .as("titleWithoutLeadingThe")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .where(Field("title").startsWith("The "))
  .select([
    Field("title").substring(position: 4)
      .as("titleWithoutLeadingThe")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .where(field("title").startsWith("The "))
    .select(
        field("title")
          .substring(constant(4),
            field("title").charLength().subtract(4))
            .alias("titleWithoutLeadingThe")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .where(field("title").startsWith("The "))
    .select(
        field("title").substring(
          constant(4),
            field("title").charLength().subtract(4))
            .alias("titleWithoutLeadingThe")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .where(Field.of("title").starts_with("The "))
    .select(Field.of("title").substring(4).as_("titleWithoutLeadingThe"))
    .execute()
)firestore_pipelines.py

STRING_REVERSE

语法：

string_reverse[T <: STRING | BYTES](input: T) -> T

说明：

按相反顺序返回所提供的输入内容。

当输入为 STRING 类型时，字符以 Unicode 码位为单位进行划分；当输入为 BYTES 类型的值时，则以字节为单位进行划分。

示例：

输入	`string_reverse(input)`
"abc"	"cba"
"a🌹b"	"b🌹a"
"hello"	"olleh"
b"abc"	b"cba"

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("name").reverse().as("reversedName")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("name").reverse().as("reversedName")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("name").reverse().alias("reversedName")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("name").reverse().alias("reversedName")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("name").string_reverse().as_("reversedName"))
    .execute()
)firestore_pipelines.py

TRIM

语法：

trim[T <: STRING | BYTES](input: T, values_to_trim: T) -> T
trim[T <: STRING | BYTES](input: T) -> T

说明：

从所提供的 input 的开头和结尾处，移除指定的一组 BYTES 或 CHARS。

如果未提供 values_to_trim，则会去除空白字符。

示例：

未提供 values_to_trim 时：

输入	`trim(input)`
"foo"	"foo"
b" foo "	b"foo"
"foo"	"foo"
""	""
" "	""
"\t foo \n"	"foo"
b"\t foo \n"	b"foo"
"\r\f\v foo \r\f\v"	"foo"
b"\r\f\v foo \r\f\v"	b"foo"

当提供 values_to_trim 时：

输入	values_to_trim	`trim(input, values_to_trim)`
"abcbfooaacb"	"abc"	"foo"
"abcdaabadbac"	"abc"	"daabad"
b"C1C2C3"	b"C1"	b"C2C3"
b"C1C2"	"foo"	错误
"foo"	b"C1"	错误

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("name").trim().as("whitespaceTrimmedName")
  )
);test.firestore.js

Swift

let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("name").trim(" \n\t").as("whitespaceTrimmedName")
  ])
  .execute()PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("name").trim().alias("whitespaceTrimmedName")
    )
    .execute()DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("name").trim().alias("whitespaceTrimmedName")
    )
    .execute();DocSnippets.java

Python

from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("name").trim().as_("whitespaceTrimmedName"))
    .execute()
)firestore_pipelines.py

SPLIT

语法：

split(input: STRING) -> ARRAY<STRING>
split[T <: STRING | BYTES](input: T, delimiter: T) -> ARRAY<T>

说明：

使用分隔符拆分 STRING 或 BYTES 值。

对于 STRING，默认分隔符是英文逗号 ,。分隔符会被视为单个字符串。
对于 BYTES，您必须指定一个分隔符。
使用空分隔符进行拆分时，对于 STRING 类型的值会生成 Unicode 码位数组，而对于 BYTES 类型的值则会生成 BYTES 数组。
拆分空 STRING 会返回一个 ARRAY，其中只包含一个空 STRING 元素。

示例：

未提供 delimiter 时：

输入	`split(input)`
"foo,bar,foo"	["foo", "bar", "foo"]
"foo"	["foo"]
",foo,"	["", "foo", ""]
""	[""]
b"C120C2C4"	错误

当提供 delimiter 时：

输入	定界符	`split(input, delimiter)`
"foo bar foo"	" "	["foo", "bar", "foo"]
"foo bar foo"	"z"	["foo bar foo"]
"abc"	""	["a", "b", "c"]
b"C1,C2,C4"	b","	[b"C1", b"C2", b"C4"]
b"ABC"	b""	[b"A", b"B", b"C"]
"foo"	b"C1"	错误

字符串函数 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。