Method: projects.databases.documents.runAggregationQuery

एग्रीगेशन क्वेरी चलाता है.

यह एपीआई, Firestore.RunQuery जैसे Document नतीजे बनाने के बजाय, AggregationResult सर्वर साइड की सीरीज़ बनाने के लिए एग्रीगेशन को चलाने की अनुमति देता है.

हाई-लेवल का उदाहरण:

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

एचटीटीपी अनुरोध

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

यह यूआरएल gRPC ट्रांसकोडिंग सिंटैक्स का इस्तेमाल करता है.

पाथ के पैरामीटर

पैरामीटर
parent

string

ज़रूरी है. पैरंट रिसॉर्स का नाम. फ़ॉर्मैट: projects/{projectId}/databases/{databaseId}/documents या projects/{projectId}/databases/{databaseId}/documents/{document_path}. उदाहरण के लिए: projects/my-project/databases/my-database/documents या projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

अनुरोध का मुख्य भाग

अनुरोध के मुख्य हिस्से में, इस तरह का डेटा शामिल होता है:

जेएसओएन के काेड में दिखाना 
{
  "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)

दिए गए टाइमस्टैंप पर क्वेरी को एक्ज़ीक्यूट करता है.

यह पिछले एक घंटे के अंदर का माइक्रोसेकंड का सटीक टाइमस्टैंप होना चाहिए. इसके अलावा, अगर पॉइंट-इन-टाइम रिकवरी चालू है, तो यह पिछले सात दिनों में पूरे मिनट का टाइमस्टैंप भी हो सकता है.

RFC3339 यूटीसी "ज़ुलु" फ़ॉर्मैट में एक टाइमस्टैंप, जिसमें नैनोसेकंड का रिज़ॉल्यूशन और नौ फ़्रैक्शनल अंक हो सकते हैं. उदाहरण: "2014-10-02T15:01:23Z" और "2014-10-02T15:01:23.045123456Z".

जवाब का मुख्य भाग

Firestore.RunAggregationQuery के लिए रिस्पॉन्स.

अगर एपीआई सही से जुड़ जाता है, ताे जवाब के मुख्य भाग में नीचे दिए गए स्ट्रक्चर शामिल होता है.

जेएसओएन के काेड में दिखाना 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
फ़ील्ड
result

object (AggregationResult)

एग्रीगेशन का सिर्फ़ एक नतीजा.

आंशिक प्रगति की रिपोर्ट करते समय मौजूद नहीं.
transaction

string (bytes format)

वह लेन-देन, जो इस अनुरोध के तहत शुरू किया गया था.

पहली बार जवाब देने पर सिर्फ़ तब मौजूद होगा, जब नया लेन-देन शुरू करने के अनुरोध का अनुरोध किया गया हो.

base64 कोड में बदली गई स्ट्रिंग.
readTime

string (Timestamp format)

वह समय जब सभी नतीजों का हिसाब लगाया गया था. यह हमेशा एक ही तरह से बढ़ता रहता है. इस मामले में, नतीजे की स्ट्रीम में मौजूद पिछले Aggregatनतीजे में, यह गारंटी मिलती है कि वह readTime और इसके बीच में कोई बदलाव नहीं करेगा.

अगर क्वेरी का कोई नतीजा नहीं मिलता है, तो readTime वाला जवाब भेजा जाएगा और कोई result नहीं भेजा जाएगा. इससे पता चलता है कि क्वेरी कब चलाई गई थी.

RFC3339 यूटीसी "ज़ुलु" फ़ॉर्मैट में एक टाइमस्टैंप, जिसमें नैनोसेकंड का रिज़ॉल्यूशन और नौ फ़्रैक्शनल अंक हो सकते हैं. उदाहरण: "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

StructuredQuery पर एग्रीगेशन चलाने के लिए Firestore क्वेरी.

जेएसओएन के काेड में दिखाना 
{
  "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)

नेस्ट की गई स्ट्रक्चर्ड क्वेरी.

एक साथ दिखाना

ऐसे एग्रीगेशन के बारे में बताता है जो एक ही नतीजा देता है.

जेएसओएन के काेड में दिखाना 
{
  "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(*) एग्रीगेशन फ़ंक्शन, पूरे दस्तावेज़ पर काम करता है. इसलिए, इसे किसी फ़ील्ड रेफ़रंस की ज़रूरत नहीं होती.

जेएसओएन के काेड में दिखाना 
{
  "upTo": string
}
फ़ील्ड
upTo

string (Int64Value format)

ज़रूरी नहीं. गिनती के लिए दस्तावेज़ों की ज़्यादा से ज़्यादा संख्या की वैकल्पिक सीमा.

इसकी मदद से, स्कैन करने के लिए दस्तावेज़ों की संख्या के लिए ऊपरी सीमा सेट की जा सकती है. साथ ही, शिपिंग के लिए लगने वाले समय को कम किया जा सकता है और शिपिंग के लिए लगने वाला शुल्क कम किया जा सकता है.

अनिर्दिष्ट का अर्थ कोई सीमा नहीं है.

हाई-लेवल का उदाहरण:

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

ज़रूरी है:

  • मौजूद होने पर शून्य से ज़्यादा होना चाहिए.

कुल योग

अनुरोध किए गए फ़ील्ड की वैल्यू का योग.

  • सिर्फ़ अंकों वाली वैल्यू को एग्रीगेट किया जाएगा. NULL के साथ-साथ बिना संख्या वाली सभी वैल्यू छोड़ दी जाती हैं.

  • अगर एग्रीगेट की गई वैल्यू में NaN है, तो NaN दिखाता है. इनफ़िनिटी मैथ IEEE-754 के मानकों का पालन करता है.

  • अगर एग्रीगेट की गई वैल्यू का सेट खाली है, तो यह 0 दिखाता है.

  • अगर सभी एग्रीगेट की गई संख्याएं पूर्णांक होती हैं और कुल योग के नतीजे ओवरफ़्लो नहीं होते हैं, तो 64-बिट पूर्णांक लौटाता है. ऐसा न होने पर, नतीजा डबल के तौर पर दिखता है. ध्यान दें कि भले ही सभी एग्रीगेट की गई वैल्यू पूर्णांक हों, लेकिन नतीजे को डबल के तौर पर दिखाया जाता है. हालांकि, ऐसा तब ही होता है, जब यह 64-बिट के साइन किए गए इंटीजर के अंदर फ़िट न हो पाए. ऐसा होने पर, वापस की गई वैल्यू सटीक नहीं होगी.

  • जब अंडरफ़्लो होता है, तो फ़्लोटिंग-पॉइंट एग्रीगेशन, तय नहीं होता. इसका मतलब है कि मौजूदा वैल्यू में बदलाव किए बिना, एक ही क्वेरी को बार-बार चलाने से हर बार थोड़े अलग नतीजे मिल सकते हैं. ऐसे मामलों में, वैल्यू को फ़्लोटिंग-पॉइंट नंबर पर पूर्णांक के तौर पर स्टोर किया जाना चाहिए.

जेएसओएन के काेड में दिखाना 
{
  "field": {
    object (FieldReference)
  }
}
फ़ील्ड
field

object (FieldReference)

वह फ़ील्ड जिसके लिए डेटा इकट्ठा करना है.

Avg

अनुरोध किए गए फ़ील्ड की वैल्यू का औसत.

  • सिर्फ़ अंकों वाली वैल्यू को एग्रीगेट किया जाएगा. NULL के साथ-साथ बिना संख्या वाली सभी वैल्यू छोड़ दी जाती हैं.

  • अगर एग्रीगेट की गई वैल्यू में NaN है, तो NaN दिखाता है. इनफ़िनिटी मैथ IEEE-754 के मानकों का पालन करता है.

  • अगर एग्रीगेट की गई वैल्यू का सेट खाली है, तो NULL दिखाता है.

  • नतीजे को हमेशा डबल के तौर पर दिखाता है.

जेएसओएन के काेड में दिखाना 
{
  "field": {
    object (FieldReference)
  }
}
फ़ील्ड
field

object (FieldReference)

वह फ़ील्ड जिसके लिए डेटा इकट्ठा करना है.

AggregationResult

Firestore एग्रीगेशन क्वेरी से एक बकेट का नतीजा.

एग्रीगेशन क्वेरी में सभी नतीजों के लिए aggregateFields की कुंजियां एक जैसी होती हैं. यह दस्तावेज़ क्वेरी से अलग होती है, जिसमें हर नतीजे के लिए अलग-अलग फ़ील्ड हो सकते हैं.

जेएसओएन के काेड में दिखाना 
{
  "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" }.