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/v1/{parent=projects/*/databases/*/documents}:runAggregationQuery

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של 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

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג 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, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "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)

המועד שבו חושבה התוצאה המצטברת. הערך הזה תמיד גדל באופן מונוטוני. במקרה הזה, מובטח שתוצאת הצבירה הקודמת בזרם התוצאות לא תשתנה בין readTime לבין התוצאה הזו.

אם השאילתה לא מחזירה תוצאות, תישלח תשובה עם readTime וללא result, שמייצגת את השעה שבה השאילתה רצה.

חותמת זמן בפורמט "זולו" RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "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)

זה שינוי אופציונלי. מגבלה אופציונלית על המספר המקסימלי של מסמכים לספירה.

כך אפשר להגדיר גבול עליון למספר המסמכים לסריקה, להגבלת זמן האחזור והעלות.

המשמעות של 'לא צוין' היא 'ללא הגבלה'.

דוגמה לרמה גבוהה:

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

אלה הדרישות שצריך לעמוד בהן:

  • הערך חייב להיות גדול מאפס כשמזינים אותו.

סכום

סכום הערכים של השדה המבוקש.

  • רק ערכים מספריים יצטברו. המערכת תדלג על כל הערכים הלא מספריים, כולל NULL.

  • אם הערכים המצטברים מכילים NaN, הפונקציה מחזירה NaN. מתמטית אינסופית עומדת בתקני IEEE-754.

  • אם קבוצת הערכים הנצברים היא ריקה, הפונקציה מחזירה 0.

  • מחזירה מספר שלם של 64 סיביות אם כל המספרים המצטברים הם מספרים שלמים והתוצאה הסופית לא גולשת. אחרת, התוצאה תוחזר ככפולה. שימו לב שגם אם כל הערכים המצטברים הם מספרים שלמים, התוצאה מוחזרת ככפולה אם היא לא יכולה להתאים בתוך מספר שלם חתום של 64 ביט. במקרה כזה, הערך שיוחזר יאבד את הדיוק.

  • במקרה של תת-זרימה, צבירת נתונים בנקודה צפה (floating-point) אינה דטרמיניסטית. המשמעות היא שאם תריץ את אותה שאילתה שוב ושוב ללא שינויים בערכים הבסיסיים, תוכל להפיק תוצאות מעט שונות בכל פעם. במקרים כאלה, צריך לאחסן את הערכים כמספרים שלמים מעל למספרים עם נקודה צפה (floating-point).

ייצוג JSON 
{
  "field": {
    object (FieldReference)
  }
}
שדות
field

object (FieldReference)

השדה שבו תתבצע צבירה.

Avg

ממוצע הערכים של השדה המבוקש.

  • רק ערכים מספריים יצטברו. המערכת תדלג על כל הערכים הלא מספריים, כולל NULL.

  • אם הערכים המצטברים מכילים NaN, הפונקציה מחזירה NaN. מתמטית אינסופית עומדת בתקני IEEE-754.

  • אם קבוצת הערכים הנצברים ריקה, הפונקציה מחזירה NULL.

  • מחזירה תמיד את התוצאה כ-double.

ייצוג JSON 
{
  "field": {
    object (FieldReference)
  }
}
שדות
field

object (FieldReference)

השדה שבו תתבצע צבירה.

AggregationResult

התוצאה של קטגוריה יחידה משאילתת צבירה של 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" }.