جميع الدوال

تجميع

يمكن استخدام جميع دوال التجميع كتعبيرات ذات مستوى أعلى في مرحلة aggregate(...).

الاسم الوصف
COUNT تعرض هذه الدالة عدد المستندات.
COUNT_IF تعرض هذه الدالة عدد المستندات التي يتم فيها تقييم تعبير على أنّه TRUE
COUNT_DISTINCT تعرض عدد القيم الفريدة غير الفارغة (NULL)
SUM تعرض هذه الدالة مجموع كل قيم NUMERIC
AVERAGE تعرض هذه الدالة متوسط جميع قيم NUMERIC
MINIMUM تعرض الحد الأدنى للقيمة غير NULL
MAXIMUM تعرض القيمة القصوى غير NULL
FIRST تعرض هذه الدالة قيمة expression للمستند الأول.
LAST تعرض قيمة expression للمستند الأخير.
ARRAY_AGG تعرض صفيفًا لجميع قيم الإدخال.
ARRAY_AGG_DISTINCT تعرض مصفوفة لجميع قيم الإدخال المميزة.

COUNT

البنية:

count() -> INT64
count(expression: ANY) -> INT64

الوصف:

تعرض هذه الدالة عدد المستندات من المرحلة السابقة التي يتم فيها تقييم expression على أنّه أي قيمة غير NULL. في حال عدم تقديم expression، يتم عرض إجمالي عدد المستندات من المرحلة السابقة.

Node.js
// Total number of books in the collection
const countOfAll = await db.pipeline()
  .collection("books")
  .aggregate(countAll().as("count"))
  .execute();

// Number of books with nonnull `ratings` field
const countField = await db.pipeline()
  .collection("books")
  .aggregate(field("ratings").count().as("count"))
  .execute();

Web

// Total number of books in the collection
const countOfAll = await execute(db.pipeline()
  .collection("books")
  .aggregate(countAll().as("count"))
);

// Number of books with nonnull `ratings` field
const countField = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("ratings").count().as("count"))
);
Swift
// Total number of books in the collection
let countAll = try await db.pipeline()
  .collection("books")
  .aggregate([CountAll().as("count")])
  .execute()

// Number of books with nonnull `ratings` field
let countField = try await db.pipeline()
  .collection("books")
  .aggregate([Field("ratings").count().as("count")])
  .execute()

Kotlin

// Total number of books in the collection
val countAll = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countAll().alias("count"))
    .execute()

// Number of books with nonnull `ratings` field
val countField = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.count("ratings").alias("count"))
    .execute()

Java

// Total number of books in the collection
Task<Pipeline.Snapshot> countAll = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countAll().alias("count"))
    .execute();

