elasticgraph-schema_definition 1.0.1 → 1.0.3.rc1

data/lib/elastic_graph/schema_definition/rake_tasks.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -155,14 +155,14 @@ module ElasticGraph
       end
 
       def schema_artifact_manager
-        require "elastic_graph/schema_definition/schema_artifact_manager"
+        require "elastic_graph/schema_definition/api"
 
         # :nocov: -- tests don't cover the `VERBOSE` side
         max_diff_lines = ENV["VERBOSE"] ? 999999999 : 50
         # :nocov:
 
-        SchemaArtifactManager.new(
-          schema_definition_results: schema_definition_results,
+        schema_def_api.factory.new_schema_artifact_manager(
+          schema_definition_results: schema_def_api.results,
           schema_artifacts_directory: @schema_artifacts_directory.to_s,
           enforce_json_schema_version: @enforce_json_schema_version,
           output: @output,
@@ -170,7 +170,7 @@ module ElasticGraph
         )
       end
 
-      def schema_definition_results
+      def schema_def_api
         require "elastic_graph/schema_definition/api"
 
         API.new(
@@ -183,7 +183,7 @@ module ElasticGraph
           output: @output
         ).tap do |api|
           api.as_active_instance { load @path_to_schema.to_s }
-        end.results
+        end
       end
     end
   end

data/lib/elastic_graph/schema_definition/results.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -18,6 +18,7 @@ require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
 require "elastic_graph/schema_definition/schema_elements/field_path"
 require "elastic_graph/schema_definition/scripting/file_system_repository"
 require "elastic_graph/support/memoizable_data"
+require "elastic_graph/version"
 
 module ElasticGraph
   module SchemaDefinition
@@ -180,7 +181,7 @@ module ElasticGraph
         check_for_circular_dependencies!
 
         index_templates, indices = state.object_types_by_name.values
-          .flat_map(&:indices)
+          .filter_map(&:index_def)
           .sort_by(&:name)
           .partition(&:rollover_config)
 
@@ -220,11 +221,12 @@ module ElasticGraph
           .to_h { |t| [t.name, t.runtime_metadata] }
           .merge(indexed_enum_types_by_name)
 
-        index_definitions_by_name = state.object_types_by_name.values.flat_map(&:indices).to_h do |index|
+        index_definitions_by_name = state.object_types_by_name.values.filter_map(&:index_def).to_h do |index|
           [index.name, index.runtime_metadata]
         end
 
         SchemaArtifacts::RuntimeMetadata::Schema.new(
+          elasticgraph_version: ElasticGraph::VERSION,
           object_types_by_name: object_types_by_name,
           scalar_types_by_name: scalar_types_by_name,
           enum_types_by_name: enum_types_by_name,
@@ -246,7 +248,7 @@ module ElasticGraph
           ::Hash.new { |h, k| h[k] = [] } # : ::Hash[untyped, ::Array[SchemaArtifacts::RuntimeMetadata::UpdateTarget]]
         ) do |object_type, accum|
           fields_with_sources_by_relationship_name =
-            if object_type.indices.empty?
+            if object_type.index_def.nil?
               # only indexed types can have `sourced_from` fields, and resolving `fields_with_sources` on an unindexed union type
               # such as `_Entity` when we are using apollo can lead to exceptions when multiple entity types have the same field name
               # that use different mapping types.
@@ -274,7 +276,7 @@ module ElasticGraph
             resolved_relationship, relationship_error = relationship_resolver.resolve
             relationship_errors << relationship_error if relationship_error
 
-            if object_type.indices.any? && resolved_relationship && sourced_fields.any?
+            if object_type.index_def && resolved_relationship && sourced_fields.any?
               update_target_resolver = Indexing::UpdateTargetResolver.new(
                 object_type: object_type,
                 resolved_relationship: resolved_relationship,
@@ -285,6 +287,15 @@ module ElasticGraph
               update_target, errors = update_target_resolver.resolve
               accum[resolved_relationship.related_type.name] << update_target if update_target
               sourced_field_errors.concat(errors)
+
+              # Validate that has_had_multiple_sources! has been called when sourced_from is used
+              if (index_def = object_type.index_def) && !index_def.has_had_multiple_sources_flag
+                sourced_field_errors << "Type `#{object_type.name}` uses `sourced_from` fields but its index `#{index_def.name}` " \
+                  "has not been configured with `has_had_multiple_sources!`. To resolve this, add `i.has_had_multiple_sources!` within the " \
+                  "`t.index \"#{index_def.name}\"` block. This flag is required because indices with multiple sources can contain " \
+                  "incomplete documents, and ElasticGraph needs to know this to apply proper filtering. Once set, this flag should remain even " \
+                  "if you later remove all `sourced_from` fields, as the index may still contain historical incomplete documents."
+              end
             end
           end
         end.tap do

data/lib/elastic_graph/schema_definition/schema_artifact_manager.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -45,28 +45,6 @@ module ElasticGraph
             "they can perform code generation and event validation."
           ]
         )
