elasticgraph-schema_definition 0.18.0.0

data/lib/elastic_graph/schema_definition/mixins/has_type_info.rb

@@ -0,0 +1,181 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/json_schema/meta_schema_validator"
+
+module ElasticGraph
+  module SchemaDefinition
+    module Mixins
+      # Mixin used to specify non-GraphQL type info (datastore index and JSON schema type info).
+      # Exists as a mixin so we can apply the same consistent API to every place we need to use this.
+      # Currently it's used in 3 places:
+      #
+      # - {SchemaElements::ScalarType}: allows specification of how scalars are represented in JSON schema and the index.
+      # - {SchemaElements::TypeWithSubfields}: allows customization of how an object type is represented in JSON schema and the index.
+      # - {SchemaElements::Field}: allows customization of a specific field over the field type's standard JSON schema and the index mapping.
+      module HasTypeInfo
+        # @return [Hash<Symbol, Object>] datastore mapping options
+        def mapping_options
+          @mapping_options ||= {}
+        end
+
+        # @return [Hash<Symbol, Object>] JSON schema options
+        def json_schema_options
+          @json_schema_options ||= {}
+        end
+
+        # Set of mapping parameters that it makes sense to allow customization of, based on
+        # [the Elasticsearch docs](https://www.elastic.co/guide/en/elasticsearch/reference/8.15/mapping-params.html).
+        CUSTOMIZABLE_DATASTORE_PARAMS = Set[
+          :analyzer,
+          :eager_global_ordinals,
+          :enabled,
+          :fields,
+          :format,
+          :index,
+          :meta, # not actually in the doc above. Added to support some `index_configurator` tests on 7.9+.
+          :norms,
+          :null_value,
+          :search_analyzer,
+          :type,
+        ]
+
+        # Defines the Elasticsearch/OpenSearch [field mapping type](https://www.elastic.co/guide/en/elasticsearch/reference/7.10/mapping-types.html)
+        # and [mapping parameters](https://www.elastic.co/guide/en/elasticsearch/reference/7.10/mapping-params.html) for a field or type.
+        # The options passed here will be included in the generated `datastore_config.yaml` artifact that ElasticGraph uses to configure
+        # Elasticsearch/OpenSearch.
+        #
+        # Can be called multiple times; each time, the options will be merged into the existing options.
+        #
+        # This is required on a {SchemaElements::ScalarType}; without it, ElasticGraph would have no way to know how the datatype should be
+        # indexed in the datastore.
+        #
+        # On a {SchemaElements::Field}, this can be used to customize how a field is indexed. For example, `String` fields are normally
+        # indexed as [keywords](https://www.elastic.co/guide/en/elasticsearch/reference/7.10/keyword.html); to instead index a `String`
+        # field for full text search, you’d need to configure `mapping type: "text"`.
+        #
+        # On a {SchemaElements::ObjectType}, this can be used to use a specific Elasticsearch/OpenSearch data type for something that is
+        # modeled as an object in GraphQL. For example, we use it for the `GeoLocation` type so they get indexed in Elasticsearch using the
+        # [geo_point type](https://www.elastic.co/guide/en/elasticsearch/reference/7.10/geo-point.html).
+        #
+        # @param options [Hash<Symbol, Object>] mapping options--must be limited to {CUSTOMIZABLE_DATASTORE_PARAMS}
+        # @return [void]
+        #
+        # @example Define the mapping of a custom scalar type
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.scalar_type "URL" do |t|
+        #       t.mapping type: "keyword"
+        #       t.json_schema type: "string", format: "uri"
+        #     end
+        #   end
+        #
+        # @example Customize the mapping of a field
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Card" do |t|
+        #       t.field "id", "ID!"
+        #
+        #       t.field "cardholderName", "String" do |f|
+        #         # index this field for full text search
+        #         f.mapping type: "text"
+        #       end
+        #
+        #       t.field "expYear", "Int" do |f|
+        #         # Use a smaller numeric type to save space in the datastore
+        #         f.mapping type: "short"
+        #         f.json_schema minimum: 2000, maximum: 2099
+        #       end
+        #
+        #       t.field "expMonth", "Int" do |f|
+        #         # Use a smaller numeric type to save space in the datastore
+        #         f.mapping type: "byte"
+        #         f.json_schema minimum: 1, maximum: 12
+        #       end
+        #
+        #       t.index "cards"
+        #     end
+        #   end
+        def mapping(**options)
+          param_diff = (options.keys.to_set - CUSTOMIZABLE_DATASTORE_PARAMS).to_a
+
+          unless param_diff.empty?
+            raise SchemaError, "Some configured mapping overrides are unsupported: #{param_diff.inspect}"
+          end
+
+          mapping_options.update(options)
+        end
+
+        # Defines the [JSON schema](https://json-schema.org/understanding-json-schema/) validations for this field or type. Validations
+        # defined here will be included in the generated `json_schemas.yaml` artifact, which is used by the ElasticGraph indexer to
+        # validate events before indexing their data in the datastore. In addition, the publisher may use `json_schemas.yaml` for code
+        # generation and to apply validation before publishing an event to ElasticGraph.
+        #
+        # Can be called multiple times; each time, the options will be merged into the existing options.
+        #
+        # This is _required_ on a {SchemaElements::ScalarType} (since we don’t know how a custom scalar type should be represented in
+        # JSON!). On a {SchemaElements::Field}, this is optional, but can be used to make the JSON schema validation stricter then it
+        # would otherwise be. For example, you could use `json_schema maxLength: 30` on a `String` field to limit the length.
+        #
+        # You can use any of the JSON schema validation keywords here. In addition, `nullable: false` is supported to configure the
+        # generated JSON schema to disallow `null` values for the field. Note that if you define a field with a non-nullable GraphQL type
+        # (e.g. `Int!`), the JSON schema will automatically disallow nulls. However, as explained in the
+        # {SchemaElements::TypeWithSubfields#field} documentation, we generally recommend against defining non-nullable GraphQL fields.
+        # `json_schema nullable: false` will disallow `null` values from being indexed, while still keeping the field nullable in the
+        # GraphQL schema. If you think you might want to make a field non-nullable in the GraphQL schema some day, it’s a good idea to use
+        # `json_schema nullable: false` now to ensure every indexed record has a non-null value for the field.
+        #
+        # @note We recommend using JSON schema validations in a limited fashion. Validations that are appropriate to apply when data is
+        #   entering the system-of-record are often not appropriate on a secondary index like ElasticGraph. Events that violate a JSON
+        #   schema validation will fail to index (typically they will be sent to the dead letter queue and page an oncall engineer). If an
+        #   ElasticGraph instance is meant to contain all the data of some source system, you probably don’t want it applying stricter
+        #   validations than the source system itself has. We recommend limiting your JSON schema validations to situations where
+        #   violations would prevent ElasticGraph from operating correctly.
+        #
+        # @param options [Hash<Symbol, Object>] JSON schema options
+        # @return [void]
+        #
+        # @example Define the JSON schema validations of a custom scalar type
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.scalar_type "URL" do |t|
+        #       t.mapping type: "keyword"
+        #
+        #       # JSON schema has a built-in URI format validator:
+        #       # https://json-schema.org/understanding-json-schema/reference/string.html#resource-identifiers
+        #       t.json_schema type: "string", format: "uri"
+        #     end
+        #   end
+        #
+        # @example Define additional validations on a field
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Card" do |t|
+        #       t.field "id", "ID!"
+        #
+        #       t.field "expYear", "Int" do |f|
+        #         # Use JSON schema to ensure the publisher is sending us 4 digit years, not 2 digit years.
+        #         f.json_schema minimum: 2000, maximum: 2099
+        #       end
+        #
+        #       t.field "expMonth", "Int" do |f|
+        #         f.json_schema minimum: 1, maximum: 12
+        #       end
+        #
+        #       t.index "cards"
+        #     end
+        #   end
+        def json_schema(**options)
+          validatable_json_schema = Support::HashUtil.stringify_keys(options)
+
+          if (error_msg = JSONSchema.strict_meta_schema_validator.validate_with_error_message(validatable_json_schema))
+            raise SchemaError, "Invalid JSON schema options set on #{self}:\n\n#{error_msg}"
+          end
+
+          json_schema_options.update(options)
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/mixins/implements_interfaces.rb

