Method: projects.databases.documents.runAggregationQuery

یک پرس و جو تجمع را اجرا می کند.

به جای تولید نتایج Document مانند Firestore.RunQuery ، این API به اجرای یک تجمع برای تولید یک سری از AggregationResult سمت سرور اجازه می دهد.

مثال سطح بالا:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );

درخواست HTTP

POST https://firestore.googleapis.com/v1beta1/{parent=projects/*/databases/*/documents}:runAggregationQuery

URL از دستور GRPC Transcoding استفاده می کند.

پارامترهای مسیر

مولفه های
parent

string

ضروری. نام منبع والد در قالب: projects/{projectId}/databases/{databaseId}/documents or projects/{projectId}/databases/{databaseId}/documents/{document_path} . به عنوان مثال: projects/my-project/databases/my-database/documents /اسناد یا projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

درخواست بدن

بدنه درخواست حاوی داده هایی با ساختار زیر است:

نمایندگی JSON
{
  "explainOptions": {
    object (ExplainOptions)
  },

  // Union field query_type can be only one of the following:
  "structuredAggregationQuery": {
    object (StructuredAggregationQuery)
  }
  // End of list of possible types for union field query_type.

  // Union field consistency_selector can be only one of the following:
  "transaction": string,
  "newTransaction": {
    object (TransactionOptions)
  },
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
زمینه های
explainOptions

object ( ExplainOptions )

اختیاری. گزینه های مربوط به پرس و جو را توضیح دهید. در صورت تنظیم، آمار پرس و جو اضافی برگردانده خواهد شد. در غیر این صورت، فقط نتایج پرس و جو برگردانده می شود.

فیلد اتحادیه query_type . پرس و جو برای اجرا. query_type فقط می تواند یکی از موارد زیر باشد:
structuredAggregationQuery

object ( StructuredAggregationQuery )

یک پرس و جو تجمع

اتحاد فیلد consistency_selector . حالت سازگاری برای پرس و جو، به طور پیش فرض سازگاری قوی است. consistency_selector تنها می تواند یکی از موارد زیر باشد:
transaction

string ( bytes format)

تجمیع را در یک تراکنش فعال از قبل اجرا کنید.

مقدار در اینجا شناسه تراکنش مات برای اجرای پرس و جو در آن است.

رشته ای با کد base64.

newTransaction

object ( TransactionOptions )

یک تراکنش جدید را به عنوان بخشی از پرس و جو شروع می کند که پیش فرض آن فقط خواندنی است.

شناسه تراکنش جدید به عنوان اولین پاسخ در جریان بازگردانده می شود.

readTime

string ( Timestamp format)

پرس و جو را در مهر زمانی داده شده اجرا می کند.

این باید یک مهر زمانی دقیق میکروثانیه در یک ساعت گذشته باشد، یا اگر بازیابی نقطه در زمان فعال باشد، می‌تواند یک مهر زمانی کامل در 7 روز گذشته باشد.

مهر زمانی در قالب RFC3339 UTC "Zulu"، با وضوح نانوثانیه و حداکثر نه رقم کسری. مثال‌ها: "2014-10-02T15:01:23Z" و "2014-10-02T15:01:23.045123456Z" .

بدن پاسخگو

پاسخ برای Firestore.RunAggregationQuery .

در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی داده هایی با ساختار زیر است:

نمایندگی JSON
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
زمینه های
result

object ( AggregationResult )

یک نتیجه تجمع واحد.

هنگام گزارش پیشرفت جزئی وجود ندارد.

transaction

string ( bytes format)

معامله ای که به عنوان بخشی از این درخواست آغاز شد.

فقط در اولین پاسخ زمانی که درخواست برای شروع یک تراکنش جدید درخواست شده باشد.

رشته ای با کد base64.

readTime

string ( Timestamp format)

زمانی که نتیجه کل محاسبه شد. این همیشه به طور یکنواخت در حال افزایش است. در این مورد، نتایج قبلی AggregationResult در جریان نتیجه تضمین می شود که بین readTime و این یکی تغییر نکرده باشند.

اگر پرس و جو نتیجه ای نداشته باشد، پاسخی با readTime و بدون result ارسال می شود و این نشان دهنده زمانی است که پرس و جو اجرا شده است.

مهر زمانی در قالب RFC3339 UTC "Zulu"، با وضوح نانوثانیه و حداکثر نه رقم کسری. مثال‌ها: "2014-10-02T15:01:23Z" و "2014-10-02T15:01:23.045123456Z" .

explainMetrics

object ( ExplainMetrics )

پرس و جو برای توضیح معیارها این تنها زمانی وجود دارد که RunAggregationQueryRequest.explain_options ارائه شده باشد، و تنها یک بار با آخرین پاسخ در جریان ارسال می شود.

محدوده مجوز

به یکی از حوزه های OAuth زیر نیاز دارد:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

برای اطلاعات بیشتر، به نمای کلی احراز هویت مراجعه کنید.

StructuredAggregationQuery

پرس و جوی Firestore برای اجرای یک تجمیع روی یک StructuredQuery .

نمایندگی JSON
{
  "aggregations": [
    {
      object (Aggregation)
    }
  ],

  // Union field query_type can be only one of the following:
  "structuredQuery": {
    object (StructuredQuery)
  }
  // End of list of possible types for union field query_type.
}
زمینه های
aggregations[]

object ( Aggregation )

اختیاری. مجموعه‌ای از تجمیع‌ها برای اعمال بر روی نتایج structuredQuery .

نیاز دارد:

  • حداقل یک و حداکثر پنج تجمیع در هر پرس و جو.
فیلد اتحادیه query_type . پرس و جو پایه برای جمع آوری. query_type فقط می تواند یکی از موارد زیر باشد:
structuredQuery

object ( StructuredQuery )

پرس و جوی ساختاریافته تو در تو.

تجمع

مجموعه ای را تعریف می کند که یک نتیجه واحد ایجاد می کند.

نمایندگی JSON
{
  "alias": string,

  // Union field operator can be only one of the following:
  "count": {
    object (Count)
  },
  "sum": {
    object (Sum)
  },
  "avg": {
    object (Avg)
  }
  // End of list of possible types for union field operator.
}
زمینه های
alias

string

اختیاری. نام اختیاری فیلد برای ذخیره نتیجه تجمیع در.

اگر ارائه نشده باشد، Firestore یک نام پیش‌فرض را به دنبال field_<incremental_id++> . مثلا:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2),
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*)
OVER (
  ...
);

