جمع‌آوری

شرح

مرحله aggregate(...) نتایج انبوهشی (مثلاً تعداد، مجموع) را از اسناد برگردانده‌شده توسط مرحله قبلی محاسبه می‌کند.

اختیاراً، وقتی عبارت گروه‌بندی ارائه می‌شود، اسناد را براساس عبارت‌های ارائه‌شده گروه‌بندی می‌کند و سپس توابع انباشتگر را برای هر گروه اعمال می‌کند.

مثال‌ها

برای تجمیع‌های بدون گروه براساس، مرحله aggregate(...) یک یا چند عبارت تجمیع‌کننده با نام مستعار را می‌گیرد:

Node.js

const cities = await db.pipeline()
  .collection("/cities")
  .aggregate(
      countAll().as("total"),
      average("population").as("avg_population")
  )
  .execute();

برای تجمیع با گروه‌بندی، گروه‌های دیگری علاوه‌بر تجمیع‌کننده‌ها درنظر گرفته می‌شود:

Node.js

const result = await db.pipeline()
  .collectionGroup('citites')
  .aggregate({
    accumulators: [
      countAll().as('cities'),
      field('population').sum().as('total_popoluation')
    ],
    groups: [field('location.state').as('state')]
  })
  .execute();

رفتار

انبوهش بدون گروه‌بندی

مجموعه cities با اسناد زیر ایجاد شود:

Node.js

await db.collection('cities').doc('SF').set({name: 'San Francisco', state: 'CA', country: 'USA', population: 870000});
await db.collection('cities').doc('LA').set({name: 'Los Angeles', state: 'CA', country: 'USA', population: 3970000});
await db.collection('cities').doc('NY').set({name: 'New York', state: 'NY', country: 'USA', population: 8530000});
await db.collection('cities').doc('TOR').set({name: 'Toronto', state: null, country: 'Canada', population: 2930000});
await db.collection('cities').doc('MEX').set({name: 'Mexico City', state: null, country: 'Mexico', population: 9200000});

برای پیدا کردن تعداد کل شهرها و میانگین جمعیت آن‌ها:

Node.js

const cities = await db.pipeline()
  .collection("/cities")
  .aggregate(
      countAll().as("total"),
      average("population").as("avg_population")
  )
  .execute();

که این نتیجه را می‌دهد:

{avg_population: 5100000, total: 5}

انجام تجمیع در گروه‌ها

با ارائه آرگومان groups، می‌توانید تجمیع‌ها را در هر گروه متمایز انجام دهید.

برای مثال، برای پیدا کردن شهری که بیشترین جمعیت را در هر کشور و هر ایالت دارد:

Node.js

const cities = await db.pipeline()
  .collection("/cities")
  .aggregate({
      accumulators: [
          countAll().as("number_of_cities"),
          maximum("population").as("max_population")
      ],
      groups: ["country", "state"]
  })
  .execute();

که نتیجه آن می‌شود:

{country: "USA", state: "CA", max_population: 3970000, number_of_cities: 2},
{country: "USA", state: "NY", max_population: 8530000, number_of_cities: 1},
{country: "Canada", state: null, max_population: 2930000, number_of_cities: 1},
{country: "Mexico", state: null,  max_population: 9200000, number_of_cities: 1}

عبارت‌های پیچیده در گروه‌بندی

فراتر از گروه‌بندی فقط براساس مقادیر فیلد، مرحله aggregate(...) از گروه‌بندی براساس نتایج عبارت‌های پیچیده پشتیبانی می‌کند. هر عبارتی که در مرحله select(...) معتبر باشد می‌تواند به‌عنوان کلید گروه‌بندی استفاده شود. این کار امکان گروه‌بندی انعطاف‌پذیر براساس مقادیر یا شرایط محاسبه‌شده را فراهم می‌کند.

برای مثال، برای گروه‌بندی براساس اینکه فیلد state تهی است یا نه، و پیدا کردن کل جمعیت در هر گروه:

Node.js

const cities = await db.pipeline()
  .collection("/cities")
  .aggregate({
      accumulators: [
         sum("population").as("total_population")
      ],
      groups: [equal(field("state"), null).as("state_is_null")]
  })
  .execute();

این موارد را برمی‌گرداند:

{state_is_null: true, total_population: 12130000}
{state_is_null: false, total_population: 13370000}

رفتارهای تجمیع‌گر

رفتار تجمیعی هر تابع پشتیبانی‌شده (مثلاً count، sum، avg) را می‌توانید در صفحه اختصاصی توابع تجمیعی پیدا کنید.

رفتارهای کلیدی گروه

هنگام گروه‌بندی اسناد، Cloud Firestore از معناشناسی برابری برای تعیین اینکه آیا مقادیر به یک گروه تعلق دارند یا نه استفاده می‌کند.

این یعنی مقادیر معادل، مثلاً مقادیر عددی معادل ازنظر ریاضی، صرف‌نظر از نوع اصلی (عدد صحیح ۳۲ بیتی، عدد صحیح ۶۴ بیتی، اعداد ممیز شناور، decimal128، و غیره)، همگی باهم گروه‌بندی می‌شوند.

به‌عنوان مثال، در مجموعه numerics با اسناد مختلف حاوی foo مقادیر عدد صحیح ۳۲ بیتی 1، عدد صحیح ۶۴ بیتی 1L و عدد ممیز شناور 1.0، همه آن‌ها در یک گروه جمع‌آوری می‌شوند. اجرای گروه‌بندی شمارش براساس foo این نتیجه را برمی‌گرداند:

{foo: 1.0, count: 3}

در چنین مواردی که مقادیر معادل متفاوتی در مجموعه داده وجود دارد، مقدار خروجی گروه می‌تواند هرکدام از این مقادیر معادل باشد. در این مثال، foo می‌تواند 1، 1L، یا 1.0 باشد.

حتی اگر به‌نظر می‌رسد که قطعی است، نباید سعی کنید به رفتار یک مقدار خاص که انتخاب شده است تکیه کنید.

استفاده از حافظه

نحوه اجرای انبوهش به نمایه‌های دردسترس بستگی دارد. وقتی نمایه مناسبی توسط بهینه‌ساز پُرسمان انتخاب نشده باشد، مجموع باید همه گروه‌ها را در حافظه میان‌گیر کند.

درصورت داشتن تعداد بسیار زیادی گروه، یا اگر هر گروه بسیار بزرگ باشد (مثلاً گروه‌بندی براساس مقادیر بسیار بزرگ)، ممکن است این مرحله با کمبود حافظه مواجه شود.

در چنین مواردی، باید فیلترهایی اعمال کنید تا مجموعه داده را برای انبوهش محدود کنید، در فیلدهای کوچک‌تر/کمتر گروه‌بندی کنید، یا نمایه‌هایی را که توصیه شده است ایجاد کنید تا از استفاده زیاد از حافظه جلوگیری شود. Query Explain اطلاعاتی درباره طرح اجرای پُرسمان واقعی و داده‌های نمایه‌سازی ارائه می‌دهد تا به اشکال‌زدایی کمک کند.