집계 쿼리를 실행합니다.
이 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/v1beta1/{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일 이내의 분 전체 타임스탬프가 될 수도 있습니다. 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 |
집계할 필드입니다. |
Avg
요청된 필드 값의 평균입니다.
숫자 값만 집계됩니다.
NULL
을(를) 포함하여 숫자가 아닌 모든 값은 건너뜁니다.집계된 값에
NaN
이 포함되어 있으면NaN
을 반환합니다. 무한대 수학은 IEEE-754 표준을 따릅니다.집계된 값 세트가 비어 있으면
NULL
를 반환합니다.결과를 항상 double로 반환합니다.
JSON 표현 |
---|
{
"field": {
object ( |
입력란 | |
---|---|
field |
집계할 필드입니다. |
AggregationResult
Firestore 집계 쿼리의 단일 버킷 결과입니다.
aggregateFields
의 키는 결과마다 다른 필드가 있을 수 있는 문서 쿼리와 달리 집계 쿼리의 모든 결과에 대해 동일합니다.
JSON 표현 |
---|
{
"aggregateFields": {
string: {
object ( |
입력란 | |
---|---|
aggregateFields |
집계 함수의 결과입니다(예: 키는 입력 시 집계 함수에 할당된
|