字串函式

字串函式

名稱 說明
BYTE_LENGTH 傳回 STRINGBYTES 值中的 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 STRINGBYTES 值轉換為大寫。
TO_LOWER STRINGBYTES 值轉換為小寫。
SUBSTRING 取得 STRINGBYTES 值的子字串。
STRING_REVERSE 反轉 STRINGBYTES 值。
TRIM STRINGBYTES 值中移除開頭和結尾字元。
SPLIT STRINGBYTES 值分割為陣列。

BYTE_LENGTH

語法:

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

說明:

傳回 STRINGBYTES 值中的 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")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").byteLength().as("titleByteLength")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").byteLength().alias("titleByteLength")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

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

CHAR_LENGTH

語法:

char_length(value: STRING) -> INT64

說明:

傳回 STRING 值中的 Unicode 碼位數。

範例:

char_length(value)
"abc" 3
「你好」 5
「world」 5

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("title").charLength().as("titleCharLength")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").charLength().as("titleCharLength")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").charLength().alias("titleCharLength")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

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

STARTS_WITH

語法:

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

說明:

如果 valueprefix 開頭,則傳回 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")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").startsWith("The")
      .as("needsSpecialAlphabeticalSort")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").startsWith("The")
            .alias("needsSpecialAlphabeticalSort")
    )
    .execute();
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()
)

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()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("inventory/devices/laptops")
    .select(
        field("name").endsWith("16 inch")
            .alias("16InLaptops")
    )
    .execute();
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()
)

喜歡

語法:

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

說明:

如果 valuepattern 相符,則傳回 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")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre").like("%Fiction")
      .as("anyFiction")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre").like("%Fiction")
            .alias("anyFiction")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

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

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")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("title").regexContains("Firestore (Enterprise|Standard)")
      .as("isFirestoreRelated")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("title").regexContains("Firestore (Enterprise|Standard)")
            .alias("isFirestoreRelated")
    )
    .execute();
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()
)

REGEX_MATCH

語法:

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

說明:

如果 valuepattern 完全相符,則會傳回 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")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("title").regexMatch("Firestore (Enterprise|Standard)")
      .as("isFirestoreExactly")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("title").regexMatch("Firestore (Enterprise|Standard)")
            .alias("isFirestoreExactly")
    )
    .execute();
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()
)

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")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("title").concat([" by ", Field("author")])
      .as("fullyQualifiedTitle")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("title").concat(" by ", field("author"))
            .alias("fullyQualifiedTitle")
    )
    .execute();
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()
)

STRING_CONTAINS

語法:

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

說明:

檢查 value 是否包含字串常值 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")
  )
);
Swift
let result = try await db.pipeline()
  .collection("articles")
  .select([
    Field("body").stringContains("Firestore")
      .as("isFirestoreRelated")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("articles")
    .select(
        field("body").stringContains("Firestore")
            .alias("isFirestoreRelated")
    )
    .execute();
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()
)

TO_UPPER

語法:

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

說明:

STRINGBYTES 值轉換為大寫。

如果位元組或字元不對應至 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")
  )
);
Swift
let result = try await db.pipeline()
  .collection("authors")
  .select([
    Field("name").toUpper()
      .as("uppercaseName")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("authors")
    .select(
        field("name").toUpper()
            .alias("uppercaseName")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

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

TO_LOWER

語法:

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

說明:

STRINGBYTES 值轉換為小寫。

如果位元組或字元不對應至 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")
  )
);
Swift
let result = try await db.pipeline()
  .collection("authors")
  .select([
    Field("genre").toLower().equal("fantasy")
      .as("isFantasy")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("authors")
    .select(
        field("genre").toLower().equal("fantasy")
            .alias("isFantasy")
    )
    .execute();
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()
)

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,則會傳回從 positioninput 結尾的子字串。

  • 如果 inputSTRING 值,則 positionlength 會以 Unicode 碼點為單位。如果是 BYTES 值,則以位元組為單位。

  • 如果 position 大於 input 的長度,系統會傳回空白子字串。如果 position 加上 length 大於 input 的長度,子字串會截斷至 input 的結尾。

  • 如果 position 為負數,位置會從輸入內容的結尾開始計算。如果負數 position 大於輸入內容的大小,位置會設為零。length 不得為負數。

範例:

如果未提供 length

輸入 位置 substring(input, position)
"abc" 0 "abc"
"abc" 1 "bc"
"abc" 3 ""
"abc" -1 「c」
b"abc" 1 b"bc"

提供 length 時:

輸入 位置 長度 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")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .where(Field("title").startsWith("The "))
  .select([
    Field("title").substring(position: 4)
      .as("titleWithoutLeadingThe")
  ])
  .execute()

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()

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();
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()
)

STRING_REVERSE

語法:

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

說明:

以相反順序傳回提供的輸入內容。

如果輸入內容為 STRING,系統會以 Unicode 碼位劃分字元;如果輸入內容為 BYTES 值,系統則會以位元組劃分字元。

範例:

輸入 string_reverse(input)
"abc" "cba"
"a🌹b" "b🌹a"
「你好」 「olleh」
b"abc" b"cba"

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("name").reverse().as("reversedName")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("name").reverse().as("reversedName")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("name").reverse().alias("reversedName")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

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

TRIM

語法:

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

說明:

從提供的 input 開頭和結尾,修剪一組指定的 BYTESCHARS

  • 如果未提供 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")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("name").trim(" \n\t").as("whitespaceTrimmedName")
  ])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("name").trim().alias("whitespaceTrimmedName")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

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

SPLIT

語法:

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

說明:

使用分隔符號拆分 STRINGBYTES 值。

  • 對於 STRING,預設分隔符號是逗號 ,。分隔符號會視為單一字串。

  • 對於 BYTES,您必須指定分隔符號。

  • 以空的分隔符號分割時,STRING 值會產生 Unicode 碼位陣列,BYTES 值則會產生 BYTES 陣列。

  • 分割空的 STRING 會傳回帶有單一空白 STRINGARRAY

範例:

如果未提供 delimiter

輸入 split(input)
「foo,bar,foo」 ["foo", "bar", "foo"]
"foo" ["foo"]
",foo," ["", "foo", ""]
"" [""]
b"C120C2C4" 錯誤

提供 delimiter 時:

輸入 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" 錯誤