elasticgraph-schema_definition 0.19.2.1 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa12b20af98ac82e8d84681ad3cb5f342d496fff461dadb54252dc44e5cb8202
-  data.tar.gz: f8ad7f681ba53c230931ec5f7338dafd10a611d668f9069b37122c23cf529d22
+  metadata.gz: 54e9fd94b73a36f09e090c68605743766da45b9f1777e5622a8b1b0e6985a5a5
+  data.tar.gz: c656f8bf79e9dcfa7bf88d9f4e2944a606d436b440e337fd3db9d064ad59aad5
 SHA512:
-  metadata.gz: fa2e0bd0e057cdc776384c0063426a5d85d0b36f1668edb0e15949699cbf7b67e1596f702361a20a5a5be54d20441ecd44d616110d2434db7a6b6ffb99a9e76b
-  data.tar.gz: 7294c2075b4ef69c6f40bb53e2d478a67f196a9c5936e57cf90dbcaadeb8a951b8a9581b676d4686c70b96a391965172324d4f239f64ce0d7059bf54d075c867
+  metadata.gz: d348ef2187ff3dbd29c7c3c198a61153fdf86219bca6b37c35f92bafa0bbc17a26ac46d655f5a871c5d33f14568d27ff91a413ed1431a714491119b94d2ac67b
+  data.tar.gz: 7db25426957cd9ddfd2a0af5ee78c7248040a270438d95016b73edf9e2c74a08f830866f17a381488bf11706624ef0c58cfe41405b2eaaa485b5277fd2f75914

data/lib/elastic_graph/schema_definition/factory.rb

@@ -433,6 +433,8 @@ module ElasticGraph
 
       def edge_type_for(type_name)
         type_ref = @state.type_ref(type_name)
+        object_type = type_ref.as_object_type # : SchemaElements::ObjectType
+
         new_object_type type_ref.as_edge.name do |t|
           t.relay_pagination_type = true
           t.default_graphql_resolver = :object_without_lookahead
@@ -440,7 +442,7 @@ module ElasticGraph
 
           t.documentation <<~EOS
             Represents a specific `#{type_name}` in the context of a `#{type_ref.as_connection.name}`,
-            providing access to both the `#{type_name}` and a pagination `Cursor`.
+            providing access to both the `#{type_name}` and query-specific information such as the pagination `Cursor`.
 
             See the [Relay GraphQL Cursor Connections
             Specification](https://relay.dev/graphql/connections.htm#sec-Edge-Types) for more info.
@@ -456,6 +458,18 @@ module ElasticGraph
               a `before` or `after` argument to continue paginating from this `#{type_name}`.
             EOS
           end
+
+          if object_type&.indexed?
+            t.field @state.schema_elements.all_highlights, "[SearchHighlight!]!" do |f|
+              f.documentation "All search highlights for this `#{type_name}`, indicating where in the indexed document the query matched."
+            end
+
+            if object_type.supports?(&:highlightable?)
+              t.field @state.schema_elements.highlights, type_ref.as_highlights.name do |f|
+                f.documentation "Specific search highlights for this `#{type_name}`, providing matching snippets for the requested fields."
+              end
+            end
+          end
         end
       end
 

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

@@ -42,7 +42,7 @@ module ElasticGraph
           :norms,
           :null_value,
           :search_analyzer,
-          :type,
+          :type
         ]
 
         # Defines the Elasticsearch/OpenSearch [field mapping type](https://www.elastic.co/guide/en/elasticsearch/reference/7.10/mapping-types.html)

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

@@ -70,7 +70,8 @@ module ElasticGraph
             build_aggregation_sub_aggregations_types + [
               indexed_agg_type,
               to_grouped_by_type,
-              to_aggregated_values_type
+              to_aggregated_values_type,
+              to_highlights_type
             ].compact
         end
 
@@ -263,6 +264,20 @@ module ElasticGraph
           end
         end
 
+        def to_highlights_type
+          # If the type uses a custom mapping type we don't know how it can be highlighted, so we assume it needs no highlights type.
+          return nil if does_not_support?(&:highlightable?)
+
+          new_non_empty_object_type type_ref.as_highlights.name do |t|
+            t.documentation "Type used to request desired `#{name}` search highlight fields."
+            t.default_graphql_resolver = :get_record_field_value
+
+            graphql_fields_by_name.values.each do |field|
+              field.define_highlights_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?

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

@@ -109,15 +109,9 @@ module ElasticGraph
       # ElasticGraph defines these enum types. Most of these are intended for usage as an _input_
       # argument, but they could be used as a return type in your schema if they meet your needs.
       #
