توابع آرایه

توابع آرایه

نام توضیحات
ARRAY یک ARRAY شامل یک عنصر برای هر آرگومان ورودی برمی‌گرداند
ARRAY_CONCAT چندین آرایه را به یک ARRAY واحد متصل می‌کند.
ARRAY_CONTAINS اگر ARRAY داده شده حاوی مقدار خاصی باشد TRUE را برمی‌گرداند.
ARRAY_CONTAINS_ALL اگر همه مقادیر در ARRAY وجود داشته باشند، TRUE برمی‌گرداند
ARRAY_CONTAINS_ANY اگر هر یک از مقادیر در ARRAY وجود داشته باشد، TRUE برمی‌گرداند
ARRAY_GET عنصر موجود در یک اندیس مشخص در یک ARRAY را برمی‌گرداند.
ARRAY_LENGTH تعداد عناصر موجود در یک ARRAY را برمی‌گرداند
ARRAY_REVERSE ترتیب عناصر یک ARRAY را معکوس می‌کند.
SUM مجموع تمام مقادیر NUMERIC موجود در یک ARRAY را برمی‌گرداند.
JOIN عناصر موجود در یک ARRAY را به صورت یک مقدار STRING به هم پیوند می‌دهد.

آرایه

نحو:

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

شرح:

یک آرایه از عناصر داده شده می‌سازد.

  • اگر آرگومانی وجود نداشته باشد، در آرایه حاصل با NULL جایگزین می‌شود.

مثال‌ها:

ارزش‌ها array(values)
() []
(1، 2، 3) [1، 2، 3]
("الف"، ۱، درست) ["الف"، 1، درست]
(1، تهی) [1، تهی]
(1، [2، 3]) [1، [2، 3]]

آرایه_کانکت

نحو:

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

شرح:

دو یا چند آرایه را در یک ARRAY واحد به هم متصل می‌کند.

مثال‌ها:

آرایه‌ها array_concat(arrays)
([1، 2]، [3، 4]) [1، 2، 3، 4]
(["الف"، "ب"]، ["ج"]) ["الف"، "ب"، "ج"]
([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
سویفت 
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
پایتون 
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: ARRAY, value: ANY) -> BOOLEAN

شرح:

اگر value در array یافت شود، TRUE و در غیر این صورت FALSE را برمی‌گرداند.

مثال‌ها:

آرایه ارزش array_contains(array, value)
[1، 2، 3] ۲ درست
[[1، 2]، [3]] [1، 2] درست
[1، تهی] تهی درست
"ای بی سی" هر خطا

Web 

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayContains(constant("mystery")).as("isMystery"))
);
test.firestore.js
سویفت 
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
پایتون 
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: ARRAY, search_values: ARRAY) -> BOOLEAN

شرح:

اگر همه search_values در array پیدا شوند، مقدار TRUE و در غیر این صورت FALSE برمی‌گرداند.

مثال‌ها:

آرایه مقادیر_جستجو array_contains_all(array, search_values)
[1، 2، 3] [1، 2] درست
[1، 2، 3] [1، 4] نادرست
[1، تهی] [تهی] درست
[نان] [نان] درست
[] [] درست
[1، 2، 3] [] درست

Web 

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAll([constant("fantasy"), constant("adventure")])
      .as("isFantasyAdventure")
  )
);
test.firestore.js
سویفت 
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
پایتون 
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: ARRAY, search_values: ARRAY) -> BOOLEAN

شرح:

اگر هر یک از مقادیر search_values در array یافت شود، مقدار TRUE و در غیر این صورت FALSE برمی‌گرداند.

مثال‌ها:

آرایه مقادیر_جستجو array_contains_any(array, search_values)
[1، 2، 3] [4، 1] درست
[1، 2، 3] [4، 5] نادرست
[1، 2، تهی] [تهی] درست

Web 

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAny([constant("fantasy"), constant("nonfiction")])
      .as("isMysteryOrFantasy")
  )
);
test.firestore.js
سویفت 
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
پایتون 
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: ARRAY, index: INT64) -> ANY

