字串函式

字串函式

名稱 說明
BYTE_LENGTH 傳回 STRING 或 BYTES 值中的 BYTES 數量
CHAR_LENGTH 傳回 STRING 值中的萬國碼 (Unicode) 字元數
STARTS_WITH 如果 STRING 的開頭為指定前置字元，則傳回 TRUE
ENDS_WITH 如果 STRING 以指定後置字串結尾，則傳回 TRUE
LIKE 如果 STRING 符合模式，則傳回 TRUE
REGEX_CONTAINS 如果值與規則運算式部分或完全相符，則傳回 TRUE
REGEX_FIND 傳回符合規則運算式的第一個子字串，如果沒有相符項目，則傳回 NULL。
REGEX_FIND_ALL 傳回符合規則運算式的所有子字串陣列，如果沒有相符項目，則傳回空白陣列。
REGEX_MATCH 如果值的任何部分符合規則運算式，則傳回 TRUE
STRING_CONCAT 將多個 STRING 串連成 STRING
STRING_CONTAINS 如果值包含 STRING，則傳回 TRUE
STRING_INDEX_OF 傳回 STRING 或 BYTES 值首次出現時，從 0 起算的索引。
TO_UPPER 將 STRING 或 BYTES 值轉換為大寫。
TO_LOWER 將 STRING 或 BYTES 值轉換為小寫。
SUBSTRING 取得 STRING 或 BYTES 值的子字串。
STRING_REVERSE 反轉 STRING 或 BYTES 值。
STRING_REPEAT 重複 STRING 或 BYTES 值指定的次數。
STRING_REPLACE_ALL 取代所有 STRING 或 BYTES 值。
STRING_REPLACE_ONE 取代第一個出現的 STRING 或 BYTES 值。
TRIM 從 STRING 或 BYTES 值中移除開頭和結尾字元。
LTRIM 從 STRING 或 BYTES 值中移除前置字元。
RTRIM 從 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
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").byteLength().as("titleByteLength")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(byteLength(field("title")).as("titleByteLength"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ByteLength(firestore.FieldOf("title")).As("titleByteLength"),
	)).
	Execute(ctx)

CHAR_LENGTH

語法：

char_length(value: STRING) -> INT64

說明：

傳回 STRING 值中的 Unicode 碼點數量。

範例：

值 char_length(value)
"abc" 3
「你好」 5
"world" 5
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").charLength().as("titleCharLength")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(charLength(field("title")).as("titleCharLength"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.CharLength(firestore.FieldOf("title")).As("titleCharLength"),
	)).
	Execute(ctx)

STARTS_WITH

語法：

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

說明：

如果 value 的開頭是 prefix，則傳回 TRUE。

範例：