@@ -0,0 +1,122 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/error"
+
+module ElasticGraph
+  module SchemaDefinition
+    module Mixins
+      # Mixin for types that can implement interfaces ({SchemaElements::ObjectType} and {SchemaElements::InterfaceType}).
+      module ImplementsInterfaces
+        # Declares that the current type implements the specified interface, making the current type a subtype of the interface. The
+        # current type must define all of the fields of the named interface, with the exact same field types.
+        #
+        # @param interface_names [Array<String>] names of interface types implemented by this type
+        # @return [void]
+        #
+        # @example Implement an interface
+        #  ElasticGraph.define_schema do |schema|
+        #    schema.interface_type "Athlete" do |t|
+        #      t.field "name", "String"
+        #      t.field "team", "String"
+        #    end
+        #
+        #    schema.object_type "BaseballPlayer" do |t|
+        #      t.implements "Athlete"
+        #      t.field "name", "String"
+        #      t.field "team", "String"
+        #      t.field "battingAvg", "Float"
+        #    end
+        #
+        #    schema.object_type "BasketballPlayer" do |t|
+        #      t.implements "Athlete"
+        #      t.field "name", "String"
+        #      t.field "team", "String"
+        #      t.field "pointsPerGame", "Float"
+        #    end
+        #  end
+        def implements(*interface_names)
+          interface_refs = interface_names.map do |interface_name|
+            schema_def_state.type_ref(interface_name).to_final_form.tap do |interface_ref|
+              schema_def_state.implementations_by_interface_ref[interface_ref] << self
+            end
+          end
+
+          implemented_interfaces.concat(interface_refs)
+        end
+
+        # @return [Array<SchemaElements::TypeReference>] list of type references for the interface types implemented by this type
+        def implemented_interfaces
+          @implemented_interfaces ||= []
+        end
+
+        # Called after the schema definition is complete, before dumping artifacts. Here we validate
+        # the correctness of interface implementations. We defer it until this time to not require the
+        # interface and fields to be defined before the `implements` call.
+        #
+        # Note that the GraphQL gem on its own supports a form of "interface inheritance": if declaring
+        # that an object type implements an interface, and the object type is missing one or more of the
+        # interface fields, the GraphQL gem dynamically adds the missing interface fields to the object
+        # type (at least, that's the result I noted when dumping the GraphQL SDL after trying that!).
+        # However, we cannot allow that, because our schema definition is used to generate non-GrapQL
+        # artifacts (e.g. the JSON schema and the index mapping), and all the artifacts must agree
+        # on the fields. Therefore, we use this method to verify that the object type fully implements
+        # the specified interfaces.
+        #
+        # @return [void]
+        # @private
+        def verify_graphql_correctness!
+          schema_error_messages = implemented_interfaces.filter_map do |interface_ref|
+            interface = interface_ref.resolved
+
+            case interface
+            when SchemaElements::InterfaceType
+              differences = (_ = interface).interface_fields_by_name.values.filter_map do |interface_field|
+                my_field_sdl = graphql_fields_by_name[interface_field.name]&.to_sdl(type_structure_only: true)
+                interface_field_sdl = interface_field.to_sdl(type_structure_only: true)
+
+                if my_field_sdl.nil?
+                  "missing `#{interface_field.name}`"
+                elsif my_field_sdl != interface_field_sdl
+                  "`#{interface_field_sdl.strip}` vs `#{my_field_sdl.strip}`"
+                end
+              end
+
+              unless differences.empty?
+                "Type `#{name}` does not correctly implement interface `#{interface_ref}` " \
+                  "due to field differences: #{differences.join("; ")}."
+              end
+            when nil
+              "Type `#{name}` cannot implement `#{interface_ref}` because `#{interface_ref}` is not defined."
+            else
+              "Type `#{name}` cannot implement `#{interface_ref}` because `#{interface_ref}` is not an interface."
+            end
+          end
+
+          unless schema_error_messages.empty?
+            raise SchemaError, schema_error_messages.join("\n\n")
+          end
+        end
+
+        # @yield [SchemaElements::Argument] an argument
+        # @yieldreturn [Boolean] whether or not to include the argument in the generated GraphQL SDL
+        # @return [String] SDL string of the type
+        def to_sdl(&field_arg_selector)
+          name_section =
+            if implemented_interfaces.empty?
+              name
+            else
+              "#{name} implements #{implemented_interfaces.join(" & ")}"
+            end
+
+          generate_sdl(name_section: name_section, &field_arg_selector)
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/mixins/supports_default_value.rb