شرح:

عنصری را که در index مبتنی بر 0 در array قرار دارد، برمی‌گرداند.

  • اگر index منفی باشد، عناصر از انتهای آرایه قابل دسترسی هستند، که در آن -1 آخرین عنصر است.
  • اگر array از نوع ARRAY نباشد، تابع مقداری را برمی‌گرداند که وجود ندارد.
  • اگر index خارج از محدوده باشد، تابع مقداری را برمی‌گرداند که وجود ندارد.
  • اگر index از نوع INT64 نباشد، تابع خطا برمی‌گرداند.

مثال‌ها:

آرایه شاخص array_get(array, index)
[1، 2، 3] 0 ۱
[1، 2، 3] -1 ۳
[1، 2، 3] ۳ غایب
[1، 2، 3] -4 غایب
"ای بی سی" 0 غایب
تهی 0 غایب
Array «الف» خطا
Array ۲.۰ خطا

طول آرایه

نحو: 

array_length(array: ARRAY) -> INT64

شرح:

تعداد عناصر موجود در array را برمی‌گرداند.

مثال‌ها:

آرایه array_length(array)
[1، 2، 3] ۳
[] 0
[1، 1، 1] ۳
[1، تهی] ۲

Web 

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("genre").arrayLength().as("genreCount"))
);
test.firestore.js
سویفت 
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
پایتون 
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: ARRAY) -> ARRAY

شرح:

array داده شده را معکوس می‌کند.

مثال‌ها:

آرایه array_reverse(array)
[1، 2، 3] [3، 2، 1]
["الف"، "ب"] ["ب"، "الف"]
[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
سویفت 
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
پایتون 
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(array: ARRAY) -> INT64 | FLOAT64

شرح:

مجموع تمام مقادیر NUMERIC موجود در یک ARRAY را برمی‌گرداند.

  • مقادیر غیر عددی در آرایه نادیده گرفته می‌شوند.
  • اگر هر مقدار عددی در آرایه NaN باشد، تابع مقدار NaN را برمی‌گرداند.
  • نوع بازگشتی توسط عریض‌ترین نوع عددی در آرایه تعیین می‌شود: INT64 < FLOAT64 .
  • اگر قبل از جمع کردن هر مقدار اعشاری، سرریز عدد صحیح ۶۴ بیتی رخ دهد، خطایی برگردانده می‌شود. اگر مقادیر اعشاری جمع شوند، سرریز منجر به بی‌نهایت +/- خواهد شد.
  • اگر آرایه اصلاً حاوی مقادیر عددی نباشد، تابع مقدار NULL را برمی‌گرداند.

مثال‌ها:

آرایه sum(array)
[1، 2، 3] 6 لیتر
[۱ لیتر، ۲ لیتر، ۳ لیتر] 6 لیتر
[2000000000، 2000000000] ۴۰۰۰۰۰۰۰۰۰لیتر
[10، 20.5] ۳۰.۵
[1، "الف"، 2] ۳ لیتر
[INT64.MAX_VALUE، ۱] خطا
[INT64.MAX_VALUE، ۱، -۱.۰] خطا
[INT64.MAX_VALUE، ۱.۰] ۹.۲۲۳۳۷۲۰۳۶۸۵۴۷۷۶e+۱۸

بپیوندید

نحو: 

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'، ب'c'] "،" خطا

وقتی null_text ارائه می‌شود:

آرایه جداکننده متن_خالی join(array, delimiter, null_text)
["الف"، تهی، "ج"] "،" «گمشده» «الف، مفقود، ج»
[b'a'، تهی، b'c'] ب'،' پوچ ب'a، تهی، ج'
[تهی، "ب"، تهی] "،" «گمشده» «گمشده، ب، گم‌شده»
[b'a'، تهی، تهی] ب'،' پوچ بی، پوچ، پوچ
["الف"، تهی] "،" بی.ان. خطا
[b'a'، تهی] ب'،' «ن» خطا