字串函式
| 名稱 | 說明 |
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") ) );
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
說明:
如果 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") ) );
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
說明:
如果 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") ) );
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
說明:
如果 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") ) );
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
說明:
將 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") ) );
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
說明:
將 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") ) );
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,則會傳回從 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" |
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 開頭和結尾,修剪一組指定的 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() )
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"," | [b"C1", b"C2", b"C4"] |
| b"ABC" | b"" | [b"A", b"B", b"C"] |
| "foo" | b"C1" | 錯誤 |