elasticgraph-graphql 0.19.1.1 → 0.19.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 901a1ac5d9fe88204d9f9b63d6db558c2cd8f7ef49f442343f1dadd7ec37aa24
-  data.tar.gz: 3c4656b4061d9945fba22aabca8362ca9ad0299225d439a35424ba7598d2be5b
+  metadata.gz: c406c0dd4109d2b92b834f989f5819fc6342696b9c0b231f38b0bb4fc0d8f858
+  data.tar.gz: 95b206f183b6ccfc644ffab571e43232be92123d8c0998bd4add03b4d8571404
 SHA512:
-  metadata.gz: 1a244b8226108ae8b5080630c01ae6fd1ff2e8647a9ac41a4e6da5f4f455c9e47d70cc04744468a21ece403ee4c2354996be56f435e4aa1e5b403f9367567409
-  data.tar.gz: 62f158c296f883dfdb59c302efbc5ef087f933175b042ca49c76e47b71aa70e109a05170b357ec7a81844226586044b6e912882e2b5363adedc543a04d3906ee
+  metadata.gz: 5a1474ca90d5ec6a4c65996491e3570d3b4fef1bd40c9550b0b850bb663018dd9cd690e262af080212019ab12c05651aeca3f79f22ba1007a676422578e8787e
+  data.tar.gz: 8d7f2aff08c7ea4f6038943682f1231d4371c67003acf2f78321b749d4838550eef4b53df7a37b02ee134a10075e0f382251c06d9d18ce7f8bada9838579f201

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2024 Block, Inc.
+Copyright (c) 2024 - 2025 Block, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/elastic_graph/graphql/aggregation/composite_grouping_adapter.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/computation.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/date_histogram_grouping.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/field_path_encoder.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/field_term_grouping.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/key.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/nested_sub_aggregation.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/non_composite_grouping_adapter.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -124,7 +124,7 @@ module ElasticGraph
                 # a time breaker to ensure deterministic results, but don't particularly care which buckets
                 # come first.
                 [-b.fetch("doc_count"), b.fetch("key_values").map(&:to_s)]
-              end.first(size)
+              end.first(size + 1) # We add 1 so `page_info.has_next_page` detection works.
           end
 
           def missing_bucket_path_from(buckets_path)

data/lib/elastic_graph/graphql/aggregation/path_segment.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -22,7 +22,7 @@ module ElasticGraph
 
           new(
             name_in_graphql_query: ast_node.alias || ast_node.name,
-            name_in_index: field&.name_in_index&.to_s
+            name_in_index: field&.name_in_index
           )
         end
       end

data/lib/elastic_graph/graphql/aggregation/query.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/query_adapter.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -24,12 +24,39 @@ module ElasticGraph
       # Responsible for taking in the incoming GraphQL request context, arguments, and the GraphQL
       # schema and directives and populating the `aggregations` portion of `query`.
       class QueryAdapter < Support::MemoizableData.define(:schema, :config, :filter_args_translator, :runtime_metadata, :sub_aggregation_grouping_adapter)
+        # Partially applied `QueryAdapter` -- essentially the `QueryAdapter` without the schema,
+        # so that it can be instantiated before the `Schema` instance exists, instead providing it from
+        # `context` at query time.
+        class WithoutSchema
+          def initialize(config:, filter_args_translator:, runtime_metadata:, sub_aggregation_grouping_adapter:)
+            @build_adapter = ->(schema) do
+              QueryAdapter.new(
+                schema: schema,
+                config: config,
+                filter_args_translator: filter_args_translator,
+                runtime_metadata: runtime_metadata,
+                sub_aggregation_grouping_adapter: sub_aggregation_grouping_adapter
+              )
+            end
+          end
+
+          def call(query:, lookahead:, args:, field:, context:)
+            return query unless field.type.unwrap_fully.indexed_aggregation?
+
+            @build_adapter.call(context.fetch(:elastic_graph_schema)).call(
+              query: query,
+              lookahead: lookahead,
+              args: args,
+              field: field,
+              context: context
+            )
+          end
+        end
+
         # @dynamic element_names
         attr_reader :element_names
 
         def call(query:, lookahead:, args:, field:, context:)
-          return query unless field.type.unwrap_fully.indexed_aggregation?
-
           aggregations_node = extract_aggregation_node(lookahead, field, context.query)
           return query unless aggregations_node
 
