توابع تجمیعی

تجمیع

همه توابع تجمیعی می‌توانند به‌عنوان عبارت‌های سطح بالا در مرحله 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();
پایتون
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()
)
جاوا
// 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();
پایتون
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()
)
جاوا
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();
پایتون
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("author").count_distinct().as_("unique_authors"))
    .execute()
)
جاوا
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 نتواند به‌عنوان INTEGER نمایش داده شود، به DOUBLE تبدیل خواهد شد.
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();
پایتون
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("cities")
    .aggregate(Field.of("population").sum().as_("totalPopulation"))
    .execute()
)
جاوا
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(expression: ANY) -> FLOAT64

شرح:

میانگین همه مقادیر عددی را برمی‌گرداند و مقادیر غیرعددی را نادیده می‌گیرد. اگر هرکدام از مقادیر NaN باشد، به NaN ارزیابی می‌شود، یا اگر هیچ مقدار عددی‌ای تجمیع نشده باشد، به NULL ارزیابی می‌شود.

برونداد همان نوع ورودی را خواهد داشت، به‌جز در موارد زیر:

  • اگر INTEGER نتواند به‌عنوان INTEGER نمایش داده شود، به DOUBLE تبدیل خواهد شد.
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();
پایتون
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("cities")
    .aggregate(Field.of("population").average().as_("averagePopulation"))
    .execute()
)
جاوا
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();
پایتون
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("price").minimum().as_("minimumPrice"))
    .execute()
)
جاوا
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();
پایتون
from google.cloud.firestore_v1.pipeline_expressions import Field

result = (
    client.pipeline()
    .collection("books")
    .aggregate(Field.of("price").maximum().as_("maximumPrice"))
    .execute()
)
جاوا
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 تبدیل می‌شود.

ترتیب عناصر در آرایه برونداد پایدار نیست و نباید به آن اعتماد کرد.