-      # DateGroupingGranularity
-      # : Enumerates the supported granularities of a `Date`.
-      #
       # DateGroupingTruncationUnit
       # : Enumerates the supported truncation units of a `Date`.
       #
-      # DateTimeGroupingGranularity
-      # : Enumerates the supported granularities of a `DateTime`.
-      #
       # DateTimeGroupingTruncationUnit
       # : Enumerates the supported truncation units of a `DateTime`.
       #
@@ -157,6 +151,9 @@ module ElasticGraph
       #   `PageInfo` specification from the [Relay GraphQL Cursor Connections
       #   Specification](https://relay.dev/graphql/connections.htm#sec-undefined.PageInfo).
       #
+      # SearchHighlight
+      # : Provides information about why a document matched a search via highlighted snippets.
+      #
       # @!attribute [rw] schema_def_api
       #   @private
       # @!attribute [rw] schema_def_state
@@ -206,23 +203,6 @@ module ElasticGraph
         def register_standard_elastic_graph_types
           # This is a special filter on a `String` type, so we don't have a `Text` scalar to generate it from.
           schema_def_state.factory.build_standard_filter_input_types_for_index_leaf_type("String", name_prefix: "Text") do |t|
-            # We can't support filtering on `null` within a list, so make the field non-nullable when it's the
-            # `ListElementFilterInput` type. See scalar_type.rb for a larger comment explaining the rationale behind this.
-            equal_to_any_of_type = t.type_ref.list_element_filter_input? ? "[String!]" : "[String]"
-            t.field names.equal_to_any_of, equal_to_any_of_type do |f|
-              f.documentation ScalarType::EQUAL_TO_ANY_OF_DOC
-            end
-
-            t.field names.matches, "String" do |f|
-              f.documentation <<~EOS
-                Matches records where the field value matches the provided value using full text search.
-
-                When `null` is passed, matches all documents.
-              EOS
-
-              f.directive "deprecated", reason: "Use `#{names.matches_query}` instead."
-            end
-
             t.field names.matches_query, schema_def_state.type_ref("MatchesQuery").as_filter_input.name do |f|
               f.documentation <<~EOS
                 Matches records where the field value matches the provided query using full text search.
@@ -300,7 +280,71 @@ module ElasticGraph
               f.documentation "The input phrase to search for."
             end
 
-            # any_of/all_of/not don't really make sense on this filter because it doesn't make
+            # 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.
+
+              When `null` is passed, matches all documents.
+            EOS
+
+            t.field names.any_substring_of, "[String!]" do |f|
+              f.documentation <<~EOS
+                Matches records where the field value contains one or more of the provided substrings.
+
+                When `null` is passed, matches all documents. When an empty list is passed,
+                this part of the filter matches no documents.
+              EOS
+            end
+
+            t.field names.all_substrings_of, "[String!]" do |f|
+              f.documentation <<~EOS
+                Matches records where the field value contains all of the provided substrings.
+
+                When `null` is passed or an empty list is passed, matches all documents.
+              EOS
+            end
+
+            t.field names.ignore_case, "Boolean!" do |f|
+              f.default false
+              f.documentation "Determines if the substring matching is case-sensitive (the default) or case-insensitive."
+            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 "StringStartsWith" do |t|
+            t.documentation <<~EOS
+              Input type used to specify parameters for the `#{names.starts_with}` string filtering operator.
+
+              When `null` is passed, matches all documents.
+            EOS
+
+            t.field names.any_prefix_of, "[String!]" do |f|
+              f.documentation <<~EOS
+                Matches records where the field value starts with one or more of the provided prefixes.
+
+                When `null` is passed, matches all documents. When an empty list is passed,
+                this part of the filter matches no documents.
+              EOS
+            end
+
+            t.field names.ignore_case, "Boolean!" do |f|
+              f.default false
+              f.documentation "Determines if the prefix matching is case-sensitive (the default) or case-insensitive."
+            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.
@@ -425,6 +469,23 @@ module ElasticGraph
             end
           end
 
+          register_framework_object_type "SearchHighlight" do |t|
+            t.default_graphql_resolver = :object_without_lookahead
+
+            t.documentation "Provides information about why a document matched a search via highlighted snippets."
+
+            t.field names.path, "[String!]!" do |f|
+              f.documentation <<~EOS
+                Path to a leaf field containing one or more search highlight snippets. The returned list will contain a path segment for
+                each object layer of the schema, from the document root.
+              EOS
+            end
+
+            t.field names.snippets, "[String!]!" do |f|
+              f.documentation "List of snippets containing search highlights from field values at this `path`."
+            end
+          end
+
           schema_def_api.factory.new_input_type("DateTimeGroupingOffsetInput") do |t|
             t.documentation <<~EOS
               Input type offered when grouping on `DateTime` fields, representing the amount of offset