-
-        # Here we round-trip the SDL string through the GraphQL gem's formatting logic. This provides
-        # nice, consistent formatting (alphabetical order, consistent spacing, etc) and also prunes out
-        # any "orphaned" schema types (that is, types that are defined but never referenced).
-        # We also prepend a line break so there's a blank line between the comment block and the
-        # schema elements.
-        graphql_schema = ::GraphQL::Schema.from_definition(schema_definition_results.graphql_schema_string).to_definition.chomp
-
-        unversioned_artifacts = [
-          new_yaml_artifact(DATASTORE_CONFIG_FILE, schema_definition_results.datastore_config),
-          new_yaml_artifact(RUNTIME_METADATA_FILE, pruned_runtime_metadata(graphql_schema).to_dumpable_hash),
-          @json_schemas_artifact,
-          new_raw_artifact(GRAPHQL_SCHEMA_FILE, "\n" + graphql_schema)
-        ]
-
-        versioned_artifacts = build_desired_versioned_json_schemas(@json_schemas_artifact.desired_contents).values.map do |versioned_schema|
-          new_versioned_json_schema_artifact(versioned_schema)
-        end
-
-        @artifacts = (unversioned_artifacts + versioned_artifacts).sort_by(&:file_name)
-        notify_about_unused_type_name_overrides
-        notify_about_unused_enum_value_overrides
       end
 
       # Dumps all the schema artifacts to disk.
@@ -80,7 +58,7 @@ module ElasticGraph
             setter_location_path = ::Pathname.new(setter_location.absolute_path.to_s).relative_path_from(::Dir.pwd)
 
             abort "A change has been attempted to `json_schemas.yaml`, but the `json_schema_version` has not been correspondingly incremented. Please " \
-              "increase the schema's version, and then run the `schema_artifacts:dump` command again.\n\n" \
+              "increase the schema's version, and then run the `bundle exec rake schema_artifacts:dump` command again.\n\n" \
               "To update the schema version to the expected version, change line #{setter_location.lineno} at `#{setter_location_path}` to:\n" \
               "  `schema.json_schema_version #{recommended_json_schema_version}`\n\n" \
               "Alternately, pass `enforce_json_schema_version: false` to `ElasticGraph::SchemaDefinition::RakeTasks.new` to allow the JSON schemas " \
@@ -94,15 +72,15 @@ module ElasticGraph
         end
 
         ::FileUtils.mkdir_p(@schema_artifacts_directory)
-        @artifacts.each { |artifact| artifact.dump(@output) }
+        artifacts.each { |artifact| artifact.dump(@output) }
       end
 
       # Checks that all schema artifacts are up-to-date, raising an exception if not.
       def check_artifacts
-        out_of_date_artifacts = @artifacts.select(&:out_of_date?)
+        out_of_date_artifacts = artifacts.select(&:out_of_date?)
 
         if out_of_date_artifacts.empty?
-          descriptions = @artifacts.map.with_index(1) { |art, i| "#{i}. #{art.file_name}" }
+          descriptions = artifacts.map.with_index(1) { |art, i| "#{i}. #{art.file_name}" }
           @output.puts <<~EOS
             Your schema artifacts are all up to date:
             #{descriptions.join("\n")}