@@ -165,7 +192,7 @@ module ElasticGraph
 
                 Aggregation::Computation.new(
                   source_field_path: field_path,
-                  computed_index_field_name: computed_field.name_in_index.to_s,
+                  computed_index_field_name: computed_field.name_in_index,
                   detail: computation_detail
                 )
               end
@@ -186,7 +213,7 @@ module ElasticGraph
             elsif !field.type.object?
               case field.type.name
               # Legacy date grouping API
-              when :Date
+              when "Date"
                 legacy_date_histogram_groupings_from(
                   field_path: field_path,
                   node: node,
@@ -194,7 +221,7 @@ module ElasticGraph
                   get_offset: ->(args) { args[element_names.offset_days]&.then { |days| "#{days}d" } }
                 )
               # Legacy datetime grouping API
-              when :DateTime
+              when "DateTime"
                 legacy_date_histogram_groupings_from(
                   field_path: field_path,
                   node: node,

data/lib/elastic_graph/graphql/aggregation/query_optimizer.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/resolvers/aggregated_values.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -15,17 +15,13 @@ module ElasticGraph
     module Aggregation
       module Resolvers
         class AggregatedValues < ::Data.define(:aggregation_name, :bucket, :field_path)
-          def can_resolve?(field:, object:)
-            true
-          end
-
           def resolve(field:, object:, args:, context:, lookahead:)
             return with(field_path: field_path + [PathSegment.for(field: field, lookahead: lookahead)]) if field.type.object?
 
             key = Key::AggregatedValue.new(
               aggregation_name: aggregation_name,
               field_path: field_path.map(&:name_in_graphql_query),
-              function_name: field.name_in_index.to_s
+              function_name: field.name_in_index
             )
 
             result = Support::HashUtil.verbose_fetch(bucket, key.encode)

data/lib/elastic_graph/graphql/aggregation/resolvers/count_detail.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/resolvers/grouped_by.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -14,16 +14,36 @@ module ElasticGraph
     module Aggregation
       module Resolvers
         class GroupedBy < ::Data.define(:bucket, :field_path)
-          def can_resolve?(field:, object:)
-            true
-          end
-
           def resolve(field:, object:, args:, context:, lookahead:)
             new_field_path = field_path + [PathSegment.for(field: field, lookahead: lookahead)]
             return with(field_path: new_field_path) if field.type.object?
 
             bucket_entry = Support::HashUtil.verbose_fetch(bucket, "key")
-            Support::HashUtil.verbose_fetch(bucket_entry, FieldPathEncoder.encode(new_field_path.map(&:name_in_graphql_query)))
+            value = Support::HashUtil.verbose_fetch(bucket_entry, FieldPathEncoder.encode(new_field_path.map(&:name_in_graphql_query)))
+
+            if field.type.unwrap_fully.name == "Boolean"
+              work_around_terms_aggregation_boolean_value(value)
+            else
+              value
+            end
+          end
+
+          private
+
+          # Elasticsearch/OpenSearch generally return `true`/`false` for Boolean fields. However, there's one exception to that[^1]:
+          #
+          # > Aggregations like the terms aggregation use 1 and 0 for the key, and the strings "true" and "false" for the key_as_string.
+          #
+          # Since we get 0/1 in _only_ this one case, we translate it back to false/true here. While a bit hacky, there isn't a widespread
+          # need to handle Booleans like this in other places. It would be nice to apply this logic in the `NonCompositeGroupingAdapter`
+          # (since the `composite` aggregation used by the `CompositeGroupingAdapter` does not suffer from this issue!) but we don't have
+          # ready access to the field type there to know that 0/1 mean false/true.
+          #
+          # [^1]: https://www.elastic.co/guide/en/elasticsearch/reference/8.17/boolean.html
+          def work_around_terms_aggregation_boolean_value(value)
+            return false if value == 0
+            return true if value == 1
+            value
           end
         end
       end

data/lib/elastic_graph/graphql/aggregation/resolvers/node.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/resolvers/relay_connection_builder.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -55,17 +55,16 @@ module ElasticGraph
           end
 
           private_class_method def self.extract_buckets_from(search_response, for_query:)
-            search_response.raw_data.dig(
-              "aggregations",
+            search_response.aggregations.dig(
               for_query.name,
               "buckets"
-            ) || [build_bucket(for_query, search_response.raw_data)]
+            ) || [build_bucket(for_query, search_response)]
           end
 
           private_class_method def self.build_bucket(query, response)
             defaults = {
               "key" => query.groupings.to_h { |g| [g.key, nil] },
-              "doc_count" => response.dig("hits", "total", "value") || 0
+              "doc_count" => response.total_document_count(default: 0)
             }
 
             empty_bucket_computations = query.computations.to_h do |computation|
@@ -74,7 +73,7 @@ module ElasticGraph
 
             defaults
               .merge(empty_bucket_computations)
-              .merge(response["aggregations"] || {})
+              .merge(response.aggregations)
           end
         end
       end

data/lib/elastic_graph/graphql/aggregation/resolvers/sub_aggregations.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -20,10 +20,6 @@ module ElasticGraph
     module Aggregation
       module Resolvers
         class SubAggregations < ::Data.define(:schema_element_names, :sub_aggregations, :parent_queries, :sub_aggs_by_agg_key, :field_path)
-          def can_resolve?(field:, object:)
-            true
-          end
-
           def resolve(field:, object:, args:, context:, lookahead:)
             path_segment = PathSegment.for(field: field, lookahead: lookahead)
             new_field_path = field_path + [path_segment]
@@ -69,15 +65,21 @@ module ElasticGraph
                   sub_agg
                 end
 
-              # When we have a single ungrouped bucket, we never have any error on the `doc_count`.
-              # Our resolver logic expects it to be present, though.
-              [singleton_bucket.merge({"doc_count_error_upper_bound" => 0})]
+              [SINGLETON_BUCKET_DEFAULTS.merge(singleton_bucket)]
             end
           end
 
           BUCKET_ADAPTERS = [CompositeGroupingAdapter, NonCompositeGroupingAdapter].to_h do |adapter|
             [adapter.meta_name, adapter]
           end
+
+          SINGLETON_BUCKET_DEFAULTS = {
+            # When we have a single ungrouped bucket, we never have any error on the `doc_count`.
+            # Our resolver logic expects it to be present, though.
+            "doc_count_error_upper_bound" => 0,
+            # Our resolver logic expects a `key` as it gets used by the `PageInfo` resolver when that's requested.
+            "key" => {}
+          }
         end
       end
     end

data/lib/elastic_graph/graphql/aggregation/script_term_grouping.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/aggregation/term_grouping.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -33,7 +33,7 @@ module ElasticGraph
           clause_value = work_around_elasticsearch_bug(terms_subclause)
           {
             "terms" => clause_value.merge({
-              "size" => query.paginator.desired_page_size,
+              "size" => query.paginator.requested_page_size,
               "show_term_doc_count_error" => query.needs_doc_count_error
             })
           }

data/lib/elastic_graph/graphql/client.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/config.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -20,6 +20,12 @@ module ElasticGraph
       :max_page_size,
       # Queries that take longer than this configured threshold will have a sanitized version logged.
       :slow_query_latency_warning_threshold_in_ms,
+      # How to resolve nested relationships:
+      #
+      # - `optimized` (default): uses the new (in ElasticGraph 0.19.2.0) optimized resolver logic.
+      # - `original`: uses the resolver logic from ElasticGraph v0.19.1.1 and before.
+      # - `comparison`: runs both versions of the logic in serial, to compare them for correctness and performance. Results are logged.
+      :nested_relationship_resolver_mode,
       # Object used to identify the client of a GraphQL query based on the HTTP request.
       :client_resolver,
       # Array of modules that will be extended onto the `GraphQL` instance to support extension libraries.
@@ -38,17 +44,24 @@ module ElasticGraph
 
         extension_loader = SchemaArtifacts::RuntimeMetadata::ExtensionLoader.new(::Module.new)
         extension_mods = parsed_yaml.fetch("extension_modules", []).map do |mod_hash|
-          extension_loader.load(mod_hash.fetch("extension_name"), from: mod_hash.fetch("require_path"), config: {}).extension_class.tap do |mod|
+          extension_loader.load(mod_hash.fetch("name"), from: mod_hash.fetch("require_path"), config: {}).extension_class.tap do |mod|
             unless mod.instance_of?(::Module)
-              raise Errors::ConfigError, "`#{mod_hash.fetch("extension_name")}` is not a module, but all application extension modules must be modules."
+              raise Errors::ConfigError, "`#{mod_hash.fetch("name")}` is not a module, but all application extension modules must be modules."
             end
           end
         end
 
+        nested_relationship_resolver_mode = parsed_yaml["nested_relationship_resolver_mode"]&.to_sym || :optimized
+        unless VALID_NESTED_RELATIONSHIP_RESOLVER_MODES.include?(nested_relationship_resolver_mode)
+          raise Errors::ConfigError, "Invalid value for `nested_relationship_resolver_mode`: #{nested_relationship_resolver_mode}. " \
+            "Valid values: #{VALID_NESTED_RELATIONSHIP_RESOLVER_MODES.join(", ")}."
+        end
+
         new(
           default_page_size: parsed_yaml.fetch("default_page_size"),
           max_page_size: parsed_yaml.fetch("max_page_size"),
           slow_query_latency_warning_threshold_in_ms: parsed_yaml["slow_query_latency_warning_threshold_in_ms"] || 5000,
+          nested_relationship_resolver_mode: nested_relationship_resolver_mode,
           client_resolver: load_client_resolver(parsed_yaml),
           extension_modules: extension_mods,
           extension_settings: entire_parsed_yaml.except(*ELASTICGRAPH_CONFIG_KEYS)
@@ -61,6 +74,8 @@ module ElasticGraph
       # The standard ElasticGraph root config setting keys; anything else is assumed to be extension settings.
       ELASTICGRAPH_CONFIG_KEYS = %w[graphql indexer logger datastore schema_artifacts]
 
+      VALID_NESTED_RELATIONSHIP_RESOLVER_MODES = [:optimized, :original, :comparison]
+
       private_class_method def self.load_client_resolver(parsed_yaml)
         config = parsed_yaml.fetch("client_resolver") do
           return Client::DefaultResolver.new({})
@@ -68,13 +83,13 @@ module ElasticGraph
 
         client_resolver_loader = SchemaArtifacts::RuntimeMetadata::ExtensionLoader.new(Client::DefaultResolver)
         extension = client_resolver_loader.load(
-          config.fetch("extension_name"),
+          config.fetch("name"),
           from: config.fetch("require_path"),
-          config: config.except("extension_name", "require_path")
+          config: config.except("name", "require_path")
         )
         extension_class = extension.extension_class # : ::Class
 
-        __skip__ = extension_class.new(extension.extension_config)
+        __skip__ = extension_class.new(extension.config)
       end
     end
   end

data/lib/elastic_graph/graphql/datastore_query/document_paginator.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -22,7 +22,9 @@ module ElasticGraph
         :individual_docs_needed,
         # `total_document_count_needed`: when false, `track_total_hits` will be 0 in our datastore query.
         # This will prevent the datastore from doing extra work to get an accurate count
-        :total_document_count_needed
+        :total_document_count_needed,
+        :size_multiplier,
+        :max_effective_size
       )
         # Builds a hash containing the portions of a datastore search body related to pagination.
         def to_datastore_body
@@ -57,12 +59,15 @@ module ElasticGraph
           end
         end
 
-        private
-
         def effective_size
-          individual_docs_needed ? paginator.requested_page_size : 0
+          @effective_size ||= begin
+            uncapped_size = (individual_docs_needed ? paginator.requested_page_size : 0) * size_multiplier
+            (uncapped_size > max_effective_size) ? max_effective_size : uncapped_size
+          end
         end
 
+        private
+
         def effective_sort
           return [] unless effective_size > 0
           paginator.search_in_reverse? ? reverse_sort : sort

data/lib/elastic_graph/graphql/datastore_query/index_expression_builder.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -142,8 +142,7 @@ module ElasticGraph
       private_constant :IndexExpressionBuilder
 
       # Steep is complaining that it can't find some `Query` but they are not in this file...
-      # @dynamic aggregations, shard_routing_values, search_index_definitions, merge_with, search_index_expression
-      # @dynamic with, to_datastore_msearch_header_and_body, document_paginator
+      # @dynamic shard_routing_values, effective_size, merge_with, search_index_expression, with, to_datastore_msearch_header_and_body
     end
   end
 end

data/lib/elastic_graph/graphql/datastore_query/paginator.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at

data/lib/elastic_graph/graphql/datastore_query/routing_picker.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 Block, Inc.
+# Copyright 2024 - 2025 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -168,8 +168,7 @@ module ElasticGraph
       private_constant :RoutingValueSet
 
       # Steep is complaining that it can't find some `Query` but they are not in this file...
-      # @dynamic aggregations, shard_routing_values, search_index_definitions, merge_with, search_index_expression
-      # @dynamic with, to_datastore_msearch_header_and_body, document_paginator
+      # @dynamic shard_routing_values, effective_size, merge_with, search_index_expression, with, to_datastore_msearch_header_and_body
     end
   end
 end