@@ -619,6 +680,24 @@ module ElasticGraph
           schema_def_api.scalar_type "String" do |t|
             t.mapping type: "keyword"
             t.json_schema type: "string"
+
+            t.customize_filter_input_type do |fit|
+              fit.field names.contains, schema_def_state.type_ref("StringContains").as_filter_input.name do |f|
+                f.documentation <<~EOS
+                  Matches documents using substring filtering.
+
+                  When `null` is passed, matches all documents.
+                EOS
+              end
+
+              fit.field names.starts_with, schema_def_state.type_ref("StringStartsWith").as_filter_input.name do |f|
+                f.documentation <<~EOS
+                  Matches documents using prefix filtering.
+
+                  When `null` is passed, matches all documents.
+                EOS
+              end
+            end
           end
         end
 
@@ -953,38 +1032,6 @@ module ElasticGraph
           # elasticgraph-graphql/spec/acceptance/elasticgraph_graphql_spec.rb
           es_first_day_of_week = "Monday"
 
-          # TODO: Drop support for legacy grouping schema
-          schema_def_api.enum_type "DateGroupingGranularity" do |t|
-            t.documentation <<~EOS
-              Enumerates the supported granularities of a `Date`.
-            EOS
-
-            t.value "YEAR" do |v|
-              v.documentation "The year a `Date` falls in."
-              v.update_runtime_metadata datastore_value: "year"
-            end
-
-            t.value "QUARTER" do |v|
-              v.documentation "The quarter a `Date` falls in."
-              v.update_runtime_metadata datastore_value: "quarter"
-            end
-
-            t.value "MONTH" do |v|
-              v.documentation "The month a `Date` falls in."
-              v.update_runtime_metadata datastore_value: "month"
-            end
-
-            t.value "WEEK" do |v|
-              v.documentation "The week, beginning on #{es_first_day_of_week}, a `Date` falls in."
-              v.update_runtime_metadata datastore_value: "week"
-            end
-
-            t.value "DAY" do |v|
-              v.documentation "The exact day of a `Date`."
-              v.update_runtime_metadata datastore_value: "day"
-            end
-          end
-
           schema_def_api.enum_type "DateGroupingTruncationUnit" do |t|
             t.documentation <<~EOS
               Enumerates the supported truncation units of a `Date`.
@@ -1016,53 +1063,6 @@ module ElasticGraph
             end
           end
 
-          # TODO: Drop support for legacy grouping schema
-          schema_def_api.enum_type "DateTimeGroupingGranularity" do |t|
-            t.documentation <<~EOS
-              Enumerates the supported granularities of a `DateTime`.
-            EOS
-
-            t.value "YEAR" do |v|
-              v.documentation "The year a `DateTime` falls in."
-              v.update_runtime_metadata datastore_value: "year"
-            end
-
-            t.value "QUARTER" do |v|
-              v.documentation "The quarter a `DateTime` falls in."
-              v.update_runtime_metadata datastore_value: "quarter"
-            end
-
-            t.value "MONTH" do |v|
-              v.documentation "The month a `DateTime` falls in."
-              v.update_runtime_metadata datastore_value: "month"
-            end
-
-            t.value "WEEK" do |v|
-              v.documentation "The week, beginning on #{es_first_day_of_week}, a `DateTime` falls in."
-              v.update_runtime_metadata datastore_value: "week"
-            end
-
-            t.value "DAY" do |v|
-              v.documentation "The day a `DateTime` falls in."
-              v.update_runtime_metadata datastore_value: "day"
-            end
-
-            t.value "HOUR" do |v|
-              v.documentation "The hour a `DateTime` falls in."
-              v.update_runtime_metadata datastore_value: "hour"
-            end
-
-            t.value "MINUTE" do |v|
-              v.documentation "The minute a `DateTime` falls in."
-              v.update_runtime_metadata datastore_value: "minute"
-            end
-
-            t.value "SECOND" do |v|
-              v.documentation "The second a `DateTime` falls in."
-              v.update_runtime_metadata datastore_value: "second"
-            end
-          end
-
           schema_def_api.enum_type "DateTimeGroupingTruncationUnit" do |t|
             t.documentation <<~EOS
               Enumerates the supported truncation units of a `DateTime`.

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