@@ -115,6 +93,38 @@ module ElasticGraph
 
       private
 
+      def artifacts
+        @artifacts ||= artifacts_from_schema_def.sort_by(&:file_name).tap do
+          # This must be deferred until artifacts are generated, as we can't fully detect
+          # unused things until after we've used things to generate artifacts.
+          notify_about_unused_type_name_overrides
+          notify_about_unused_enum_value_overrides
+        end
+      end
+
+      # Defined to offer a convenient method to override in an extension in order to add a new schema artifact.
+      def artifacts_from_schema_def
+        # Here we round-trip the SDL string through the GraphQL gem's formatting logic. This provides
+        # nice, consistent formatting (alphabetical order, consistent spacing, etc) and also prunes out
+        # any "orphaned" schema types (that is, types that are defined but never referenced).
+        # We also prepend a line break so there's a blank line between the comment block and the
+        # schema elements.
+        graphql_schema = ::GraphQL::Schema.from_definition(schema_definition_results.graphql_schema_string).to_definition.chomp
+
+        unversioned_artifacts = [
+          new_yaml_artifact(DATASTORE_CONFIG_FILE, schema_definition_results.datastore_config),
+          new_yaml_artifact(RUNTIME_METADATA_FILE, pruned_runtime_metadata(graphql_schema).to_dumpable_hash),
+          @json_schemas_artifact,
+          new_raw_artifact(GRAPHQL_SCHEMA_FILE, "\n" + graphql_schema)
+        ]
+
+        versioned_artifacts = build_desired_versioned_json_schemas(@json_schemas_artifact.desired_contents).values.map do |versioned_schema|
+          new_versioned_json_schema_artifact(versioned_schema)
+        end
+
+        unversioned_artifacts + versioned_artifacts
+      end
+
       def notify_about_unused_type_name_overrides
         type_namer = @schema_definition_results.state.type_namer
         return if (unused_overrides = type_namer.unused_name_overrides).empty?
@@ -338,7 +348,7 @@ module ElasticGraph
         end
 
         <<~EOS.strip
-          #{out_of_date_artifacts.size} schema artifact(s) are out of date. Run `rake schema_artifacts:dump` to update the following artifact(s):
+          #{out_of_date_artifacts.size} schema artifact(s) are out of date. Run `bundle exec rake schema_artifacts:dump` to update the following artifact(s):
 
           #{descriptions.join("\n")}
 
@@ -471,7 +481,7 @@ module ElasticGraph
 
       def comment_preamble
         lines = [
-          "Generated by `rake schema_artifacts:dump`.",
+          "Generated by `bundle exec rake schema_artifacts:dump`.",
           "DO NOT EDIT BY HAND. Any edits will be lost the next time the rake task is run."
         ]
 

data/lib/elastic_graph/schema_definition/schema_elements/argument.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/built_in_types.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -222,6 +222,15 @@ module ElasticGraph
                 When `null` is passed, matches all documents.
               EOS
             end
+
+            t.field names.matches_query_with_prefix, schema_def_state.type_ref("MatchesQueryWithPrefix").as_filter_input.name do |f|
+              f.documentation <<~EOS
+                Matches records where the field value matches the provided query with the last term treated as a prefix.
+                Similar to `#{names.matches_query}`, but allows prefix matching on the last term.
+
+                When `null` is passed, matches all documents.
+              EOS
+            end
           end.each do |input_type|
             field_type = input_type.type_ref.list_filter_input? ? "[String]" : "String"
             input_type.documentation <<~EOS
@@ -287,6 +296,42 @@ module ElasticGraph
             remove_any_of_and_all_of_and_not_filter_operators_on(t)
           end
 
