Cloud Firestore Enterprise edition in Native mode is now available! Learn more.

פונקציות של מערכים

גרסת טרום-GA: השימוש ב-Firestore במצב Native (עם פעולות Pipeline) במהדורת Enterprise כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, שמפורטים בחלק "תנאים כלליים לשירות" בתנאים הספציפיים של השירות. אתם יכולים להשתמש בתכונה הזו כדי לעבד מידע אישי כמו שמפורט בנספח לעיבוד נתונים ב-Cloud, בכפוף למחויבויות ולהגבלות שמפורטות בהסכם שמעניק לכם גישה ל-Google Cloud. השימוש בתכונות בגרסת טרום-GA הוא "כפי שהן" (As is), ויכול להיות שהתמיכה בהן תהיה מוגבלת. מידע נוסף זמין בקטע תיאורים של שלבי ההשקה.

פונקציות של מערכים

שם	תיאור
`ARRAY`	מחזירה רכיב `ARRAY` שמכיל רכיב אחד לכל ארגומנט קלט
`ARRAY_CONCAT`	הפונקציה משרשרת כמה מערכים למערך אחד `ARRAY`
`ARRAY_CONTAINS`	הפונקציה מחזירה את הערך `TRUE` אם הערך `ARRAY` מכיל ערך מסוים
`ARRAY_CONTAINS_ALL`	הפונקציה מחזירה `TRUE` אם כל הערכים מופיעים ב-`ARRAY`
`ARRAY_CONTAINS_ANY`	הפונקציה מחזירה את הערך `TRUE` אם אחד מהערכים מופיע ב-`ARRAY`
`ARRAY_GET`	מחזירה את הרכיב באינדקס נתון ב-`ARRAY`
`ARRAY_LENGTH`	הפונקציה מחזירה את מספר הרכיבים ב-`ARRAY`
`ARRAY_REVERSE`	הופכת את סדר הרכיבים ב-`ARRAY`
`SUM`	הפונקציה מחזירה את סכום כל הערכים של `NUMERIC` ב-`ARRAY`.
`JOIN`	יוצרת שרשור של הרכיבים ב-`ARRAY` כערך `STRING`.

ARRAY

תחביר:

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

תיאור:

יוצרת מערך מהרכיבים שצוינו.

אם ארגומנט לא קיים, הוא מוחלף ב-NULL במערך שמתקבל.

לדוגמה:

values	`array(values)`
()	[]
(1, 2, 3)	‫[1, 2, 3]
‪("a", 1, true)	‪["a", 1, true]
‪(1, null)	‫[1, null]
(1, [2, 3])	‫[1, [2, 3]]

ARRAY_CONCAT

תחביר:

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

תיאור:

הפונקציה משרשרת שני מערכים או יותר למערך אחד ARRAY.

לדוגמה:

מערכים	`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

תחביר:

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

תיאור:

הפונקציה מחזירה TRUE אם המחרוזת value נמצאת במחרוזת array, ו-FALSE אחרת.

לדוגמה:

מערך	ערך	`array_contains(array, value)`
‫[1, 2, 3]	2	true
‪[[1, 2], [3]]	[1, 2]	true
‫[1, null]	null	true
‪"abc"	הכול	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

תחביר:

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

תיאור:

הפונקציה מחזירה TRUE אם כל הערכים search_values נמצאים ב-array, ומחזירה FALSE אחרת.

לדוגמה:

מערך	search_values	`array_contains_all(array, search_values)`
‫[1, 2, 3]	[1, 2]	true
‫[1, 2, 3]	[1, 4]	false
‫[1, null]	[אפס]	true
[NaN]	[NaN]	true
[]	[]	true
‫[1, 2, 3]	[]	true

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

ARRAY_CONTAINS_ANY

תחביר:

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

תיאור:

הפונקציה מחזירה TRUE אם אחד מהערכים search_values נמצא בערך array, ואם לא, היא מחזירה FALSE.

לדוגמה:

מערך	search_values	`array_contains_any(array, search_values)`
‫[1, 2, 3]	[4, 1]	true
‫[1, 2, 3]	[4, 5]	false
[1, 2, null]	[אפס]	true

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

ARRAY_GET

תחביר:

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

תיאור:

הפונקציה מחזירה את הרכיב במיקום index (החל מ-0) ב-array.

אם index הוא מספר שלילי, הגישה לרכיבים היא מסוף המערך, כאשר -1 הוא הרכיב האחרון.
אם array הוא לא מסוג ARRAY, הפונקציה מחזירה ערך חסר.
אם index הוא מחוץ לתחום, הפונקציה מחזירה ערך חסר.
אם index הוא לא מסוג INT64, הפונקציה מחזירה שגיאה.

לדוגמה:

מערך	אינדקס	`array_get(array, index)`
‫[1, 2, 3]	0	1
‫[1, 2, 3]	-1	3
‫[1, 2, 3]	3	נעדר/ת
‫[1, 2, 3]	-4	נעדר/ת
‪"abc"	0	נעדר/ת
null	0	נעדר/ת
`Array`	‪"a"	error
`Array`	2.0	error

ARRAY_LENGTH

תחביר:

array_length(array: ARRAY) -> INT64

תיאור:

הפונקציה מחזירה את מספר הרכיבים ב-array.

לדוגמה:

מערך	`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

ARRAY_REVERSE

תחביר:

array_reverse(array: ARRAY) -> ARRAY

תיאור:

היפוך של array הנתון.

לדוגמה:

מערך	`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

תחביר:

sum(array: ARRAY) -> INT64 | FLOAT64

תיאור:

הפונקציה מחזירה את סכום כל הערכים של NUMERIC ב-ARRAY.

המערכת מתעלמת מערכים לא מספריים במערך.
אם ערך מספרי כלשהו במערך הוא NaN, הפונקציה מחזירה NaN.
סוג ההחזרה נקבע לפי הסוג המספרי הרחב ביותר במערך: INT64 < FLOAT64.
אם מתרחשת גלישה של מספר שלם בן 64 ביט לפני סיכום של ערך נקודה צפה כלשהו, הפונקציה מחזירה שגיאה. אם מסכמים ערכים של נקודה צפה, גלישה תגרום לתוצאה של אינסוף חיובי או שלילי.
אם המערך לא מכיל ערכים מספריים בכלל, הפונקציה מחזירה NULL.

לדוגמה:

מערך	`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

JOIN

תחביר:

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

תיאור:

הפונקציה מחזירה שרשור של האלמנטים ב-array בתור STRING. הפרמטר array יכול להיות מסוג הנתונים STRING או BYTES.

כל הרכיבים ב-array,‏ delimiter וגם null_text צריכים להיות מאותו סוג. הם צריכים להיות כולם STRING או כולם BYTES.
אם מציינים את null_text, כל הערכים של NULL ב-array מוחלפים ב-null_text.
אם לא מציינים את null_text, ערכי NULL ב-array לא נכללים בתוצאה.

לדוגמה:

אם לא מציינים את הערך null_text:

מערך	תו מפריד	`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

כשהערך בשדה null_text הוא:

מערך	תו מפריד	null_text	`join(array, delimiter, null_text)`
‪["a", null, "c"]	","	"MISSING"	‪"a,MISSING,c"
‪[b'a', null, 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

פונקציות של מערכים קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.