@@ -52,6 +52,8 @@ module ElasticGraph
       #   @private
       # @!attribute [rw] grouped_by_customizations
       #   @private
+      # @!attribute [rw] highlights_customizations
+      #   @private
       # @!attribute [rw] sub_aggregations_customizations
       #   @private
       # @!attribute [rw] aggregated_values_customizations
@@ -68,6 +70,8 @@ module ElasticGraph
       #   @private
       # @!attribute [rw] groupable
       #   @private
+      # @!attribute [rw] highlightable
+      #   @private
       # @!attribute [rw] source
       #   @private
       # @!attribute [rw] runtime_field_script
@@ -80,19 +84,16 @@ module ElasticGraph
       #   @private
       # @!attribute [rw] non_nullable_in_json_schema
       #   @private
-      # @!attribute [rw] backing_indexing_field
-      #   @private
       # @!attribute [rw] as_input
       #   @private
-      # @!attribute [rw] legacy_grouping_schema
-      #   @private
       class Field < Struct.new(
         :name, :original_type, :parent_type, :original_type_for_derived_types, :schema_def_state, :accuracy_confidence,
-        :filter_customizations, :grouped_by_customizations, :sub_aggregations_customizations,
-        :aggregated_values_customizations, :sort_order_enum_value_customizations,
-        :args, :sortable, :filterable, :aggregatable, :groupable, :graphql_only, :source, :runtime_field_script, :relationship, :singular_name,
-        :computation_detail, :non_nullable_in_json_schema, :backing_indexing_field, :as_input,
-        :legacy_grouping_schema, :name_in_index, :resolver
+        :filter_customizations, :grouped_by_customizations, :highlights_customizations, :sub_aggregations_customizations,
+        :aggregated_values_customizations, :sort_order_enum_value_customizations, :args,
+        :sortable, :filterable, :aggregatable, :groupable, :highlightable,
+        :graphql_only, :source, :runtime_field_script, :relationship, :singular_name,
+        :computation_detail, :non_nullable_in_json_schema, :as_input,
+        :name_in_index, :resolver
       )
         include Mixins::HasDocumentation
         include Mixins::HasDirectives
@@ -104,8 +105,8 @@ module ElasticGraph
           name:, type:, parent_type:, schema_def_state:,
           accuracy_confidence: :high, name_in_index: name,
           type_for_derived_types: nil, graphql_only: nil, singular: nil,
-          sortable: nil, filterable: nil, aggregatable: nil, groupable: nil,
-          backing_indexing_field: nil, as_input: false, legacy_grouping_schema: false, resolver: nil
+          sortable: nil, filterable: nil, aggregatable: nil, groupable: nil, highlightable: nil,
+          as_input: false, resolver: nil
         )
           type_ref = schema_def_state.type_ref(type)
           super(
@@ -117,6 +118,7 @@ module ElasticGraph
             accuracy_confidence: accuracy_confidence,
             filter_customizations: [],
             grouped_by_customizations: [],
+            highlights_customizations: [],
             sub_aggregations_customizations: [],
             aggregated_values_customizations: [],
             sort_order_enum_value_customizations: [],
@@ -125,6 +127,7 @@ module ElasticGraph
             filterable: filterable,
             aggregatable: aggregatable,
             groupable: groupable,
+            highlightable: highlightable,
             graphql_only: graphql_only,
             source: nil,
             runtime_field_script: nil,
@@ -134,9 +137,7 @@ module ElasticGraph
             singular_name: singular,
             name_in_index: name_in_index,
             non_nullable_in_json_schema: false,
-            backing_indexing_field: backing_indexing_field,
             as_input: as_input,
-            legacy_grouping_schema: legacy_grouping_schema,
             resolver: resolver
           )
 
@@ -179,6 +180,7 @@ module ElasticGraph
         # @return [void]
         # @see #customize_aggregated_values_field
         # @see #customize_grouped_by_field
+        # @see #customize_highlights_field
         # @see #customize_sort_order_enum_values
         # @see #customize_sub_aggregations_field
         # @see #on_each_generated_schema_element
@@ -211,6 +213,7 @@ module ElasticGraph
         # @return [void]
         # @see #customize_filter_field
         # @see #customize_grouped_by_field
+        # @see #customize_highlights_field
         # @see #customize_sort_order_enum_values
         # @see #customize_sub_aggregations_field
         # @see #on_each_generated_schema_element
@@ -243,6 +246,7 @@ module ElasticGraph
         # @return [void]
         # @see #customize_aggregated_values_field
         # @see #customize_filter_field