+          register_filter "MatchesQueryWithPrefix" do |t|
+            t.documentation <<~EOS
+              Input type used to specify parameters for the `#{names.matches_query_with_prefix}` filtering operator.
+
+              When `null` is passed, matches all documents.
+            EOS
+
+            t.field names.query_with_prefix, "String!" do |f|
+              f.documentation "The input query to search for, with the last term treated as a prefix."
+            end
+
+            t.field names.allowed_edits_per_term, "MatchesQueryAllowedEditsPerTerm!" do |f|
+              f.documentation <<~EOS
+                Number of allowed modifications per term to arrive at a match. For example, if set to 'ONE', the input
+                term 'glue' would match 'blue' but not 'clued', since the latter requires two modifications.
+              EOS
+
+              f.default "DYNAMIC"
+            end
+
+            t.field names.require_all_terms, "Boolean!" do |f|
+              f.documentation <<~EOS
+                Set to `true` to match only if all terms in `#{names.query_with_prefix}` are found, or
+                `false` to only require one term to be found.
+              EOS
+
+              f.default false
+            end
+
+            # any_of/all_of/not don't really make sense on this filter because it doesn't make sense
+            # to apply an OR operator or negation to the fields of this type since they are all an
+            # indivisible part of a single filter operation on a specific field. So we remove them
+            # here.
+            remove_any_of_and_all_of_and_not_filter_operators_on(t)
+          end
+
           register_filter "StringContains" do |t|
             t.documentation <<~EOS
               Input type used to specify parameters for the `#{names.contains}` string filtering operator.
@@ -674,6 +719,11 @@ module ElasticGraph
             t.prepare_for_indexing_with "ElasticGraph::Indexer::IndexingPreparers::Integer",
               defined_at: "elastic_graph/indexer/indexing_preparers/integer"
 
+            # The GraphQL gem automatically coerces Int values, so we can safely use MISSING_NUMERIC_PLACEHOLDER
+            # as the grouping missing value placeholder even though we don't override the default (no-op) ElasticGraph
+            # scalar coercion adapter.
+            t.grouping_missing_value_placeholder MISSING_NUMERIC_PLACEHOLDER
+
             define_integral_aggregated_values_for(t)
           end
 
@@ -744,6 +794,8 @@ module ElasticGraph
             t.json_schema type: "string", format: "date-time"
             t.coerce_with "ElasticGraph::GraphQL::ScalarCoercionAdapters::DateTime",
               defined_at: "elastic_graph/graphql/scalar_coercion_adapters/date_time"
+            t.prepare_for_indexing_with "ElasticGraph::Indexer::IndexingPreparers::DateTime",
+              defined_at: "elastic_graph/indexer/indexing_preparers/date_time"
 
             t.documentation <<~EOS
               A timestamp, represented as an [ISO 8601 time string](https://en.wikipedia.org/wiki/ISO_8601).

data/lib/elastic_graph/schema_definition/schema_elements/deprecated_element.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/directive.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/enum_type.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/enum_value.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/enum_value_namer.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/enums_for_indexed_types.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/field.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -515,7 +515,9 @@ module ElasticGraph
         #         f.sourced_from "capitalOf", "currency"
         #       end
         #
-        #       t.index "cities"
+        #       t.index "cities" do |i|
+        #         i.has_had_multiple_sources!
+        #       end
         #     end
         #   end
         def sourced_from(relationship, field_path)
@@ -968,7 +970,8 @@ module ElasticGraph
             json_schema_options: json_schema_options,
             accuracy_confidence: accuracy_confidence,
             source: source,
-            runtime_field_script: runtime_field_script
+            runtime_field_script: runtime_field_script,
+            doc_comment: doc_comment
           )
         end
 
@@ -1045,7 +1048,7 @@ module ElasticGraph
         # are exactly equal (in which case we can return either).
         #
         # @private
-        def self.pick_most_accurate_from(field1, field2, to_comparable: ->(it) { it })
+        def self.pick_most_accurate_from(field1, field2, to_comparable: ->(value) { value })
           return field1 if to_comparable.call(field1) == to_comparable.call(field2)
           yield if field1.accuracy_confidence == field2.accuracy_confidence
           # Array#max_by can return nil (when called on an empty array), but our steep type is non-nil.

data/lib/elastic_graph/schema_definition/schema_elements/field_path.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/field_source.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/graphql_sdl_enumerator.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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,6 +14,7 @@ module ElasticGraph
       # @private
       class GraphQLSDLEnumerator
         include ::Enumerable
