Hàm mảng

Hàm mảng

Tên Mô tả
ARRAY Trả về một ARRAY chứa một phần tử cho mỗi đối số đầu vào
ARRAY_CONCAT Nối nhiều mảng thành một ARRAY
ARRAY_CONTAINS Trả về TRUE nếu một ARRAY nhất định chứa một giá trị cụ thể
ARRAY_CONTAINS_ALL Trả về TRUE nếu tất cả giá trị đều có trong ARRAY
ARRAY_CONTAINS_ANY Trả về TRUE nếu có bất kỳ giá trị nào trong ARRAY
ARRAY_GET Trả về phần tử tại một chỉ mục nhất định trong ARRAY
ARRAY_LENGTH Trả về số lượng phần tử trong một ARRAY
ARRAY_REVERSE Đảo ngược thứ tự của các phần tử trong ARRAY
SUM Trả về tổng của tất cả các giá trị NUMERIC trong một ARRAY.
JOIN Tạo ra một chuỗi nối các phần tử trong ARRAY dưới dạng giá trị STRING.

MẢNG

Cú pháp:

array(values: ANY...) -> ARRAY

Nội dung mô tả:

Tạo một mảng từ các phần tử đã cho.

  • Nếu không có đối số, đối số đó sẽ được thay thế bằng NULL trong mảng kết quả.

Ví dụ:

giá_trị array(values)
() []
(1, 2, 3) [1, 2, 3]
("a", 1, true) ["a", 1, true]
(1, null) [1, null]
(1; [2; 3]) [1, [2, 3]]

Hàm ARRAY_CONCAT

Cú pháp:

array_concat(arrays: ARRAY...) -> ARRAY

Nội dung mô tả:

Nối hai hoặc nhiều mảng thành một ARRAY duy nhất.

Ví dụ:

mảng array_concat(arrays)
([1, 2], [3, 4]) [1, 2, 3, 4]
(["a", "b"], ["c"]) ["a", "b", "c"]
([1], [2], [3]) [1, 2, 3]
([], [1, 2]) [1, 2]

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayConcat([field("subGenre")]).as("allGenres"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayConcat([Field("subGenre")]).as("allGenres")])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres"))
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_concat(Field.of("subGenre")).as_("allGenres"))
    .execute()
)
firestore_pipelines.py

ARRAY_CONTAINS

Cú pháp:

array_contains(array: ARRAY, value: ANY) -> BOOLEAN

Nội dung mô tả:

Trả về TRUE nếu tìm thấy value trong array, và FALSE trong trường hợp ngược lại.

Ví dụ:

mảng value array_contains(array, value)
[1, 2, 3] 2 đúng
[[1, 2], [3]] [1, 2] đúng
[1, null] null đúng
"abc" BẤT KỲ error

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayContains(constant("mystery")).as("isMystery"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayContains(Constant("mystery")).as("isMystery")])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayContains("mystery").alias("isMystery"))
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayContains("mystery").alias("isMystery"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_contains("mystery").as_("isMystery"))
    .execute()
)
firestore_pipelines.py

ARRAY_CONTAINS_ALL

Cú pháp:

array_contains_all(array: ARRAY, search_values: ARRAY) -> BOOLEAN

Nội dung mô tả:

Trả về TRUE nếu tìm thấy tất cả search_values trong array và FALSE trong trường hợp ngược lại.

Ví dụ:

mảng search_values array_contains_all(array, search_values)
[1, 2, 3] [1, 2] đúng
[1, 2, 3] [1, 4] false
[1, null] [không] đúng
[NaN] [NaN] đúng
[] [] đúng
[1, 2, 3] [] đúng

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAll([constant("fantasy"), constant("adventure")])
      .as("isFantasyAdventure")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre")
      .arrayContainsAll([Constant("fantasy"), Constant("adventure")])
      .as("isFantasyAdventure")
  ])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAll(listOf("fantasy", "adventure"))
            .alias("isFantasyAdventure")
    )
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAll(Arrays.asList("fantasy", "adventure"))
            .alias("isFantasyAdventure")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("genre")
        .array_contains_all(["fantasy", "adventure"])
        .as_("isFantasyAdventure")
    )
    .execute()
)
firestore_pipelines.py

Hàm ARRAY_CONTAINS_ANY

Cú pháp:

array_contains_any(array: ARRAY, search_values: ARRAY) -> BOOLEAN

Nội dung mô tả:

Trả về TRUE nếu tìm thấy bất kỳ search_values nào trong array và FALSE trong trường hợp ngược lại.

Ví dụ:

mảng search_values array_contains_any(array, search_values)
[1, 2, 3] [4, 1] đúng
[1, 2, 3] [4, 5] false
[1, 2, null] [không] đúng

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAny([constant("fantasy"), constant("nonfiction")])
      .as("isMysteryOrFantasy")
  )
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre")
      .arrayContainsAny([Constant("fantasy"), Constant("nonfiction")])
      .as("isMysteryOrFantasy")
  ])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAny(listOf("fantasy", "nonfiction"))
            .alias("isMysteryOrFantasy")
    )
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAny(Arrays.asList("fantasy", "nonfiction"))
            .alias("isMysteryOrFantasy")
    )
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("genre")
        .array_contains_any(["fantasy", "nonfiction"])
        .as_("isMysteryOrFantasy")
    )
    .execute()
)
firestore_pipelines.py

