Cloud Firestore API - Class Google::Cloud::Firestore::AggregateQuery (v3.1.0)

Reference documentation and code samples for the Cloud Firestore API class Google::Cloud::Firestore::AggregateQuery.

AggregateQuery

An aggregate query can be used to fetch aggregate values (ex: count) for a query

Instances of this class are immutable. All methods that refine the aggregate query return new instances.

Inherits

  • Object

Examples

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

query = firestore.col "cities"

# Create an aggregate query
aggregate_query = query.aggregate_query
                       .add_count

aggregate_query.get do |aggregate_snapshot|
  puts aggregate_snapshot.get
end

Alias an aggregate query

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Create a query
query = firestore.col "cities"

# Create an aggregate query
aggregate_query = query.aggregate_query
                       .add_count aggregate_alias: 'total_cities'

aggregate_query.get do |aggregate_snapshot|
  puts aggregate_snapshot.get('total_cities')
end

Methods

#add_avg

def add_avg(field, aggregate_alias: nil) -> AggregateQuery

Adds an average aggregate.

Parameters
  • field (String) — The field to apply average on
  • aggregate_alias (String) (defaults to: nil) — Alias to refer to the aggregate
Returns
  • (AggregateQuery) — A new aggregate query with the added average aggregate.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

query = firestore.col "cities"

# Create an aggregate query
aggregate_query = query.aggregate_query
                       .add_avg("population")

aggregate_query.get do |aggregate_snapshot|
  puts aggregate_snapshot.get
end

#add_count

def add_count(aggregate_alias: nil) -> AggregateQuery

Adds a count aggregate.

Parameter
  • aggregate_alias (String) (defaults to: nil) — Alias to refer to the aggregate. Optional
Returns
  • (AggregateQuery) — A new aggregate query with the added count aggregate.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

query = firestore.col "cities"

# Create an aggregate query
aggregate_query = query.aggregate_query
                       .add_count

aggregate_query.get do |aggregate_snapshot|
  puts aggregate_snapshot.get
end

#add_sum

def add_sum(field, aggregate_alias: nil) -> AggregateQuery

Adds a sum aggregate.

Parameters
  • field (String) — The field to sum by
  • aggregate_alias (String) (defaults to: nil) — Alias to refer to the aggregate
Returns
  • (AggregateQuery) — A new aggregate query with the added sum aggregate.
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

query = firestore.col "cities"

# Create an aggregate query
aggregate_query = query.aggregate_query
                       .add_sum("population")

aggregate_query.get do |aggregate_snapshot|
  puts aggregate_snapshot.get
end

#explain

def explain(analyze: false) -> AggregateQueryExplainResult

Retrieves the query explanation for the aggregate query. By default, the query is only planned, not executed, returning only metrics from the planning stages. If analyze is set to true the query will be planned and executed, returning the AggregateQuerySnapshot alongside both planning and execution stage metrics.

Unlike the enumerator returned from AggregateQuery#get, the AggregateQueryExplainResult caches its snapshot and metrics after the first access.

Parameter
  • analyze (Boolean) (defaults to: false) — Whether to execute the query and return the execution stage metrics in addition to planning metrics. If set to false the query will be planned only and will return planning stage metrics without results. If set to true the query will be executed, and will return the query results, planning stage metrics, and execution stage metrics. Defaults to false.
Returns
Examples

Getting only the planning stage metrics for the aggregate query

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
query = firestore.col(:cities).aggregate_query.add_count

explain_result = query.explain
metrics = explain_result.explain_metrics
puts "Plan summary: #{metrics.plan_summary}" if metrics&.plan_summary

Getting planning and execution stage metrics, as well as aggregate query results

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new
query = firestore.col(:cities).aggregate_query.add_count

explain_result = query.explain analyze: true
metrics = explain_result.explain_metrics
puts "Plan summary: #{metrics.plan_summary}" if metrics&.plan_summary
puts "Results returned: #{metrics.execution_stats.results_returned}" if metrics&.execution_stats
snapshot = explain_result.snapshot
puts "Count: #{snapshot.get}" if snapshot

#get

def get() { |An| ... } -> Enumerator<AggregateQuerySnapshot>

Retrieves aggregate snapshot for the query.

Yields
  • (snapshot) — The block for accessing the aggregate query snapshots.
Yield Parameter
Returns
Example 
require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

query = firestore.col "cities"

# Create an aggregate query
aggregate_query = query.aggregate_query
                       .add_count

aggregate_query.get do |aggregate_snapshot|
  puts aggregate_snapshot.get
end