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

دوال المصفوفات

معاينة: يخضع Firestore في الوضع الأصلي (مع عمليات Pipeline) لإصدار Enterprise لـ "أحكام العرض لمرحلة ما قبل التوفّر للجمهور العام" في قسم "بنود الخدمة العامة" من بنود الخدمة الخاصة. يمكنك معالجة البيانات الشخصية لهذه الميزة على النحو الموضّح في ملحق معالجة البيانات في خدمات Cloud، وذلك وفقًا للالتزامات والقيود الموضّحة في الاتفاقية التي تتيح لك الوصول إلى Google Cloud. تتوفّر الميزات في مرحلة ما قبل التوفّر للجمهور العام "كما هي"، وقد يقتصر دعمها على نطاق محدود. لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق.

دوال المصفوفات

الاسم	الوصف
`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	صحيح
[[1, 2], [3]]	[1, 2]	صحيح
[1, null]	قيمة فارغة	صحيح
"abc"	أي سعر	خطأ

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 بخلاف ذلك.

أمثلة:

مصفوفة	قيم_البحث	`array_contains_all(array, search_values)`
[1, 2, 3]	[1, 2]	صحيح
[1, 2, 3]	[1, 4]	خطأ
[1, null]	[فارغ]	صحيح
[NaN]	[NaN]	صحيح
[]	[]	صحيح
[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

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 بخلاف ذلك.

أمثلة:

مصفوفة	قيم_البحث	`array_contains_any(array, search_values)`
[1, 2, 3]	[4, 1]	صحيح
[1, 2, 3]	[4, 5]	خطأ
[1, 2, null]	[فارغ]	صحيح

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	غياب
قيمة فارغة	0	غياب
`Array`	"a"	خطأ
`Array`	2.0	خطأ

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]	خطأ
[INT64.MAX_VALUE, 1, -1.0]	خطأ
[INT64.MAX_VALUE, 1.0]	9.223372036854776e+18

الضم

البنية:

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']	","	خطأ
["a", "c"]	b','	خطأ
[b'a', b'c']	","	خطأ

عند تقديم 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'	خطأ
[b'a', null]	b','	"N"	خطأ

دوال المصفوفات تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.