집계 쿼리를 실행합니다.
이 API를 사용하면 Firestore.RunQuery
와 같은 Document
결과를 생성하는 대신 집계를 실행하여 일련의 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 |
필수 항목입니다. 상위 리소스 이름입니다. 형식: |
요청 본문
요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.
JSON 표현 |
---|
{ "explainOptions": { object ( |
필드 | |
---|---|
explainOptions |
선택사항입니다. 쿼리의 옵션을 설명합니다. 설정하면 추가 쿼리 통계가 반환됩니다. 그렇지 않으면 쿼리 결과만 반환됩니다. |
통합 필드 query_type . 실행할 쿼리입니다. query_type 은 다음 중 하나여야 합니다. |
|
structuredAggregationQuery |
집계 쿼리입니다. |
통합 필드 consistency_selector . 쿼리의 일관성 모드로, 기본값은 strong consistency입니다. consistency_selector 은 다음 중 하나여야 합니다. |
|
transaction |
이미 활성 상태인 트랜잭션 내에서 집계를 실행합니다. 이 값은 쿼리를 실행할 불투명한 트랜잭션 ID입니다. base64 인코딩 문자열입니다. |
newTransaction |
쿼리의 일부로 새 트랜잭션을 시작합니다. 기본값은 읽기 전용입니다. 새 트랜잭션 ID가 스트림의 첫 번째 응답으로 반환됩니다. |
readTime |
지정된 타임스탬프에 쿼리를 실행합니다. 지난 1시간 이내의 마이크로초 정밀도 타임스탬프여야 합니다. 또는 PITR(point-in-time recovery)이 사용 설정된 경우 지난 7일 이내의 1분짜리 타임스탬프일 수도 있습니다. RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 |
응답 본문
Firestore.RunAggregationQuery
의 응답입니다.
성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.
JSON 표현 |
---|
{ "result": { object ( |
필드 | |
---|---|
result |
단일 집계 결과입니다. 부분 진행 상황을 보고할 때는 표시되지 않습니다. |
transaction |
이 요청의 일부로 시작된 트랜잭션입니다. 요청이 새 트랜잭션의 시작을 요청한 경우에만 첫 번째 응답에 표시됩니다. base64 인코딩 문자열입니다. |
readTime |
집계 결과가 계산된 시간입니다. 이 수치는 항상 단조롭게 증가합니다. 이 경우 결과 스트림의 이전 AggregationResult는 쿼리에서 반환된 결과가 없으면 RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 |
explainMetrics |
쿼리 설명 측정항목 |
승인 범위
다음 OAuth 범위 중 하나가 필요합니다.
https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/cloud-platform
자세한 내용은 인증 개요를 참조하세요.
StructuredAggregationQuery
StructuredQuery
를 통해 집계를 실행하기 위한 Firestore 쿼리
JSON 표현 |
---|
{ "aggregations": [ { object ( |
필드 | |
---|---|
aggregations[] |
선택사항입니다. 요구사항:
|
통합 필드 query_type . 집계할 기본 쿼리입니다. query_type 은 다음 중 하나여야 합니다. |
|
structuredQuery |
중첩된 구조화된 쿼리입니다. |
집계
단일 결과를 생성하는 집계를 정의합니다.
JSON 표현 |
---|
{ "alias": string, // Union field |
필드 | |
---|---|
alias |
선택사항입니다. 집계 결과를 저장할 필드의 이름입니다(선택사항). 입력하지 않으면 Firestore에서
다음과 같이 변환됩니다.
요구사항:
|
통합 필드 operator . 수행할 집계 유형입니다(필수). operator 은 다음 중 하나여야 합니다. |
|
count |
집계 애그리게이터입니다. |
sum |
합계 애그리게이터입니다. |
avg |
평균 애그리게이터입니다. |
개수
쿼리와 일치하는 문서 수입니다.
COUNT(*)
집계 함수는 문서 전체에서 작동하므로 필드 참조가 필요하지 않습니다.
JSON 표현 |
---|
{ "upTo": string } |
필드 | |
---|---|
upTo |
선택사항입니다. 계산할 최대 문서 수에 대한 선택적 제약조건입니다. 이를 통해 스캔할 문서 수의 상한선을 설정하여 지연 시간 및 비용을 제한할 수 있습니다. 지정되지 않으면 경계가 없는 것으로 해석됩니다. 대략적인 예:
요구사항:
|
합계
요청된 필드 값의 합계입니다.
숫자 값만 집계됩니다.
NULL
등 숫자가 아닌 모든 값은 건너뜁니다.집계된 값에
NaN
이 포함되어 있으면NaN
이 반환됩니다. 무한대 수학은 IEEE-754 표준을 따릅니다.집계된 값이 비어 있으면 0이 반환됩니다.
집계된 모든 숫자가 정수이고 합계 결과가 오버플로되지 않는 경우 64비트 정수를 반환합니다. 그렇지 않으면 결과가 double로 반환됩니다. 집계된 값이 모두 정수인 경우에도 64비트의 부호 있는 정수 내에 들어가지 못하면 결과가 double로 반환됩니다. 이 경우 반환되는 값의 정밀도가 떨어집니다.
언더플로가 발생하면 부동 소수점 집계는 비확정적입니다. 즉, 기본 값을 변경하지 않고 동일한 쿼리를 반복적으로 실행하면 매번 약간 다른 결과가 생성될 수 있습니다. 이러한 경우 값을 부동 소수점 수 대신 정수로 저장해야 합니다.
JSON 표현 |
---|
{
"field": {
object ( |
필드 | |
---|---|
field |
집계할 필드입니다. |
평균
요청된 필드 값의 평균입니다.
숫자 값만 집계됩니다.
NULL
등 숫자가 아닌 모든 값은 건너뜁니다.집계된 값에
NaN
이 포함되어 있으면NaN
이 반환됩니다. 무한대 수학은 IEEE-754 표준을 따릅니다.집계된 값이 비어 있으면
NULL
이 반환됩니다.결과를 항상 double로 반환합니다.
JSON 표현 |
---|
{
"field": {
object ( |
필드 | |
---|---|
field |
집계할 필드입니다. |
AggregationResult
Firestore 집계 쿼리의 단일 버킷 결과입니다.
결과마다 다른 필드가 있을 수 있는 문서 쿼리와 달리 aggregateFields
의 키는 집계 쿼리의 모든 결과에서 동일합니다.
JSON 표현 |
---|
{
"aggregateFields": {
string: {
object ( |
필드 | |
---|---|
aggregateFields |
집계 함수의 결과입니다(예: 키는 입력 시 집계 함수에 할당된
|