+
         # @dynamic schema_def_state
         attr_reader :schema_def_state
 

data/lib/elastic_graph/schema_definition/schema_elements/input_field.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/input_type.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/interface_type.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/list_counts_state.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/object_type.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/relationship.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -112,8 +112,9 @@ module ElasticGraph
         #         f.sourced_from "launchPlan", "launchDate"
         #       end
         #
-        #       t.index "campaigns"do |i|
+        #       t.index "campaigns" do |i|
         #         i.rollover :yearly, "createdAt"
+        #         i.has_had_multiple_sources!
         #       end
         #     end
         #

data/lib/elastic_graph/schema_definition/schema_elements/scalar_type.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -44,6 +44,7 @@ module ElasticGraph
       class ScalarType < Struct.new(
         :schema_def_state,
         :type_ref,
+        :grouping_missing_value_placeholder_overridden,
         :mapping_type,
         :runtime_metadata,
         :aggregated_values_customizations,
@@ -66,12 +67,13 @@ module ElasticGraph
 
         # @private
         def initialize(schema_def_state, name)
-          super(schema_def_state, schema_def_state.type_ref(name).to_final_form)
+          super(schema_def_state, schema_def_state.type_ref(name).to_final_form, false)
 
           # Default the runtime metadata before yielding, so it can be overridden as needed.
           self.runtime_metadata = SchemaArtifacts::RuntimeMetadata::ScalarType.new(
             coercion_adapter_ref: SchemaArtifacts::RuntimeMetadata::ScalarType::DEFAULT_COERCION_ADAPTER_REF,
-            indexing_preparer_ref: SchemaArtifacts::RuntimeMetadata::ScalarType::DEFAULT_INDEXING_PREPARER_REF
+            indexing_preparer_ref: SchemaArtifacts::RuntimeMetadata::ScalarType::DEFAULT_INDEXING_PREPARER_REF,
+            grouping_missing_value_placeholder: nil
           )
 
           yield self
@@ -84,6 +86,10 @@ module ElasticGraph
           if missing.any?
             raise Errors::SchemaError, "Scalar types require `mapping` and `json_schema` to be configured, but `#{name}` lacks #{missing.join(" and ")}."
           end
+
+          if (placeholder = inferred_grouping_missing_value_placeholder)
+            self.runtime_metadata = runtime_metadata.with(grouping_missing_value_placeholder: placeholder)
+          end
         end
 
         # @return [String] name of the scalar type
@@ -154,6 +160,31 @@ module ElasticGraph
           }).tap(&:load_indexing_preparer) # verify the preparer is valid.
         end
 
+        # Specifies a placeholder value to use for missing values when grouping by this scalar type.
+        # This optimization allows ElasticGraph to use a single terms aggregation instead of separate
+        # terms and missing aggregations, reducing the exponential explosion of subaggregations when
+        # grouping by multiple fields.
+        #
+        # @param placeholder [String, Numeric] the placeholder value to use for missing/null values
+        # @return [void]
+        #
+        # @example Define a grouping missing value placeholder
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.scalar_type "BigInt" do |t|
+        #       t.mapping type: "long"
+        #       t.json_schema type: "integer", minimum: -(2**53) + 1, maximum: (2**53) - 1
+        #       t.grouping_missing_value_placeholder "NaN"
+        #     end
+        #   end
+        def grouping_missing_value_placeholder(placeholder)
+          unless placeholder.nil? || placeholder.is_a?(String) || placeholder.is_a?(Numeric)
+            raise Errors::SchemaError, "grouping_missing_value_placeholder must be a String or Numeric value, but got #{placeholder.class}: #{placeholder.inspect}"
+          end
+
+          self.grouping_missing_value_placeholder_overridden = true
+          self.runtime_metadata = runtime_metadata.with(grouping_missing_value_placeholder: placeholder)
+        end
+
         # @return [String] the GraphQL SDL form of this scalar
         def to_sdl
           "#{formatted_documentation}scalar #{name} #{directives_sdl}"
