Method: projects.databases.documents.runAggregationQuery

Chạy một truy vấn tổng hợp.

Thay vì tạo kết quả Document như Firestore.RunQuery, API này cho phép chạy tổng hợp để tạo một loạt AggregationResult phía máy chủ.

Ví dụ ở cấp cao:

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

yêu cầu HTTP

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

URL sử dụng cú pháp Chuyển mã gRPC.

Tham số đường dẫn

Thông số
parent

string

Bắt buộc. Tên tài nguyên mẹ. Ở định dạng: projects/{projectId}/databases/{databaseId}/documents hoặc projects/{projectId}/databases/{databaseId}/documents/{document_path}. Ví dụ: projects/my-project/databases/my-database/documents hoặc projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng 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.
}
Trường
explainOptions

object (ExplainOptions)

Không bắt buộc. Giải thích các tuỳ chọn cho truy vấn. Nếu được đặt, số liệu thống kê truy vấn bổ sung sẽ được trả về. Nếu không, hệ thống sẽ chỉ trả về kết quả truy vấn.
Trường kết hợp query_type. Truy vấn cần chạy. query_type chỉ có thể là một trong những trạng thái sau đây:
structuredAggregationQuery

object (StructuredAggregationQuery)

Truy vấn tổng hợp.
Trường kết hợp consistency_selector. Chế độ nhất quán cho truy vấn, mặc định là nhất quán cao. consistency_selector chỉ có thể là một trong những trạng thái sau đây:
transaction

string (bytes format)

Chạy tính năng tổng hợp trong một giao dịch đang hoạt động.

Giá trị ở đây là mã giao dịch mờ để thực thi truy vấn.

Chuỗi được mã hoá base64.
newTransaction

object (TransactionOptions)

Bắt đầu một giao dịch mới trong truy vấn, chế độ mặc định là chỉ có thể đọc.

Mã giao dịch mới sẽ được trả về dưới dạng phản hồi đầu tiên trong luồng.
readTime

string (Timestamp format)

Thực thi truy vấn tại dấu thời gian cụ thể.

Đây phải là một dấu thời gian có độ chính xác là micrô giây trong vòng 1 giờ qua, hoặc nếu tính năng Khôi phục tại một thời điểm đang bật, thì đây cũng có thể là dấu thời gian cả phút trong vòng 7 ngày qua.

Dấu thời gian theo múi giờ "Zulu" RFC3339 (giờ UTC) với độ phân giải nano giây và lên đến 9 chữ số phân số. Ví dụ: "2014-10-02T15:01:23Z" và "2014-10-02T15:01:23.045123456Z".

Nội dung phản hồi

Phản hồi cho Firestore.RunAggregationQuery.

Nếu thành công, nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "result": {
    object (AggregationResult)
  },
  "transaction": string,
  "readTime": string,
  "explainMetrics": {
    object (ExplainMetrics)
  }
}
Trường
result

object (AggregationResult)

Một kết quả tổng hợp duy nhất.

Không xuất hiện khi báo cáo một phần tiến trình.
transaction

string (bytes format)

Giao dịch đã bắt đầu theo yêu cầu này.

Chỉ xuất hiện trong phản hồi đầu tiên khi yêu cầu được yêu cầu bắt đầu một giao dịch mới.

Chuỗi được mã hoá base64.
readTime

string (Timestamp format)

Thời điểm tính toán kết quả tổng hợp. Tỷ lệ này luôn tăng đơn điệu; trong trường hợp này, SyntheticResult trước đó trong luồng kết quả được đảm bảo không thay đổi giữa readTime và kết quả này.

Nếu truy vấn không trả về kết quả nào, thì phản hồi có readTime và không có result sẽ được gửi, đồng thời thể hiện thời gian chạy truy vấn.

Dấu thời gian theo múi giờ "Zulu" RFC3339 (giờ UTC) với độ phân giải nano giây và lên đến 9 chữ số phân số. Ví dụ: "2014-10-02T15:01:23Z" và "2014-10-02T15:01:23.045123456Z".
explainMetrics

object (ExplainMetrics)

Truy vấn giải thích về các chỉ số. Điều này chỉ có khi RunAggregationQueryRequest.explain_options được cung cấp và chỉ được gửi một lần cùng với phản hồi cuối cùng trong luồng.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Truy vấn tổng hợp có cấu trúc

Truy vấn trên Firestore để chạy tổng hợp trên StructuredQuery.

Biểu diễn dưới dạng 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.
}
Trường
aggregations[]

object (Aggregation)

Không bắt buộc. Chuỗi các hàm tổng hợp cần áp dụng cho kết quả của structuredQuery.

Yêu cầu:

  • Tối thiểu một và tối đa năm dữ liệu tổng hợp cho mỗi truy vấn.
Trường kết hợp query_type. Truy vấn cơ sở để tổng hợp. query_type chỉ có thể là một trong những trạng thái sau đây:
structuredQuery

object (StructuredQuery)

