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

พารามิเตอร์เส้นทาง

พารามิเตอร์
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)

เรียกใช้การรวมภายในธุรกรรมที่ใช้งานอยู่แล้ว

ค่าในส่วนนี้คือรหัสธุรกรรมที่ไม่ชัดเจนสำหรับดำเนินการค้นหา

สตริงที่เข้ารหัสฐาน 64
newTransaction

object (TransactionOptions)

เริ่มธุรกรรมใหม่ในการค้นหา โดยมีค่าเริ่มต้นเป็นแบบอ่านอย่างเดียว

ระบบจะแสดงรหัสธุรกรรมใหม่เป็นคำตอบแรกในสตรีม
readTime

string (Timestamp format)

ดำเนินการค้นหาตามการประทับเวลาที่ระบุ

โดยต้องเป็นการประทับเวลาที่แม่นยำในระดับไมโครวินาทีภายใน 1 ชั่วโมงที่ผ่านมา หรือหากเปิดใช้การกู้คืนช่วงเวลาอยู่ ก็อาจเป็นการประทับเวลาแบบเต็มนาทีภายในช่วง 7 วันที่ผ่านมาด้วย

การประทับเวลาจะอยู่ในรูปแบบ RFC3339 UTC "Zulu" ที่มีความละเอียดระดับนาโนวินาทีและมีตัวเลขที่เป็นเศษส่วนได้สูงสุด 9 หลัก ตัวอย่าง: "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)

ธุรกรรมที่เริ่มต้นโดยเป็นส่วนหนึ่งของคำขอนี้

มีอยู่ในการตอบกลับครั้งแรกเมื่อคำขอขอให้เริ่มธุรกรรมใหม่เท่านั้น

สตริงที่เข้ารหัสฐาน 64
readTime

string (Timestamp format)

เวลาที่มีการคํานวณผลลัพธ์รวม จะมีปริมาณเพิ่มขึ้นอยู่เสมอ ในกรณีนี้ Aggregation Results ก่อนหน้าในสตรีมผลลัพธ์นี้รับประกันว่าจะไม่มีการเปลี่ยนแปลงระหว่าง readTime กับรายการนี้

หากการค้นหาไม่แสดงผลลัพธ์ ระบบจะตอบกลับด้วย readTime และไม่มี result ซึ่งจะแสดงเวลาที่เรียกใช้การค้นหา

การประทับเวลาจะอยู่ในรูปแบบ RFC3339 UTC "Zulu" ที่มีความละเอียดระดับนาโนวินาทีและมีตัวเลขที่เป็นเศษส่วนได้สูงสุด 9 หลัก ตัวอย่าง: "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

ข้อกำหนด

  • มีการรวมอย่างน้อย 1 รายการและไม่เกิน 5 รายการต่อการค้นหา
ฟิลด์สหภาพ 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 );

ข้อกำหนด

  • ต้องมากกว่า 0 หากมี

ผลรวม

ผลรวมของมูลค่าของช่องที่ขอ

  • ระบบจะรวมเฉพาะค่าที่เป็นตัวเลขเท่านั้น ระบบจะข้ามค่าที่ไม่ใช่ตัวเลขทั้งหมดรวมถึง NULL

  • หากค่ารวมมี NaN ระบบจะแสดงผล NaN Infinity math เป็นไปตามมาตรฐาน IEEE-754

  • หากชุดค่ารวมเป็นค่าว่าง ระบบจะแสดงผลเป็น 0

  • แสดงผลจำนวนเต็ม 64 บิต หากจำนวนที่สรุปรวมทั้งหมดเป็นจำนวนเต็มและผลลัพธ์รวมไม่เกิน มิฉะนั้น ผลลัพธ์จะแสดงเป็นเลขคู่ โปรดทราบว่าแม้ว่าค่ารวมทั้งหมดจะเป็นจำนวนเต็ม แต่ผลลัพธ์จะแสดงค่าเป็นเลขคู่หากไม่สามารถให้พอดีกับจำนวนเต็มแบบมีเครื่องหมาย 64 บิต เมื่อกรณีนี้เกิดขึ้น ค่าที่ส่งกลับจะสูญเสียความแม่นยํา

  • เมื่อเกิดภาวะน้ำล้นเกินกำหนด การรวมจุดลอยตัวจะไม่กำหนด ซึ่งหมายความว่าการเรียกใช้การค้นหาเดียวกันซ้ำๆ โดยไม่มีการเปลี่ยนแปลงค่าที่สำคัญอาจให้ผลลัพธ์ที่แตกต่างกันเล็กน้อยในแต่ละครั้ง ในกรณีดังกล่าว ควรเก็บค่าไว้เป็นจำนวนเต็มเหนือเลขทศนิยม

การแสดง JSON 
{
  "field": {
    object (FieldReference)
  }
}
ช่อง
field

object (FieldReference)

ฟิลด์ที่จะรวบรวมข้อมูล

เฉลี่ย

ค่าเฉลี่ยของช่องที่ขอ

  • ระบบจะรวมเฉพาะค่าที่เป็นตัวเลขเท่านั้น ระบบจะข้ามค่าที่ไม่ใช่ตัวเลขทั้งหมดรวมถึง NULL

  • หากค่ารวมมี NaN ระบบจะแสดงผล NaN Infinity math เป็นไปตามมาตรฐาน IEEE-754

  • หากชุดค่ารวมว่างเปล่า ระบบจะแสดงผล NULL

  • แสดงผลลัพธ์เป็นเลขคู่เสมอ

การแสดง 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" }