تبدیل می شود:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2) AS field_1,
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*) AS field_2
OVER (
  ...
);

نیاز دارد:

  • باید در همه نام های مستعار انباشته منحصر به فرد باشد.
  • مطابق با محدودیت های document field name .
operator میدان اتحادیه نوع تجمیع برای انجام، مورد نیاز. operator فقط می تواند یکی از موارد زیر باشد:
count

object ( Count )

جمع کننده شمارش.

sum

object ( Sum )

جمع کننده جمع.

avg

object ( Avg )

جمع کننده متوسط.

شمردن

تعداد اسنادی که با درخواست مطابقت دارند.

تابع تجمیع COUNT(*) روی کل سند عمل می کند، بنابراین نیازی به مرجع فیلد ندارد.

نمایندگی JSON
{
  "upTo": string
}
زمینه های
upTo

string ( Int64Value format)

اختیاری. محدودیت اختیاری در حداکثر تعداد اسناد برای شمارش.

این روشی را برای تعیین حد بالایی در تعداد اسناد برای اسکن، محدود کردن تأخیر و هزینه فراهم می‌کند.

Unspecified به عنوان بدون محدودیت تفسیر می شود.

مثال سطح بالا:

AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );

نیاز دارد:

  • در صورت وجود باید بزرگتر از صفر باشد.

مجموع

مجموع مقادیر فیلد درخواستی

  • فقط مقادیر عددی جمع می شوند. تمام مقادیر غیر عددی از جمله NULL نادیده گرفته می شوند.

  • اگر مقادیر تجمیع شده حاوی NaN باشد، NaN برمی گرداند. ریاضیات بی نهایت از استانداردهای IEEE-754 پیروی می کند.

  • اگر مجموعه مقدار تجمیع شده خالی باشد، 0 را برمی گرداند.

  • اگر همه اعداد جمع‌آوری‌شده اعداد صحیح باشند و حاصل جمع سرریز نشود، یک عدد صحیح 64 بیتی را برمی‌گرداند. در غیر این صورت، نتیجه به صورت دوبل برگردانده می شود. توجه داشته باشید که حتی اگر همه مقادیر جمع‌آوری شده اعداد صحیح باشند، اگر نتواند در یک عدد صحیح امضا شده 64 بیتی قرار گیرد، نتیجه به صورت دوبرابر برگردانده می‌شود. وقتی این اتفاق می افتد، مقدار برگشتی دقت خود را از دست می دهد.

  • هنگامی که جریان پایین رخ می دهد، تجمع ممیز شناور غیر قطعی است. این بدان معنی است که اجرای مکرر یک پرس و جو بدون هیچ تغییری در مقادیر اساسی می تواند نتایج کمی متفاوت در هر بار ایجاد کند. در این موارد، مقادیر باید به صورت اعداد صحیح روی اعداد ممیز شناور ذخیره شوند.