+        # @see #customize_highlights_field
         # @see #customize_sort_order_enum_values
         # @see #customize_sub_aggregations_field
         # @see #on_each_generated_schema_element
@@ -265,6 +269,39 @@ module ElasticGraph
           grouped_by_customizations << customization_block
         end
 
+        # @note For each field defined in your schema that is highlightable, a corresponding highlights field will be created on the
+        #   `*Highlights` type derived from the parent object type.
+        #
+        # Registers a customization callback that will be applied to the corresponding highlights field that will be generated for this
+        # field.
+        #
+        # @yield [Field] derived highlights field
+        # @return [void]
+        # @see #customize_aggregated_values_field
+        # @see #customize_filter_field
+        # @see #customize_grouped_by_field
+        # @see #customize_sort_order_enum_values
+        # @see #customize_sub_aggregations_field
+        # @see #on_each_generated_schema_element
+        #
+        # @example Mark `CampaignHighlights.organizationId` with `@deprecated`
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Campaign" do |t|
+        #       t.field "id", "ID"
+        #
+        #       t.field "organizationId", "ID" do |f|
+        #         f.customize_highlights_field do |gbf|
+        #           gbf.directive "deprecated"
+        #         end
+        #       end
+        #
+        #       t.index "campaigns"
+        #     end
+        #   end
+        def customize_highlights_field(&customization_block)
+          highlights_customizations << customization_block
+        end
+
         # @note For each field defined in your schema that is sub-aggregatable (e.g. list fields indexed using the `nested` mapping type),
         # a corresponding field will be created on the `*AggregationSubAggregations` type derived from the parent object type.
         #
@@ -276,6 +313,7 @@ module ElasticGraph
         # @see #customize_aggregated_values_field
         # @see #customize_filter_field
         # @see #customize_grouped_by_field
+        # @see #customize_highlights_field
         # @see #customize_sort_order_enum_values
         # @see #on_each_generated_schema_element
         #
@@ -317,6 +355,7 @@ module ElasticGraph
         # @see #customize_aggregated_values_field
         # @see #customize_filter_field
         # @see #customize_grouped_by_field
+        # @see #customize_highlights_field
         # @see #customize_sub_aggregations_field
         # @see #on_each_generated_schema_element
         #
@@ -345,6 +384,8 @@ module ElasticGraph
         #   ask for values for the field in a response.
         # * A {Field} may be generated on the `*FilterInput` {InputType} derived from the parent {ObjectType} or {InterfaceType}. This is
         #   used by clients to specify how the query should filter.
+        # * A {Field} may be generated on the `*Highlights` {ObjectType} derived from the parent {ObjectType} or {InterfaceType}. This is
+        #   used by clients to request search highlights for a field.
         # * A {Field} may be generated on the `*AggregationGroupedBy` {ObjectType} derived from the parent {ObjectType} or {InterfaceType}.
         #   This is used by clients to specify how aggregations should be grouped.
         # * A {Field} may be generated on the `*AggregatedValues` {ObjectType} derived from the parent {ObjectType} or {InterfaceType}.
@@ -361,6 +402,7 @@ module ElasticGraph
         # @see #customize_aggregated_values_field
         # @see #customize_filter_field
         # @see #customize_grouped_by_field
+        # @see #customize_highlights_field
         # @see #customize_sort_order_enum_values
         # @see #customize_sub_aggregations_field
         #
@@ -369,15 +411,16 @@ module ElasticGraph
         #     schema.object_type "Transaction" do |t|
         #       t.field "id", "ID"
         #
-        #       t.field "amount", "Int" do |f|
+        #       t.field "currency", "String" do |f|
         #         f.on_each_generated_schema_element do |element|
-        #           # Adds a `@deprecated` directive to every GraphQL schema element generated for `amount`:
+        #           # Adds a `@deprecated` directive to every GraphQL schema element generated for `currency`:
         #           #
-        #           # - The `Transaction.amount` field.
-        #           # - The `TransactionFilterInput.amount` field.
-        #           # - The `TransactionAggregationGroupedBy.amount` field.
-        #           # - The `TransactionAggregatedValues.amount` field.
-        #           # - The `TransactionSortOrder.amount_ASC` and`TransactionSortOrder.amount_DESC` enum values.
+        #           # - The `Transaction.currency` field.
+        #           # - The `TransactionFilterInput.currency` field.
+        #           # - The `TransactionHighlights.currency` field.
+        #           # - The `TransactionAggregationGroupedBy.currency` field.
+        #           # - The `TransactionAggregatedValues.currency` field.
+        #           # - The `TransactionSortOrder.currency_ASC` and`TransactionSortOrder.currency_DESC` enum values.
         #           element.directive "deprecated"
         #         end
         #       end