@@ -310,9 +341,56 @@ module ElasticGraph
           schema_def_state.factory.new_aggregated_values_type_for_index_leaf_type(name, &customization_block)
         end
 
+        def inferred_grouping_missing_value_placeholder
+          return nil if grouping_missing_value_placeholder_overridden || mapping_type.nil?
+
+          if STRING_TYPES.include?(mapping_type)
+            MISSING_STRING_PLACEHOLDER
+          elsif FLOAT_TYPES.include?(mapping_type)
+            MISSING_NUMERIC_PLACEHOLDER
+          elsif mapping_type == "long"
+            # It is only safe to use NaN for a long when the long's range is safe to coerce to a float
+            # without loss of precision. This is because using NaN as the missing value will cause
+            # the datastore to coerce the other bucket keys to float.
+            # JSON schema min/max only constrains newly indexed values, not existing data that may fall outside the range before the constraints were added.
+            # This is an edge case where the long range may exceed safe float precision.
+            # In this case, users can set grouping_missing_value_placeholder to nil.
+            if (json_schema_options[:minimum] || LONG_STRING_MIN) >= JSON_SAFE_LONG_MIN &&
+                (json_schema_options[:maximum] || LONG_STRING_MAX) <= JSON_SAFE_LONG_MAX
+              inferred_numeric_placeholder_for_integer_type
+            end
+          elsif mapping_type == "unsigned_long"
+            # Similar to the checks above for long except we only need to check the max
+            # (since the min is zero even if not specified)
+            if (json_schema_options[:maximum] || LONG_STRING_MAX) <= JSON_SAFE_LONG_MAX
+              inferred_numeric_placeholder_for_integer_type
+            end
+          elsif INTEGER_TYPES.include?(mapping_type)
+            # All other integer types can safely be coerced to float without loss of precision
+            inferred_numeric_placeholder_for_integer_type
+          end
+        end
+
+        def inferred_numeric_placeholder_for_integer_type
+          # Using NaN as the missing value placeholder causes the datastore to coerce all bucket keys to float.
+          # If using the default coercion adapter (which is a no-op), the values won't be coerced back to integers,
+          # causing a type change in the returned values. Only use NaN if a custom coercion adapter is configured.
+          if runtime_metadata.coercion_adapter_ref == SchemaArtifacts::RuntimeMetadata::ScalarType::DEFAULT_COERCION_ADAPTER_REF
+            nil
+          else
+            MISSING_NUMERIC_PLACEHOLDER
+          end
+        end
+
         # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html
         # https://www.elastic.co/guide/en/elasticsearch/reference/7.13/number.html#number
-        NUMERIC_TYPES = %w[long integer short byte double float half_float scaled_float unsigned_long].to_set
+        FLOAT_TYPES = %w[double float half_float scaled_float].to_set
+        INTEGER_TYPES = %w[long integer short byte unsigned_long].to_set
+        NUMERIC_TYPES = FLOAT_TYPES | INTEGER_TYPES
+        # https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/keyword
+        # https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/text-type-family
+        # https://docs.opensearch.org/latest/mappings/supported-field-types/index/#string-based-field-types
+        STRING_TYPES = %w[keyword constant_keyword wildcard text match_only_text pattern_text semantic_text].to_set
         DATE_TYPES = %w[date date_nanos].to_set
         # The Elasticsearch/OpenSearch docs do not exhaustively give a list of types on which range queries are efficient,
         # but the docs are clear that it is efficient on numeric and date types, and is inefficient on string

data/lib/elastic_graph/schema_definition/schema_elements/sort_order_enum_value.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/sub_aggregation_path.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/type_namer.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 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/schema_definition/schema_elements/type_reference.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# Copyright 2024 - 2026 Block, Inc.
 #
 # Use of this source code is governed by an MIT-style
 # license that can be found in the LICENSE file or at
@@ -28,6 +28,7 @@ module ElasticGraph
       # @private
       class TypeReference < Support::MemoizableData.define(:name, :schema_def_state)
         extend Forwardable
+
         # @dynamic type_namer
         def_delegator :schema_def_state, :type_namer