Method: projects.databases.documents.runAggregationQuery

집계 쿼리를 실행합니다.

이 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

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. 쿼리의 일관성 모드로, 기본값은 strong consistency입니다. consistency_selector은 다음 중 하나여야 합니다.
transaction

string (bytes format)

이미 활성 상태인 트랜잭션 내에서 집계를 실행합니다.

이 값은 쿼리를 실행할 불투명한 트랜잭션 ID입니다.

base64 인코딩 문자열입니다.
newTransaction

object (TransactionOptions)

쿼리의 일부로 새 트랜잭션을 시작합니다. 기본값은 읽기 전용입니다.

새 트랜잭션 ID가 스트림의 첫 번째 응답으로 반환됩니다.
readTime

string (Timestamp format)

지정된 타임스탬프에 쿼리를 실행합니다.

지난 1시간 이내의 마이크로초 정밀도 타임스탬프여야 합니다. 또는 PITR(point-in-time recovery)이 사용 설정된 경우 지난 7일 이내의 1분짜리 타임스탬프일 수도 있습니다.

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)

이 요청의 일부로 시작된 트랜잭션입니다.

요청이 새 트랜잭션의 시작을 요청한 경우에만 첫 번째 응답에 표시됩니다.

base64 인코딩 문자열입니다.
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

자세한 내용은 인증 개요를 참조하세요.

StructuredAggregationQuery

StructuredQuery를 통해 집계를 실행하기 위한 Firestore 쿼리

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이 반환됩니다. 무한대 수학은 IEEE-754 표준을 따릅니다.

  • 집계된 값이 비어 있으면 0이 반환됩니다.

  • 집계된 모든 숫자가 정수이고 합계 결과가 오버플로되지 않는 경우 64비트 정수를 반환합니다. 그렇지 않으면 결과가 double로 반환됩니다. 집계된 값이 모두 정수인 경우에도 64비트의 부호 있는 정수 내에 들어가지 못하면 결과가 double로 반환됩니다. 이 경우 반환되는 값의 정밀도가 떨어집니다.

  • 언더플로가 발생하면 부동 소수점 집계는 비확정적입니다. 즉, 기본 값을 변경하지 않고 동일한 쿼리를 반복적으로 실행하면 매번 약간 다른 결과가 생성될 수 있습니다. 이러한 경우 값을 부동 소수점 수 대신 정수로 저장해야 합니다.

JSON 표현 
{
  "field": {
    object (FieldReference)
  }
}
필드
field

object (FieldReference)

집계할 필드입니다.

평균

요청된 필드 값의 평균입니다.

  • 숫자 값만 집계됩니다. NULL 등 숫자가 아닌 모든 값은 건너뜁니다.

  • 집계된 값에 NaN이 포함되어 있으면 NaN이 반환됩니다. 무한대 수학은 IEEE-754 표준을 따릅니다.

  • 집계된 값이 비어 있으면 NULL이 반환됩니다.

  • 결과를 항상 double로 반환합니다.

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" }