值 前置字串 starts_with(value, prefix)
"abc" "a" true
"abc" "b" false
"abc" "" true
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").startsWith("The")
      .as("needsSpecialAlphabeticalSort")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(startsWith(field("title"), "The").as("needsSpecialAlphabeticalSort"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.StartsWith(firestore.FieldOf("title"), "The").As("needsSpecialAlphabeticalSort"),
	)).
	Execute(ctx)

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
Node.js
const result = await db.pipeline()
  .collection("inventory/devices/laptops")
  .select(
    field("name").endsWith("16 inch")
      .as("16InLaptops")
  )
  .execute();
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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("inventory/devices/laptops")
        .select(endsWith(field("name"), "16 inch").as("16InLaptops"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("inventory/devices/laptops").
	Select(firestore.Fields(
		firestore.EndsWith(firestore.FieldOf("name"), "16 inch").As("`Laptops16in`"),
	)).
	Execute(ctx)

喜歡

語法：

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

說明：

如果 value 與 pattern 相符，則傳回 TRUE。

範例：

值 圖案 like(value, pattern)
「Firestore」 「火屬性%」 true
「Firestore」 「%store」 true
「Datastore」 「Data_tore」 true
"100%" "100\%" true
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("genre").like("%Fiction")
      .as("anyFiction")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(like(field("genre"), "%Fiction").as("anyFiction"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Like(firestore.FieldOf("genre"), "%Fiction").As("anyFiction"),
	)).
	Execute(ctx)

REGEX_CONTAINS

語法：

regex_contains(value: STRING, regexp: STRING | REGEX) -> BOOLEAN

說明：

如果 value 的部分內容與 regexp 相符，則傳回 TRUE。如果 regexp 不是有效的規則運算式，這個函式會傳回 error。

regexp 引數也可以是使用 regex("pattern", "options") 建立的 REGEX 值。這種格式可讓您提供規則運算式選項和模式。支援的選項如下：

  • i：不區分大小寫的比對。
  • m：多行模式 (^ 和 $ 比對行首或行尾)。
  • s：Dotall 模式 (. 比對換行符號)。

如果 regexp 是 STRING，除了嵌入模式本身的選項 (例如 (?i)) 之外，不會套用任何選項。

規則運算式遵循 re2 程式庫的語法。

範例：

值 規則運算式 regex_contains(value, regexp)
「Firestore」 "Fire" true
「Firestore」 "store$" true
「Firestore」 "data" false
「Firestore」 regex("fire", "i") true
「Firestore」 regex("FIRE", "") false
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("title").regexContains("Firestore (Enterprise|Standard)")
      .as("isFirestoreRelated")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(
            regexContains(field("title"), "Firestore (Enterprise|Standard)")
                .as("isFirestoreRelated"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.RegexContains(firestore.FieldOf("title"), "Firestore (Enterprise|Standard)").As("isFirestoreRelated"),
	)).
	Execute(ctx)

REGEX_FIND

語法：

regex_find(value: STRING, regexp: STRING | REGEX) -> STRING

說明：

傳回 value 中與 regexp 相符的第一個子字串，如果沒有相符項目，則傳回 NULL。如果 regexp 不是有效的規則運算式，這個函式會傳回 error。

regexp 引數也可以是使用 regex("pattern", "options") 建立的 REGEX 值。這種格式可讓您提供規則運算式選項和模式。支援的選項如下：

  • i：不區分大小寫的比對。
  • m：多行模式 (^ 和 $ 比對行首或行尾)。
  • s：Dotall 模式 (. 比對換行符號)。

如果 regexp 是 STRING，除了嵌入模式本身的選項 (例如 (?i)) 之外，不會套用任何選項。

規則運算式遵循 re2 程式庫的語法。

範例：

值 規則運算式 regex_find(value, regexp)
"Sometext MATCH" "SomeText" "Sometext"
"Sometext MATCH" regex("match", "i") "MATCH"
"Sometext MATCH" regex("(match)", "i") "MATCH"
「部分文字相符」 regex("MATCH", "") null

REGEX_FIND_ALL

語法：

regex_find_all(value: STRING, regexp: STRING | REGEX) -> ARRAY<STRING>

說明：

傳回 value 中與 regexp 相符的所有子字串陣列，如果沒有相符項目，則傳回空陣列。如果 regexp 不是有效的規則運算式，這個函式會傳回 error。

regexp 引數也可以是使用 regex("pattern", "options") 建立的 REGEX 值。這種格式可讓您提供規則運算式選項和模式。支援的選項如下：

  • i：不區分大小寫的比對。
  • m：多行模式 (^ 和 $ 比對行首或行尾)。
  • s：Dotall 模式 (. 比對換行符號)。

如果 regexp 是 STRING，除了嵌入模式本身的選項 (例如 (?i)) 之外，不會套用任何選項。

規則運算式遵循 re2 程式庫的語法。

範例：

值 規則運算式 regex_find_all(value, regexp)
「一二三二」 「一」 ["one"]
「one TWO three Two」 regex("two", "i") ["TWO", "Two"]
「一二三二」 regex("TWO", "") []

REGEX_MATCH

語法：

regex_match(value: STRING, regexp: STRING | REGEX) -> BOOLEAN

說明：

如果 value 與 regexp 完全相符，則傳回 TRUE。如果 regexp 不是有效的規則運算式，這個函式會傳回 error。

regexp 引數也可以是使用 regex("pattern", "options") 建立的 REGEX 值。這種格式可讓您提供規則運算式選項和模式。支援的選項如下：

  • i：不區分大小寫的比對。
  • m：多行模式 (^ 和 $ 比對行首或行尾)。
  • s：Dotall 模式 (. 比對換行符號)。

如果 regexp 是 STRING，除了嵌入模式本身的選項 (例如 (?i)) 之外，不會套用任何選項。

規則運算式遵循 re2 程式庫的語法。

範例：

值 規則運算式 regex_match(value, regexp)
「Firestore」 "F.*store" true
「Firestore」 "Fire" false
「Firestore」 "^F.*e$" true
「FiReStOrE」 regex("firestore", "i") true
「Firestore」 regex("firestore", "") false
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("title").regexMatch("Firestore (Enterprise|Standard)")
      .as("isFirestoreExactly")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(
            regexMatch(field("title"), "Firestore (Enterprise|Standard)")
                .as("isFirestoreExactly"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.RegexMatch(firestore.FieldOf("title"), "Firestore (Enterprise|Standard)").As("isFirestoreExactly"),
	)).
	Execute(ctx)

STRING_CONCAT

語法：

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

說明：

將兩個以上的 STRING 值串連成單一結果。

範例：

引數 string_concat(values...)
() 錯誤
("a") "a"
("abc", "def") "abcdef"
("a", "", "c") "ac"
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").stringConcat(" by ", field("author"))
      .as("fullyQualifiedTitle")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(stringConcat(field("title"), " by ", field("author")).as("fullyQualifiedTitle"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.StringConcat(firestore.FieldOf("title"), " by ", firestore.FieldOf("author")).As("fullyQualifiedTitle"),
	)).
	Execute(ctx)

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
Node.js
const result = await db.pipeline()
  .collection("articles")
  .select(
    field("body").stringContains("Firestore")
      .as("isFirestoreRelated")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("articles")
        .select(stringContains(field("body"), "Firestore").as("isFirestoreRelated"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("articles").
	Select(firestore.Fields(
		firestore.StringContains(firestore.FieldOf("body"), "Firestore").As("isFirestoreRelated"),
	)).
	Execute(ctx)

STRING_INDEX_OF

語法：

string_index_of[T <: STRING | BYTES](value: T, search: T) -> INT64

說明：

傳回 value 中第一個 search 的索引 (從 0 開始)。

  • 如果找不到 search，則傳回「-1」。
  • 如果 value 是 STRING 值，則結果會以 Unicode 碼點為單位。如果是 BYTES 值，則以位元組為單位。
  • 如果 search 是空白的 STRING 或 BYTES 值，結果會是 0。

範例：

值 搜尋 string_index_of(value, search)
"hello world" "o" 4
"hello world" "l" 2
"hello world" "z" -1
"banana" "ana" 1
"abc" "" 0
b"abc" b"b" 1
"é" "é" 0
b"é" b"é" 0

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"
Node.js
const result = await db.pipeline()
  .collection("authors")
  .select(
    field("name").toUpper()
      .as("uppercaseName")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("authors")
        .select(toUpper(field("name")).as("uppercaseName"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("authors").
	Select(firestore.Fields(
		firestore.ToUpper(firestore.FieldOf("name")).As("uppercaseName"),
	)).
	Execute(ctx)

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"
Node.js
const result = await db.pipeline()
  .collection("authors")
  .select(
    field("genre").toLower().equal("fantasy")
      .as("isFantasy")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("authors")
        .select(equal(toLower(field("genre")), "fantasy").as("isFantasy"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("authors").
	Select(firestore.Fields(
		firestore.Equal(firestore.ToLower(firestore.FieldOf("genre")), "fantasy").As("isFantasy"),
	)).
	Execute(ctx)

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：

輸入 位置 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"
Node.js
const result = await db.pipeline()
  .collection("books")
  .where(field("title").startsWith("The "))
  .select(
    field("title").substring(4)
      .as("titleWithoutLeadingThe")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .where(startsWith(field("title"), "The "))
        .select(
            substring(field("title"), constant(4), field("title").charLength())
                .as("titleWithoutLeadingThe"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("books").
	Where(firestore.StartsWith(firestore.FieldOf("title"), "The ")).
	Select(firestore.Fields(
		firestore.Substring(firestore.FieldOf("title"), firestore.ConstantOf(4), firestore.FieldOf("title").CharLength()).As("titleWithoutLeadingThe"),
	)).
	Execute(ctx)

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"
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("name").reverse().as("reversedName")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(reverse(field("name")).as("reversedName"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Reverse(firestore.FieldOf("name")).As("reversedName"),
	)).
	Execute(ctx)

STRING_REPEAT

語法：

string_repeat[T <: STRING | BYTES](input: T, repetitions: INT64) -> T

說明：

傳回重複 repetitions 次的 input。

  • repetitions 必須為非負整數。
  • 如果 repetitions 為 0，則傳回與 input 相同類型的空值。
  • 如果結果超過允許的大小上限 (1 MB)，系統會傳回錯誤。

範例：

輸入 重複次數 string_repeat(input, repetitions)
"foo" 3 "foofoofoo"
"foo" 0 ""
"a " 3 "a a a "
b"ab" 2 b"abab"
"é🦆" 2 "é🦆é🦆"

STRING_REPLACE_ALL

語法：

string_replace_all[T <: STRING | BYTES](input: T, find: T, replacement: T) -> T

說明：

將 input 中所有不重疊的 find 替換為 replacement。

  • 比對時會區分大小寫。
  • 如果 find 為空白，則不會進行任何替換。

範例：

輸入 find 更換 string_replace_all(input, find, replacement)
"foobarfoo" "foo" "baz" "bazbarbaz"
"ababab" "aba" "c" "cbab"
"foobar" "o" "" "fbar"
"é🦆🌎🦆" "🦆" "a" "éa🌎a"
b"abc" b"b" b"d" b"adc"

STRING_REPLACE_ONE

語法：

string_replace_one[T <: STRING | BYTES](input: T, find: T, replacement: T) -> T

說明：

將 input 中第一個出現的 find 替換為 replacement。

  • 比對時會區分大小寫。
  • 如果 find 為空白，則不會進行任何替換。

範例：

輸入 find 更換 string_replace_one(input, find, replacement)
"foobarfoo" "foo" "baz" "bazbarfoo"
"é" "é" "a" "a"
b"foobar" b"o" b"z" b"fzoobar"

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")
  )
);
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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(trim(field("name")).as("whitespaceTrimmedName"))
        .execute()
        .get();
Go
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Trim(firestore.FieldOf("name")).As("whitespaceTrimmedName"),
	)).
	Execute(ctx)

LTRIM

語法：

ltrim[T <: STRING | BYTES](value: T, to_trim: T) -> T
ltrim[T <: STRING | BYTES](value: T) -> T

說明：

從提供的 value 開頭，修剪指定的一組 BYTES 或 CHARS。

  • 如未提供 to_trim，則會移除開頭的空白字元。

範例：

如未提供 to_trim：

值 ltrim(value)
" foo " "foo "
"foo" "foo"

提供 to_trim 時：

值 to_trim ltrim(value, to_trim)
"aaabc" "a" "bc"
"abacaba" "ba" "caba"
"é" "é" ""

RTRIM

語法：

rtrim[T <: STRING | BYTES](value: T, to_trim: T) -> T
rtrim[T <: STRING | BYTES](value: T) -> T

說明：

從提供的 value 結尾，修剪一組指定的 BYTES 或 CHARS。

  • 如未提供 to_trim，則會修剪結尾的空白字元。

範例：

如未提供 to_trim：

值 rtrim(value)
" foo " " foo"
"foo" "foo"

提供 to_trim 時：

值 to_trim rtrim(value, to_trim)
"abccc" "c" "ab"
"abacaba" "ba" "abac"
"é" "é" ""

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 會傳回含有單一空白 STRING 的 ARRAY。

範例：

如未提供 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"C1", b"C2", b"C4"]
b"ABC" b"" [b"A", b"B", b"C"]
"foo" b"C1" 錯誤