@@ -390,6 +433,7 @@ module ElasticGraph
           customize_filter_field(&customization_block)
           customize_aggregated_values_field(&customization_block)
           customize_grouped_by_field(&customization_block)
+          customize_highlights_field(&customization_block)
           customize_sub_aggregations_field(&customization_block)
           customize_sort_order_enum_values(&customization_block)
         end
@@ -607,6 +651,17 @@ module ElasticGraph
           nested? || type_for_derived_types.fully_unwrapped.as_object_type&.supports?(&:sub_aggregatable?)
         end
 
+        # @private
+        HIGHLIGHTABLE_MAPPING_TYPES = %w[keyword text match_only_text]
+
+        def highlightable?
+          return highlightable unless highlightable.nil?
+          return false if relationship
+          return true if HIGHLIGHTABLE_MAPPING_TYPES.include?(mapping_type)
+
+          type_for_derived_types.fully_unwrapped.as_object_type&.supports?(&:highlightable?)
+        end
+
         # Defines an argument on the field.
         #
         # @note ElasticGraph takes care of defining arguments for all the query features it supports, so there is generally no need to use
@@ -672,16 +727,32 @@ module ElasticGraph
           parent_type.field field_name, grouped_by_field_type_name, name_in_index: name_in_index, graphql_only: true do |f|
             add_grouped_by_field_documentation(f)
 
-            define_legacy_timestamp_grouping_arguments_if_needed(f) if legacy_grouping_schema
-
             grouped_by_customizations.each { |block| block.call(f) }
           end
         end
 
+        # @private
+        def define_highlights_field(parent_type)
+          return unless highlightable?
+
+          unwrapped_type = type_for_derived_types.fully_unwrapped
+          type_name =
+            if unwrapped_type.leaf?
+              "[String!]!"
+            else
+              unwrapped_type.as_highlights.name
+            end
+
+          parent_type.field name, type_name, name_in_index: name_in_index, graphql_only: true do |f|
+            f.documentation derived_documentation("Search highlights for the `#{name}`, providing snippets of the matching text")
+            highlights_customizations.each { |block| block.call(f) }
+          end
+        end
+
         # @private
         def grouped_by_field_type_name
           unwrapped_type = type_for_derived_types.fully_unwrapped
-          if unwrapped_type.scalar_type_needing_grouped_by_object? && !legacy_grouping_schema
+          if unwrapped_type.scalar_type_needing_grouped_by_object?
             unwrapped_type.with_reverted_override.as_grouped_by.name
           elsif unwrapped_type.leaf?
             unwrapped_type.name
@@ -702,7 +773,7 @@ module ElasticGraph
               "The `#{name}` field value for this group",
               list_field_grouped_by_doc_note("the selected subfields of `#{name}`")
             )
-          elsif type_for_derived_types.fully_unwrapped.scalar_type_needing_grouped_by_object? && !legacy_grouping_schema
+          elsif type_for_derived_types.fully_unwrapped.scalar_type_needing_grouped_by_object?
             derived_documentation("Offers the different grouping options for the `#{name}` value within this group")
           else
             derived_documentation("The `#{name}` field value for this group")
@@ -936,6 +1007,11 @@ module ElasticGraph
 
         private
 
+        def backing_indexing_field
+          return nil unless graphql_only
+          parent_type.indexing_fields_by_name_in_index[name_in_index]
+        end
+
         def args_sdl(joiner:, after_opening_paren: "", &arg_selector)
           selected_args = args.values.select(&arg_selector)
           args_sdl = selected_args.map(&:to_sdl).flat_map { |s| s.split("\n") }.join(joiner)
@@ -948,40 +1024,6 @@ module ElasticGraph
           mapping_type == "text"
         end
 