@@ -0,0 +1,47 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/support/graphql_formatter"
+
+module ElasticGraph
+  module SchemaDefinition
+    module Mixins
+      # A mixin designed to be included in a schema element class that supports default values.
+      # Designed to be `prepended` so that it can hook into `initialize`.
+      module SupportsDefaultValue
+        # @private
+        def initialize(...)
+          __skip__ = super # steep can't type this.
+          @default_value = NO_DEFAULT_PROVIDED
+        end
+
+        # Used to specify the default value for this field or argument.
+        #
+        # @param default_value [Object] default value for this field or argument
+        # @return [void]
+        def default(default_value)
+          @default_value = default_value
+        end
+
+        # Generates SDL for the default value. Suitable for inclusion in the schema elememnts `#to_sdl`.
+        #
+        # @return [String]
+        def default_value_sdl
+          return nil if @default_value == NO_DEFAULT_PROVIDED
+          " = #{Support::GraphQLFormatter.serialize(@default_value)}"
+        end
+
+        private
+
+        # A sentinel value that we can use to detect when a default has been provided.
+        # We can't use `nil` to detect if a default has been provided because `nil` is a valid default value!
+        NO_DEFAULT_PROVIDED = Module.new
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/mixins/supports_filtering_and_aggregation.rb

@@ -0,0 +1,267 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+module ElasticGraph
+  module SchemaDefinition
+    module Mixins
+      # Responsible for building object types for filtering and aggregation, from an existing object type.
+      #
+      # This is specifically designed to support {SchemaElements::TypeWithSubfields} (where we have the fields directly available) and
+      # {SchemaElements::UnionType} (where we will need to compute the list of fields by resolving the subtypes and merging their fields).
+      #
+      # @private
+      module SupportsFilteringAndAggregation
+        # Indicates if this type supports a given feature (e.g. `filterable?`).
+        def supports?(&feature_predicate)
+          # If the type uses a custom mapping type we don't know if it can support a feature, so we assume it can't.
+          # TODO: clean this up using an interface instead of checking mapping options.
+          return false if has_custom_mapping_type?
+
+          graphql_fields_by_name.values.any?(&feature_predicate)
+        end
+
+        # Inverse of `supports?`.
+        def does_not_support?(&feature_predicate)
+          !supports?(&feature_predicate)
+        end
+
+        def derived_graphql_types
+          return [] if graphql_only?
+
+          indexed_agg_type = to_indexed_aggregation_type
+          indexed_aggregation_pagination_types =
+            if indexed_agg_type
+              schema_def_state.factory.build_relay_pagination_types(indexed_agg_type.name)
+            else
+              [] # : ::Array[SchemaElements::ObjectType]
+            end
+
+          sub_aggregation_types = sub_aggregation_types_for_nested_field_references.flat_map do |type|
+            [type] + schema_def_state.factory.build_relay_pagination_types(type.name, support_pagination: false) do |t|
+              # Record metadata that is necessary for elasticgraph-graphql to correctly recognize and handle
+              # this sub-aggregation correctly.
+              t.runtime_metadata_overrides = {elasticgraph_category: :nested_sub_aggregation_connection}
+            end
+          end
+
+          document_pagination_types =
+            if indexed?
+              schema_def_state.factory.build_relay_pagination_types(name, include_total_edge_count: true, derived_indexed_types: (_ = self).derived_indexed_types)
+            elsif schema_def_state.paginated_collection_element_types.include?(name)
+              schema_def_state.factory.build_relay_pagination_types(name, include_total_edge_count: true)
+            else
+              [] # : ::Array[SchemaElements::ObjectType]
+            end
+
+          sort_order_enum_type = schema_def_state.enums_for_indexed_types.sort_order_enum_for(self)
+          derived_sort_order_enum_types = [sort_order_enum_type].compact + (sort_order_enum_type&.derived_graphql_types || [])
+
+          to_input_filters +
+            document_pagination_types +
+            indexed_aggregation_pagination_types +
+            sub_aggregation_types +
+            derived_sort_order_enum_types +
+            build_aggregation_sub_aggregations_types + [
+              indexed_agg_type,
+              to_grouped_by_type,
+              to_aggregated_values_type
+            ].compact
+        end
+
+        def has_custom_mapping_type?
+          mapping_type = mapping_options[:type]
+          mapping_type && mapping_type != "object"
+        end
+
+        private
+
+        # Converts the type to the corresponding input filter type.
+        def to_input_filters
+          return [] if does_not_support?(&:filterable?)
+
+          schema_def_state.factory.build_standard_filter_input_types_for_index_object_type(name) do |t|
+            graphql_fields_by_name.values.each do |field|
+              if field.filterable?
+                t.graphql_fields_by_name[field.name] = field.to_filter_field(parent_type: t)
+              end
+            end
+          end
+        end
+
+        # Generates the `*SubAggregation` types for all of the `mapping type: "nested"` fields that reference this type.
+        # A different `*SubAggregation` type needs to be generated for each nested field reference, and for each parent nesting
+        # context of that nested field reference. This is necessary because we will support different available `sub_aggregations`
+        # based on the parents of a particular nested field.
+        #
+        # For example, given a `Player` object type definition and a `Team` type definition like this:
+        #
+        # schema.object_type "Team" do |t|
+        #   t.field "id", "ID!"
+        #   t.field "name", "String"
+        #   t.field "players", "[Player!]!" do |f|
+        #     f.mapping type: "nested"
+        #   end
+        #   t.index "teams"
+        # end
+        #
+        # ...we will generate a `TeamPlayerSubAggregation` type which will have a `sub_aggregations` field which can have
+        # `parent_team` and `seasons` fields (assuming `Player` has a `seasons` nested field...).
+        def sub_aggregation_types_for_nested_field_references
+          schema_def_state.user_defined_field_references_by_type_name.fetch(name) { [] }.select(&:nested?).flat_map do |nested_field_ref|
+            schema_def_state.sub_aggregation_paths_for(nested_field_ref.parent_type).map do |path|
+              schema_def_state.factory.new_object_type type_ref.as_sub_aggregation(parent_doc_types: path.parent_doc_types).name do |t|
+                t.documentation "Return type representing a bucket of `#{name}` objects for a sub-aggregation within each `#{type_ref.as_parent_aggregation(parent_doc_types: path.parent_doc_types).name}`."
+
+                t.field schema_def_state.schema_elements.count_detail, "AggregationCountDetail", graphql_only: true do |f|
+                  f.documentation "Details of the count of `#{name}` documents in a sub-aggregation bucket."
+                end
+
+                if supports?(&:groupable?)
+                  t.field schema_def_state.schema_elements.grouped_by, type_ref.as_grouped_by.name, graphql_only: true do |f|
+                    f.documentation "Used to specify the `#{name}` fields to group by. The returned values identify each sub-aggregation bucket."
+                  end
+                end
+
+                if supports?(&:aggregatable?)
+                  t.field schema_def_state.schema_elements.aggregated_values, type_ref.as_aggregated_values.name, graphql_only: true do |f|
+                    f.documentation "Provides computed aggregated values over all `#{name}` documents in a sub-aggregation bucket."
+                  end
+                end
+
+                if graphql_fields_by_name.values.any?(&:sub_aggregatable?)
+                  sub_aggs_name = type_ref.as_aggregation_sub_aggregations(parent_doc_types: path.parent_doc_types + [name]).name
+                  t.field schema_def_state.schema_elements.sub_aggregations, sub_aggs_name, graphql_only: true do |f|
+                    f.documentation "Used to perform sub-aggregations of `#{t.name}` data."
+                  end
+                end
+              end
+            end
+          end
+        end
+
+        # Builds the `*AggregationSubAggregations` types. For example, for an indexed type named `Team` which has nested fields,
+        # this would generate a `TeamAggregationSubAggregations` type. This type provides access to the various sub-aggregation
+        # fields.
+        def build_aggregation_sub_aggregations_types
+          # The sub-aggregation types do not generate correctly for abstract types, so for now we omit sub-aggregations for abstract types.
+          return [] if abstract?
+
+          sub_aggregatable_fields = graphql_fields_by_name.values.select(&:sub_aggregatable?)
+          return [] if sub_aggregatable_fields.empty?
+
+          schema_def_state.sub_aggregation_paths_for(self).map do |path|
+            agg_sub_aggs_type_ref = type_ref.as_aggregation_sub_aggregations(
+              parent_doc_types: path.parent_doc_types,
+              field_path: path.field_path
+            )
+
+            schema_def_state.factory.new_object_type agg_sub_aggs_type_ref.name do |t|
+              under_field_description = "under `#{path.field_path_string}` " unless path.field_path.empty?
+              t.documentation "Provides access to the `#{schema_def_state.schema_elements.sub_aggregations}` #{under_field_description}within each `#{type_ref.as_parent_aggregation(parent_doc_types: path.parent_doc_types).name}`."
+
+              sub_aggregatable_fields.each do |field|
+                if field.nested?
+                  unwrapped_type = field.type_for_derived_types.fully_unwrapped
+                  field_type_name = unwrapped_type
+                    .as_sub_aggregation(parent_doc_types: path.parent_doc_types)
+                    .as_connection
+                    .name
+
+                  field.define_sub_aggregations_field(parent_type: t, type: field_type_name) do |f|
+                    f.argument schema_def_state.schema_elements.filter, unwrapped_type.as_filter_input.name do |a|
+                      a.documentation "Used to filter the `#{unwrapped_type.name}` documents included in this sub-aggregation based on the provided criteria."
+                    end
+
+                    f.argument schema_def_state.schema_elements.first, "Int" do |a|
+                      a.documentation "Determines how many sub-aggregation buckets should be returned."
+                    end
+                  end
+                else
+                  field_type_name = type_ref.as_aggregation_sub_aggregations(
+                    parent_doc_types: path.parent_doc_types,
+                    field_path: path.field_path + [field]
+                  ).name
+
+                  field.define_sub_aggregations_field(parent_type: t, type: field_type_name)
+                end
+              end
+            end
+          end
+        end
+
+        def to_indexed_aggregation_type
+          return nil unless indexed?
+
+          schema_def_state.factory.new_object_type type_ref.as_aggregation.name do |t|
+            t.documentation "Return type representing a bucket of `#{name}` documents for an aggregations query."
+
+            if supports?(&:groupable?)
+              t.field schema_def_state.schema_elements.grouped_by, type_ref.as_grouped_by.name, graphql_only: true do |f|
+                f.documentation "Used to specify the `#{name}` fields to group by. The returned values identify each aggregation bucket."
+              end
+            end
+
+            t.field schema_def_state.schema_elements.count, "JsonSafeLong!", graphql_only: true do |f|
+              f.documentation "The count of `#{name}` documents in an aggregation bucket."
+            end
+
+            if supports?(&:aggregatable?)
+              t.field schema_def_state.schema_elements.aggregated_values, type_ref.as_aggregated_values.name, graphql_only: true do |f|
+                f.documentation "Provides computed aggregated values over all `#{name}` documents in an aggregation bucket."
+              end
+            end
+
+            # The sub-aggregation types do not generate correctly for abstract types, so for now we omit sub-aggregations for abstract types.
+            if !abstract? && supports?(&:sub_aggregatable?)
+              t.field schema_def_state.schema_elements.sub_aggregations, type_ref.as_aggregation_sub_aggregations.name, graphql_only: true do |f|
+                f.documentation "Used to perform sub-aggregations of `#{t.name}` data."
+              end
+            end
+
+            # Record metadata that is necessary for elasticgraph-graphql to correctly recognize and handle
+            # this indexed aggregation type correctly.
+            t.runtime_metadata_overrides = {source_type: name, elasticgraph_category: :indexed_aggregation}
+          end
+        end
+
+        def to_grouped_by_type
+          # If the type uses a custom mapping type we don't know how it can be aggregated, so we assume it needs no aggregation type.
+          # TODO: clean this up using an interface instead of checking mapping options.
+          return nil if has_custom_mapping_type?
+
+          new_non_empty_object_type type_ref.as_grouped_by.name do |t|
+            t.documentation "Type used to specify the `#{name}` fields to group by for aggregations."
+
+            graphql_fields_by_name.values.each do |field|
+              field.define_grouped_by_field(t)
+            end
+          end
+        end
+
+        def to_aggregated_values_type
+          # If the type uses a custom mapping type we don't know how it can be aggregated, so we assume it needs no aggregation type.
+          # TODO: clean this up using an interface instead of checking mapping options.
+          return nil if has_custom_mapping_type?
+
+          new_non_empty_object_type type_ref.as_aggregated_values.name do |t|
+            t.documentation "Type used to perform aggregation computations on `#{name}` fields."
+
+            graphql_fields_by_name.values.each do |field|
+              field.define_aggregated_values_field(t)
+            end
+          end
+        end
+
+        def new_non_empty_object_type(name, &block)
+          type = schema_def_state.factory.new_object_type(name, &block)
+          type unless type.graphql_fields_by_name.empty?
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/mixins/verifies_graphql_name.rb

@@ -0,0 +1,38 @@
+# Copyright 2024 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+require "elastic_graph/constants"
+
+module ElasticGraph
+  module SchemaDefinition
+    module Mixins
+      # Used to verify the validity of the name of GraphQL schema elements.
+      #
+      # @note This mixin is designed to be used via `prepend`, so it can add a constructor override that enforces
+      # the GraphQL name pattern as the object is built.
+      module VerifiesGraphQLName
+        # @private
+        def initialize(...)
+          __skip__ = super(...) # __skip__ tells Steep to ignore this
+
+          VerifiesGraphQLName.verify_name!(name)
+        end
+
+        # Raises if the provided name is invalid.
+        #
+        # @param name [String] name of GraphQL schema element
+        # @return [void]
+        # @raise [InvalidGraphQLNameError] if the name is invalid
+        def self.verify_name!(name)
+          return if GRAPHQL_NAME_PATTERN.match?(name)
+          raise InvalidGraphQLNameError, "Not a valid GraphQL name: `#{name}`. #{GRAPHQL_NAME_VALIDITY_DESCRIPTION}"
+        end
+      end
+    end
+  end
+end