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)

เวลาที่มีการคำนวณผลลัพธ์รวม ซึ่งเพิ่มขึ้นอย่างต่อเนื่อง ในกรณีนี้ AggregationResult ก่อนหน้าในสตรีมผลลัพธ์ในสตรีมผลลัพธ์จะไม่มีการเปลี่ยนแปลงระหว่าง 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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

คำค้นหาการรวมข้อมูลที่มีโครงสร้าง

คำค้นหา 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 รายการต่อการค้นหา 1 รายการ
ช่องการรวม 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 เป็นไปตามมาตรฐาน IEEE-754

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

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

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

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

object (FieldReference)

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

เฉลี่ย

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

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

  • หากค่าที่รวมมี NaN จะแสดงผล NaN คณิตศาสตร์ Infinity เป็นไปตามมาตรฐาน 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" }