-        def define_legacy_timestamp_grouping_arguments_if_needed(grouping_field)
-          case type.fully_unwrapped.name
-          when "Date"
-            grouping_field.argument schema_def_state.schema_elements.granularity, "DateGroupingGranularity!" do |a|
-              a.documentation "Determines the grouping granularity for this field."
-            end
-
-            grouping_field.argument schema_def_state.schema_elements.offset_days, "Int" do |a|
-              a.documentation <<~EOS
-                Number of days (positive or negative) to shift the `Date` boundaries of each date grouping bucket.
-
-                For example, when grouping by `YEAR`, this can be used to align the buckets with fiscal or school years instead of calendar years.
-              EOS
-            end
-          when "DateTime"
-            grouping_field.argument schema_def_state.schema_elements.granularity, "DateTimeGroupingGranularity!" do |a|
-              a.documentation "Determines the grouping granularity for this field."
-            end
-
-            grouping_field.argument schema_def_state.schema_elements.time_zone, "TimeZone" do |a|
-              a.documentation "The time zone to use when determining which grouping a `DateTime` value falls in."
-              a.default "UTC"
-            end
-
-            grouping_field.argument schema_def_state.schema_elements.offset, "DateTimeGroupingOffsetInput" do |a|
-              a.documentation <<~EOS
-                Amount of offset (positive or negative) to shift the `DateTime` boundaries of each grouping bucket.
-
-                For example, when grouping by `WEEK`, you can shift by 24 hours to change what day-of-week weeks are considered to start on.
-              EOS
-            end
-          end
-        end
-
         def list_field_grouped_by_doc_note(individual_value_selection_description)
           <<~EOS.strip
             Note: `#{name}` is a collection field, but selecting this field will group on individual values of #{individual_value_selection_description}.

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

@@ -39,7 +39,16 @@ module ElasticGraph
       #   @private
       # @!attribute [rw] aggregated_values_customizations
       #   @private
-      class ScalarType < Struct.new(:schema_def_state, :type_ref, :mapping_type, :runtime_metadata, :aggregated_values_customizations)
+      # @!attribute [rw] filter_input_customizations
+      #   @private
+      class ScalarType < Struct.new(
+        :schema_def_state,
+        :type_ref,
+        :mapping_type,
+        :runtime_metadata,
+        :aggregated_values_customizations,
+        :filter_input_customizations
+      )
         # `Struct.new` provides the following methods:
         # @dynamic type_ref, runtime_metadata
         prepend Mixins::VerifiesGraphQLName
@@ -157,6 +166,13 @@ module ElasticGraph
           self.aggregated_values_customizations = block
         end
 
+        # Registers a block which will be used to customize the derived `*FilterInput` object type.
+        #
+        # @private
+        def customize_filter_input_type(&block)
+          self.filter_input_customizations = block
+        end
+
         # @private
         def aggregated_values_type
           if aggregated_values_customizations
@@ -284,6 +300,8 @@ module ElasticGraph
                 f.documentation LTE_DOC
               end
             end
+
+            filter_input_customizations&.call(t)
           end
         end
 

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

@@ -147,6 +147,7 @@ module ElasticGraph
           FieldsListFilterInput: "%{base}FieldsListFilterInput",
           FilterInput: "%{base}FilterInput",
           GroupedBy: "%{base}GroupedBy",
+          Highlights: "%{base}Highlights",
           InputEnum: "%{base}Input",
           ListElementFilterInput: "%{base}ListElementFilterInput",
           ListFilterInput: "%{base}ListFilterInput",

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

@@ -287,6 +287,7 @@ module ElasticGraph
         # @dynamic as_edge
         # @dynamic as_fields_list_filter_input
         # @dynamic as_filter_input
+        # @dynamic as_highlights
         # @dynamic as_input_enum
         # @dynamic as_list_element_filter_input, list_element_filter_input?
         # @dynamic as_list_filter_input, list_filter_input?

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

@@ -301,7 +301,7 @@ module ElasticGraph
 
           schema_def_state.paginated_collection_element_types << element_type
 
-          backing_indexing_field = field(name, "[#{element_type}!]!", indexing_only: true, name_in_index: name_in_index, &block)
+          field(name, "[#{element_type}!]!", indexing_only: true, name_in_index: name_in_index, &block)
 
           field(
             name,
@@ -311,8 +311,7 @@ module ElasticGraph
             groupable: !!singular,
             sortable: false,
             graphql_only: true,
-            singular: singular,
-            backing_indexing_field: backing_indexing_field
+            singular: singular
           ) do |f|
             f.define_relay_pagination_arguments!
             block&.call(f)

data/lib/elastic_graph/schema_definition/scripting/scripts/update/index_data.painless

@@ -31,30 +31,10 @@ if (previousSourceIdsForRelationship.size() > 0) {
  );
 }
 