نمایندگی JSON
{
  "field": {
    object (FieldReference)
  }
}
زمینه های
field

object ( FieldReference )

میدانی برای تجمیع

میانگین

میانگین مقادیر فیلد درخواستی

  • فقط مقادیر عددی جمع می شوند. تمام مقادیر غیر عددی از جمله NULL نادیده گرفته می شوند.

  • اگر مقادیر تجمیع شده حاوی NaN باشد، NaN برمی گرداند. ریاضیات بی نهایت از استانداردهای IEEE-754 پیروی می کند.

  • اگر مجموعه مقدار تجمیع شده خالی باشد، NULL برمی‌گرداند.

  • همیشه نتیجه را به صورت دوبل برمی گرداند.

نمایندگی JSON
{
  "field": {
    object (FieldReference)
  }
}
زمینه های
field

object ( FieldReference )

میدانی برای تجمیع

نتیجه تجمع

نتیجه یک سطل منفرد از یک پرس و جو تجمع Firestore.

کلیدهای aggregateFields برای همه نتایج در یک پرس و جو تجمع یکسان است، بر خلاف کوئری های سند که می توانند فیلدهای متفاوتی برای هر نتیجه داشته باشند.

نمایندگی JSON
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
زمینه های
aggregateFields

map (key: string, value: object ( Value ))

نتیجه توابع تجمع، به عنوان مثال: COUNT(*) AS total_docs .

کلید، alias اختصاص داده شده به تابع تجمع در ورودی است و اندازه این نقشه برابر با تعداد توابع تجمع در پرس و جو است.

یک شی حاوی لیستی از "key": value . مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" } .

،

یک پرس و جو تجمع را اجرا می کند.

به جای تولید نتایج Document مانند Firestore.RunQuery ، این API به اجرای یک تجمع برای تولید یک سری از AggregationResult سمت سرور اجازه می دهد.

مثال سطح بالا:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );

درخواست HTTP

POST https://firestore.googleapis.com/v1beta1/{parent=projects/*/databases/*/documents}:runAggregationQuery

URL از دستور GRPC Transcoding استفاده می کند.

پارامترهای مسیر

مولفه های
parent

string

ضروری. نام منبع والد در قالب: projects/{projectId}/databases/{databaseId}/documents or projects/{projectId}/databases/{databaseId}/documents/{document_path} . به عنوان مثال: projects/my-project/databases/my-database/documents /اسناد یا projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

درخواست بدن

بدنه درخواست حاوی داده هایی با ساختار زیر است:

نمایندگی JSON
{
  "explainOptions": {
    object (ExplainOptions)
  },

  // Union field query_type can be only one of the following:
  "structuredAggregationQuery": {
    object (StructuredAggregationQuery)
  }
  // End of list of possible types for union field query_type.

  // Union field consistency_selector can be only one of the following:
  "transaction": string,
  "newTransaction": {
    object (TransactionOptions)
  },
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
زمینه های
explainOptions

object ( ExplainOptions )

اختیاری. گزینه های مربوط به پرس و جو را توضیح دهید. در صورت تنظیم، آمار پرس و جو اضافی برگردانده خواهد شد. در غیر این صورت، فقط نتایج پرس و جو برگردانده می شود.

فیلد اتحادیه query_type . پرس و جو برای اجرا. query_type فقط می تواند یکی از موارد زیر باشد:
structuredAggregationQuery

object ( StructuredAggregationQuery )

یک پرس و جو تجمع

اتحاد فیلد consistency_selector . حالت سازگاری برای پرس و جو، به طور پیش فرض سازگاری قوی است. consistency_selector تنها می تواند یکی از موارد زیر باشد:
transaction

string ( bytes format)

تجمیع را در یک تراکنش فعال از قبل اجرا کنید.

مقدار در اینجا شناسه تراکنش مات برای اجرای پرس و جو در آن است.

رشته ای با کد base64.

newTransaction

object ( TransactionOptions )

یک تراکنش جدید را به عنوان بخشی از پرس و جو شروع می کند که پیش فرض آن فقط خواندنی است.

شناسه تراکنش جدید به عنوان اولین پاسخ در جریان بازگردانده می شود.

readTime

string ( Timestamp format)

پرس و جو را در مهر زمانی داده شده اجرا می کند.

این باید یک مهر زمانی دقیق میکروثانیه در یک ساعت گذشته باشد، یا اگر بازیابی نقطه در زمان فعال باشد، می‌تواند یک مهر زمانی کامل در 7 روز گذشته باشد.

مهر زمانی در قالب RFC3339 UTC "Zulu"، با وضوح نانوثانیه و حداکثر نه رقم کسری. مثال‌ها: "2014-10-02T15:01:23Z" و "2014-10-02T15:01:23.045123456Z" .

بدن پاسخگو

پاسخ برای Firestore.RunAggregationQuery .

در صورت موفقیت آمیز بودن، بدنه پاسخ حاوی داده هایی با ساختار زیر است:

نمایندگی JSON
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
زمینه های
result

object ( AggregationResult )

یک نتیجه تجمع واحد.

هنگام گزارش پیشرفت جزئی وجود ندارد.

transaction

string ( bytes format)

معامله ای که به عنوان بخشی از این درخواست آغاز شد.

فقط در اولین پاسخ زمانی که درخواست برای شروع یک تراکنش جدید درخواست شده باشد.

رشته ای با کد base64.

readTime

string ( Timestamp format)

زمانی که نتیجه کل محاسبه شد. این همیشه به طور یکنواخت در حال افزایش است. در این مورد، نتایج قبلی AggregationResult در جریان نتیجه تضمین می شود که بین readTime و این یکی تغییر نکرده باشند.

اگر پرس و جو نتیجه ای نداشته باشد، پاسخی با readTime و بدون result ارسال می شود و این نشان دهنده زمانی است که پرس و جو اجرا شده است.

مهر زمانی در قالب RFC3339 UTC "Zulu"، با وضوح نانوثانیه و حداکثر نه رقم کسری. مثال‌ها: "2014-10-02T15:01:23Z" و "2014-10-02T15:01:23.045123456Z" .

explainMetrics

object ( ExplainMetrics )

پرس و جو برای توضیح معیارها این تنها زمانی وجود دارد که RunAggregationQueryRequest.explain_options ارائه شده باشد، و تنها یک بار با آخرین پاسخ در جریان ارسال می شود.

محدوده مجوز

به یکی از حوزه های OAuth زیر نیاز دارد:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

برای اطلاعات بیشتر، به نمای کلی احراز هویت مراجعه کنید.

StructuredAggregationQuery

پرس و جوی Firestore برای اجرای یک تجمیع روی یک StructuredQuery .

نمایندگی JSON
{
  "aggregations": [
    {
      object (Aggregation)
    }
  ],

  // Union field query_type can be only one of the following:
  "structuredQuery": {
    object (StructuredQuery)
  }
  // End of list of possible types for union field query_type.
}
زمینه های
aggregations[]

object ( Aggregation )

اختیاری. مجموعه‌ای از تجمیع‌ها برای اعمال بر روی نتایج structuredQuery .

نیاز دارد:

  • حداقل یک و حداکثر پنج تجمیع در هر پرس و جو.
فیلد اتحادیه query_type . پرس و جو پایه برای جمع آوری. query_type فقط می تواند یکی از موارد زیر باشد:
structuredQuery

object ( StructuredQuery )

پرس و جوی ساختاریافته تو در تو.

تجمع

مجموعه ای را تعریف می کند که یک نتیجه واحد ایجاد می کند.

نمایندگی JSON
{
  "alias": string,

  // Union field operator can be only one of the following:
  "count": {
    object (Count)
  },
  "sum": {
    object (Sum)
  },
  "avg": {
    object (Avg)
  }
  // End of list of possible types for union field operator.
}
زمینه های
alias

string

اختیاری. نام اختیاری فیلد برای ذخیره نتیجه تجمیع در.

اگر ارائه نشده باشد، Firestore یک نام پیش‌فرض را به دنبال field_<incremental_id++> . مثلا:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2),
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*)
OVER (
  ...
);

تبدیل می شود:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2) AS field_1,
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*) AS field_2
OVER (
  ...
);