Hàm ARRAY_GET

Cú pháp:

array_get(array: ARRAY, index: INT64) -> ANY

Nội dung mô tả:

Trả về phần tử tại index dựa trên 0 trong array.

  • Nếu index là số âm, các phần tử sẽ được truy cập từ cuối mảng, trong đó -1 là phần tử cuối cùng.
  • Nếu array không thuộc kiểu ARRAY, hàm sẽ trả về một giá trị không có.
  • Nếu index nằm ngoài phạm vi, hàm sẽ trả về một giá trị không có.
  • Nếu index không thuộc kiểu INT64, hàm sẽ trả về lỗi.

Ví dụ:

mảng index array_get(array, index)
[1, 2, 3] 0 1
[1, 2, 3] -1 3
[1, 2, 3] 3 vắng mặt
[1, 2, 3] -4 vắng mặt
"abc" 0 vắng mặt
null 0 vắng mặt
Array "a" error
Array 2.0 error

Hàm ARRAY_LENGTH

Cú pháp:

array_length(array: ARRAY) -> INT64

Nội dung mô tả:

Trả về số lượng phần tử trong array.

Ví dụ:

mảng array_length(array)
[1, 2, 3] 3
[] 0
[1, 1, 1] 3
[1, null] 2

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayLength().as("genreCount"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayLength().as("genreCount")])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayLength().alias("genreCount"))
    .execute()
DocSnippets.kt

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayLength().alias("genreCount"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_length().as_("genreCount"))
    .execute()
)
firestore_pipelines.py

Hàm ARRAY_REVERSE

Cú pháp:

array_reverse(array: ARRAY) -> ARRAY

Nội dung mô tả:

Đảo ngược array đã cho.

Ví dụ:

mảng array_reverse(array)
[1, 2, 3] [3, 2, 1]
["a", "b"] ["b", "a"]
[1, 2, 2, 3] [3, 2, 2, 1]

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayReverse().as("reversedGenres"))
);
test.firestore.js
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayReverse().as("reversedGenres")])
  .execute()
PipelineSnippets.swift

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayReverse().alias("reversedGenres"))
    .execute()
DocSnippets.kt
 
    
Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayReverse().alias("reversedGenres"))
    .execute();
DocSnippets.java
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_reverse().as_("reversedGenres"))
    .execute()
)
firestore_pipelines.py

SUM

Cú pháp:

sum(array: ARRAY) -> INT64 | FLOAT64

Nội dung mô tả:

Trả về tổng của tất cả các giá trị NUMERIC trong một ARRAY.

  • Các giá trị không phải là số trong mảng sẽ bị bỏ qua.
  • Nếu có giá trị số nào trong mảng là NaN, thì hàm sẽ trả về NaN.
  • Loại dữ liệu trả về được xác định bằng loại số rộng nhất trong mảng: INT64 < FLOAT64.
  • Nếu xảy ra tràn số nguyên 64 bit trước khi bất kỳ giá trị dấu phẩy động nào được cộng, thì một lỗi sẽ được trả về. Nếu các giá trị dấu phẩy động được cộng lại, thì tình trạng tràn số sẽ dẫn đến kết quả là +/- vô cực.
  • Nếu mảng không chứa giá trị số nào, hàm sẽ trả về NULL.

Ví dụ:

mảng sum(array)
[1, 2, 3] 6L
[1L, 2L, 3L] 6L
[2000000000, 2000000000] 4000000000L
[10, 20.5] 30,5
[1, "a", 2] 3L
[INT64.MAX_VALUE, 1] error
[INT64.MAX_VALUE, 1, -1.0] error
[INT64.MAX_VALUE, 1.0] 9,223372036854776e+18

THAM GIA

Cú pháp:

join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T) -> STRING
join[T <: STRING | BYTES](array: ARRAY<T>, delimiter: T, null_text: T) -> STRING

Nội dung mô tả:

Trả về chuỗi kết hợp của các phần tử trong array dưới dạng STRING. array có thể thuộc kiểu dữ liệu STRING hoặc BYTES.

  • Tất cả các phần tử trong array, delimiter và null_text phải thuộc cùng một loại; tất cả đều phải là STRING hoặc tất cả đều phải là BYTES.
  • Nếu bạn cung cấp null_text, mọi giá trị NULL trong array sẽ được thay thế bằng null_text.
  • Nếu bạn không cung cấp null_text, các giá trị NULL trong array sẽ bị loại khỏi kết quả.

Ví dụ:

Khi bạn không cung cấp null_text:

mảng dấu phân cách join(array, delimiter)
["a", "b", "c"] "," "a,b,c"
["a", null, "c"] "," "a,c"
[b'a', b'b', b'c'] b',' b'a,b,c'
["a", b'c'] "," error
["a", "c"] b',' error
[b'a', b'c'] "," error

Khi bạn cung cấp null_text:

mảng dấu phân cách null_text join(array, delimiter, null_text)
["a", null, "c"] "," "MISSING" "a,MISSING,c"
[b'a', None, b'c'] b',' b'NULL' b'a,NULL,c'
[null, "b", null] "," "MISSING" "MISSING,b,MISSING"
[b'a', null, null] b',' b'NULL' b'a,NULL,NULL'
["a", null] "," b'N' error
[b'a', null] b',' "N" error