-// While the version in `__versions` is going to be used for the doc version in the future, for now
-// we need to continue getting it from `__sourceVersions`. Both our old version and this versions of this
-// script keep the value in `__sourceVersions` up-to-date, whereas the old script only writes it to
-// `__sourceVersions`. Until we have completely migrated off of the old script for all ElasticGraph
-// clusters, we need to keep using it.
-//
-// Later, after the old script is no longer used by any clusters, we'll stop using `__sourceVersions`.
-Number _versionForSourceType = source.get("__sourceVersions")?.get(params.sourceType)?.get(sourceId);
-Number _versionForRelationship = relationshipVersionsMap.get(sourceId);
+Number maybeDocVersion = source.__versions.get(params.relationship)?.get(params.sourceId);
 
 // Our JSON schema requires event versions to be non-negative, so we can safely use Long.MIN_VALUE as a stand-in when the value is null.
-long versionForSourceType = _versionForSourceType == null ? Long.MIN_VALUE : _versionForSourceType.longValue();
-long versionForRelationship = _versionForRelationship == null ? Long.MIN_VALUE : _versionForRelationship.longValue();
-
-// Pick the larger of the two versions as our doc version. Note that `Math.max` didn't work for me here for
-// reasons I don't understand, but a simple ternary works fine.
-//
-// In theory, we could just use `versionForSourceType` as the `docVersion` (and not even check `__versions` at all)
-// since both the old version and this version maintain the doc version in `__sourceVersions`. However, that would
-// prevent this version of the script from being forward-compatible with the planned next version of this script.
-// In the next version, we plan to stop writing to `__sourceVersions`, and as we can't deploy that change atomically,
-// this version of the script will continue to run after that has begun to be used. So this version of the script
-// must consider which version is greater here, and not simply trust either version value.
-long docVersion = versionForSourceType > versionForRelationship ? versionForSourceType : versionForRelationship;
+long docVersion = maybeDocVersion == null ? Long.MIN_VALUE : maybeDocVersion.longValue();
 
 if (docVersion >= eventVersion) {
   throw new IllegalArgumentException("ElasticGraph update was a no-op: [" +

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: elasticgraph-schema_definition
 version: !ruby/object:Gem::Version
-  version: 0.19.2.1
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Myron Marston
@@ -9,7 +9,7 @@ authors:
 - Block Engineering
 bindir: bin
 cert_chain: []
-date: 2025-04-24 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: elasticgraph-graphql
@@ -17,84 +17,84 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
 - !ruby/object:Gem::Dependency
   name: elasticgraph-indexer
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
 - !ruby/object:Gem::Dependency
   name: elasticgraph-json_schema
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
 - !ruby/object:Gem::Dependency
   name: elasticgraph-schema_artifacts
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
 - !ruby/object:Gem::Dependency
   name: elasticgraph-support
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
 - !ruby/object:Gem::Dependency
   name: graphql
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.5.4
+        version: 2.5.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.5.4
+        version: 2.5.6
 - !ruby/object:Gem::Dependency
   name: graphql-c_parser
   requirement: !ruby/object:Gem::Requirement
@@ -104,7 +104,7 @@ dependencies:
         version: '1.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.2
+        version: 1.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -114,7 +114,7 @@ dependencies:
         version: '1.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.2
+        version: 1.1.3
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -141,56 +141,56 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
 - !ruby/object:Gem::Dependency
   name: elasticgraph-datastore_core
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
 - !ruby/object:Gem::Dependency
   name: elasticgraph-elasticsearch
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
 - !ruby/object:Gem::Dependency
   name: elasticgraph-opensearch
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.19.2.1
+        version: 1.0.0.rc1
 email:
 - myron@squareup.com
 executables: []
@@ -275,10 +275,10 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/block/elasticgraph/issues
-  changelog_uri: https://github.com/block/elasticgraph/releases/tag/v0.19.2.1
-  documentation_uri: https://block.github.io/elasticgraph/api-docs/v0.19.2.1/
+  changelog_uri: https://github.com/block/elasticgraph/releases/tag/v1.0.0.rc1
+  documentation_uri: https://block.github.io/elasticgraph/api-docs/v1.0.0.rc1/
   homepage_uri: https://block.github.io/elasticgraph/
-  source_code_uri: https://github.com/block/elasticgraph/tree/v0.19.2.1/elasticgraph-schema_definition
+  source_code_uri: https://github.com/block/elasticgraph/tree/v1.0.0.rc1/elasticgraph-schema_definition
   gem_category: local
 rdoc_options: []
 require_paths:
@@ -287,7 +287,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.4'
   - - "<"
     - !ruby/object:Gem::Version
       version: '3.5'
@@ -297,7 +297,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: ElasticGraph gem that provides the schema definition API and generates schema
   artifacts.