Class: Google::Cloud::Firestore::AggregateQuery

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/firestore/aggregate_query.rb

Overview

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.

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

Instance Method Summary collapse

Instance Method Details

#add_avg(field, aggregate_alias: nil) ⇒ AggregateQuery

Adds an average aggregate.

Examples:

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

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.



193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/google/cloud/firestore/aggregate_query.rb', line 193

def add_avg field, aggregate_alias: nil
  aggregate_alias ||= DEFAULT_AVG_ALIAS
  field = FieldPath.parse field unless field.is_a? FieldPath
  new_aggregate = Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation.new(
    avg: Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation::Avg.new(
      field: Google::Cloud::Firestore::V1::StructuredQuery::FieldReference.new(
        field_path: field.formatted_string
      )
    ),
    alias: aggregate_alias
  )

  start new_aggregate
end

#add_count(aggregate_alias: nil) ⇒ AggregateQuery

Adds a count aggregate.

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

Parameters:

  • aggregate_alias (String) (defaults to: nil) —

    Alias to refer to the aggregate. Optional

Returns:

  • (AggregateQuery) —

    A new aggregate query with the added count aggregate.



122
123
124
125
126
127
128
129
130
 
# File 'lib/google/cloud/firestore/aggregate_query.rb', line 122

def add_count aggregate_alias: nil
  aggregate_alias ||= DEFAULT_COUNT_ALIAS
  new_aggregate = Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation.new(
    count: Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation::Count.new,
    alias: aggregate_alias
  )

  start new_aggregate
end

#add_sum(field, aggregate_alias: nil) ⇒ AggregateQuery

Adds a sum aggregate.

Examples:

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

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.



155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/google/cloud/firestore/aggregate_query.rb', line 155

def add_sum field, aggregate_alias: nil
  aggregate_alias ||= DEFAULT_SUM_ALIAS
  field = FieldPath.parse field unless field.is_a? FieldPath
  new_aggregate = Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation.new(
    sum: Google::Cloud::Firestore::V1::StructuredAggregationQuery::Aggregation::Sum.new(
      field: Google::Cloud::Firestore::V1::StructuredQuery::FieldReference.new(
        field_path: field.formatted_string
      )
    ),
    alias: aggregate_alias
  )

  start new_aggregate
end

#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.

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

Parameters:

  • 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:



299
300
301
302
303
304
305
306
307
308
 
# File 'lib/google/cloud/firestore/aggregate_query.rb', line 299

def explain analyze: false
  ensure_service!
  validate_analyze_option! analyze

  explain_options = ::Google::Cloud::Firestore::V1::ExplainOptions.new analyze: analyze

  responses_enum = service.run_aggregate_query @parent_path, @grpc, explain_options: explain_options

  AggregateQueryExplainResult.new responses_enum
end

#get {|snapshot| ... } ⇒ Enumerator<AggregateQuerySnapshot>

Retrieves aggregate snapshot for the query.

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

Yields:

  • (snapshot) —

    The block for accessing the aggregate query snapshots.

Yield Parameters:

Returns:



244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/google/cloud/firestore/aggregate_query.rb', line 244

def get
  ensure_service!

  return enum_for :get unless block_given?

  responses = service.run_aggregate_query @parent_path, @grpc
  responses.each do |response|
    next if response.result.nil?
    yield AggregateQuerySnapshot.from_run_aggregate_query_response response
  end
end