نیاز دارد:

  • باید در همه نام های مستعار انباشته منحصر به فرد باشد.
  • مطابق با محدودیت های document field name .
operator میدان اتحادیه نوع تجمیع برای انجام، مورد نیاز. operator فقط می تواند یکی از موارد زیر باشد:
count

object ( Count )

جمع کننده شمارش.

sum

object ( Sum )

جمع کننده مجموع.

avg

object ( Avg )

جمع کننده متوسط.

شمردن

تعداد اسنادی که با درخواست مطابقت دارند.

تابع تجمیع COUNT(*) روی کل سند عمل می کند، بنابراین نیازی به مرجع فیلد ندارد.

نمایندگی JSON
{
  "upTo": string
}
زمینه های
upTo

string ( Int64Value format)

اختیاری. محدودیت اختیاری در حداکثر تعداد اسناد برای شمارش.

این روشی را برای تعیین حد بالایی در تعداد اسناد برای اسکن، محدود کردن تأخیر و هزینه فراهم می‌کند.

Unspecified به عنوان بدون محدودیت تفسیر می شود.

مثال سطح بالا:

AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );

نیاز دارد:

  • در صورت وجود باید بزرگتر از صفر باشد.

مجموع

مجموع مقادیر فیلد درخواستی

  • فقط مقادیر عددی جمع می شوند. تمام مقادیر غیر عددی از جمله NULL نادیده گرفته می شوند.

  • اگر مقادیر تجمیع شده حاوی NaN باشد، NaN برمی گرداند. ریاضیات بی نهایت از استانداردهای IEEE-754 پیروی می کند.

  • اگر مجموعه مقدار تجمیع شده خالی باشد، 0 را برمی گرداند.

  • اگر همه اعداد جمع‌آوری‌شده اعداد صحیح باشند و حاصل جمع سرریز نشود، یک عدد صحیح 64 بیتی را برمی‌گرداند. در غیر این صورت، نتیجه به صورت دوبل برگردانده می شود. توجه داشته باشید که حتی اگر همه مقادیر جمع‌آوری شده اعداد صحیح باشند، اگر نتواند در یک عدد صحیح امضا شده 64 بیتی قرار گیرد، نتیجه به صورت دوبرابر برگردانده می‌شود. وقتی این اتفاق می افتد، مقدار برگشتی دقت خود را از دست می دهد.

  • هنگامی که جریان پایین رخ می دهد، تجمع ممیز شناور غیر قطعی است. این بدان معنی است که اجرای مکرر یک پرس و جو بدون هیچ تغییری در مقادیر اساسی می تواند نتایج کمی متفاوت در هر بار ایجاد کند. در این موارد، مقادیر باید به صورت اعداد صحیح روی اعداد ممیز شناور ذخیره شوند.

نمایندگی JSON
{
  "field": {
    object (FieldReference)
  }
}
زمینه های
field

object ( FieldReference )

میدانی برای تجمیع

میانگین

میانگین مقادیر فیلد درخواستی

  • فقط مقادیر عددی جمع می شوند. تمام مقادیر غیر عددی از جمله NULL نادیده گرفته می شوند.

  • اگر مقادیر تجمیع شده حاوی NaN باشد، NaN برمی گرداند. ریاضیات بی نهایت از استانداردهای IEEE-754 پیروی می کند.

  • اگر مجموعه مقدار تجمیع شده خالی باشد، NULL برمی‌گرداند.

  • همیشه نتیجه را به صورت دوبل برمی گرداند.

نمایندگی JSON
{
  "field": {
    object (FieldReference)
  }
}
زمینه های
field

object ( FieldReference )

میدانی برای تجمیع

نتیجه تجمع

نتیجه یک سطل منفرد از یک پرس و جو تجمع Firestore.

کلیدهای aggregateFields برای همه نتایج در یک پرس و جو تجمع یکسان است، بر خلاف کوئری های سند که می توانند فیلدهای متفاوتی برای هر نتیجه داشته باشند.

نمایندگی JSON
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
زمینه های
aggregateFields

map (key: string, value: object ( Value ))

نتیجه توابع تجمع، به عنوان مثال: COUNT(*) AS total_docs .

کلید، alias اختصاص داده شده به تابع تجمع در ورودی است و اندازه این نقشه برابر با تعداد توابع تجمع در پرس و جو است.

یک شی حاوی لیستی از "key": value . مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" } .