Truy vấn có cấu trúc lồng nhau.

Tổng hợp

Xác định dữ liệu tổng hợp tạo ra một kết quả duy nhất.

Biểu diễn dưới dạng 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.
}
Trường
alias

string

Không bắt buộc. Tên không bắt buộc của trường để lưu trữ kết quả tổng hợp.

Nếu không được cung cấp, Firestore sẽ chọn một tên mặc định theo định dạng field_<incremental_id++>. Ví dụ:

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 (
  ...
);

trở thành:

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 (
  ...
);

Yêu cầu:

  • Phải là duy nhất trên tất cả các bí danh tổng hợp.
  • Tuân thủ document field name giới hạn.
Trường kết hợp operator. Loại tổng hợp cần thực hiện, bắt buộc. operator chỉ có thể là một trong những trạng thái sau đây:
count

object (Count)

Đơn vị tổng hợp số lượng.
sum

object (Sum)

Trang web tổng hợp số liệu.
avg

object (Avg)

Trang web tổng hợp trung bình.

Số lượng

Số lượng tài liệu khớp với truy vấn.

Hàm tổng hợp COUNT(*) hoạt động trên toàn bộ tài liệu nên không cần tham chiếu trường.

Biểu diễn dưới dạng JSON 
{
  "upTo": string
}
Trường
upTo

string (Int64Value format)

Không bắt buộc. Quy tắc ràng buộc không bắt buộc về số lượng tài liệu tối đa cần đếm.

Đây là một cách để đặt giới hạn trên cho số lượng tài liệu cần quét, hạn chế độ trễ và chi phí.

Không xác định được hiểu là không có ràng buộc.

Ví dụ ở cấp cao:

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

Yêu cầu:

  • Phải lớn hơn 0 khi hiển thị.

Tổng

Tổng giá trị của trường được yêu cầu.

  • Hệ thống chỉ tổng hợp các giá trị dạng số. Tất cả giá trị không phải số, bao gồm cả NULL, đều bị bỏ qua.

  • Nếu giá trị tổng hợp chứa NaN, hàm sẽ trả về NaN. Toán học của Infinity tuân theo tiêu chuẩn IEEE-754.

  • Nếu tập hợp giá trị tổng hợp trống, trả về 0.

  • Trả về số nguyên 64 bit nếu tất cả các số tổng hợp là số nguyên và kết quả tổng không bị tràn. Nếu không, kết quả sẽ được trả về dưới dạng kép. Lưu ý rằng ngay cả khi tất cả giá trị tổng hợp đều là số nguyên, kết quả vẫn được trả về dưới dạng số kép nếu không thể nằm trong phạm vi số nguyên 64 bit đã ký. Khi điều này xảy ra, giá trị được trả về sẽ mất độ chính xác.

  • Khi xảy ra hiện tượng sụt giảm, phương pháp tổng hợp dấu phẩy động là không xác định. Điều này có nghĩa là mỗi lần chạy cùng một truy vấn mà không có bất kỳ thay đổi nào đối với các giá trị cơ bản có thể cho ra kết quả hơi khác nhau. Trong những trường hợp đó, các giá trị phải được lưu trữ dưới dạng số nguyên thay vì số dấu phẩy động.

Biểu diễn dưới dạng JSON 
{
  "field": {
    object (FieldReference)
  }
}
Trường
field

object (FieldReference)

Trường để tổng hợp.

Avg

Giá trị trung bình của các trường được yêu cầu.

  • Hệ thống chỉ tổng hợp các giá trị dạng số. Tất cả giá trị không phải số, bao gồm cả NULL, đều bị bỏ qua.

  • Nếu giá trị tổng hợp chứa NaN, hàm sẽ trả về NaN. Toán học của Infinity tuân theo tiêu chuẩn IEEE-754.

  • Nếu tập hợp giá trị tổng hợp trống, trả về NULL.

  • Luôn trả về kết quả dưới dạng kép.

Biểu diễn dưới dạng JSON 
{
  "field": {
    object (FieldReference)
  }
}
Trường
field

object (FieldReference)

Trường để tổng hợp.

Kết quả tổng hợp

Kết quả của một bộ chứa trong một truy vấn tổng hợp trên Firestore.

Khoá của aggregateFields là giống nhau cho tất cả kết quả trong một truy vấn tổng hợp, không giống như các truy vấn tài liệu có thể có các trường khác nhau cho mỗi kết quả.

Biểu diễn dưới dạng JSON 
{
  "aggregateFields": {
    string: {
      object (Value)
    },
    ...
  }
}
Trường
aggregateFields

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

Kết quả của các hàm tổng hợp, ví dụ: COUNT(*) AS total_docs.

Khoá là alias được gán cho hàm tổng hợp khi nhập vào và kích thước của tệp ánh xạ này bằng số hàm tổng hợp trong truy vấn.

Một đối tượng chứa danh sách các cặp "key": value. Ví dụ: { "name": "wrench", "mass": "1.3kg", "count": "3" }.