// Number of books with nonnull `ratings` field
Task<Pipeline.Snapshot> countField = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.count("ratings").alias("count"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Count

# Total number of books in the collection
count_all = (
    client.pipeline().collection("books").aggregate(Count().as_("count")).execute()
)

# Number of books with nonnull `ratings` field
count_field = (
    client.pipeline()
    .collection("books")
    .aggregate(Count("ratings").as_("count"))
    .execute()
)
Java
// Total number of books in the collection
Pipeline.Snapshot countAll =
    firestore.pipeline().collection("books").aggregate(countAll().as("count")).execute().get();

// Number of books with nonnull `ratings` field
Pipeline.Snapshot countField =
    firestore
        .pipeline()
        .collection("books")
        .aggregate(count("ratings").as("count"))
        .execute()
        .get();
متابعة
// Total number of books in the collection
countAll, err := client.Pipeline().Collection("books").
	Aggregate(firestore.Accumulators(firestore.CountAll().As("count"))).
	Execute(ctx).Results().GetAll()
if err != nil {
	fmt.Fprintf(w, "GetAll failed: %v", err)
	return err
}

// Number of books with nonnull `ratings` field
countField, err := client.Pipeline().
	Collection("books").
	Aggregate(firestore.Accumulators(firestore.Count("ratings").As("count"))).
	Execute(ctx).Results().GetAll()
if err != nil {
	fmt.Fprintf(w, "GetAll failed: %v", err)
	return err
}

COUNT_IF

البنية:

count_if(expression: BOOLEAN) -> INT64

الوصف:

تعرض هذه الدالة عدد المستندات من المرحلة السابقة التي يكون فيها تقييم expression هو TRUE.

Node.js
const result = await db.pipeline()
  .collection("books")
  .aggregate(
    field("rating").greaterThan(4).countIf().as("filteredCount")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(
    field("rating").greaterThan(4).countIf().as("filteredCount")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([
    AggregateFunction("count_if", [Field("rating").greaterThan(4)]).as("filteredCount")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .aggregate(
        AggregateFunction.countIf(field("rating").greaterThan(4)).alias("filteredCount")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(
        AggregateFunction.countIf(field("rating").greaterThan(4)).alias("filteredCount")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("rating").greater_than(4).count_if().as_("filteredCount"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .aggregate(countIf(field("rating").greaterThan(4)).as("filteredCount"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Aggregate(firestore.Accumulators(
		firestore.CountIf(firestore.FieldOf("rating").GreaterThan(4)).As("filteredCount"),
	)).
	Execute(ctx)

COUNT_DISTINCT

البنية:

count_distinct(expression: ANY) -> INT64

الوصف:

تعرض هذه الدالة عدد القيم الفريدة غير الفارغة وغير الخالية من NULL وABSENT في expression.

Node.js
const result = await db.pipeline()
  .collection("books")
  .aggregate(field("author").countDistinct().as("unique_authors"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("author").countDistinct().as("unique_authors"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([AggregateFunction("count_distinct", [Field("author")]).as("unique_authors")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countDistinct("author").alias("unique_authors"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.countDistinct("author").alias("unique_authors"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("author").count_distinct().as_("unique_authors"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .aggregate(countDistinct("author").as("unique_authors"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Aggregate(firestore.Accumulators(
		firestore.CountDistinct("author").As("unique_authors"),
	)).
	Execute(ctx)

SUM

البنية:

sum(expression: ANY) -> NUMBER

الوصف:

تعرض مجموع كل القيم الرقمية، مع تجاهل القيم غير الرقمية. يتم عرض NaN إذا كانت أي قيم NaN.

سيكون الناتج من النوع نفسه لأوسع نوع إدخال باستثناء الحالات التالية:

  • سيتم تحويل INTEGER إلى DOUBLE إذا تعذّر تمثيله كـ INTEGER.
Node.js
const result = await db.pipeline()
  .collection("cities")
  .aggregate(field("population").sum().as("totalPopulation"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("cities")
  .aggregate(field("population").sum().as("totalPopulation"))
);
Swift
let result = try await db.pipeline()
  .collection("cities")
  .aggregate([Field("population").sum().as("totalPopulation")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.sum("population").alias("totalPopulation"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.sum("population").alias("totalPopulation"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("cities")
    .aggregate(Field.of("population").sum().as_("totalPopulation"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("cities")
        .aggregate(sum("population").as("totalPopulation"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("cities").
	Aggregate(firestore.Accumulators(
		firestore.Sum("population").As("totalPopulation"),
	)).
	Execute(ctx)

AVERAGE

البنية:

average(expression: ANY) -> FLOAT64

الوصف:

تعرض هذه الدالة متوسط جميع القيم الرقمية، مع تجاهل القيم غير الرقمية. يتم تقييمها على أنّها NaN إذا كانت أي قيم هي NaN، أو NULL إذا لم يتم تجميع أي قيم رقمية.

سيكون الناتج من النوع نفسه الذي تم إدخاله باستثناء الحالات التالية:

  • سيتم تحويل INTEGER إلى DOUBLE إذا تعذّر تمثيله كـ INTEGER.
Node.js
const result = await db.pipeline()
  .collection("cities")
  .aggregate(field("population").average().as("averagePopulation"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("cities")
  .aggregate(field("population").average().as("averagePopulation"))
);
Swift
let result = try await db.pipeline()
  .collection("cities")
  .aggregate([Field("population").average().as("averagePopulation")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.average("population").alias("averagePopulation"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("cities")
    .aggregate(AggregateFunction.average("population").alias("averagePopulation"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("cities")
    .aggregate(Field.of("population").average().as_("averagePopulation"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("cities")
        .aggregate(average("population").as("averagePopulation"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("cities").
	Aggregate(firestore.Accumulators(
		firestore.Average("population").As("averagePopulation"),
	)).
	Execute(ctx)

الحد الأدنى

البنية:

minimum(expression: ANY) -> ANY

الوصف:

تعرض الحد الأدنى للقيمة غير الفارغة وغير NULL لـ expression عند تقييمها في كل مستند.

إذا لم تكن هناك قيم غير NULL وغير فارغة، يتم عرض NULL. ويشمل ذلك الحالات التي لا يتم فيها النظر في أي مستندات.

إذا كانت هناك قيم دنيا متكافئة متعددة، يمكن عرض أي من هذه القيم. يتبع ترتيب نوع القيمة الترتيب الموثَّق.

Node.js
const result = await db.pipeline()
  .collection("books")
  .aggregate(field("price").minimum().as("minimumPrice"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").minimum().as("minimumPrice"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([Field("price").minimum().as("minimumPrice")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.minimum("price").alias("minimumPrice"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.minimum("price").alias("minimumPrice"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("price").minimum().as_("minimumPrice"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .aggregate(minimum("price").as("minimumPrice"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Aggregate(firestore.Accumulators(
		firestore.Minimum("price").As("minimumPrice"),
	)).
	Execute(ctx)

الحد الأقصى

البنية:

maximum(expression: ANY) -> ANY

الوصف:

تعرض هذه الدالة الحد الأقصى للقيمة غير الفارغة وغير NULL لـ expression عند تقييمها في كل مستند.

إذا لم تكن هناك قيم غير NULL وغير فارغة، يتم عرض NULL. ويشمل ذلك الحالات التي لا يتم فيها النظر في أي مستندات.

في حال توفّر قيم قصوى متكافئة متعددة، يمكن عرض أيّ منها. يتبع ترتيب نوع القيمة الترتيب الموثَّق.

Node.js
const result = await db.pipeline()
  .collection("books")
  .aggregate(field("price").maximum().as("maximumPrice"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").maximum().as("maximumPrice"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .aggregate([Field("price").maximum().as("maximumPrice")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.maximum("price").alias("maximumPrice"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .aggregate(AggregateFunction.maximum("price").alias("maximumPrice"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("price").maximum().as_("maximumPrice"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .aggregate(maximum("price").as("maximumPrice"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Aggregate(firestore.Accumulators(
		firestore.Maximum("price").As("maximumPrice"),
	)).
	Execute(ctx)

أولاً

البنية:

first(expression: ANY) -> ANY

الوصف:

تعرض هذه الدالة قيمة expression للمستند الأول الذي يتم عرضه.

الأخير

البنية:

last(expression: ANY) -> ANY

الوصف:

تعرض هذه الدالة قيمة expression لآخر مستند تم عرضه.

ARRAY_AGG

البنية:

array_agg(expression: ANY) -> ARRAY<ANY>

الوصف:

تعرض هذه الدالة مصفوفة تحتوي على جميع قيم expression عند تقييمها في كل مستند.

إذا تم تحليل التعبير إلى قيمة غير متوفّرة، يتم تحويله إلى NULL.

ترتيب العناصر في مصفوفة النتائج غير ثابت ولا يجب الاعتماد عليه.

ARRAY_AGG_DISTINCT

البنية:

array_agg_distinct(expression: ANY) -> ARRAY<ANY>

الوصف:

تعرض هذه السمة مصفوفة تحتوي على جميع القيم المميزة لـ expression عند تقييمها في كل مستند.

إذا تم تحليل التعبير إلى قيمة غير متوفّرة، يتم تحويله إلى NULL.

ترتيب العناصر في مصفوفة النتائج غير ثابت ولا يجب الاعتماد عليه.

الدوال الحسابية

تتّبع جميع الدوال الحسابية في Cloud Firestore السلوكيات التالية:

  • يتم تقييمها على أنّها NULL إذا كانت أي من مَعلمات الإدخال هي NULL.
  • يتم تقييمها على أنّها NaN إذا كانت أي من الوسيطات NaN.
  • يؤدي ذلك إلى حدوث خطأ في حال حدوث تجاوز الحد الأقصى أو تجاوز الحد الأدنى.

تنفّذ الدالة Cloud Firestore توسيعًا للنوع الرقمي استنادًا إلى التسلسل الهرمي التالي: INT32 < INT64 < FLOAT64 < DECIMAL128. عندما تأخذ دالة حسابية وسيطات رقمية متعددة من أنواع مختلفة (على سبيل المثال، add(5.0D, 6L))، يتم تحويل الأنواع الأضيق ضمنيًا إلى أوسع نوع موجود بين المعاملات. في المثال السابق، يتم توسيع 6L إلى 6.0D، ما يؤدي إلى عرض التعبير لنوع FLOAT64.

قد يؤدي التحويل الضمني من INT64 إلى FLOAT64 إلى فقدان الدقة لأنّ القيمة التي تم تحويلها قد تفقد وحدات البت الأقل أهمية. ستكون القيمة الناتجة نسخة مقرَّبة من قيمة العدد الصحيح الأصلي باستخدام وضع التقريب إلى أقرب عدد صحيح وفقًا لمعيار IEEE 754.

الاسم الوصف
ABS تعرض القيمة المطلقة لـ number
ADD تعرض قيمة x + y
SUBTRACT تعرض قيمة x - y
MULTIPLY تعرض قيمة x * y
DIVIDE تعرض قيمة x / y
MOD تعرض هذه الدالة باقي قسمة x / y
CEIL تعرض الحد الأقصى لـ number
FLOOR تعرض هذه الدالة الحد الأدنى لـ number
ROUND تقريب number إلى places منزلة عشرية
TRUNC يتم اقتطاع number إلى places من المنازل العشرية
POW تعرض قيمة base^exponent
SQRT تعرض هذه الدالة الجذر التربيعي لـ number
EXP لعرض عدد أويلر مرفوعًا إلى الأُس exponent
LN تعرض هذه الدالة اللوغاريتم الطبيعي لـ number
LOG تعرض لوغاريتم number
LOG10 لعرض لوغاريتم number للأساس 10
RAND تعرض هذه الدالة رقم نقطة عائمة عشوائيًا زائفًا

ABS

البنية:

abs[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](number: N) -> N

الوصف:

تعرض هذه الدالة القيمة المطلقة لـ number.

  • يتم عرض خطأ عندما تتجاوز الدالة قيمة INT32 أو INT64.

أمثلة:

رقم abs(number)
10 10
-10 10
‫10 لتر ‫10 لتر
-0.0 0.0
10.5 10.5
-10.5 10.5
-231 [error]
-263 [error]

إضافة

البنية:

add[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](x: N, y: N) -> N

الوصف:

تعرض قيمة x + y.

أمثلة:

x y add(x, y)
20 3 23
10.0 1 11.0
22.5 2.0 24.5
INT64.MAX 1 [error]
INT64.MIN -1 [error]
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("soldBooks").add(field("unsoldBooks")).as("totalBooks"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("soldBooks").add(field("unsoldBooks")).as("totalBooks"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("soldBooks").add(Field("unsoldBooks")).as("totalBooks")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(Expression.add(field("soldBooks"), field("unsoldBooks")).alias("totalBooks"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.add(field("soldBooks"), field("unsoldBooks")).alias("totalBooks"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("soldBooks").add(Field.of("unsoldBooks")).as_("totalBooks"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(add(field("soldBooks"), field("unsoldBooks")).as("totalBooks"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Add(firestore.FieldOf("soldBooks"), firestore.FieldOf("unsoldBooks")).As("totalBooks"),
	)).
	Execute(ctx)

SUBTRACT

البنية:

subtract[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](x: N, y: N) -> N

الوصف:

تعرض قيمة x - y.

أمثلة:

x y subtract(x, y)
20 3 17
10.0 1 9.0
22.5 2.0 20.5
INT64.MAX -1 [error]
INT64.MIN 1 [error]
Node.js
const storeCredit = 7;
const result = await db.pipeline()
  .collection("books")
  .select(field("price").subtract(constant(storeCredit)).as("totalCost"))
  .execute();

Web

const storeCredit = 7;
const result = await execute(db.pipeline()
  .collection("books")
  .select(field("price").subtract(constant(storeCredit)).as("totalCost"))
);
Swift
let storeCredit = 7
let result = try await db.pipeline()
  .collection("books")
  .select([Field("price").subtract(Constant(storeCredit)).as("totalCost")])
  .execute()

Kotlin

val storeCredit = 7
val result = db.pipeline()
    .collection("books")
    .select(Expression.subtract(field("price"), storeCredit).alias("totalCost"))
    .execute()

Java

int storeCredit = 7;
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.subtract(field("price"), storeCredit).alias("totalCost"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

store_credit = 7
result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("price").subtract(store_credit).as_("totalCost"))
    .execute()
)
Java
int storeCredit = 7;
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(subtract(field("price"), storeCredit).as("totalCost"))
        .execute()
        .get();
متابعة
storeCredit := 7
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Subtract(firestore.FieldOf("price"), storeCredit).As("totalCost"),
	)).
	Execute(ctx)

MULTIPLY

البنية:

multiply[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](x: N, y: N) -> N

الوصف:

تعرض قيمة x * y.

أمثلة:

x y multiply(x, y)
20 3 60
10.0 1 10.0
22.5 2.0 45.0
INT64.MAX 2 [error]
INT64.MIN 2 [error]
FLOAT64.MAX FLOAT64.MAX +inf
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("price").multiply(field("soldBooks")).as("revenue"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("price").multiply(field("soldBooks")).as("revenue"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("price").multiply(Field("soldBooks")).as("revenue")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(Expression.multiply(field("price"), field("soldBooks")).alias("revenue"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.multiply(field("price"), field("soldBooks")).alias("revenue"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("price").multiply(Field.of("soldBooks")).as_("revenue"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(multiply(field("price"), field("soldBooks")).as("revenue"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Multiply(firestore.FieldOf("price"), firestore.FieldOf("soldBooks")).As("revenue"),
	)).
	Execute(ctx)

DIVIDE

البنية:

divide[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](x: N, y: N) -> N

الوصف:

تعرض قيمة x / y. يتم اقتطاع قسمة العدد الصحيح.

أمثلة:

x y divide(x, y)
20 3 6
10.0 3 3.333...
22.5 2 11.25
10 0 [error]
1.0 0.0 +inf
-1.0 0.0 -inf
0.0 0.0 NaN
+inf +inf NaN
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("ratings").divide(field("soldBooks")).as("reviewRate"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("ratings").divide(field("soldBooks")).as("reviewRate"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("ratings").divide(Field("soldBooks")).as("reviewRate")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(Expression.divide(field("ratings"), field("soldBooks")).alias("reviewRate"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.divide(field("ratings"), field("soldBooks")).alias("reviewRate"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("ratings").divide(Field.of("soldBooks")).as_("reviewRate"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(divide(field("ratings"), field("soldBooks")).as("reviewRate"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Divide(firestore.FieldOf("ratings"), firestore.FieldOf("soldBooks")).As("reviewRate"),
	)).
	Execute(ctx)

تعديل

البنية:

mod[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](x: N, y: N) -> N

الوصف:

تعرض هذه الدالة باقي قسمة x / y.

  • يتم عرض error عندما تكون قيمة y صفرًا لأنواع الأعداد الصحيحة (INT64).
  • تعرض هذه الدالة NaN عندما تكون قيمة y صفرًا لأنواع الأعداد العشرية (FLOAT64).

أمثلة:

x y mod(x, y)
20 3 2
-10 3 -1
10 -3 1
-10 -3 -1
10 1 0
22.5 2 0.5
22.5 0.0 NaN
25 0 [error]
Node.js
const displayCapacity = 1000;
const result = await db.pipeline()
  .collection("books")
  .select(field("unsoldBooks").mod(constant(displayCapacity)).as("warehousedBooks"))
  .execute();

Web

const displayCapacity = 1000;
const result = await execute(db.pipeline()
  .collection("books")
  .select(field("unsoldBooks").mod(constant(displayCapacity)).as("warehousedBooks"))
);
Swift
let displayCapacity = 1000
let result = try await db.pipeline()
  .collection("books")
  .select([Field("unsoldBooks").mod(Constant(displayCapacity)).as("warehousedBooks")])
  .execute()

Kotlin

val displayCapacity = 1000
val result = db.pipeline()
    .collection("books")
    .select(Expression.mod(field("unsoldBooks"), displayCapacity).alias("warehousedBooks"))
    .execute()

Java

int displayCapacity = 1000;
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.mod(field("unsoldBooks"), displayCapacity).alias("warehousedBooks"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

display_capacity = 1000
result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("unsoldBooks").mod(display_capacity).as_("warehousedBooks"))
    .execute()
)
Java
int displayCapacity = 1000;
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(mod(field("unsoldBooks"), displayCapacity).as("warehousedBooks"))
        .execute()
        .get();
متابعة
displayCapacity := 1000
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Mod(firestore.FieldOf("unsoldBooks"), displayCapacity).As("warehousedBooks"),
	)).
	Execute(ctx)

CEIL

البنية:

ceil[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](number: N) -> N

الوصف:

تعرض أصغر قيمة عدد صحيح لا تقل عن number.

أمثلة:

رقم ceil(number)
20 20
10 10
0 0
‫24 لتر ‫24 لتر
-0.4 -0.0
0.4 1.0
22.5 23.0
NaN NaN
+inf +inf
-inf -inf
Node.js
const booksPerShelf = 100;
const result = await db.pipeline()
  .collection("books")
  .select(
    field("unsoldBooks").divide(constant(booksPerShelf)).ceil().as("requiredShelves")
  )
  .execute();

Web

const booksPerShelf = 100;
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("unsoldBooks").divide(constant(booksPerShelf)).ceil().as("requiredShelves")
  )
);
Swift
let booksPerShelf = 100
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("unsoldBooks").divide(Constant(booksPerShelf)).ceil().as("requiredShelves")
  ])
  .execute()

Kotlin

val booksPerShelf = 100
val result = db.pipeline()
    .collection("books")
    .select(
        Expression.divide(field("unsoldBooks"), booksPerShelf).ceil().alias("requiredShelves")
    )
    .execute()

Java

int booksPerShelf = 100;
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        Expression.divide(field("unsoldBooks"), booksPerShelf).ceil().alias("requiredShelves")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

books_per_shelf = 100
result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("unsoldBooks")
        .divide(books_per_shelf)
        .ceil()
        .as_("requiredShelves")
    )
    .execute()
)
Java
int booksPerShelf = 100;
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(ceil(divide(field("unsoldBooks"), booksPerShelf)).as("requiredShelves"))
        .execute()
        .get();
متابعة
booksPerShelf := 100
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Ceil(firestore.Divide(firestore.FieldOf("unsoldBooks"), booksPerShelf)).As("requiredShelves"),
	)).
	Execute(ctx)

FLOOR

البنية:

floor[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](number: N) -> N

الوصف:

تعرض أكبر قيمة عدد صحيح لا تزيد عن number.

أمثلة:

رقم floor(number)
20 20
10 10
0 0
2147483648 2147483648
-0.4 -1.0
0.4 0.0
22.5 22.0
NaN NaN
+inf +inf
-inf -inf
Node.js
const result = await db.pipeline()
  .collection("books")
  .addFields(
    field("wordCount").divide(field("pages")).floor().as("wordsPerPage")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .addFields(
    field("wordCount").divide(field("pages")).floor().as("wordsPerPage")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .addFields([
    Field("wordCount").divide(Field("pages")).floor().as("wordsPerPage")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .addFields(
        Expression.divide(field("wordCount"), field("pages")).floor().alias("wordsPerPage")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .addFields(
        Expression.divide(field("wordCount"), field("pages")).floor().alias("wordsPerPage")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .add_fields(
        Field.of("wordCount").divide(Field.of("pages")).floor().as_("wordsPerPage")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .addFields(floor(divide(field("wordCount"), field("pages"))).as("wordsPerPage"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	AddFields(firestore.Selectables(
		firestore.Floor(firestore.Divide(firestore.FieldOf("wordCount"), firestore.FieldOf("pages"))).As("wordsPerPage"),
	)).
	Execute(ctx)

ROUND

البنية:

round[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](number: N) -> N
round[N <: INT32 | INT64 | FLOAT64 | DECIMAL128](number: N, places: INT64) -> N

الوصف:

لتقريب أرقام places من number. يتم تقريب الأرقام من يمين النقطة العشرية إذا كانت قيمة places موجبة، ومن يسار النقطة العشرية إذا كانت سالبة.

  • إذا تم توفير number فقط، يتم التقريب إلى أقرب قيمة صحيحة.
  • يتم التقريب بعيدًا عن الصفر في الحالات التي تقع في المنتصف.
  • يتم عرض error إذا أدى التقريب باستخدام قيمة places سالبة إلى تجاوز الحد الأقصى.

أمثلة:

رقم أماكن round(number, places)
15.5 0 16.0
-15.5 0 -16.0
15 1 15
15 0 15
15 -1 20
15 -2 0
15.48924 1 15.5
231-1 -1 [error]
263-1L -1 [error]
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("soldBooks").multiply(field("price")).round().as("partialRevenue"))
  .aggregate(field("partialRevenue").sum().as("totalRevenue"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("soldBooks").multiply(field("price")).round().as("partialRevenue"))
  .aggregate(field("partialRevenue").sum().as("totalRevenue"))
  );
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("soldBooks").multiply(Field("price")).round().as("partialRevenue")])
  .aggregate([Field("partialRevenue").sum().as("totalRevenue")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(Expression.multiply(field("soldBooks"), field("price")).round().alias("partialRevenue"))
    .aggregate(AggregateFunction.sum("partialRevenue").alias("totalRevenue"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(Expression.multiply(field("soldBooks"), field("price")).round().alias("partialRevenue"))
    .aggregate(AggregateFunction.sum("partialRevenue").alias("totalRevenue"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("soldBooks")
        .multiply(Field.of("price"))
        .round()
        .as_("partialRevenue")
    )
    .aggregate(Field.of("partialRevenue").sum().as_("totalRevenue"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(round(multiply(field("soldBooks"), field("price"))).as("partialRevenue"))
        .aggregate(sum("partialRevenue").as("totalRevenue"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Round(firestore.Multiply(firestore.FieldOf("soldBooks"), firestore.FieldOf("price"))).As("partialRevenue"),
	)).
	Aggregate(firestore.Accumulators(
		firestore.Sum("partialRevenue").As("totalRevenue"),
	)).
	Execute(ctx)

TRUNC

البنية:

trunc[N <: Number](number: N) -> N
trunc[N <: Number](number:  N, places: INT64) -> N

الوصف:

تقتطع هذه الدالة number إلى عدد محدّد من المنازل العشرية في places. يتم اقتطاع الأرقام من يمين النقطة العشرية إذا كانت قيمة places موجبة، ومن يسار النقطة العشرية إذا كانت سالبة.

  • إذا تم توفير number فقط، يتم اقتطاع القيمة إلى أقرب قيمة صحيحة باتجاه الصفر.
  • يتم طرح error إذا أدى الاقتطاع إلى تجاوز السعة.

أمثلة:

رقم أماكن trunc(number, places)
15.5 0 15.0
-15.5 0 -15.0
15 1 15
15 0 15
15 -1 10
15 -2 0
15.48924 1 15.4
-15.48924 2 -15.48

POW

البنية:

pow(base: FLOAT64, exponent: FLOAT64) -> FLOAT64

الوصف:

لعرض القيمة base مرفوعة إلى القوة exponent

  • يتم عرض خطأ إذا كانت قيمة base <= 0 وexponent سالبة.

  • بالنسبة إلى أي exponent (بما في ذلك NaN)، تكون قيمة pow(1, exponent) هي 1.

  • بالنسبة إلى أي base (بما في ذلك NaN)، تكون قيمة pow(base, 0) هي 1.

أمثلة:

قاعدة أساس اللوغاريتم الطبيعي pow(base, exponent)
2 3 8.0
2 -3 0.125
+inf 0 1.0
1 +inf 1.0
NaN 0 1.0
1 NaN 1.0
NaN Numeric NaN
Numeric NaN NaN
-1 0.5 [error]
0 -1 [error]
Node.js
const googleplex = { latitude: 37.4221, longitude: 122.0853 };
const result = await db.pipeline()
  .collection("cities")
  .addFields(
    field("lat").subtract(constant(googleplex.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    field("lng").subtract(constant(googleplex.longitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  )
  .select(
    field("latitudeDifference").add(field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  )
  .execute();

Web

const googleplex = { latitude: 37.4221, longitude: 122.0853 };
const result = await execute(db.pipeline()
  .collection("cities")
  .addFields(
    field("lat").subtract(constant(googleplex.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    field("lng").subtract(constant(googleplex.longitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  )
  .select(
    field("latitudeDifference").add(field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  )
);
Swift
let googleplex = CLLocation(latitude: 37.4221, longitude: 122.0853)
let result = try await db.pipeline()
  .collection("cities")
  .addFields([
    Field("lat").subtract(Constant(googleplex.coordinate.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    Field("lng").subtract(Constant(googleplex.coordinate.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  ])
  .select([
    Field("latitudeDifference").add(Field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  ])
  .execute()

Kotlin

val googleplex = GeoPoint(37.4221, -122.0853)
val result = db.pipeline()
    .collection("cities")
    .addFields(
        field("lat").subtract(googleplex.latitude)
            .multiply(111) // km per degree
            .pow(2)
            .alias("latitudeDifference"),
        field("lng").subtract(googleplex.longitude)
            .multiply(111) // km per degree
            .pow(2)
            .alias("longitudeDifference")
    )
    .select(
        field("latitudeDifference").add(field("longitudeDifference")).sqrt()
            // Inaccurate for large distances or close to poles
            .alias("approximateDistanceToGoogle")
    )
    .execute()

Java

GeoPoint googleplex = new GeoPoint(37.4221, -122.0853);
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("cities")
    .addFields(
        field("lat").subtract(googleplex.getLatitude())
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("latitudeDifference"),
        field("lng").subtract(googleplex.getLongitude())
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("longitudeDifference")
    )
    .select(
        field("latitudeDifference").add(field("longitudeDifference")).sqrt()
            // Inaccurate for large distances or close to poles
            .alias("approximateDistanceToGoogle")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

googleplexLat = 37.4221
googleplexLng = -122.0853
result = (
    client.pipeline()
    .collection("cities")
    .add_fields(
        Field.of("lat")
        .subtract(googleplexLat)
        .multiply(111)  # km per degree
        .pow(2)
        .as_("latitudeDifference"),
        Field.of("lng")
        .subtract(googleplexLng)
        .multiply(111)  # km per degree
        .pow(2)
        .as_("longitudeDifference"),
    )
    .select(
        Field.of("latitudeDifference")
        .add(Field.of("longitudeDifference"))
        .sqrt()
        # Inaccurate for large distances or close to poles
        .as_("approximateDistanceToGoogle")
    )
    .execute()
)
Java
double googleplexLat = 37.4221;
double googleplexLng = -122.0853;
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("cities")
        .addFields(
            pow(multiply(subtract(field("lat"), googleplexLat), 111), 2)
                .as("latitudeDifference"),
            pow(multiply(subtract(field("lng"), googleplexLng), 111), 2)
                .as("longitudeDifference"))
        .select(
            sqrt(add(field("latitudeDifference"), field("longitudeDifference")))
                // Inaccurate for large distances or close to poles
                .as("approximateDistanceToGoogle"))
        .execute()
        .get();
متابعة
googleplexLat := 37.4221
googleplexLng := -122.0853
snapshot := client.Pipeline().
	Collection("cities").
	AddFields(firestore.Selectables(
		firestore.Pow(firestore.Multiply(firestore.Subtract(firestore.FieldOf("lat"), googleplexLat), 111), 2).As("latitudeDifference"),
		firestore.Pow(firestore.Multiply(firestore.Subtract(firestore.FieldOf("lng"), googleplexLng), 111), 2).As("longitudeDifference"),
	)).
	Select(firestore.Fields(
		firestore.Sqrt(firestore.Add(firestore.FieldOf("latitudeDifference"), firestore.FieldOf("longitudeDifference"))).
			// Inaccurate for large distances or close to poles
			As("approximateDistanceToGoogle"),
	)).
	Execute(ctx)

SQRT

البنية:

sqrt[N <: FLOAT64 | DECIMAL128](number: N) -> N

الوصف:

تعرض هذه الدالة الجذر التربيعي لـ number.

  • يتم عرض error إذا كانت قيمة number سالبة.

أمثلة:

رقم sqrt(number)
25 5.0
12.002 3.464...
0.0 0.0
NaN NaN
+inf +inf
-inf [error]
x < 0 [error]
Node.js
const googleplex = { latitude: 37.4221, longitude: 122.0853 };
const result = await db.pipeline()
  .collection("cities")
  .addFields(
    field("lat").subtract(constant(googleplex.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    field("lng").subtract(constant(googleplex.longitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  )
  .select(
    field("latitudeDifference").add(field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  )
  .execute();

Web

const googleplex = { latitude: 37.4221, longitude: 122.0853 };
const result = await execute(db.pipeline()
  .collection("cities")
  .addFields(
    field("lat").subtract(constant(googleplex.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    field("lng").subtract(constant(googleplex.longitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  )
  .select(
    field("latitudeDifference").add(field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  )
);
Swift
let googleplex = CLLocation(latitude: 37.4221, longitude: 122.0853)
let result = try await db.pipeline()
  .collection("cities")
  .addFields([
    Field("lat").subtract(Constant(googleplex.coordinate.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("latitudeDifference"),
    Field("lng").subtract(Constant(googleplex.coordinate.latitude))
      .multiply(111 /* km per degree */)
      .pow(2)
      .as("longitudeDifference")
  ])
  .select([
    Field("latitudeDifference").add(Field("longitudeDifference")).sqrt()
      // Inaccurate for large distances or close to poles
      .as("approximateDistanceToGoogle")
  ])
  .execute()

Kotlin

val googleplex = GeoPoint(37.4221, -122.0853)
val result = db.pipeline()
    .collection("cities")
    .addFields(
        field("lat").subtract(googleplex.latitude)
            .multiply(111) // km per degree
            .pow(2)
            .alias("latitudeDifference"),
        field("lng").subtract(googleplex.longitude)
            .multiply(111) // km per degree
            .pow(2)
            .alias("longitudeDifference")
    )
    .select(
        field("latitudeDifference").add(field("longitudeDifference")).sqrt()
            // Inaccurate for large distances or close to poles
            .alias("approximateDistanceToGoogle")
    )
    .execute()

Java

GeoPoint googleplex = new GeoPoint(37.4221, -122.0853);
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("cities")
    .addFields(
        field("lat").subtract(googleplex.getLatitude())
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("latitudeDifference"),
        field("lng").subtract(googleplex.getLongitude())
            .multiply(111 /* km per degree */)
            .pow(2)
            .alias("longitudeDifference")
    )
    .select(
        field("latitudeDifference").add(field("longitudeDifference")).sqrt()
            // Inaccurate for large distances or close to poles
            .alias("approximateDistanceToGoogle")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

googleplexLat = 37.4221
googleplexLng = -122.0853
result = (
    client.pipeline()
    .collection("cities")
    .add_fields(
        Field.of("lat")
        .subtract(googleplexLat)
        .multiply(111)  # km per degree
        .pow(2)
        .as_("latitudeDifference"),
        Field.of("lng")
        .subtract(googleplexLng)
        .multiply(111)  # km per degree
        .pow(2)
        .as_("longitudeDifference"),
    )
    .select(
        Field.of("latitudeDifference")
        .add(Field.of("longitudeDifference"))
        .sqrt()
        # Inaccurate for large distances or close to poles
        .as_("approximateDistanceToGoogle")
    )
    .execute()
)
Java
double googleplexLat = 37.4221;
double googleplexLng = -122.0853;
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("cities")
        .addFields(
            pow(multiply(subtract(field("lat"), googleplexLat), 111), 2)
                .as("latitudeDifference"),
            pow(multiply(subtract(field("lng"), googleplexLng), 111), 2)
                .as("longitudeDifference"))
        .select(
            sqrt(add(field("latitudeDifference"), field("longitudeDifference")))
                // Inaccurate for large distances or close to poles
                .as("approximateDistanceToGoogle"))
        .execute()
        .get();
متابعة
googleplexLat := 37.4221
googleplexLng := -122.0853
snapshot := client.Pipeline().
	Collection("cities").
	AddFields(firestore.Selectables(
		firestore.Pow(firestore.Multiply(firestore.Subtract(firestore.FieldOf("lat"), googleplexLat), 111), 2).As("latitudeDifference"),
		firestore.Pow(firestore.Multiply(firestore.Subtract(firestore.FieldOf("lng"), googleplexLng), 111), 2).As("longitudeDifference"),
	)).
	Select(firestore.Fields(
		firestore.Sqrt(firestore.Add(firestore.FieldOf("latitudeDifference"), firestore.FieldOf("longitudeDifference"))).
			// Inaccurate for large distances or close to poles
			As("approximateDistanceToGoogle"),
	)).
	Execute(ctx)

EXP

البنية:

exp(exponent: FLOAT64) -> FLOAT64

الوصف:

تعرض هذه الدالة قيمة عدد أويلر مرفوعة إلى الأس exponent، وتُعرف أيضًا باسم الدالة الأسية الطبيعية.

أمثلة:

أساس اللوغاريتم الطبيعي exp(exponent)
0.0 1.0
10 e^10 (FLOAT64)
NaN NaN
+inf +inf
-inf 0
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").exp().as("expRating"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").exp().as("expRating"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").exp().as("expRating")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("rating").exp().alias("expRating"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").exp().alias("expRating"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").exp().as_("expRating"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(exp(field("rating")).as("expRating"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Exp(firestore.FieldOf("rating")).As("expRating"),
	)).
	Execute(ctx)

LN

البنية:

ln(number: FLOAT64) -> FLOAT64

الوصف:

تعرض اللوغاريتم الطبيعي لـ number. هذه الدالة مكافئة لـ log(number).

أمثلة:

رقم ln(number)
1 0.0
‫2 لتر 0.693...
1.0 0.0
e (FLOAT64) 1.0
NaN NaN
-inf NaN
+inf +inf
x <= 0 [error]
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").ln().as("lnRating"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").ln().as("lnRating"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").ln().as("lnRating")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("rating").ln().alias("lnRating"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").ln().alias("lnRating"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").ln().as_("lnRating"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(ln(field("rating")).as("lnRating"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Ln(firestore.FieldOf("rating")).As("lnRating"),
	)).
	Execute(ctx)

LOG

البنية:

log(number: FLOAT64, base: FLOAT64) -> FLOAT64
log(number: FLOAT64) -> FLOAT64

الوصف:

تعرض لوغاريتم number للأساس base.

  • إذا تم تقديم number فقط، يتم عرض اللوغاريتم لـ number إلى base (مرادف لـ ln(number)).

أمثلة:

رقم قاعدة log(number, base)
100 10 2.0
NaN Numeric NaN
Numeric NaN NaN
-inf Numeric NaN
Numeric. +inf NaN
number <= 0 Numeric [error]
Numeric base <= 0 [error]
Numeric 1.0 [error]

LOG10

البنية:

log10(x: FLOAT64) -> FLOAT64

الوصف:

لعرض لوغاريتم number للأساس 10.

أمثلة:

رقم log10(number)
100 2.0
NaN NaN
-inf NaN
+inf +inf
x <= 0 [error]

RAND

البنية:

rand() -> FLOAT64

الوصف:

عرض رقم نقطة عائمة عشوائي زائف، يتم اختياره بشكل موحّد بين 0.0 (شامل) و1.0 (غير شامل).

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

الاسم الوصف
ARRAY تعرض هذه الدالة ARRAY يحتوي على عنصر واحد لكل وسيطة إدخال
ARRAY_CONCAT تدمج هذه الدالة مصفوفات متعددة في مصفوفة واحدة من النوع ARRAY
ARRAY_CONTAINS تعرض هذه الدالة TRUE إذا كانت السمة ARRAY المحدّدة تحتوي على قيمة معيّنة
ARRAY_CONTAINS_ALL تعرض هذه الدالة TRUE إذا كانت جميع القيم متوفّرة في ARRAY
ARRAY_CONTAINS_ANY تعرض هذه الدالة TRUE إذا كانت أي من القيم متوفّرة في ARRAY
ARRAY_FILTER تتم فلترة العناصر من ARRAY التي لا تستوفي شرطًا معيّنًا
ARRAY_FIRST تعرض هذه الدالة العنصر الأول في ARRAY
ARRAY_FIRST_N تعرض هذه الدالة أول عناصر n في ARRAY
ARRAY_GET لعرض العنصر في فهرس معيّن في ARRAY
ARRAY_INDEX_OF تعرض هذه الدالة فهرس أول ظهور لقيمة في ARRAY
ARRAY_INDEX_OF_ALL تعرض هذه الدالة جميع فهارس قيمة معيّنة في ARRAY
ARRAY_LENGTH تعرض عدد العناصر في ARRAY
ARRAY_LAST تعرض هذه الدالة العنصر الأخير في ARRAY
ARRAY_LAST_N تعرض هذه الدالة آخر عناصر n في ARRAY
ARRAY_REVERSE لعكس ترتيب العناصر في ARRAY
ARRAY_SLICE تعرض جزءًا من ARRAY
ARRAY_TRANSFORM تحوّل العناصر في ARRAY من خلال تطبيق تعبير على كل عنصر
MAXIMUM تعرض هذه الدالة الحد الأقصى للقيمة في ARRAY
MAXIMUM_N تعرض أكبر قيم عددها n في ARRAY
MINIMUM تعرض الحد الأدنى للقيمة في ARRAY
MINIMUM_N تعرض أصغر قيم عددها n في 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]
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("genre").arrayConcat([field("subGenre")]).as("allGenres"))
  .execute();
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("genre").arrayConcat([Field("subGenre")]).as("allGenres")])
  .execute()

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayConcat(field("subGenre")).alias("allGenres"))
    .execute();
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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayConcat(field("genre"), field("subGenre")).as("allGenres"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayConcat(firestore.FieldOf("genre"), firestore.FieldOf("subGenre")).As("allGenres"),
	)).
	Execute(ctx)

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" أي سعر خطأ
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("genre").arrayContains(constant("mystery")).as("isMystery"))
  .execute();

Web

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

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("genre").arrayContains("mystery").alias("isMystery"))
    .execute();
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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayContains(field("genre"), "mystery").as("isMystery"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayContains(firestore.FieldOf("genre"), "mystery").As("isMystery"),
	)).
	Execute(ctx)

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] صحيح
[1, 2, 3] [1, 4] خطأ
[1, null] [فارغ] صحيح
[NaN] [NaN] صحيح
[] [] صحيح
[1, 2, 3] [] صحيح
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAll([constant("fantasy"), constant("adventure")])
      .as("isFantasyAdventure")
  )
  .execute();

Web

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

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAll(Arrays.asList("fantasy", "adventure"))
            .alias("isFantasyAdventure")
    )
    .execute();
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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            arrayContainsAll(field("genre"), Arrays.asList("fantasy", "adventure"))
                .as("isFantasyAdventure"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayContainsAll(firestore.FieldOf("genre"), []string{"fantasy", "adventure"}).As("isFantasyAdventure"),
	)).
	Execute(ctx)

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] صحيح
[1, 2, 3] [4, 5] خطأ
[1, 2, null] [فارغ] صحيح
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("genre")
      .arrayContainsAny([constant("fantasy"), constant("nonfiction")])
      .as("isMysteryOrFantasy")
  )
  .execute();

Web

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

Kotlin

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

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre")
            .arrayContainsAny(Arrays.asList("fantasy", "nonfiction"))
            .alias("isMysteryOrFantasy")
    )
    .execute();
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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            arrayContainsAny(field("genre"), Arrays.asList("fantasy", "nonfiction"))
                .as("isMysteryOrFantasy"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayContainsAny(firestore.FieldOf("genre"), []string{"fantasy", "nonfiction"}).As("isMysteryOrFantasy"),
	)).
	Execute(ctx)

ARRAY_FILTER

البنية:

array_filter(array: ARRAY, predicate: (ANY) -> BOOLEAN) -> ARRAY

الوصف:

تتم فلترة array باستخدام تعبير predicate، ما يؤدي إلى عرض مصفوفة جديدة تحتوي فقط على العناصر التي تستوفي الشرط.

  • يتم تقييم predicate لكل عنصر في array. إذا كانت النتيجة true، يتم تضمين العنصر في النتيجة، وإلا (إذا كانت النتيجة false أو null)، يتم حذفه.
  • إذا تم تقييم predicate على أنّه قيمة غير منطقية أو غير فارغة، ستعرض الدالة خطأ.

أمثلة:

مصفوفة predicate array_filter(array, predicate)
[1, 2, 3] x -> x > 1 [2, 3]
[1, null, 3] x -> x > 1 [3]
["a", "b", "c"] x -> x != "b" ["a", "c"]
[] x -> true []

ARRAY_GET

البنية:

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

الوصف:

تعرض هذه الدالة العنصر في index المستند إلى 0 في array.

  • إذا كانت قيمة index سالبة، يتم الوصول إلى العناصر من نهاية المصفوفة، حيث يكون -1 هو العنصر الأخير.
  • إذا لم تكن السمة array من النوع ARRAY وليست null، يتم عرض خطأ.
  • إذا كانت قيمة 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
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("genre").arrayLength().as("genreCount"))
  .execute();

Web

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

Kotlin

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

Java

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

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_length().as_("genreCount"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayLength(field("genre")).as("genreCount"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayLength(firestore.FieldOf("genre")).As("genreCount"),
	)).
	Execute(ctx)

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]
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(arrayReverse(field("genre")).as("reversedGenres"))
  .execute();

Web

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

Kotlin

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

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

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("genre").array_reverse().as_("reversedGenres"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(arrayReverse(field("genre")).as("reversedGenres"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayReverse(firestore.FieldOf("genre")).As("reversedGenres"),
	)).
	Execute(ctx)

ARRAY_FIRST

البنية:

array_first(array: ARRAY) -> ANY

الوصف:

تعرض هذه الدالة العنصر الأول في array. يعادل هذا المبلغ array_get(array, 0).

  • إذا كانت السمة array فارغة، يتم عرض قيمة غير متوفّرة.

أمثلة:

مصفوفة array_first(array)
[1, 2, 3] 1
[] غائب

ARRAY_FIRST_N

البنية:

array_first_n(array: ARRAY, n: INT64) -> ARRAY

الوصف:

تعرض هذه الدالة أول عناصر n من array. يعادل هذا المبلغ array_slice(array, 0, n).

  • إذا كانت قيمة n سالبة، يتم عرض خطأ.

أمثلة:

مصفوفة n array_first_n(array, n)
[1, 2, 3, 4, 5] 3 [1, 2, 3]
[1, 2] 3 [1, 2]
[1, 2, 3] 0 []

ARRAY_INDEX_OF

البنية:

array_index_of(array: ARRAY, value: ANY) -> INT64

الوصف:

تعرض هذه الدالة الفهرس الذي يبدأ من 0 لأول تكرار لـ value في array. تعرض الدالة ‎-1 إذا لم يتم العثور على value.

أمثلة:

مصفوفة القيمة array_index_of(array, value)
[1, 2, 3, 2] 2 1
[1, 2, 3] 4 -1
[1, null, 3] قيمة فارغة 1

ARRAY_INDEX_OF_ALL

البنية:

array_index_of_all(array: ARRAY, value: ANY) -> ARRAY<INT64>

الوصف:

تعرض هذه الدالة مصفوفة تحتوي على الفهارس المستندة إلى الصفر لجميع تكرارات value في array. تعرض هذه الدالة [] في حال عدم العثور على value.

أمثلة:

مصفوفة القيمة array_index_of_all(array, value)
[1, 2, 3, 2] 2 [1, 3]
[1, 2, 3] 4 []
[1, null, 3, null] قيمة فارغة [1, 3]

ARRAY_LAST

البنية:

array_last(array: ARRAY) -> ANY

الوصف:

تعرض هذه الدالة العنصر الأخير في array. يعادل هذا المبلغ array_get(array, -1).

  • إذا كانت السمة array فارغة، يتم عرض قيمة غير متوفّرة.

أمثلة:

مصفوفة array_last(array)
[1, 2, 3] 3
[] غائب

ARRAY_LAST_N

البنية:

array_last_n(array: ARRAY, n: INT64) -> ARRAY

الوصف:

تعرض هذه الدالة آخر عناصر n من array.

  • إذا كانت قيمة n سالبة، يتم عرض خطأ.

أمثلة:

مصفوفة n array_last_n(array, n)
[1, 2, 3, 4, 5] 3 [3, 4, 5]
[1, 2] 3 [1, 2]
[1, 2, 3] 0 []

ARRAY_SLICE

البنية:

array_slice(array: ARRAY, offset: INT64, length: INT64) -> ARRAY

الوصف:

تعرض هذه الدالة مجموعة فرعية من array تبدأ من الفهرس offset الذي يبدأ من 0، وتتضمّن عناصر length.

  • إذا كانت قيمة offset سالبة، تشير إلى موضع البدء من نهاية الصفيفة، مع كون -1 هو العنصر الأخير.
  • إذا كانت قيمة length أكبر من عدد العناصر المتبقية في الصفيفة بعد offset، تمتد النتيجة إلى نهاية الصفيفة.
  • يجب أن تكون قيمة length غير سالبة، وإلا ستعرض الدالة خطأ.

أمثلة:

مصفوفة اقتطاع الطول array_slice(array, offset, length)
[1, 2, 3, 4, 5] 1 3 [2, 3, 4]
[1, 2, 3, 4, 5] -2 2 [4, 5]
[1, 2, 3] 1 5 [2, 3]
[1, 2, 3] 3 2 []

ARRAY_TRANSFORM

البنية:

array_transform(array: ARRAY, expression: (ANY) -> ANY) -> ARRAY
array_transform(array: ARRAY, expression: (ANY, INT64) -> ANY) -> ARRAY

الوصف:

تحوّل هذه الدالة array من خلال تطبيق expression على كل عنصر، وتعرض صفيفًا جديدًا يتضمّن العناصر المحوَّلة. ستكون مصفوفة الإخراج دائمًا بالحجم نفسه لمصفوفة الإدخال.

  • يمكن أن تكون الدالة expression دالة أحادية element -> result أو دالة ثنائية (element, index) -> result.
  • إذا كانت الدالة expression أحادية، يتم استدعاؤها مع كل عنصر من عناصر array.
  • إذا كانت الدالة expression ثنائية، يتم استدعاؤها مع كل عنصر من عناصر array وفهرسه المقابل الذي يستند إلى 0.

أمثلة:

مصفوفة تعبير array_transform(array, expression)
[1, 2, 3] x -> x * 2 [2, 4, 6]
[1, 2, 3] x -> x + 1 [2, 3, 4]
[10, 20] (x, i) -> x + i [10, 21]
[] x -> 1 []

الحد الأقصى

البنية:

maximum(array: ARRAY) -> ANY

الوصف:

تعرض هذه الدالة القيمة القصوى في array.

  • يتم تجاهل قيم NULL أثناء المقارنة.
  • إذا كانت السمة array فارغة أو تحتوي على قيم NULL فقط، يتم عرض NULL.

أمثلة:

مصفوفة maximum(array)
[1, 5, 2] 5
[1, null, 5] 5
["a", "c", "b"] "c"
[null, null] قيمة فارغة
[] قيمة فارغة

MAXIMUM_N

البنية:

maximum_n(array: ARRAY, n: INT64) -> ARRAY

الوصف:

تعرض مصفوفة من أكبر قيم عددها n في array بترتيب تنازلي.

  • يتم تجاهل قيم NULL.
  • إذا كانت قيمة n سالبة، يتم عرض خطأ.

أمثلة:

مصفوفة n maximum_n(array, n)
[1, 5, 2, 4, 3] 3 [5, 4, 3]
[1, null, 5] 3 [5, 1]

الحد الأدنى

البنية:

minimum(array: ARRAY) -> ANY

الوصف:

تعرض هذه الدالة الحد الأدنى للقيمة في array.

  • يتم تجاهل قيم NULL أثناء المقارنة.
  • إذا كانت السمة array فارغة أو تحتوي على قيم NULL فقط، يتم عرض NULL.

أمثلة:

مصفوفة minimum(array)
[1, 5, 2] 1
[5, null, 1] 1
["a", "c", "b"] "a"
[null, null] قيمة فارغة
[] قيمة فارغة

MINIMUM_N

البنية:

minimum_n(array: ARRAY, n: INT64) -> ARRAY

الوصف:

تعرض مصفوفة من أصغر قيم عددها n في array بترتيب تصاعدي.

  • يتم تجاهل قيم NULL.
  • إذا كانت قيمة n سالبة، يتم عرض خطأ.

أمثلة:

مصفوفة n minimum_n(array, n)
[1, 5, 2, 4, 3] 3 [1, 2, 3]
[5, null, 1] 3 [1, 5]

SUM

البنية:

sum(array: ARRAY) -> INT64 | FLOAT64

الوصف:

تعرض هذه الدالة مجموع كل قيم NUMERIC في ARRAY.

  • يتم تجاهل القيم غير الرقمية في الصفيفة.
  • إذا كانت أي قيمة رقمية في الصفيف هي NaN، ستعرض الدالة NaN.
  • يتم تحديد نوع القيمة التي تم إرجاعها من خلال أكبر نوع رقمي في الصفيفة: INT64 < FLOAT64.
  • في حال حدوث تجاوز سعة لعدد صحيح من 64 بت قبل جمع أي قيمة نقطة عائمة، يتم عرض خطأ. إذا تم جمع قيم النقطة العائمة، سيؤدي التجاوز إلى +/- ما لا نهاية.
  • إذا لم تحتوِ المصفوفة على أي قيم رقمية على الإطلاق، ستعرض الدالة NULL.

أمثلة:

مصفوفة sum(array)
[1, 2, 3] ‫6 لتر
[1L, 2L, 3L] ‫6 لتر
[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" خطأ

دوال المقارنة

الاسم الوصف
EQUAL مقارنة المساواة
GREATER_THAN مقارنة "أكبر من"
GREATER_THAN_OR_EQUAL مقارنة أكبر من أو يساوي
LESS_THAN مقارنة "أقل من"
LESS_THAN_OR_EQUAL مقارنة أقل من أو يساوي
NOT_EQUAL مقارنة "لا يساوي"
CMP مقارنة عامة

EQUAL

البنية:

equal(x: ANY, y: ANY) -> BOOLEAN

أمثلة:

x y equal(x, y)
1 لتر 1 لتر TRUE
1.0 1 لتر TRUE
-1.0 1 لتر FALSE
NaN NaN TRUE
NULL NULL TRUE
NULL ABSENT FALSE

الوصف:

تعرض هذه الدالة TRUE إذا كان x وy متساويَين، وFALSE في الحالات الأخرى.

Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").equal(5).as("hasPerfectRating"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").equal(5).as("hasPerfectRating"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").equal(5).as("hasPerfectRating")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("rating").equal(5).alias("hasPerfectRating"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").equal(5).alias("hasPerfectRating"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").equal(5).as_("hasPerfectRating"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(equal(field("rating"), 5).as("hasPerfectRating"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Equal(firestore.FieldOf("rating"), 5).As("hasPerfectRating"),
	)).
	Execute(ctx)

GREATER_THAN

البنية:

greater_than(x: ANY, y: ANY) -> BOOLEAN

الوصف:

تعرض هذه الدالة TRUE إذا كانت قيمة x أكبر من y، وتعرض FALSE في الحالات الأخرى.

إذا لم تكن x وy قابلة للمقارنة، يتم عرض FALSE.

أمثلة:

x y greater_than(x, y)
1 لتر 0.0 TRUE
1 لتر 1 لتر FALSE
1 لتر ‫2 لتر FALSE
"foo" 0 لتر FALSE
0 لتر "foo" FALSE
NaN 0 لتر FALSE
0 لتر NaN FALSE
NULL NULL FALSE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").greaterThan(4).as("hasHighRating"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").greaterThan(4).as("hasHighRating"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").greaterThan(4).as("hasHighRating")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("rating").greaterThan(4).alias("hasHighRating"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").greaterThan(4).alias("hasHighRating"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").greater_than(4).as_("hasHighRating"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(greaterThan(field("rating"), 4).as("hasHighRating"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.GreaterThan(firestore.FieldOf("rating"), 4).As("hasHighRating"),
	)).
	Execute(ctx)

GREATER_THAN_OR_EQUAL

البنية:

greater_than_or_equal(x: ANY, y: ANY) -> BOOLEAN

الوصف:

تعرض هذه الدالة TRUE إذا كانت قيمة x أكبر من أو تساوي y، وتعرض FALSE في الحالات الأخرى.

إذا لم تكن x وy قابلة للمقارنة، يتم عرض FALSE.

أمثلة:

x y greater_than_or_equal(x, y)
1 لتر 0.0 TRUE
1 لتر 1 لتر TRUE
1 لتر ‫2 لتر FALSE
"foo" 0 لتر FALSE
0 لتر "foo" FALSE
NaN 0 لتر FALSE
0 لتر NaN FALSE
NULL NULL TRUE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("published").greaterThanOrEqual(1900).as("publishedIn20thCentury"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("published").greaterThanOrEqual(1900).as("publishedIn20thCentury"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("published").greaterThanOrEqual(1900).as("publishedIn20thCentury")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("published").greaterThanOrEqual(1900).alias("publishedIn20thCentury"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("published").greaterThanOrEqual(1900).alias("publishedIn20thCentury"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("published")
        .greater_than_or_equal(1900)
        .as_("publishedIn20thCentury")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(greaterThanOrEqual(field("published"), 1900).as("publishedIn20thCentury"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.GreaterThanOrEqual(firestore.FieldOf("published"), 1900).As("publishedIn20thCentury"),
	)).
	Execute(ctx)

LESS_THAN

البنية:

less_than(x: ANY, y: ANY) -> BOOLEAN

الوصف:

تعرض هذه الدالة TRUE إذا كانت قيمة x أقل من y، وتعرض FALSE في الحالات الأخرى.

إذا لم تكن x وy قابلة للمقارنة، يتم عرض FALSE.

أمثلة:

x y less_than(x, y)
1 لتر 0.0 FALSE
1 لتر 1 لتر FALSE
1 لتر ‫2 لتر TRUE
"foo" 0 لتر FALSE
0 لتر "foo" FALSE
NaN 0 لتر FALSE
0 لتر NaN FALSE
NULL NULL FALSE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("published").lessThan(1923).as("isPublicDomainProbably"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("published").lessThan(1923).as("isPublicDomainProbably"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("published").lessThan(1923).as("isPublicDomainProbably")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("published").lessThan(1923).alias("isPublicDomainProbably"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("published").lessThan(1923).alias("isPublicDomainProbably"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("published").less_than(1923).as_("isPublicDomainProbably"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(lessThan(field("published"), 1923).as("isPublicDomainProbably"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.LessThan(firestore.FieldOf("published"), 1923).As("isPublicDomainProbably"),
	)).
	Execute(ctx)

LESS_THAN_OR_EQUAL

البنية:

less_than_or_equal(x: ANY, y: ANY) -> BOOLEAN

الوصف:

تعرض هذه الدالة TRUE إذا كانت قيمة x أقل من أو تساوي y، وتعرض FALSE في الحالات الأخرى.

إذا لم تكن x وy قابلة للمقارنة، يتم عرض FALSE.

أمثلة:

x y less_than(x, y)
1 لتر 0.0 FALSE
1 لتر 1 لتر TRUE
1 لتر ‫2 لتر TRUE
"foo" 0 لتر FALSE
0 لتر "foo" FALSE
NaN 0 لتر FALSE
0 لتر NaN FALSE
NULL NULL TRUE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").lessThanOrEqual(2).as("hasBadRating"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").lessThanOrEqual(2).as("hasBadRating"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").lessThanOrEqual(2).as("hasBadRating")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("rating").lessThanOrEqual(2).alias("hasBadRating"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").lessThanOrEqual(2).alias("hasBadRating"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").less_than_or_equal(2).as_("hasBadRating"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(lessThanOrEqual(field("rating"), 2).as("hasBadRating"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.LessThanOrEqual(firestore.FieldOf("rating"), 2).As("hasBadRating"),
	)).
	Execute(ctx)

NOT_EQUAL

البنية:

not_equal(x: ANY, y: ANY) -> BOOLEAN

الوصف:

تعرض هذه الدالة TRUE إذا لم تكن قيمة x مساوية لـ y، وتعرض FALSE في الحالات الأخرى.

أمثلة:

x y not_equal(x, y)
1 لتر 1 لتر FALSE
1.0 1 لتر FALSE
-1.0 1 لتر TRUE
NaN 0 لتر TRUE
NaN NaN FALSE
NULL NULL FALSE
NULL ABSENT TRUE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("title").notEqual("1984").as("not1984"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("title").notEqual("1984").as("not1984"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("title").notEqual("1984").as("not1984")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("title").notEqual("1984").alias("not1984"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("title").notEqual("1984").alias("not1984"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("title").not_equal("1984").as_("not1984"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(notEqual(field("title"), "1984").as("not1984"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.NotEqual(firestore.FieldOf("title"), "1984").As("not1984"),
	)).
	Execute(ctx)

CMP

البنية:

cmp(x: ANY, y: ANY) -> Int64

الوصف:

تقارن بين x وy، وتعرض:

  • ‫1L إذا كان x أكبر من y.
  • ‫-1L إذا كان x أقل من y
  • و0L في الحالات الأخرى.

على عكس دوال المقارنة الأخرى، تعمل الدالة cmp(...) على مستوى الأنواع، باتّباع الترتيب نفسه المستخدَم في مرحلة sort(...). يمكنك الاطّلاع على ترتيب نوع القيمة لمعرفة كيفية ترتيب القيم على مستوى الأنواع.

أمثلة:

x y cmp(x, y)
1 لتر 1 لتر 0 لتر
1.0 1 لتر 0 لتر
-1.0 1 لتر -1L
‫42.5D "foo" -1L
NULL NULL 0 لتر
NULL ABSENT 0 لتر

دوال تصحيح الأخطاء

الاسم الوصف
EXISTS تعرض هذه الدالة TRUE إذا لم تكن القيمة غير متوفّرة
IS_ABSENT تعرض الدالة TRUE إذا كانت القيمة غير متوفّرة
IF_ABSENT تستبدل القيمة بتعبير إذا كانت غير متوفّرة
IS_ERROR يرصد الأخطاء ويتحقّق مما إذا كان التعبير الأساسي قد تسبّب في حدوث خطأ
IF_ERROR تستبدل القيمة بتعبير إذا عرضت خطأً
ERROR لإنهاء التقييم وعرض خطأ مع الرسالة المحدّدة

EXISTS

البنية:

exists(value: ANY) -> BOOLEAN

الوصف:

تعرض هذه الدالة TRUE إذا لم تكن قيمة value غير متوفّرة.

أمثلة:

value exists(value)
0 لتر TRUE
"foo" TRUE
NULL TRUE
ABSENT FALSE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("rating").exists().as("hasRating"))
  .execute();

Web

مثال:

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("rating").exists().as("hasRating"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("rating").exists().as("hasRating")])
  .execute()

Kotlin

مثال:

val result = db.pipeline()
    .collection("books")
    .select(field("rating").exists().alias("hasRating"))
    .execute()

Java

مثال:

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("rating").exists().alias("hasRating"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").exists().as_("hasRating"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(exists(field("rating")).as("hasRating"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.FieldExists(firestore.FieldOf("rating")).As("hasRating"),
	)).
	Execute(ctx)

IS_ABSENT

البنية:

is_absent(value: ANY) -> BOOLEAN

الوصف:

تعرض هذه الدالة TRUE إذا كانت value هي القيمة غير المتوفّرة، وFALSE في الحالات الأخرى. القيم غير المتوفّرة هي القيم التي لا تظهر في الإدخال، مثل حقل مستند غير متوفّر.

أمثلة:

value is_absent(value)
0 لتر FALSE
"foo" FALSE
NULL FALSE
ABSENT TRUE

IF_ABSENT

البنية:

if_absent(value: ANY, replacement: ANY) -> ANY

الوصف:

إذا كانت السمة value قيمة غير متوفّرة، يتم تقييم السمة replacement وعرضها. بخلاف ذلك، يتم عرض value.

أمثلة:

value replacement if_absent(value, replacement)
‫5 لتر 0 لتر ‫5 لتر
NULL 0 لتر NULL
ABSENT 0 لتر 0 لتر

IS_ERROR

البنية:

is_error(try: ANY) -> BOOLEAN

الوصف:

تعرض هذه الدالة TRUE إذا حدث خطأ أثناء تقييم try. وتعرض FALSE في الحالات الأخرى.

IF_ERROR

البنية:

if_error(try: ANY, catch: ANY) -> ANY

الوصف:

إذا حدث خطأ أثناء تقييم try، يتم تقييم replacement وعرضه. بخلاف ذلك، يتم عرض القيمة التي تم حلّها لـ try.

خطأ

البنية:

error(message: STRING) -> ANY

الوصف:

يؤدي تقييم الدالة error إلى تقييم المسار وإنهائه مع ظهور خطأ. يتم تضمين message المحدّد في الخطأ.

أمثلة:

cond res switch_on(cond, res, error("no condition matched"))
TRUE 1 لتر 1 لتر
FALSE 1 لتر ERROR ("no condition matched")

دوال المراجع

يعمل النوع REFERENCE كـ "مؤشر" إلى مستندات أخرى في قاعدة البيانات (أو حتى قواعد بيانات أخرى). تتيح الدوال التالية معالجة هذا النوع أثناء تنفيذ طلب البحث.

الاسم الوصف
COLLECTION_ID تعرض هذه الدالة معرّف المجموعة الفرعية في المرجع المحدّد
DOCUMENT_ID تعرض هذه الدالة معرّف المستند في المرجع المحدّد
PARENT عرض المرجع الرئيسي
REFERENCE_SLICE تعرض هذه الدالة مجموعة فرعية من المقاطع من المرجع المحدّد

COLLECTION_ID

البنية:

collection_id(ref: REFERENCE) -> STRING

الوصف:

تعرض هذه الدالة رقم تعريف المجموعة الفرعية لـ REFERENCE المحدّد.

أمثلة:

ref collection_id(ref)
users/user1 "users"
users/user1/posts/post1 "posts"

DOCUMENT_ID

البنية:

document_id(ref: REFERENCE) -> ANY

الوصف:

تعرض هذه الدالة معرّف المستند الخاص بـ REFERENCE المحدّد.

أمثلة:

ref document_id(ref)
users/user1 "user1"
users/user1/posts/post1 "post1"

PARENT

البنية:

parent(ref: REFERENCE) -> REFERENCE

الوصف:

تعرض هذه الدالة المرجع الرئيسي REFERENCE للمرجع المحدّد، أو NULL إذا كان المرجع هو المرجع الجذر.

أمثلة:

ref parent(ref)
/ NULL
users/user1 /
users/user1/posts/post1 users/user1

REFERENCE_SLICE

البنية:

reference_slice(ref: REFERENCE, offset: INT, length: INT) -> REFERENCE

الوصف:

‫REFERENCE هي قائمة من صفوف (collection_id, document_id)، وتتيح هذه الدالة عرض تلك القائمة، تمامًا مثل array_slice(...).

تعرض هذه الدالة REFERENCE جديدًا يمثّل مجموعة فرعية من شرائح ref المحدّد.

  • ‫offset: فهرس البداية (يبدأ من 0) للشريحة. إذا كانت القيمة سالبة، تكون إزاحة من نهاية المرجع.
  • ‫length: عدد الأجزاء التي يجب تضمينها في الشريحة.

أمثلة:

ref offset length reference_slice(ref, offset, length)
a/1/b/2/c/3 1 لتر ‫2 لتر b/2/c/3
a/1/b/2/c/3 0 لتر ‫2 لتر a/1/b/2
a/1/b/2/c/3 -2L ‫2 لتر c/3

الدوال المنطقية

الاسم الوصف
AND تنفّذ هذه الدالة عملية AND منطقية
OR تنفّذ عملية "أو" منطقية
XOR تنفّذ هذه الدالة عملية XOR منطقية
NOT تنفّذ عملية NOT منطقية
NOR تنفّذ هذه الدالة عملية NOR منطقية
CONDITIONAL يتم تقييم الفروع استنادًا إلى تعبير شرطي.
IF_NULL تعرض أول قيمة غير فارغة
SWITCH_ON تقييم الفروع استنادًا إلى سلسلة من الشروط
EQUAL_ANY تتحقّق هذه الدالة مما إذا كانت قيمة معيّنة تساوي أي عناصر في مصفوفة
NOT_EQUAL_ANY تتحقّق هذه الدالة مما إذا كانت قيمة معيّنة لا تساوي أي عنصر في مصفوفة
MAXIMUM تعرض القيمة القصوى في مجموعة من القيم
MINIMUM تعرض هذه الدالة الحد الأدنى للقيمة في مجموعة من القيم

و

البنية:

and(x: BOOLEAN...) -> BOOLEAN

الوصف:

تعرض هذه الدالة القيمة المنطقية AND لقيمتَين منطقيتَين أو أكثر.

تعرض الدالة NULL إذا تعذّر اشتقاق النتيجة بسبب أنّ أيًا من القيم المحدّدة هي ABSENT أو NULL.

أمثلة:

x y and(x, y)
TRUE TRUE TRUE
FALSE TRUE FALSE
NULL TRUE NULL
ABSENT TRUE NULL
NULL FALSE FALSE
FALSE ABSENT FALSE
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    and(field("rating").greaterThan(4), field("price").lessThan(10))
      .as("under10Recommendation")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    and(field("rating").greaterThan(4), field("price").lessThan(10))
      .as("under10Recommendation")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    (Field("rating").greaterThan(4) && Field("price").lessThan(10))
      .as("under10Recommendation")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        Expression.and(field("rating").greaterThan(4),
          field("price").lessThan(10))
            .alias("under10Recommendation")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        Expression.and(
            field("rating").greaterThan(4),
            field("price").lessThan(10)
        ).alias("under10Recommendation")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field, And

result = (
    client.pipeline()
    .collection("books")
    .select(
        And(
            Field.of("rating").greater_than(4), Field.of("price").less_than(10)
        ).as_("under10Recommendation")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            and(greaterThan(field("rating"), 4), lessThan(field("price"), 10))
                .as("under10Recommendation"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.And(
			firestore.GreaterThan(firestore.FieldOf("rating"), 4),
			firestore.LessThan(firestore.FieldOf("price"), 10),
		).As("under10Recommendation"),
	)).
	Execute(ctx)

أو

البنية:

or(x: BOOLEAN...) -> BOOLEAN

الوصف:

لعرض القيمة المنطقية OR لقيمتَين منطقيتَين أو أكثر.

تعرض الدالة NULL إذا تعذّر اشتقاق النتيجة بسبب أنّ أيًا من القيم المحدّدة هي ABSENT أو NULL.

أمثلة:

x y or(x, y)
TRUE TRUE TRUE
FALSE TRUE TRUE
NULL TRUE TRUE
ABSENT TRUE TRUE
NULL FALSE NULL
FALSE ABSENT NULL
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    or(field("genre").equal("Fantasy"), field("tags").arrayContains("adventure"))
      .as("matchesSearchFilters")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    or(field("genre").equal("Fantasy"), field("tags").arrayContains("adventure"))
      .as("matchesSearchFilters")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    (Field("genre").equal("Fantasy") || Field("tags").arrayContains("adventure"))
      .as("matchesSearchFilters")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        Expression.or(field("genre").equal("Fantasy"),
          field("tags").arrayContains("adventure"))
            .alias("matchesSearchFilters")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        Expression.or(
            field("genre").equal("Fantasy"),
            field("tags").arrayContains("adventure")
        ).alias("matchesSearchFilters")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field, And, Or

result = (
    client.pipeline()
    .collection("books")
    .select(
        Or(
            Field.of("genre").equal("Fantasy"),
            Field.of("tags").array_contains("adventure"),
        ).as_("matchesSearchFilters")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            or(equal(field("genre"), "Fantasy"), arrayContains(field("tags"), "adventure"))
                .as("matchesSearchFilters"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Or(
			firestore.Equal(firestore.FieldOf("genre"), "Fantasy"),
			firestore.ArrayContains(firestore.FieldOf("tags"), "adventure"),
		).As("matchesSearchFilters"),
	)).
	Execute(ctx)

XOR

البنية:

xor(x: BOOLEAN...) -> BOOLEAN

الوصف:

لعرض القيمة المنطقية XOR لقيمتَين منطقيتَين أو أكثر.

تعرض هذه الدالة NULL إذا كانت أي من القيم المحدّدة هي ABSENT أو NULL.

أمثلة:

x y xor(x, y)
TRUE TRUE FALSE
FALSE FALSE FALSE
FALSE TRUE TRUE
NULL TRUE NULL
ABSENT TRUE NULL
NULL FALSE NULL
FALSE ABSENT NULL
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    xor(field("tags").arrayContains("magic"), field("tags").arrayContains("nonfiction"))
      .as("matchesSearchFilters")
  )
);

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    xor(field("tags").arrayContains("magic"), field("tags").arrayContains("nonfiction"))
      .as("matchesSearchFilters")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    (Field("tags").arrayContains("magic") ^ Field("tags").arrayContains("nonfiction"))
      .as("matchesSearchFilters")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        Expression.xor(field("tags").arrayContains("magic"),
          field("tags").arrayContains("nonfiction"))
            .alias("matchesSearchFilters")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        Expression.xor(
            field("tags").arrayContains("magic"),
            field("tags").arrayContains("nonfiction")
        ).alias("matchesSearchFilters")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field, Xor

result = (
    client.pipeline()
    .collection("books")
    .select(
        Xor(
            [
                Field.of("tags").array_contains("magic"),
                Field.of("tags").array_contains("nonfiction"),
            ]
        ).as_("matchesSearchFilters")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            xor(
                    arrayContains(field("tags"), "magic"),
                    arrayContains(field("tags"), "nonfiction"))
                .as("matchesSearchFilters"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Xor(
			firestore.ArrayContains(firestore.FieldOf("tags"), "magic"),
			firestore.ArrayContains(firestore.FieldOf("tags"), "nonfiction"),
		).As("matchesSearchFilters"),
	)).
	Execute(ctx)

NOR

البنية:

nor(x: BOOLEAN...) -> BOOLEAN

الوصف:

لعرض القيمة المنطقية NOR لقيمتَين منطقيتَين أو أكثر.

تعرض الدالة NULL إذا تعذّر اشتقاق النتيجة بسبب أنّ أيًا من القيم المحدّدة هي ABSENT أو NULL.

أمثلة:

x y nor(x, y)
TRUE TRUE FALSE
FALSE TRUE FALSE
FALSE FALSE TRUE
NULL TRUE FALSE
ABSENT TRUE FALSE
NULL FALSE NULL
FALSE ABSENT NULL

NOT

البنية:

not(x: BOOLEAN) -> BOOLEAN

الوصف:

لعرض القيمة المنطقية NOT لقيمة منطقية.

Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("tags").arrayContains("nonfiction").not()
      .as("isFiction")
  )
);

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("tags").arrayContains("nonfiction").not()
      .as("isFiction")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    (!Field("tags").arrayContains("nonfiction"))
      .as("isFiction")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        Expression.not(
            field("tags").arrayContains("nonfiction")
        ).alias("isFiction")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        Expression.not(
            field("tags").arrayContains("nonfiction")
        ).alias("isFiction")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field, Not

result = (
    client.pipeline()
    .collection("books")
    .select(Not(Field.of("tags").array_contains("nonfiction")).as_("isFiction"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(not(arrayContains(field("tags"), "nonfiction")).as("isFiction"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Not(firestore.ArrayContains(firestore.FieldOf("tags"), "nonfiction")).As("isFiction"),
	)).
	Execute(ctx)

CONDITIONAL

البنية:

conditional(condition: BOOLEAN, true_case: ANY, false_case: ANY) -> ANY

الوصف:

تقيّم هذه الدالة true_case وتعرضها إذا كان تقييم condition هو TRUE.

تقيّم هذه الدالة false_case وتعرضها إذا كانت نتيجة الشرط FALSE أو NULL أو قيمة ABSENT.

أمثلة:

condition true_case false_case conditional(condition, true_case, false_case)
TRUE 1 لتر 0 لتر 1 لتر
FALSE 1 لتر 0 لتر 0 لتر
NULL 1 لتر 0 لتر 0 لتر
ABSENT 1 لتر 0 لتر 0 لتر
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("tags").arrayConcat([
      field("pages").greaterThan(100)
        .conditional(constant("longRead"), constant("shortRead"))
    ]).as("extendedTags")
  )
);

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("tags").arrayConcat([
      field("pages").greaterThan(100)
        .conditional(constant("longRead"), constant("shortRead"))
    ]).as("extendedTags")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("tags").arrayConcat([
      ConditionalExpression(
        Field("pages").greaterThan(100),
        then: Constant("longRead"),
        else: Constant("shortRead")
      )
    ]).as("extendedTags")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("tags").arrayConcat(
            Expression.conditional(
                field("pages").greaterThan(100),
                constant("longRead"),
                constant("shortRead")
            )
        ).alias("extendedTags")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("tags").arrayConcat(
            Expression.conditional(
                field("pages").greaterThan(100),
                constant("longRead"),
                constant("shortRead")
            )
        ).alias("extendedTags")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import (
    Field,
    Constant,
    Conditional,
)

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("tags")
        .array_concat(
            Conditional(
                Field.of("pages").greater_than(100),
                Constant.of("longRead"),
                Constant.of("shortRead"),
            )
        )
        .as_("extendedTags")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            arrayConcat(
                    field("tags"),
                    conditional(
                        greaterThan(field("pages"), 100),
                        constant("longRead"),
                        constant("shortRead")))
                .as("extendedTags"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ArrayConcat(
			firestore.FieldOf("tags"),
			firestore.Conditional(
				firestore.GreaterThan(firestore.FieldOf("pages"), 100),
				firestore.ConstantOf("longRead"),
				firestore.ConstantOf("shortRead"),
			),
		).As("extendedTags"),
	)).
	Execute(ctx)

IF_NULL

البنية:

if_null(expr: ANY, replacement: ANY) -> ANY

الوصف:

تعرض هذه الدالة expr إذا لم تكن NULL، وإلا فإنها تقيّم replacement وتعرضها. لا يتم تقييم التعبير replacement في حال استخدام expr.

أمثلة:

expr replacement if_null(expr, replacement)
1 لتر ‫2 لتر 1 لتر
NULL ‫2 لتر ‫2 لتر
ABSENT ‫2 لتر ABSENT

SWITCH_ON

البنية:

switch_on(cond1: BOOLEAN, res1: ANY, cond2: BOOLEAN, res2: ANY, ..., [default: ANY]) -> ANY

الوصف:

تقيّم هذه الدالة سلسلة من الشروط وتعرض النتيجة المرتبطة بالشرط الأول الذي تكون قيمته TRUE. إذا لم يتم تقييم أي شروط على أنّها TRUE، يتم عرض القيمة default إذا تم توفيرها. في حال عدم تقديم قيمة default، يتم عرض خطأ إذا لم يتم تقييم أي شروط أخرى على أنّها TRUE.

لتقديم قيمة default، يجب تمريرها كوسيطة نهائية بحيث يكون هناك عدد فردي من الوسيطات.

أمثلة:

x switch_on(eq(x, 1L), "one", eq(x, 2L), "two", "other")
1 لتر "one"
‫2 لتر "two"
3L "other"

EQUAL_ANY

البنية:

equal_any(value: ANY, search_space: ARRAY) -> BOOLEAN

الوصف:

تعرض هذه الدالة TRUE إذا كانت value في مصفوفة search_space.

أمثلة:

value search_space equal_any(value, search_space)
0 لتر [1L, 2L, 3L] FALSE
‫2 لتر [1L, 2L, 3L] TRUE
NULL [1L, 2L, 3L] FALSE
NULL [1L, NULL] TRUE
ABSENT [1L, NULL] FALSE
NaN [1L, NaN, 3L] TRUE
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre").equalAny(["Science Fiction", "Psychological Thriller"])
      .as("matchesGenreFilters")
  )
);

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("genre").equalAny(["Science Fiction", "Psychological Thriller"])
      .as("matchesGenreFilters")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("genre").equalAny(["Science Fiction", "Psychological Thriller"])
      .as("matchesGenreFilters")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("genre").equalAny(listOf("Science Fiction", "Psychological Thriller"))
            .alias("matchesGenreFilters")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("genre").equalAny(Arrays.asList("Science Fiction", "Psychological Thriller"))
            .alias("matchesGenreFilters")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("genre")
        .equal_any(["Science Fiction", "Psychological Thriller"])
        .as_("matchesGenreFilters")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            equalAny(field("genre"), Arrays.asList("Science Fiction", "Psychological Thriller"))
                .as("matchesGenreFilters"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.EqualAny(firestore.FieldOf("genre"), []string{"Science Fiction", "Psychological Thriller"}).As("matchesGenreFilters"),
	)).
	Execute(ctx)

NOT_EQUAL_ANY

البنية:

not_equal_any(value: ANY, search_space: ARRAY) -> BOOLEAN

الوصف:

تعرض الدالة TRUE إذا لم تكن value في مصفوفة search_space.

أمثلة:

value search_space not_equal_any(value, search_space)
0 لتر [1L, 2L, 3L] TRUE
‫2 لتر [1L, 2L, 3L] FALSE
NULL [1L, 2L, 3L] TRUE
NULL [1L, NULL] FALSE
ABSENT [1L, NULL] TRUE
NaN [1L, NaN, 3L] FALSE
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("author").notEqualAny(["George Orwell", "F. Scott Fitzgerald"])
      .as("byExcludedAuthors")
  )
);

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("author").notEqualAny(["George Orwell", "F. Scott Fitzgerald"])
      .as("byExcludedAuthors")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("author").notEqualAny(["George Orwell", "F. Scott Fitzgerald"])
      .as("byExcludedAuthors")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("author").notEqualAny(listOf("George Orwell", "F. Scott Fitzgerald"))
            .alias("byExcludedAuthors")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("author").notEqualAny(Arrays.asList("George Orwell", "F. Scott Fitzgerald"))
            .alias("byExcludedAuthors")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("author")
        .not_equal_any(["George Orwell", "F. Scott Fitzgerald"])
        .as_("byExcludedAuthors")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(
            notEqualAny(field("author"), Arrays.asList("George Orwell", "F. Scott Fitzgerald"))
                .as("byExcludedAuthors"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.NotEqualAny(firestore.FieldOf("author"), []string{"George Orwell", "F. Scott Fitzgerald"}).As("byExcludedAuthors"),
	)).
	Execute(ctx)

الحد الأقصى

البنية:

maximum(x: ANY...) -> ANY
maximum(x: ARRAY) -> ANY

الوصف:

لعرض الحد الأقصى للقيمة غير NULL وغير ABSENT في سلسلة من القيم x.

إذا لم تكن هناك قيم غير NULL وغير ABSENT، يتم عرض NULL.

في حال توفّر قيم قصوى متكافئة متعددة، يمكن عرض أيّ منها. يتبع ترتيب نوع القيمة الترتيب الموثَّق.

أمثلة:

x y maximum(x, y)
FALSE TRUE TRUE
FALSE ‫-10 لتر ‫-10 لتر
0.0 ‫-5 لتر 0.0
"foo" "bar" "foo"
"foo" ["foo"] ["foo"]
ABSENT ABSENT NULL
NULL NULL NULL
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").maximum().as("maximumPrice"))
);

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").maximum().as("maximumPrice"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("rating").logicalMaximum([1]).as("flooredRating")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("rating").logicalMaximum(1).alias("flooredRating")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("rating").logicalMaximum(1).alias("flooredRating")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").logical_maximum(1).as_("flooredRating"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(logicalMaximum(field("rating"), 1).as("flooredRating"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.LogicalMaximum(firestore.FieldOf("rating"), 1).As("flooredRating"),
	)).
	Execute(ctx)

الحد الأدنى

البنية:

minimum(x: ANY...) -> ANY
minimum(x: ARRAY) -> ANY

الوصف:

تعرض الحد الأدنى للقيمة غير NULL وغير ABSENT في سلسلة من القيم x.

إذا لم تكن هناك قيم غير NULL وغير ABSENT، يتم عرض NULL.

إذا كانت هناك قيم دنيا متكافئة متعددة، يمكن عرض أي من هذه القيم. يتبع ترتيب نوع القيمة الترتيب الموثَّق.

أمثلة:

x y minimum(x, y)
FALSE TRUE FALSE
FALSE ‫-10 لتر FALSE
0.0 ‫-5 لتر ‫-5 لتر
"foo" "bar" "bar"
"foo" ["foo"] "foo"
ABSENT ABSENT NULL
NULL NULL NULL
Node.js
const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").minimum().as("minimumPrice"))
);

Web

const result = await execute(db.pipeline()
  .collection("books")
  .aggregate(field("price").minimum().as("minimumPrice"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("rating").logicalMinimum([5]).as("cappedRating")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("rating").logicalMinimum(5).alias("cappedRating")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("rating").logicalMinimum(5).alias("cappedRating")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("rating").logical_minimum(5).as_("cappedRating"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(logicalMinimum(field("rating"), 5).as("cappedRating"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.LogicalMinimum(firestore.FieldOf("rating"), 5).As("cappedRating"),
	)).
	Execute(ctx)

دوال الخريطة

الاسم الوصف
MAP تنشئ هذه الدالة قيمة خريطة من سلسلة من أزواج المفاتيح والقيم
MAP_GET تعرض هذه الدالة القيمة في خريطة معيّنة استنادًا إلى مفتاح محدّد
MAP_SET تعرض هذه الدالة نسخة من خريطة تتضمّن سلسلة من المفاتيح المعدَّلة
MAP_REMOVE تعرض هذه الدالة نسخة من خريطة مع إزالة سلسلة من المفاتيح
MAP_MERGE لدمج سلسلة من الخرائط معًا
CURRENT_CONTEXT تعرض هذه الدالة السياق الحالي كخريطة.
MAP_KEYS تعرض هذه الدالة مصفوفة لجميع المفاتيح في خريطة.
MAP_VALUES تعرض مصفوفة لجميع القيم في خريطة.
MAP_ENTRIES تعرض مصفوفة من أزواج المفتاح والقيمة لخريطة.

English: MAP Arabic: English: MAP

البنية:

map(key: STRING, value: ANY, ...) -> MAP

الوصف:

تنشئ هذه الدالة خريطة من سلسلة من أزواج المفاتيح والقيم.

MAP_GET

البنية:

map_get(map: ANY, key: STRING) -> ANY

الوصف:

تعرض هذه الدالة القيمة في خريطة معيّنة استنادًا إلى مفتاح محدّد. تعرض هذه الدالة قيمة ABSENT إذا لم تكن السمة key متوفّرة في الخريطة، أو إذا لم تكن الوسيطة map من نوع MAP.

Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("awards").mapGet("pulitzer").as("hasPulitzerAward")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("awards").mapGet("pulitzer").as("hasPulitzerAward")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("awards").mapGet("pulitzer").as("hasPulitzerAward")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("awards").mapGet("pulitzer").alias("hasPulitzerAward")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("awards").mapGet("pulitzer").alias("hasPulitzerAward")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("awards").map_get("pulitzer").as_("hasPulitzerAward"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(mapGet(field("awards"), "pulitzer").as("hasPulitzerAward"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.MapGet(firestore.FieldOf("awards"), "pulitzer").As("hasPulitzerAward"),
	)).
	Execute(ctx)

MAP_SET

البنية:

map_set(map: MAP, key: STRING, value: ANY, ...) -> MAP

الوصف:

تعرض هذه الدالة نسخة من قيمة map مع تعديل محتواها من خلال سلسلة من أزواج المفاتيح والقيم.

إذا تم حلّ القيمة المحدّدة إلى قيمة غير متوفّرة، تتم إزالة المفتاح المرتبط من الخريطة.

إذا لم تكن الوسيطة map من النوع MAP، يتم عرض قيمة غير متوفّرة.

MAP_REMOVE

البنية:

map_remove(map: MAP, key: STRING...) -> MAP

الوصف:

تعرض هذه الدالة نسخة من قيمة map مع إزالة سلسلة من المفاتيح.

MAP_MERGE

البنية:

map_merge(maps: MAP...) -> MAP

تدمج هذه الدالة محتوى خريطتَين أو أكثر. إذا كانت هناك خرائط متعددة تحتوي على قيم متعارضة، يتم استخدام القيمة الأخيرة.

CURRENT_CONTEXT

البنية:

current_context() -> MAP

تعرض هذه الدالة خريطة تتألف من جميع الحقول المتاحة في نقطة التنفيذ الحالية.

MAP_KEYS

البنية:

map_keys(map: MAP) -> ARRAY<STRING>

الوصف:

تعرض هذه الدالة مصفوفة تحتوي على جميع مفاتيح القيمة map.

MAP_VALUES

البنية:

map_values(map: MAP) -> ARRAY<ANY>

الوصف:

تعرض هذه السمة مصفوفة تحتوي على جميع قيم السمة map.

MAP_ENTRIES

البنية:

map_entries(map: MAP) -> ARRAY<MAP>

الوصف:

تعرض هذه الدالة مصفوفة تحتوي على جميع أزواج المفاتيح والقيم في قيمة map.

سيكون كل زوج مفتاح/قيمة على شكل خريطة تتضمّن إدخالَين، هما k وv.

أمثلة:

map map_entries(map)
{} []
{"foo" : 2L} [{"k": "foo", "v" : 2L}]
{"foo" : "bar", "bar" : "foo"} [{"k": "foo", "v" : "bar" }, {"k" : "bar", "v": "foo"}]

دوال السلاسل

الاسم الوصف
BYTE_LENGTH تعرض عدد BYTES في قيمة STRING أو BYTES
CHAR_LENGTH تعرض عدد أحرف يونيكود في قيمة STRING
STARTS_WITH تعرض هذه الدالة TRUE إذا كانت السمة STRING تبدأ ببادئة معيّنة
ENDS_WITH تعرض هذه الدالة القيمة TRUE إذا كانت السلسلة STRING تنتهي بلاحقة معيّنة
LIKE تعرض هذه الدالة TRUE إذا تطابق STRING مع نمط معيّن
REGEX_CONTAINS تعرض هذه الدالة القيمة TRUE إذا كانت القيمة مطابقة بشكل جزئي أو كامل لتعبير عادي
REGEX_FIND تعرض هذه الدالة السلسلة الفرعية الأولى التي تطابق تعبيرًا عاديًا، أو NULL في حال عدم العثور على أي تطابق.
REGEX_FIND_ALL تعرض هذه الدالة مصفوفة من جميع السلاسل الفرعية التي تتطابق مع تعبير عادي، أو مصفوفة فارغة في حال عدم العثور على أي تطابقات.
REGEX_MATCH لعرض TRUE إذا كان أي جزء من القيمة يتطابق مع تعبير عادي
STRING_CONCAT لدمج عدة STRING في STRING
STRING_CONTAINS تعرض هذه الدالة TRUE إذا كانت القيمة تحتوي على STRING
STRING_INDEX_OF تعرض هذه الدالة الفهرس المستند إلى 0 لأول تكرار لقيمة STRING أو BYTES.
TO_UPPER تحوِّل قيمة STRING أو BYTES إلى أحرف كبيرة.
TO_LOWER تحوّل قيمة STRING أو BYTES إلى أحرف لاتينية صغيرة.
SUBSTRING تحصل على سلسلة فرعية من قيمة STRING أو BYTES.
STRING_REVERSE لعكس قيمة STRING أو BYTES
STRING_REPEAT تكرّر قيمة STRING أو BYTES لعدد محدّد من المرات.
STRING_REPLACE_ALL يستبدل كل تكرارات قيمة STRING أو BYTES.
STRING_REPLACE_ONE يستبدل هذا الإجراء أول ظهور لقيمة STRING أو BYTES.
TRIM تزيل هذه الدالة الأحرف البادئة واللاحقة من قيمة STRING أو BYTES.
LTRIM تزيل هذه الدالة الأحرف البادئة من قيمة STRING أو BYTES.
RTRIM تزيل هذه الدالة الأحرف اللاحقة من قيمة STRING أو BYTES.
SPLIT تقسّم قيمة STRING أو BYTES إلى مصفوفة.

BYTE_LENGTH

البنية:

byte_length[T <: STRING | BYTES](value: T) -> INT64

الوصف:

تعرض عدد BYTES في قيمة STRING أو BYTES.

أمثلة:

القيمة byte_length(value)
"abc" 3
"xyzabc" 6
b"abc" 3
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").byteLength().as("titleByteLength")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(byteLength(field("title")).as("titleByteLength"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.ByteLength(firestore.FieldOf("title")).As("titleByteLength"),
	)).
	Execute(ctx)

CHAR_LENGTH

البنية:

char_length(value: STRING) -> INT64

الوصف:

تعرض عدد قيم مواضع رموز يونيكود في القيمة STRING.

أمثلة:

القيمة char_length(value)
"abc" 3
"مرحبًا" 5
"العالم" 5
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").charLength().as("titleCharLength")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(charLength(field("title")).as("titleCharLength"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.CharLength(firestore.FieldOf("title")).As("titleCharLength"),
	)).
	Execute(ctx)

STARTS_WITH

البنية:

starts_with(value: STRING, prefix: STRING) -> BOOLEAN

الوصف:

تعرض TRUE إذا كانت value تبدأ بـ prefix.

أمثلة:

القيمة بادئة starts_with(value, prefix)
"abc" "a" صحيح
"abc" "b" خطأ
"abc" "" صحيح
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").startsWith("The")
      .as("needsSpecialAlphabeticalSort")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(startsWith(field("title"), "The").as("needsSpecialAlphabeticalSort"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.StartsWith(firestore.FieldOf("title"), "The").As("needsSpecialAlphabeticalSort"),
	)).
	Execute(ctx)

ENDS_WITH

البنية:

ends_with(value: STRING, postfix: STRING) -> BOOLEAN

الوصف:

تعرض TRUE إذا كانت value تنتهي بـ postfix.

أمثلة:

القيمة postfix ends_with(value, postfix)
"abc" "c" صحيح
"abc" "b" خطأ
"abc" "" صحيح
Node.js
const result = await db.pipeline()
  .collection("inventory/devices/laptops")
  .select(
    field("name").endsWith("16 inch")
      .as("16InLaptops")
  )
  .execute();
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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("inventory/devices/laptops")
        .select(endsWith(field("name"), "16 inch").as("16InLaptops"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("inventory/devices/laptops").
	Select(firestore.Fields(
		firestore.EndsWith(firestore.FieldOf("name"), "16 inch").As("`Laptops16in`"),
	)).
	Execute(ctx)

أعجبني

البنية:

like(value: STRING, pattern: STRING) -> BOOLEAN

الوصف:

تعرض TRUE إذا كانت value تتطابق مع pattern.

أمثلة:

القيمة نموذج like(value, pattern)
"Firestore" "Fire%" صحيح
"Firestore" "%store" صحيح
"Datastore" "Data_tore" صحيح
"100%" "100\%" صحيح
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("genre").like("%Fiction")
      .as("anyFiction")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(like(field("genre"), "%Fiction").as("anyFiction"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Like(firestore.FieldOf("genre"), "%Fiction").As("anyFiction"),
	)).
	Execute(ctx)

REGEX_CONTAINS

البنية:

regex_contains(value: STRING, regexp: STRING | REGEX) -> BOOLEAN

الوصف:

تعرض هذه الدالة TRUE إذا كان جزء من value يتطابق مع regexp. إذا لم تكن السمة regexp تعبيرًا عاديًا صالحًا، ستعرض هذه الدالة error.

يمكن أن تكون الوسيطة regexp أيضًا قيمة REGEX تم إنشاؤها باستخدام regex("pattern", "options"). يتيح لك هذا التنسيق تقديم خيارات التعبير العادي مع النمط. الخيارات المتاحة هي:

  • ‫i: مطابقة غير حساسة لحالة الأحرف
  • ‫m: وضع الأسطر المتعددة (يتطابق ^ و$ مع بداية الأسطر أو نهايتها).
  • s: وضع Dotall (تطابق . الأسطر الجديدة).

إذا كان regexp عبارة عن STRING، لن يتم تطبيق أي خيارات باستثناء تلك المضمّنة في النمط نفسه (مثل (?i)).

تتّبع التعبيرات العادية بنية مكتبة re2.

أمثلة:

القيمة التعبير العادي regex_contains(value, regexp)
"Firestore" "Fire" صحيح
"Firestore" "store$" صحيح
"Firestore" "data" خطأ
"Firestore" regex("fire", "i") صحيح
"Firestore" regex("FIRE", "") خطأ
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("title").regexContains("Firestore (Enterprise|Standard)")
      .as("isFirestoreRelated")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(
            regexContains(field("title"), "Firestore (Enterprise|Standard)")
                .as("isFirestoreRelated"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.RegexContains(firestore.FieldOf("title"), "Firestore (Enterprise|Standard)").As("isFirestoreRelated"),
	)).
	Execute(ctx)

REGEX_FIND

البنية:

regex_find(value: STRING, regexp: STRING | REGEX) -> STRING

الوصف:

تعرض هذه الدالة السلسلة الفرعية الأولى في value التي تطابق regexp، أو NULL في حال عدم العثور على أي تطابق. إذا لم يكن regexp تعبيرًا عاديًا صالحًا، ستعرض هذه الدالة error.

يمكن أن تكون الوسيطة regexp أيضًا قيمة REGEX تم إنشاؤها باستخدام regex("pattern", "options"). يتيح لك هذا التنسيق تقديم خيارات التعبير العادي مع النمط. الخيارات المتاحة هي:

  • ‫i: مطابقة غير حساسة لحالة الأحرف
  • ‫m: وضع الأسطر المتعددة (يتطابق ^ و$ مع بداية الأسطر أو نهايتها).
  • s: وضع Dotall (تطابق . الأسطر الجديدة).

إذا كان regexp عبارة عن STRING، لن يتم تطبيق أي خيارات باستثناء تلك المضمّنة في النمط نفسه (مثل (?i)).

تتّبع التعبيرات العادية بنية مكتبة re2.

أمثلة:

القيمة التعبير العادي regex_find(value, regexp)
"Sometext MATCH" "SomeText" "Sometext"
"Sometext MATCH" regex("match", "i") "MATCH"
"Sometext MATCH" regex("(match)", "i") "MATCH"
"مطابقة نص معيّن" regex("MATCH", "") قيمة فارغة

REGEX_FIND_ALL

البنية:

regex_find_all(value: STRING, regexp: STRING | REGEX) -> ARRAY<STRING>

الوصف:

تعرض هذه الدالة مصفوفة من جميع السلاسل الفرعية في value التي تتطابق مع regexp، أو مصفوفة فارغة في حال عدم العثور على أي تطابقات. إذا لم يكن regexp تعبيرًا عاديًا صالحًا، ستعرض هذه الدالة error.

يمكن أن تكون الوسيطة regexp أيضًا قيمة REGEX تم إنشاؤها باستخدام regex("pattern", "options"). يتيح لك هذا التنسيق تقديم خيارات التعبير العادي مع النمط. الخيارات المتاحة هي:

  • ‫i: مطابقة غير حساسة لحالة الأحرف
  • ‫m: وضع الأسطر المتعددة (يتطابق ^ و$ مع بداية الأسطر أو نهايتها).
  • s: وضع Dotall (تطابق . الأسطر الجديدة).

إذا كان regexp عبارة عن STRING، لن يتم تطبيق أي خيارات باستثناء تلك المضمّنة في النمط نفسه (مثل (?i)).

تتّبع التعبيرات العادية بنية مكتبة re2.

أمثلة:

القيمة التعبير العادي regex_find_all(value, regexp)
"واحد اثنان ثلاثة اثنان" "one" ["one"]
"واحد اثنان ثلاثة اثنان" regex("two", "i") ["TWO", "Two"]
"واحد اثنان ثلاثة اثنان" regex("TWO", "") []

REGEX_MATCH

البنية:

regex_match(value: STRING, regexp: STRING | REGEX) -> BOOLEAN

الوصف:

تعرض هذه الدالة TRUE إذا تطابقت السلسلة value تمامًا مع regexp. إذا لم يكن regexp تعبيرًا عاديًا صالحًا، ستعرض هذه الدالة error.

يمكن أن تكون الوسيطة regexp أيضًا قيمة REGEX تم إنشاؤها باستخدام regex("pattern", "options"). يتيح لك هذا التنسيق تقديم خيارات التعبير العادي مع النمط. الخيارات المتاحة هي:

  • ‫i: مطابقة غير حساسة لحالة الأحرف
  • ‫m: وضع الأسطر المتعددة (يتطابق ^ و$ مع بداية الأسطر أو نهايتها).
  • s: وضع Dotall (تطابق . الأسطر الجديدة).

إذا كان regexp عبارة عن STRING، لن يتم تطبيق أي خيارات باستثناء تلك المضمّنة في النمط نفسه (مثل (?i)).

تتّبع التعبيرات العادية بنية مكتبة re2.

أمثلة:

القيمة التعبير العادي regex_match(value, regexp)
"Firestore" "F.*store" صحيح
"Firestore" "Fire" خطأ
"Firestore" "^F.*e$" صحيح
"FiReStOrE" regex("firestore", "i") صحيح
"Firestore" regex("firestore", "") خطأ
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("title").regexMatch("Firestore (Enterprise|Standard)")
      .as("isFirestoreExactly")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(
            regexMatch(field("title"), "Firestore (Enterprise|Standard)")
                .as("isFirestoreExactly"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.RegexMatch(firestore.FieldOf("title"), "Firestore (Enterprise|Standard)").As("isFirestoreExactly"),
	)).
	Execute(ctx)

STRING_CONCAT

البنية:

string_concat(values: STRING...) -> STRING

الوصف:

تدمج قيمتَي STRING أو أكثر في نتيجة واحدة.

أمثلة:

الوسيطات string_concat(values...)
() خطأ
("a") "a"
("abc", "def") "abcdef"
("a", "", "c") "ac"
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("title").stringConcat(" by ", field("author"))
      .as("fullyQualifiedTitle")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(stringConcat(field("title"), " by ", field("author")).as("fullyQualifiedTitle"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.StringConcat(firestore.FieldOf("title"), " by ", firestore.FieldOf("author")).As("fullyQualifiedTitle"),
	)).
	Execute(ctx)

STRING_CONTAINS

البنية:

string_contains(value: STRING, substring: STRING) -> BOOLEAN

الوصف:

تتحقّق هذه الدالة مما إذا كانت السلسلة value تحتوي على السلسلة النصية substring.

أمثلة:

القيمة سلسلة فرعية string_contains(value, substring)
"abc" "b" صحيح
"abc" "d" خطأ
"abc" "" صحيح
"a.c" "." صحيح
"☃☃☃" "☃" صحيح
Node.js
const result = await db.pipeline()
  .collection("articles")
  .select(
    field("body").stringContains("Firestore")
      .as("isFirestoreRelated")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("articles")
        .select(stringContains(field("body"), "Firestore").as("isFirestoreRelated"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("articles").
	Select(firestore.Fields(
		firestore.StringContains(firestore.FieldOf("body"), "Firestore").As("isFirestoreRelated"),
	)).
	Execute(ctx)

STRING_INDEX_OF

البنية:

string_index_of[T <: STRING | BYTES](value: T, search: T) -> INT64

الوصف:

تعرض هذه الدالة الفهرس الذي يبدأ من 0 لأول تكرار لـ search في value.

  • تعرض هذه الدالة -1 في حال عدم العثور على search.
  • إذا كانت السلسلة value قيمة STRING، يتم قياس النتيجة بقيم مواضع الرموز في ترميز Unicode. إذا كانت القيمة BYTES، يتم قياسها بالبايت.
  • إذا كانت السمة search فارغة STRING أو كانت قيمة BYTES فارغة، تكون النتيجة 0.

أمثلة:

القيمة عملية بحث واحدة string_index_of(value, search)
"مرحبًا بالعالم" "o" 4
"مرحبًا بالعالم" "l" 2
"مرحبًا بالعالم" "z" -1
"موز" "ana" 1
"abc" "" 0
b"abc" b"b" 1
"é" "é" 0
b"é" b"é" 0

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"
Node.js
const result = await db.pipeline()
  .collection("authors")
  .select(
    field("name").toUpper()
      .as("uppercaseName")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("authors")
        .select(toUpper(field("name")).as("uppercaseName"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("authors").
	Select(firestore.Fields(
		firestore.ToUpper(firestore.FieldOf("name")).As("uppercaseName"),
	)).
	Execute(ctx)

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"
Node.js
const result = await db.pipeline()
  .collection("authors")
  .select(
    field("genre").toLower().equal("fantasy")
      .as("isFantasy")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("authors")
        .select(equal(toLower(field("genre")), "fantasy").as("isFantasy"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("authors").
	Select(firestore.Fields(
		firestore.Equal(firestore.ToLower(firestore.FieldOf("genre")), "fantasy").As("isFantasy"),
	)).
	Execute(ctx)

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 بقيم مواضع الرموز في يونيكود. إذا كانت القيمة 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"
Node.js
const result = await db.pipeline()
  .collection("books")
  .where(field("title").startsWith("The "))
  .select(
    field("title").substring(4)
      .as("titleWithoutLeadingThe")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .where(startsWith(field("title"), "The "))
        .select(
            substring(field("title"), constant(4), field("title").charLength())
                .as("titleWithoutLeadingThe"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Where(firestore.StartsWith(firestore.FieldOf("title"), "The ")).
	Select(firestore.Fields(
		firestore.Substring(firestore.FieldOf("title"), firestore.ConstantOf(4), firestore.FieldOf("title").CharLength()).As("titleWithoutLeadingThe"),
	)).
	Execute(ctx)

STRING_REVERSE

البنية:

string_reverse[T <: STRING | BYTES](input: T) -> T

الوصف:

لعرض الإدخال المقدَّم بترتيب عكسي

يتم تحديد الأحرف من خلال قيم مواضع رموز Unicode عندما يكون الإدخال STRING، ومن خلال وحدات البايت عندما يكون الإدخال قيمة BYTES.

أمثلة:

إدخال string_reverse(input)
"abc" "cba"
"a🌹b" "b🌹a"
"مرحبًا" "olleh"
b"abc" b"cba"
Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("name").reverse().as("reversedName")
  )
  .execute();

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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(reverse(field("name")).as("reversedName"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Reverse(firestore.FieldOf("name")).As("reversedName"),
	)).
	Execute(ctx)

STRING_REPEAT

البنية:

string_repeat[T <: STRING | BYTES](input: T, repetitions: INT64) -> T

الوصف:

تعرض input مكررًا repetitions مرة.

  • يجب أن تكون القيمة "repetitions" عددًا صحيحًا غير سالب.
  • إذا كانت قيمة repetitions هي 0، يتم عرض قيمة فارغة من النوع نفسه مثل input.
  • إذا تجاوزت النتيجة الحد الأقصى المسموح به للحجم (1 ميغابايت)، سيظهر خطأ.

أمثلة:

إدخال مرّات التكرار string_repeat(input, repetitions)
"foo" 3 "foofoofoo"
"foo" 0 ""
"a " 3 "a a a "
b"ab" 2 b"abab"
"é🦆" 2 "é🦆é🦆"

STRING_REPLACE_ALL

البنية:

string_replace_all[T <: STRING | BYTES](input: T, find: T, replacement: T) -> T

الوصف:

يستبدل جميع تكرارات find غير المتداخلة في input بـ replacement.

  • تكون المطابقات حسّاسة لحالة الأحرف.
  • إذا كانت السلسلة find فارغة، لن يتم إجراء أي استبدالات.

أمثلة:

إدخال العثور الاستبدال string_replace_all(input, find, replacement)
"foobarfoo" "foo" "baz" "bazbarbaz"
"ababab" "aba" "c" "cbab"
"foobar" "o" "" "fbar"
"é🦆🌎🦆" "🦆" "a" "éa🌎a"
b"abc" b"b" b"d" b"adc"

STRING_REPLACE_ONE

البنية:

string_replace_one[T <: STRING | BYTES](input: T, find: T, replacement: T) -> T

الوصف:

تستبدل هذه الدالة أول تكرار لـ find في input بـ replacement.

  • تكون المطابقات حسّاسة لحالة الأحرف.
  • إذا كانت السلسلة find فارغة، لن يتم إجراء أي استبدالات.

أمثلة:

إدخال العثور الاستبدال string_replace_one(input, find, replacement)
"foobarfoo" "foo" "baz" "bazbarfoo"
"é" "é" "a" "a"
b"foobar" b"o" b"z" b"fzoobar"

TRIM

البنية:

trim[T <: STRING | BYTES](input: T, values_to_trim: T) -> T
trim[T <: STRING | BYTES](input: T) -> T

الوصف:

تزيل هذه الدالة مجموعة محدّدة من BYTES أو CHARS من بداية ونهاية input المقدَّمة.

  • في حال عدم توفير 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()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(trim(field("name")).as("whitespaceTrimmedName"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.Trim(firestore.FieldOf("name")).As("whitespaceTrimmedName"),
	)).
	Execute(ctx)

LTRIM

البنية:

ltrim[T <: STRING | BYTES](value: T, to_trim: T) -> T
ltrim[T <: STRING | BYTES](value: T) -> T

الوصف:

تزيل هذه الدالة مجموعة محدّدة من BYTES أو CHARS من بداية value المقدَّمة.

  • في حال عدم توفير to_trim، يتم اقتطاع المسافات البيضاء البادئة.

أمثلة:

في حال عدم توفّر السمة to_trim:

القيمة ltrim(value)
" foo " "foo "
"foo" "foo"

عند تقديم السمة to_trim:

القيمة to_trim ltrim(value, to_trim)
"aaabc" "a" "bc"
"abacaba" "ba" "caba"
"é" "é" ""

RTRIM

البنية:

rtrim[T <: STRING | BYTES](value: T, to_trim: T) -> T
rtrim[T <: STRING | BYTES](value: T) -> T

الوصف:

تزيل هذه الدالة مجموعة محدّدة من BYTES أو CHARS من نهاية value المقدَّمة.

  • في حال عدم توفير to_trim، يتم اقتطاع المسافات البيضاء اللاحقة.

أمثلة:

في حال عدم توفّر السمة to_trim:

القيمة rtrim(value)
" foo " " foo"
"foo" "foo"

عند تقديم السمة to_trim:

القيمة to_trim rtrim(value, to_trim)
"abccc" "c" "ab"
"abacaba" "ba" "abac"
"é" "é" ""

SPLIT

البنية:

split(input: STRING) -> ARRAY<STRING>
split[T <: STRING | BYTES](input: T, delimiter: T) -> ARRAY<T>

الوصف:

تقسّم قيمة STRING أو BYTES باستخدام محدِّد.

  • بالنسبة إلى STRING، المحدِّد التلقائي هو الفاصلة ,. يتم التعامل مع المُحدِّد كسلسلة واحدة.

  • بالنسبة إلى BYTES، يجب تحديد محدِّد.

  • يؤدي التقسيم باستخدام محدّد فارغ إلى إنشاء مصفوفة من نقاط ترميز Unicode لقيم STRING، ومصفوفة من BYTES لقيم BYTES.

  • يؤدي تقسيم STRING فارغ إلى عرض ARRAY مع STRING فارغ واحد.

أمثلة:

في حال عدم توفّر السمة delimiter:

إدخال split(input)
"foo,bar,foo" ["foo", "bar", "foo"]
"foo" ["foo"]
",foo," ["", "foo", ""]
"" [""]
b"C120C2C4" خطأ

عند تقديم السمة 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" خطأ

دوال الطابع الزمني

الاسم الوصف
CURRENT_TIMESTAMP يتم إنشاء TIMESTAMP يتوافق مع وقت الطلب.
TIMESTAMP_TRUNC يتم اقتطاع TIMESTAMP إلى درجة دقة معيّنة.
UNIX_MICROS_TO_TIMESTAMP تحوّل هذه الدالة عدد الميكروثانية منذ ‎1970-01-01 00:00:00 UTC إلى TIMESTAMP
UNIX_MILLIS_TO_TIMESTAMP تحوّل هذه الدالة عدد الملّي ثانية منذ 1970-01-01 00:00:00 UTC إلى TIMESTAMP
UNIX_SECONDS_TO_TIMESTAMP تحوّل هذه الدالة عدد الثواني منذ 1970-01-01 00:00:00 UTC إلى TIMESTAMP
TIMESTAMP_ADD تضيف هذه الدالة فاصلاً زمنيًا إلى TIMESTAMP.
TIMESTAMP_SUB تطرح هذه الدالة فاصلاً زمنيًا من TIMESTAMP
TIMESTAMP_TO_UNIX_MICROS تحوّل TIMESTAMP إلى عدد الميكروثانية منذ 1970-01-01 00:00:00 UTC
TIMESTAMP_TO_UNIX_MILLIS تحوّل TIMESTAMP إلى عدد المللي ثانية منذ 1970-01-01 00:00:00 UTC
TIMESTAMP_TO_UNIX_SECONDS تحوّل TIMESTAMP إلى عدد الثواني منذ 1970-01-01 00:00:00 UTC
TIMESTAMP_DIFF تعرض هذه الدالة العدد الصحيح للفواصل الزمنية المحدّدة لـ unit بين قيمتَي TIMESTAMP.
TIMESTAMP_EXTRACT تستخرج هذه الدالة part محدّدًا (مثل السنة أو الشهر أو اليوم) من TIMESTAMP.

CURRENT_TIMESTAMP

البنية:

current_timestamp() -> TIMESTAMP

الوصف:

تحصل على الطابع الزمني في بداية وقت الطلب input (يتم تفسيره على أنّه عدد الميكروثانية منذ 1970-01-01 00:00:00 UTC).

تكون هذه الدالة ثابتة ضمن طلب البحث، وسيتم دائمًا حلّها بالقيمة نفسها إذا تم استدعاؤها عدة مرات.

TIMESTAMP_TRUNC

البنية:

timestamp_trunc(timestamp: TIMESTAMP | BSON_TIMESTAMP, granularity: STRING[, timezone: STRING]) -> TIMESTAMP

الوصف:

يتم اقتطاع طابع زمني إلى مستوى دقة معيّن.

يجب أن تكون الوسيطة granularity سلسلة وإحدى القيم التالية:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day
  • week
  • week([weekday])
  • month
  • quarter
  • year
  • isoyear

في حال تقديم الوسيطة timezone، سيستند الاقتطاع إلى حدود التقويم في المنطقة الزمنية المحدّدة (على سبيل المثال، سيتم اقتطاع اليوم إلى منتصف الليل في المنطقة الزمنية المحدّدة). سيتم اقتطاع الوقت وفقًا لنظام التوقيت الصيفي.

إذا لم يتم توفير timezone، سيتم الاقتطاع استنادًا إلى حدود التقويم UTC.

يجب أن تكون الوسيطة timezone تمثيلاً نصيًا لمنطقة زمنية من قاعدة بيانات tz، على سبيل المثال America/New_York. يمكن أيضًا استخدام إزاحة زمنية مخصّصة من خلال تحديد إزاحة من GMT.

أمثلة:

timestamp granularity timezone timestamp_trunc(timestamp, granularity, timezone)
‫2000-01-01 10:20:30:123456 بالتوقيت العالمي المنسّق "second" غير متوفر ‫2001-01-01 10:20:30 بالتوقيت العالمي المنسَّق
‫1997-05-31 04:30:30 بالتوقيت العالمي المنسّق "day" غير متوفر ‫1997-05-31 00:00:00 بالتوقيت العالمي المنسق
‫1997-05-31 04:30:30 بالتوقيت العالمي المنسّق "day" "America/Los_Angeles" ‫1997-05-30 07:00:00 بالتوقيت العالمي المنسّق
‫2001-03-16 04:00:00 بالتوقيت العالمي المنسّق "week(friday) غير متوفر ‫2001-03-16 00:00:00 بالتوقيت العالمي المنسّق
‫2001-03-23 04:00:00 بالتوقيت العالمي المنسّق "week(friday) "America/Los_Angeles" ‫2001-03-23 17:00:00 بالتوقيت العالمي المنسّق
‫24 يناير 2026، الساعة 8:00 مساءً بالتوقيت العالمي المنسّق "month" "GMT+06:32:43" ‫2026-01-01T06:32:43 بالتوقيت العالمي المنسق

UNIX_MICROS_TO_TIMESTAMP

البنية:

unix_micros_to_timestamp(input: INT64) -> TIMESTAMP

الوصف:

تحوّل هذه الدالة input (التي يتم تفسيرها على أنّها عدد الميكروثانية منذ 1970-01-01 00:00:00 UTC) إلى TIMESTAMP. يتم عرض error إذا تعذّر تحويل input إلى TIMESTAMP صالح.

أمثلة:

input unix_micros_to_timestamp(input)
0 لتر ‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق
400123456L 1970-01-01 00:06:40.123456 UTC
-1000000L ‫31/12/1969 الساعة 11:59:59 مساءً بالتوقيت العالمي المنسّق
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtMicros").unixMicrosToTimestamp().as("createdAtString")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMicros").unixMicrosToTimestamp().alias("createdAtString")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMicros").unixMicrosToTimestamp().alias("createdAtString")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("createdAtMicros")
        .unix_micros_to_timestamp()
        .as_("createdAtString")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixMicrosToTimestamp(field("createdAtMicros")).as("createdAtString"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.UnixMicrosToTimestamp(firestore.FieldOf("createdAtMicros")).As("createdAtString"),
	)).
	Execute(ctx)

UNIX_MILLIS_TO_TIMESTAMP

البنية:

unix_millis_to_timestamp(input: INT64) -> TIMESTAMP

الوصف:

تحوّل هذه الدالة input (التي يتم تفسيرها على أنّها عدد المللي ثانية منذ 1970-01-01 00:00:00 UTC) إلى TIMESTAMP. يتم عرض error إذا تعذّر تحويل input إلى TIMESTAMP صالح.

أمثلة:

input unix_millis_to_timestamp(input)
0 لتر ‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق
4000123L ‫1970-01-01 01:06:40.123 بالتوقيت العالمي المنسق
-1000000L ‫1969-12-31 23:43:20 بالتوقيت العالمي المنسّق
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtMillis").unixMillisToTimestamp().as("createdAtString")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMillis").unixMillisToTimestamp().alias("createdAtString")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtMillis").unixMillisToTimestamp().alias("createdAtString")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("createdAtMillis")
        .unix_millis_to_timestamp()
        .as_("createdAtString")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixMillisToTimestamp(field("createdAtMillis")).as("createdAtString"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.UnixMillisToTimestamp(firestore.FieldOf("createdAtMillis")).As("createdAtString"),
	)).
	Execute(ctx)

UNIX_SECONDS_TO_TIMESTAMP

البنية:

unix_seconds_to_timestamp(input: INT64) -> TIMESTAMP

الوصف:

تحوّل هذه الدالة input (التي يتم تفسيرها على أنّها عدد الثواني منذ 1970-01-01 00:00:00 UTC) إلى TIMESTAMP. يتم عرض error إذا تعذّر تحويل input إلى TIMESTAMP صالح.

أمثلة:

input unix_seconds_to_timestamp(input)
0 لتر ‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق
60 لتر ‫1970-01-01 00:01:00 بالتوقيت العالمي المنسق
-300L ‫31-12-1969 الساعة 11:55 مساءً بالتوقيت العالمي المنسّق
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAtSeconds").unixSecondsToTimestamp().as("createdAtString")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtSeconds").unixSecondsToTimestamp().alias("createdAtString")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAtSeconds").unixSecondsToTimestamp().alias("createdAtString")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("createdAtSeconds")
        .unix_seconds_to_timestamp()
        .as_("createdAtString")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(unixSecondsToTimestamp(field("createdAtSeconds")).as("createdAtString"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.UnixSecondsToTimestamp(firestore.FieldOf("createdAtSeconds")).As("createdAtString"),
	)).
	Execute(ctx)

TIMESTAMP_ADD

البنية:

timestamp_add(timestamp: TIMESTAMP | BSON_TIMESTAMP, unit: STRING, amount: INT64) -> TIMESTAMP

الوصف:

يضيف amount من unit من timestamp. يمكن أن تكون الوسيطة amount سالبة، وفي هذه الحالة تكون مكافئة لـ TIMESTAMP_SUB.

يجب أن تكون الوسيطة unit سلسلة وإحدى القيم التالية:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day

يتم عرض خطأ إذا لم يكن الطابع الزمني الناتج ضمن نطاق TIMESTAMP.

أمثلة:

timestamp unit amount timestamp_add(timestamp, unit, amount)
‫2025-02-20‎ 00:00:00 بالتوقيت العالمي المنسق "minute" ‫2 لتر ‫2025-02-20 00:02:00 بالتوقيت العالمي المنسق
‫2025-02-20‎ 00:00:00 بالتوقيت العالمي المنسق "hour" -4L ‫19-02-2025‎ 20:00:00 بالتوقيت العالمي المنسق
‫2025-02-20‎ 00:00:00 بالتوقيت العالمي المنسق "day" ‫5 لتر ‫25 فبراير 2025، الساعة 12:00 صباحًا بالتوقيت العالمي المنسَّق
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("createdAt").timestampAdd("day", 3653).as("expiresAt")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("createdAt").timestampAdd("day", 3653).as("expiresAt")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("createdAt").timestampAdd(3653, .day).as("expiresAt")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAt")
          .timestampAdd("day", 3653)
          .alias("expiresAt")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("createdAt").timestampAdd("day", 3653).alias("expiresAt")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("createdAt").timestamp_add("day", 3653).as_("expiresAt"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampAdd(field("createdAt"), "day", 3653).as("expiresAt"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampAdd(firestore.FieldOf("createdAt"), "day", 3653).As("expiresAt"),
	)).
	Execute(ctx)

TIMESTAMP_SUB

البنية:

timestamp_sub(timestamp: TIMESTAMP | BSON_TIMESTAMP, unit: STRING, amount: INT64) -> TIMESTAMP

الوصف:

تطرح هذه الدالة amount من unit من timestamp. يمكن أن تكون الوسيطة amount سالبة، وفي هذه الحالة تكون مكافئة لـ TIMESTAMP_ADD.

يجب أن تكون الوسيطة unit سلسلة وإحدى القيم التالية:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day

يتم عرض خطأ إذا لم يكن الطابع الزمني الناتج ضمن نطاق TIMESTAMP.

أمثلة:

timestamp unit amount timestamp_sub(timestamp, unit, amount)
‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق "minute" ‫40 لتر ‫2026-07-03‎ 23:20:00 بالتوقيت العالمي المنسّق
‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق "hour" -24L ‫‎2026-07-05 00:00:00 بالتوقيت العالمي المنسَّق
‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق "day" 3L ‫‎2026-07-01 00:00:00 UTC
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("expiresAt").timestampSubtract("day", 14).as("sendWarningTimestamp")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("expiresAt").timestampSubtract("day", 14).as("sendWarningTimestamp")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("expiresAt").timestampSubtract(14, .day).as("sendWarningTimestamp")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("expiresAt")
          .timestampSubtract("day", 14)
          .alias("sendWarningTimestamp")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("expiresAt").timestampSubtract("day", 14).alias("sendWarningTimestamp")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(
        Field.of("expiresAt")
        .timestamp_subtract("day", 14)
        .as_("sendWarningTimestamp")
    )
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampSubtract(field("expiresAt"), "day", 14).as("sendWarningTimestamp"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampSubtract(firestore.FieldOf("expiresAt"), "day", 14).As("sendWarningTimestamp"),
	)).
	Execute(ctx)

TIMESTAMP_TO_UNIX_MICROS

البنية:

timestamp_to_unix_micros(input: TIMESTAMP | BSON_TIMESTAMP) -> INT64

الوصف:

تحوّل input إلى عدد الميكروثانية منذ 1970-01-01 00:00:00 UTC. يتم اقتطاع المستويات الأعلى من الدقة من خلال التقريب إلى بداية الميكروثانية.

أمثلة:

input timestamp_to_unix_micros(input)
‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق 0 لتر
1970-01-01 00:06:40.123456 UTC 400123456L
‫31/12/1969 الساعة 11:59:59 مساءً بالتوقيت العالمي المنسّق -1000000L
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMicros().as("unixMicros")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMicros().as("unixMicros")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixMicros().as("unixMicros")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMicros().alias("unixMicros")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMicros().alias("unixMicros")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("dateString").timestamp_to_unix_micros().as_("unixMicros"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixMicros(field("dateString")).as("unixMicros"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampToUnixMicros(firestore.FieldOf("dateString")).As("unixMicros"),
	)).
	Execute(ctx)

TIMESTAMP_TO_UNIX_MILLIS

البنية:

timestamp_to_unix_millis(input: TIMESTAMP | BSON_TIMESTAMP) -> INT64

الوصف:

تحوّل هذه الدالة input إلى عدد الملّي ثانية منذ 1970-01-01 00:00:00 UTC. يتم اقتطاع المستويات الأعلى من الدقة عن طريق التقريب إلى بداية الملّي ثانية.

أمثلة:

input timestamp_to_unix_millis(input)
‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق 0 لتر
‫1970-01-01 01:06:40.123 بالتوقيت العالمي المنسق 4000123L
‫31/12/1969 23:43:20 -1000000L
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMillis().as("unixMillis")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixMillis().as("unixMillis")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixMillis().as("unixMillis")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMillis().alias("unixMillis")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixMillis().alias("unixMillis")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("dateString").timestamp_to_unix_millis().as_("unixMillis"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixMillis(field("dateString")).as("unixMillis"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampToUnixMillis(firestore.FieldOf("dateString")).As("unixMillis"),
	)).
	Execute(ctx)

TIMESTAMP_TO_UNIX_SECONDS

البنية:

timestamp_to_unix_seconds(input: TIMESTAMP | BSON_TIMESTAMP) -> INT64

الوصف:

تحوّل هذه الدالة input إلى عدد الثواني منذ 1970-01-01 00:00:00 UTC. يتم اقتطاع المستويات الأعلى من الدقة عن طريق التقريب إلى بداية الثانية.

أمثلة:

input timestamp_to_unix_seconds(input)
‫1970-01-01 00:00:00 بالتوقيت العالمي المنسق 0 لتر
‫1970-01-01 00:01:00 بالتوقيت العالمي المنسق 60 لتر
‫31-12-1969 الساعة 11:55 مساءً بالتوقيت العالمي المنسّق -300L
Node.js
const result = await db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixSeconds().as("unixSeconds")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("documents")
  .select(
    field("dateString").timestampToUnixSeconds().as("unixSeconds")
  )
);
Swift
let result = try await db.pipeline()
  .collection("documents")
  .select([
    Field("dateString").timestampToUnixSeconds().as("unixSeconds")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixSeconds().alias("unixSeconds")
    )
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("documents")
    .select(
        field("dateString").timestampToUnixSeconds().alias("unixSeconds")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("documents")
    .select(Field.of("dateString").timestamp_to_unix_seconds().as_("unixSeconds"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("documents")
        .select(timestampToUnixSeconds(field("dateString")).as("unixSeconds"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("documents").
	Select(firestore.Fields(
		firestore.TimestampToUnixSeconds(firestore.FieldOf("dateString")).As("unixSeconds"),
	)).
	Execute(ctx)

TIMESTAMP_DIFF

البنية:

timestamp_diff(end: TIMESTAMP | BSON_TIMESTAMP, start: TIMESTAMP | BSON_TIMESTAMP, unit: STRING) -> INT64

الوصف:

تعرض هذه الدالة العدد الصحيح للفواصل الزمنية المحدّدة لـ unit بين قيمتَي TIMESTAMP.

  • تعرض قيمة سالبة إذا كان end قبل start.
  • يتم اقتطاع أي وحدة كسرية. على سبيل المثال، تعرض الدالة timestamp_diff("2021-01-01 00:00:01", "2021-01-01 00:00:00", "minute") القيمة 0.

يجب أن تكون الوسيطة unit سلسلة وإحدى القيم التالية:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day

أمثلة:

end start unit timestamp_diff(end, start, unit)
‫‎2026-07-04 00:01:00 بالتوقيت العالمي المنسق ‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق "second" 60 لتر
‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق ‫‎2026-07-05 00:00:00 بالتوقيت العالمي المنسَّق "day" -1L
‫2026-07-04‎ 00:00:59 بالتوقيت العالمي المنسَّق ‫2026-07-04 00:00:00 بالتوقيت العالمي المنسق "minute" 0 لتر

TIMESTAMP_EXTRACT

البنية:

timestamp_extract(timestamp: TIMESTAMP | BSON_TIMESTAMP, part: STRING[, timezone: STRING]) -> INT64

الوصف:

تستخرج هذه الدالة part محدّدًا (مثل السنة أو الشهر أو اليوم) من timestamp.

يجب أن تكون الوسيطة part سلسلة وإحدى القيم التالية:

  • microsecond
  • millisecond
  • second
  • minute
  • hour
  • day
  • ‫dayofweek: تعرض قيمة بين 1 (الأحد) و7 (السبت).
  • dayofyear
  • ‫week: تعرض هذه الدالة رقم الأسبوع في السنة، بدءًا من 1 لأول يوم أحد في السنة.
  • ‫week([weekday]): تعرض هذه الدالة رقم الأسبوع في السنة، بدءًا من weekday المحدّد.
  • month
  • quarter
  • year
  • ‫isoweek: تعرض رقم الأسبوع وفقًا لمعيار ISO 8601.
  • ‫isoyear: تعرض السنة المرقمة حسب الأسبوع وفقًا لمعيار ISO 8601.

إذا تم تقديم الوسيطة timezone، سيتم الاستخراج استنادًا إلى تقويم المنطقة الزمنية المحددة. ستراعي عملية الاستخراج نظام التوقيت الصيفي.

إذا لم يتم توفير السمة timezone، سيتم الاستخراج استنادًا إلى السمة UTC.

يجب أن تكون الوسيطة timezone تمثيلاً نصيًا لمنطقة زمنية من قاعدة بيانات المناطق الزمنية، مثل America/New_York. يمكن أيضًا استخدام إزاحة زمنية مخصّصة من خلال تحديد إزاحة من GMT.

أمثلة:

timestamp part timezone timestamp_extract(timestamp, part, timezone)
‫2025-02-20 10:20:30 بالتوقيت العالمي المنسّق "year" غير متوفر 2025
‫2025-02-20 10:20:30 بالتوقيت العالمي المنسّق "day" غير متوفر 20
‫31-12-2025 الساعة 11:59:59 مساءً بالتوقيت العالمي المنسَّق "year" "Asia/Tokyo" 2026

دوال النوع

الاسم الوصف
TYPE لعرض نوع القيمة كـ STRING.
IS_TYPE تعرض الدالة true إذا كانت القيمة تتطابق مع النوع المحدّد.

النوع

البنية:

type(input: ANY) -> STRING

الوصف:

تعرض هذه الدالة تمثيل سلسلة من النوع input.

إذا تم إدخال قيمة غير متوفّرة، يتم عرض NULL.

أمثلة:

input type(input)
فارغ "null"
صحيح "boolean"
1 "int32"
-3L "int64"
3.14 "float64"
‫2024-01-01T00:00:00Z بالتوقيت العالمي المنسّق "timestamp"
"foo" "string"
b"foo" "bytes"
[1, 2] "array"
{"a": 1} "map"
path("c/d") "reference"
vector([1.0, 2.0]) "vector"
object_id "a7f2c9d18b3e4509f67c12d8" "object_id"
1.2e9m "decimal128"
regex "/pattern/i" "regex"
bson_timestamp(1732754912, 500) "bson_timestamp"
ABSENT NULL

أمثلة على العملاء

Node.js
const result = await db.pipeline()
  .collection("books")
  .select(field("title").notEqual("1984").as("not1984"))
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(field("title").notEqual("1984").as("not1984"))
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([Field("title").notEqual("1984").as("not1984")])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(field("title").notEqual("1984").alias("not1984"))
    .execute()

Java

Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(field("title").notEqual("1984").alias("not1984"))
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("title").not_equal("1984").as_("not1984"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(notEqual(field("title"), "1984").as("not1984"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.NotEqual(firestore.FieldOf("title"), "1984").As("not1984"),
	)).
	Execute(ctx)

IS_TYPE

البنية:

is_type(input: ANY, type: STRING) -> BOOLEAN

الوصف:

تعرض هذه الدالة true إذا تطابق input مع type المحدّد، وإلا تعرض false. إذا لم يتم تحديد input، يتم عرض NULL.

سلاسل type المتوافقة هي:

  • "null"
  • "boolean"
  • "int32"
  • "int64"
  • "float64"
  • "decimal128"
  • "number"
  • "timestamp"
  • "string"
  • "bytes"
  • "array"
  • "map"
  • "reference"
  • "vector"
  • "geo_point"
  • "max_key"
  • "min_key"
  • "object_id"
  • "regex"
  • "bson_timestamp"

أمثلة:

input type is_type(input, type)
فارغ "null" صحيح
صحيح "boolean" صحيح
3.14 "float64" صحيح
"foo" "string" صحيح
b"foo" "string" خطأ
[1, 2] "array" صحيح
{"a": 1} "map" صحيح
vector([1.0, 2.0]) "vector" صحيح
ABSENT "string" فارغ
"bar" "other" خطأ

دوال المتّجهات

الاسم الوصف
COSINE_DISTANCE تعرض هذه الدالة مسافة جيب التمام بين متجهَين
DOT_PRODUCT تعرض هذه الدالة حاصل الضرب القياسي لمتجهَين
EUCLIDEAN_DISTANCE تعرض هذه الدالة المسافة الإقليدية بين متجهَين
MANHATTAN_DISTANCE لعرض مسافة مانهاتن بين متجهين
VECTOR_LENGTH تعرض عدد العناصر في المتّجه

COSINE_DISTANCE

البنية:

cosine_distance(x: VECTOR, y: VECTOR) -> FLOAT64

الوصف:

تعرض هذه الدالة مسافة جيب التمام بين x وy.

Node.js
const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await db.pipeline()
  .collection("books")
  .select(
    field("embedding").cosineDistance(sampleVector).as("cosineDistance")
  )
  .execute();

Web

const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("embedding").cosineDistance(sampleVector).as("cosineDistance")));
Swift
let sampleVector = [0.0, 1, 2, 3, 4, 5]
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("embedding").cosineDistance(sampleVector).as("cosineDistance")
  ])
  .execute()

Kotlin

val sampleVector = doubleArrayOf(0.0, 1.0, 2.0, 3.0, 4.0, 5.0)
val result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").cosineDistance(sampleVector).alias("cosineDistance")
    )
    .execute()

Java

double[] sampleVector = {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").cosineDistance(sampleVector).alias("cosineDistance")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field
from google.cloud.firestore_v1.vector import Vector

sample_vector = Vector([0.0, 1.0, 2.0, 3.0, 4.0, 5.0])
result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("embedding").cosine_distance(sample_vector).as_("cosineDistance")
    )
    .execute()
)
Java
double[] sampleVector = new double[] {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(cosineDistance(field("embedding"), sampleVector).as("cosineDistance"))
        .execute()
        .get();
متابعة
sampleVector := []float64{0.0, 1.0, 2.0, 3.0, 4.0, 5.0}
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.CosineDistance(firestore.FieldOf("embedding"), sampleVector).As("cosineDistance"),
	)).
	Execute(ctx)

DOT_PRODUCT

البنية:

dot_product(x: VECTOR, y: VECTOR) -> FLOAT64

الوصف:

تعرض هذه الدالة ناتج الضرب النقطي لـ x وy.

Node.js
const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await db.pipeline()
  .collection("books")
  .select(
    field("embedding").dotProduct(sampleVector).as("dotProduct")
  )
  .execute();

Web

const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("embedding").dotProduct(sampleVector).as("dotProduct")
  )
);
Swift
let sampleVector = [0.0, 1, 2, 3, 4, 5]
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("embedding").dotProduct(sampleVector).as("dotProduct")
  ])
  .execute()

Kotlin

val sampleVector = doubleArrayOf(0.0, 1.0, 2.0, 3.0, 4.0, 5.0)
val result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").dotProduct(sampleVector).alias("dotProduct")
    )
    .execute()

Java

double[] sampleVector = {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").dotProduct(sampleVector).alias("dotProduct")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field
from google.cloud.firestore_v1.vector import Vector

sample_vector = Vector([0.0, 1.0, 2.0, 3.0, 4.0, 5.0])
result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("embedding").dot_product(sample_vector).as_("dotProduct"))
    .execute()
)
Java
double[] sampleVector = new double[] {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(dotProduct(field("embedding"), sampleVector).as("dotProduct"))
        .execute()
        .get();
متابعة
sampleVector := []float64{0.0, 1.0, 2.0, 3.0, 4.0, 5.0}
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.DotProduct(firestore.FieldOf("embedding"), sampleVector).As("dotProduct"),
	)).
	Execute(ctx)

EUCLIDEAN_DISTANCE

البنية:

euclidean_distance(x: VECTOR, y: VECTOR) -> FLOAT64

الوصف:

تحتسب هذه الدالة المسافة الإقليدية بين x وy.

Node.js
const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await db.pipeline()
  .collection("books")
  .select(
    field("embedding").euclideanDistance(sampleVector).as("euclideanDistance")
  )
  .execute();

Web

const sampleVector = [0.0, 1, 2, 3, 4, 5];
const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("embedding").euclideanDistance(sampleVector).as("euclideanDistance")
  )
);
Swift
let sampleVector = [0.0, 1, 2, 3, 4, 5]
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("embedding").euclideanDistance(sampleVector).as("euclideanDistance")
  ])
  .execute()

Kotlin

val sampleVector = doubleArrayOf(0.0, 1.0, 2.0, 3.0, 4.0, 5.0)
val result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").euclideanDistance(sampleVector).alias("euclideanDistance")
    )
    .execute()

Java

double[] sampleVector = {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Task<Pipeline.Snapshot> result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").euclideanDistance(sampleVector).alias("euclideanDistance")
    )
    .execute();
Python
from google.cloud.firestore_v1.pipeline_expressions import Field
from google.cloud.firestore_v1.vector import Vector

sample_vector = Vector([0.0, 1.0, 2.0, 3.0, 4.0, 5.0])
result = (
    client.pipeline()
    .collection("books")
    .select(
        Field.of("embedding")
        .euclidean_distance(sample_vector)
        .as_("euclideanDistance")
    )
    .execute()
)
Java
double[] sampleVector = new double[] {0.0, 1.0, 2.0, 3.0, 4.0, 5.0};
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(euclideanDistance(field("embedding"), sampleVector).as("euclideanDistance"))
        .execute()
        .get();
متابعة
sampleVector := []float64{0.0, 1.0, 2.0, 3.0, 4.0, 5.0}
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.EuclideanDistance(firestore.FieldOf("embedding"), sampleVector).As("euclideanDistance"),
	)).
	Execute(ctx)

MANHATTAN_DISTANCE

البنية:

manhattan_distance(x: VECTOR, y: VECTOR) -> FLOAT64

الوصف:

تحتسب هذه الدالة مسافة مانهاتن بين x وy.

VECTOR_LENGTH

البنية:

vector_length(vector: VECTOR) -> INT64

الوصف:

تعرض هذه الدالة عدد العناصر في VECTOR.

Node.js
const result = await db.pipeline()
  .collection("books")
  .select(
    field("embedding").vectorLength().as("vectorLength")
  )
  .execute();

Web

const result = await execute(db.pipeline()
  .collection("books")
  .select(
    field("embedding").vectorLength().as("vectorLength")
  )
);
Swift
let result = try await db.pipeline()
  .collection("books")
  .select([
    Field("embedding").vectorLength().as("vectorLength")
  ])
  .execute()

Kotlin

val result = db.pipeline()
    .collection("books")
    .select(
        field("embedding").vectorLength().alias("vectorLength")
    )
    .execute()

Java

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

result = (
    client.pipeline()
    .collection("books")
    .select(Field.of("embedding").vector_length().as_("vectorLength"))
    .execute()
)
Java
Pipeline.Snapshot result =
    firestore
        .pipeline()
        .collection("books")
        .select(vectorLength(field("embedding")).as("vectorLength"))
        .execute()
        .get();
متابعة
snapshot := client.Pipeline().
	Collection("books").
	Select(firestore.Fields(
		firestore.VectorLength(firestore.FieldOf("embedding")).As("vectorLength"),
	)).
	Execute(ctx)