elasticgraph-graphql 0.19.3.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22324b1b8acd027bd6836c86194e398e8684cdaf85df7e98cd213482b451146f
-  data.tar.gz: 82b689cf8dda30d2988dc0a775123fb549929ca0b0fb3c3ff042da9b5dbf3944
+  metadata.gz: 24f8c6670bb21bcf8936b9bd55cc2e3d6964e78ef9e3742881e720dc0e212404
+  data.tar.gz: 8b1de56fd5b6732905fb07fc4d2ece0480784104e6b860d42b0f62027463cef2
 SHA512:
-  metadata.gz: fecaef223e61e420e4111391e236e6f8e7f2aceb26039fa8bd070704c5f2dec52321b3877c85a6aefa24ad87cca286780dbf8dc033615410885cff7b229a18ef
-  data.tar.gz: f5bdbe3017ad833d6c5cc7e847812a3af051179c2becdc11f39755f98c5f0eadca9dc0d5ce86ad6a711c3fecfa50c2b745be70c2e914350ec6b8ed82a8ee2284
+  metadata.gz: 399538281bc06bcea0a5ede7fc1c63990658def8aca9e9d2d22994e59d57d157fb0ef6b7d6c6b0270b528b278e8b77b3e20303bb9cbec2a5894bfccdc209e9fa
+  data.tar.gz: '072188ff912c10f81da236a0f5c9faab646976ad0bd33e57a0008bb2fc82add9e38896aa4e55331c308520145c4e79e6a5eba942e8f8b903862d05b29b2c82b6'

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

@@ -209,29 +209,9 @@ module ElasticGraph
             # New date/time grouping API (DateGroupedBy, DateTimeGroupedBy)
             if field.type.elasticgraph_category == :date_grouped_by_object
               date_time_groupings_from(field_path: field_path, node: node)
-
             elsif !field.type.object?
-              case field.type.name
-              # Legacy date grouping API
-              when "Date"
-                legacy_date_histogram_groupings_from(
-                  field_path: field_path,
-                  node: node,
-                  get_time_zone: ->(args) {},
-                  get_offset: ->(args) { args[element_names.offset_days]&.then { |days| "#{days}d" } }
-                )
-              # Legacy datetime grouping API
-              when "DateTime"
-                legacy_date_histogram_groupings_from(
-                  field_path: field_path,
-                  node: node,
-                  get_time_zone: ->(args) { args.fetch(element_names.time_zone) },
-                  get_offset: ->(args) { datetime_offset_from(node, args) }
-                )
               # Non-date/time grouping
-              else
-                [FieldTermGrouping.new(field_path: field_path)]
-              end
+              [FieldTermGrouping.new(field_path: field_path)]
             end
           end
         end
@@ -264,7 +244,7 @@ module ElasticGraph
                 field_path: child_field_path,
                 script_id: runtime_metadata.static_script_ids_by_scoped_name.fetch("field/as_time_of_day"),
                 params: {
-                  "interval" => interval_from(child_node, schema_args, interval_unit_key: element_names.truncation_unit),
+                  "interval" => interval_from(child_node, schema_args),
                   "offset_ms" => datetime_offset_as_ms_from(child_node, schema_args),
                   "time_zone" => time_zone
                 }
@@ -272,7 +252,7 @@ module ElasticGraph
             else
               DateHistogramGrouping.new(
                 field_path: child_field_path,
-                interval: interval_from(child_node, schema_args, interval_unit_key: element_names.truncation_unit),
+                interval: interval_from(child_node, schema_args),
                 offset: datetime_offset_from(child_node, schema_args),
                 time_zone: time_zone
               )
@@ -280,22 +260,10 @@ module ElasticGraph
           end
         end
 
-        def legacy_date_histogram_groupings_from(field_path:, node:, get_time_zone:, get_offset:)
-          schema_args = Schema::Arguments.to_schema_form(node.arguments, node.field)
-
-          [DateHistogramGrouping.new(
-            field_path: field_path,
-            interval: interval_from(node, schema_args, interval_unit_key: element_names.granularity),
-            time_zone: get_time_zone.call(schema_args),
-            offset: get_offset.call(schema_args)
-          )]
-        end
-
         # Figure out the Date histogram grouping interval for the given node based on the `grouped_by` argument.
-        # Until `legacy_grouping_schema` is removed, we need to check both `granularity` and `truncation_unit`.
-        def interval_from(node, schema_args, interval_unit_key:)
-          enum_type_name = node.field.arguments.fetch(interval_unit_key).type.unwrap.graphql_name
-          enum_value_name = schema_args.fetch(interval_unit_key)
+        def interval_from(node, schema_args)
+          enum_type_name = node.field.arguments.fetch(element_names.truncation_unit).type.unwrap.graphql_name
+          enum_value_name = schema_args.fetch(element_names.truncation_unit)
           enum_value = schema.type_named(enum_type_name).enum_value_named(enum_value_name)
 
           _ = enum_value.runtime_metadata.datastore_value

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

@@ -29,7 +29,7 @@ module ElasticGraph
 
           def sub_aggregations
             @sub_aggregations ||= SubAggregations.new(
-              schema_element_names,
+              schema,
               query.sub_aggregations,
               parent_queries + [query],
               bucket,
@@ -42,7 +42,7 @@ module ElasticGraph
           end
 
           def count_detail
-            @count_detail ||= CountDetail.new(schema_element_names, bucket)
+            @count_detail ||= CountDetail.new(schema, bucket)
           end
 
           def cursor

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

@@ -15,18 +15,19 @@ module ElasticGraph
     module Aggregation
       module Resolvers
         module RelayConnectionBuilder
-          def self.build_from_search_response(query:, search_response:, schema_element_names:)
-            build_from_buckets(query: query, parent_queries: [], schema_element_names: schema_element_names) do
+          def self.build_from_search_response(query:, search_response:, schema:)
+            build_from_buckets(query: query, parent_queries: [], schema: schema) do
               extract_buckets_from(search_response, for_query: query)
             end
           end
 
-          def self.build_from_buckets(query:, parent_queries:, schema_element_names:, field_path: [], &build_buckets)
+          def self.build_from_buckets(query:, parent_queries:, schema:, field_path: [], &build_buckets)
             GraphQL::Resolvers::RelayConnection::GenericAdapter.new(
-              schema_element_names: schema_element_names,
-              raw_nodes: raw_nodes_for(query, parent_queries, schema_element_names, field_path, &build_buckets),
+              schema: schema,
+              raw_nodes: raw_nodes_for(query, parent_queries, schema, field_path, &build_buckets),
               paginator: query.paginator,
               get_total_edge_count: -> {},
+              edge_class: (_ = GraphQL::Resolvers::RelayConnection::GenericAdapter::Edge),
               to_sort_value: ->(node, decoded_cursor) do
                 query.groupings.map do |grouping|
                   DatastoreQuery::Paginator::SortValue.new(
@@ -39,13 +40,13 @@ module ElasticGraph
             )
           end
 
-          private_class_method def self.raw_nodes_for(query, parent_queries, schema_element_names, field_path)
+          private_class_method def self.raw_nodes_for(query, parent_queries, schema, field_path)
             # The `DecodedCursor::SINGLETON` is a special case, so handle it here.
             return [] if query.paginator.paginated_from_singleton_cursor?
 
             yield.map do |bucket|
               Node.new(
-                schema_element_names: schema_element_names,
+                schema: schema,
                 query: query,
                 parent_queries: parent_queries,
                 bucket: bucket,

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

@@ -19,7 +19,7 @@ module ElasticGraph
   class GraphQL
     module Aggregation
       module Resolvers
-        class SubAggregations < ::Data.define(:schema_element_names, :sub_aggregations, :parent_queries, :sub_aggs_by_agg_key, :field_path)
+        class SubAggregations < ::Data.define(:schema, :sub_aggregations, :parent_queries, :sub_aggs_by_agg_key, :field_path)
           def resolve(field:, object:, args:, context:, lookahead:)
             path_segment = PathSegment.for(field: field, lookahead: lookahead)
             new_field_path = field_path + [path_segment]
@@ -31,7 +31,7 @@ module ElasticGraph
             RelayConnectionBuilder.build_from_buckets(
               query: sub_agg_query,
               parent_queries: parent_queries,
-              schema_element_names: schema_element_names,
+              schema: schema,
               field_path: new_field_path
             ) { extract_buckets(sub_agg_key, args) }
           end
@@ -41,7 +41,7 @@ module ElasticGraph
           def extract_buckets(aggregation_field_path, args)
             # When the client passes `first: 0`, we omit the sub-aggregation from the query body entirely,
             # and it wont' be in `sub_aggs_by_agg_key`. Instead, we can just return an empty list of buckets.
-            return [] if args[schema_element_names.first] == 0
+            return [] if args[schema.element_names.first] == 0
 
             sub_agg_key = Key.encode(parent_queries.map(&:name) + [aggregation_field_path])
             sub_agg = Support::HashUtil.verbose_fetch(sub_aggs_by_agg_key, sub_agg_key)

data/lib/elastic_graph/graphql/config.rb

@@ -20,12 +20,6 @@ module ElasticGraph
       :max_page_size,
       # Queries that take longer than this configured threshold will have a sanitized version logged.
       :slow_query_latency_warning_threshold_in_ms,
-      # How to resolve nested relationships:
-      #
-      # - `optimized` (default): uses the new (in ElasticGraph 0.19.2.0) optimized resolver logic.
-      # - `original`: uses the resolver logic from ElasticGraph v0.19.1.1 and before.
-      # - `comparison`: runs both versions of the logic in serial, to compare them for correctness and performance. Results are logged.
-      :nested_relationship_resolver_mode,
       # Object used to identify the client of a GraphQL query based on the HTTP request.
       :client_resolver,
       # Array of modules that will be extended onto the `GraphQL` instance to support extension libraries.
@@ -51,17 +45,10 @@ module ElasticGraph
           end
         end
 
-        nested_relationship_resolver_mode = parsed_yaml["nested_relationship_resolver_mode"]&.to_sym || :optimized
-        unless VALID_NESTED_RELATIONSHIP_RESOLVER_MODES.include?(nested_relationship_resolver_mode)
-          raise Errors::ConfigError, "Invalid value for `nested_relationship_resolver_mode`: #{nested_relationship_resolver_mode}. " \
-            "Valid values: #{VALID_NESTED_RELATIONSHIP_RESOLVER_MODES.join(", ")}."
-        end
-
         new(
           default_page_size: parsed_yaml.fetch("default_page_size"),
           max_page_size: parsed_yaml.fetch("max_page_size"),
           slow_query_latency_warning_threshold_in_ms: parsed_yaml["slow_query_latency_warning_threshold_in_ms"] || 5000,
-          nested_relationship_resolver_mode: nested_relationship_resolver_mode,
           client_resolver: load_client_resolver(parsed_yaml),
           extension_modules: extension_mods,
           extension_settings: entire_parsed_yaml.except(*ELASTICGRAPH_CONFIG_KEYS)
@@ -74,8 +61,6 @@ module ElasticGraph
       # The standard ElasticGraph root config setting keys; anything else is assumed to be extension settings.
       ELASTICGRAPH_CONFIG_KEYS = %w[graphql indexer logger datastore schema_artifacts]
 
-      VALID_NESTED_RELATIONSHIP_RESOLVER_MODES = [:optimized, :original, :comparison]
-
       private_class_method def self.load_client_resolver(parsed_yaml)
         config = parsed_yaml.fetch("client_resolver") do
           return Client::DefaultResolver.new({})

data/lib/elastic_graph/graphql/datastore_query.rb

@@ -29,7 +29,8 @@ module ElasticGraph
     class DatastoreQuery < Support::MemoizableData.define(
       :total_document_count_needed, :aggregations, :logger, :filter_interpreter, :routing_picker,
       :index_expression_builder, :default_page_size, :search_index_definitions, :max_page_size,
-      :filters, :sort, :document_pagination, :requested_fields, :request_all_fields,
+      :client_filters, :internal_filters, :sort, :document_pagination,
+      :requested_fields, :request_all_fields, :requested_highlights, :request_all_highlights,
       :individual_docs_needed, :size_multiplier, :monotonic_clock_deadline, :schema_element_names
     )
       # Load these files after the `Query` class has been defined, to avoid
@@ -96,22 +97,34 @@ module ElasticGraph
       def merge_with(
         individual_docs_needed: false,
         total_document_count_needed: false,
-        filters: [],
+        client_filters: [],
+        internal_filters: [],
         sort: [],
         requested_fields: [],
         request_all_fields: false,
+        requested_highlights: [],
+        request_all_highlights: false,
         document_pagination: {},
         size_multiplier: 1,
         monotonic_clock_deadline: nil,
         aggregations: {}
       )
+        individual_docs_needed ||= self.individual_docs_needed ||
+          !requested_fields.empty? || request_all_fields ||
+          !requested_highlights.empty? || request_all_highlights
+
+        total_document_count_needed ||= self.total_document_count_needed || aggregations.values.any?(&:needs_total_doc_count?)
+
         with(
-          individual_docs_needed: self.individual_docs_needed || individual_docs_needed || !requested_fields.empty? || request_all_fields,
-          total_document_count_needed: self.total_document_count_needed || total_document_count_needed || aggregations.values.any?(&:needs_total_doc_count?),
-          filters: self.filters + filters,
+          individual_docs_needed: individual_docs_needed,
+          total_document_count_needed: total_document_count_needed,
+          client_filters: self.client_filters + client_filters,
+          internal_filters: self.internal_filters + internal_filters,
           sort: merge_attribute(:sort, sort),
           requested_fields: self.requested_fields + requested_fields,
           request_all_fields: self.request_all_fields || request_all_fields,
+          requested_highlights: self.requested_highlights + requested_highlights,
+          request_all_highlights: self.request_all_highlights || request_all_highlights,
           document_pagination: merge_attribute(:document_pagination, document_pagination),
           size_multiplier: self.size_multiplier * size_multiplier,
           monotonic_clock_deadline: [self.monotonic_clock_deadline, monotonic_clock_deadline].compact.min,
@@ -130,7 +143,7 @@ module ElasticGraph
       # https://www.elastic.co/guide/en/elasticsearch/reference/current/multi-index.html
       def search_index_expression
         @search_index_expression ||= index_expression_builder.determine_search_index_expression(
-          filters,
+          all_filters,
           search_index_definitions,
           # When we have aggregations, we must require indices to search. When we search no indices, the datastore does not return
           # the standard aggregations response structure, which causes problems.
@@ -167,7 +180,7 @@ module ElasticGraph
       # `[]` means that we are routing to no shards.
       def shard_routing_values
         return @shard_routing_values if defined?(@shard_routing_values)
-        routing_values = routing_picker.extract_eligible_routing_values(filters, route_with_field_paths)
+        routing_values = routing_picker.extract_eligible_routing_values(all_filters, route_with_field_paths)
 
         @shard_routing_values ||=
           if routing_values&.empty? && !aggregations_datastore_body.empty?
@@ -240,6 +253,10 @@ module ElasticGraph
         document_paginator.effective_size
       end
 
+      def all_filters
+        client_filters + internal_filters
+      end
+
       private
 
       def merge_attribute(attribute, other_value)
@@ -286,8 +303,7 @@ module ElasticGraph
       def to_datastore_body
         @to_datastore_body ||= aggregations_datastore_body
           .merge(document_paginator.to_datastore_body)
-          .merge({query: filter_interpreter.build_query(filters)}.compact)
-          .merge({_source: source})
+          .merge({highlight: highlight, query: filter_interpreter.build_query(all_filters), _source: source}.compact)
       end
 
       def aggregations_datastore_body
@@ -314,6 +330,19 @@ module ElasticGraph
         {includes: requested_source_fields.to_a}
       end
 
+      def highlight
+        return nil if !request_all_highlights && requested_highlights.empty?
+
+        # If there are no filters, there's nothing to highlight.
+        return nil if client_filters.empty?
+
+        field_paths = request_all_highlights ? ["*"] : requested_highlights
+        fields = field_paths.to_h { |field| [field, {}] }
+        highlight_query = filter_interpreter.build_query(client_filters) unless internal_filters.empty?
+
+        {fields:, highlight_query:}.compact
+      end
+
       # Encapsulates dependencies of `Query`, giving us something we can expose off of `application`
       # to build queries when desired.
       class Builder < Support::MemoizableData.define(:runtime_metadata, :logger, :filter_interpreter, :filter_node_interpreter, :default_page_size, :max_page_size)
@@ -333,13 +362,16 @@ module ElasticGraph
 
         def new_query(
           search_index_definitions:,
-          filters: [],
+          client_filters: [],
+          internal_filters: [],
           sort: [],
           document_pagination: {},
           size_multiplier: 1,
           aggregations: {},
           requested_fields: [],
           request_all_fields: false,
+          requested_highlights: [],
+          request_all_highlights: false,
           individual_docs_needed: false,
           total_document_count_needed: false,
           monotonic_clock_deadline: nil
@@ -348,21 +380,29 @@ module ElasticGraph
             raise Errors::SearchFailedError, "Query is invalid, since it contains no `search_index_definitions`."
           end
 
+          individual_docs_needed ||= !requested_fields.empty? || request_all_fields ||
+            !requested_highlights.empty? || request_all_highlights
+
+          total_document_count_needed ||= aggregations.values.any?(&:needs_total_doc_count?)
+
           DatastoreQuery.new(
             routing_picker: routing_picker,
             index_expression_builder: index_expression_builder,
             logger: logger,
             schema_element_names: runtime_metadata.schema_element_names,
             search_index_definitions: search_index_definitions,
-            filters: filters.to_set,
+            client_filters: client_filters.to_set,
+            internal_filters: internal_filters.to_set,
             sort: sort,
             document_pagination: document_pagination,
             size_multiplier: size_multiplier,
             aggregations: aggregations,
             requested_fields: requested_fields.to_set,
+            requested_highlights: requested_highlights.to_set,
             request_all_fields: request_all_fields,
-            individual_docs_needed: individual_docs_needed || !requested_fields.empty? || request_all_fields,
-            total_document_count_needed: total_document_count_needed || aggregations.values.any?(&:needs_total_doc_count?),
+            request_all_highlights: request_all_highlights,
+            individual_docs_needed: individual_docs_needed,
+            total_document_count_needed: total_document_count_needed,
             monotonic_clock_deadline: monotonic_clock_deadline,
             filter_interpreter: filter_interpreter,
             default_page_size: default_page_size,

data/lib/elastic_graph/graphql/datastore_response/document.rb

@@ -58,6 +58,10 @@ module ElasticGraph
           payload["version"]
         end
 
+        def highlights
+          raw_data["highlight"] || {}
+        end
+
         def cursor
           @cursor ||= decoded_cursor_factory.build(raw_data.fetch("sort"))
         end

data/lib/elastic_graph/graphql/filtering/boolean_query.rb

@@ -13,16 +13,33 @@ module ElasticGraph
       # https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-bool-query.html
       #
       # It is composed of:
-      #   1) The occurrence type (:must, :filter, :should, or :must_not)
+      #   1) The occurrence type (:filter, :should, or :must_not)
       #   2) A list of query clauses evaluated by the given occurrence type
       #   3) An optional flag indicating whether the occurrence should be negated
+      #
+      # Note: since we never do anything with the score, we always prefer `filter` over `must`. If we ever
+      # decide to do something with the score (such as sorting by it), then we'll want to introduce `must`.
       class BooleanQuery < ::Data.define(:occurrence, :clauses)
-        def self.must(*clauses)
-          new(:must, clauses)
-        end
-
         def self.filter(*clauses)
-          new(:filter, clauses)
+          unwrapped_clauses = clauses.map do |clause|
+            __skip__ = case clause
+            in {bool: {minimum_should_match: 1, should: [::Hash => single_should], **nil}, **nil}
+              # This case represents an `anyOf` with a single subfilter (`filter: {anyOf: [X]}`).
+              # Such an expression is semantically equivalent to `filter: X`, and we can unwrap the
+              # should clause in this case since there is only a single one.
+              #
+              # While it adds a bit of complexity to do this unwrapping, we believe it's worth it because
+              # it preserves the datastore's ability to apply caching. As the Elasticsearch documentation[^1]
+              # explains, the results of `filter` clauses can be cached, but not `should` clauses.
+              #
+              # [^1]: https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-bool-query
+              single_should
+            else
+              clause
+            end
+          end
+
+          new(:filter, unwrapped_clauses)
         end
 
         def self.should(*clauses)

data/lib/elastic_graph/graphql/filtering/filter_node_interpreter.rb

@@ -90,33 +90,64 @@ module ElasticGraph
             schema_names.gte => ->(field_name, value) { RangeQuery.new(field_name, :gte, value) },
             schema_names.lt => ->(field_name, value) { RangeQuery.new(field_name, :lt, value) },
             schema_names.lte => ->(field_name, value) { RangeQuery.new(field_name, :lte, value) },
-            schema_names.matches => ->(field_name, value) { BooleanQuery.must({match: {field_name => value}}) },
+
             schema_names.matches_query => ->(field_name, value) do
               allowed_edits_per_term = value.fetch(schema_names.allowed_edits_per_term).runtime_metadata.datastore_abbreviation
 
-              BooleanQuery.must(
-                {
-                  match: {
-                    field_name => {
-                      query: value.fetch(schema_names.query),
-                      # This is always a string field, even though the value is often an integer
-                      fuzziness: allowed_edits_per_term.to_s,
-                      operator: value[schema_names.require_all_terms] ? "AND" : "OR"
-                    }
-                  }
-                }
-              )
+              BooleanQuery.filter({match: {field_name => {
+                query: value.fetch(schema_names.query),
+                # This is always a string field, even though the value is often an integer
+                fuzziness: allowed_edits_per_term.to_s,
+                operator: value[schema_names.require_all_terms] ? "AND" : "OR"
+              }}})
             end,
+
             schema_names.matches_phrase => ->(field_name, value) {
-              BooleanQuery.must(
-                {
-                  match_phrase_prefix: {
-                    field_name => {
-                      query: value.fetch(schema_names.phrase)
-                    }
-                  }
-                }
-              )
+              BooleanQuery.filter({match_phrase_prefix: {field_name => {
+                query: value.fetch(schema_names.phrase)
+              }}})
+            },
+
+            schema_names.contains => ->(field_name, value) {
+              case_insensitive = value[schema_names.ignore_case] || false
+              anded_substrings = value[schema_names.all_substrings_of] || []
+              ored_substrings = value[schema_names.any_substring_of]
+
+              sub_expressions = anded_substrings.map do |substring|
+                substring_clause(field_name, substring, case_insensitive)
+              end
+
+              if ored_substrings
+                should_sub_expressions = ored_substrings.map do |substring|
+                  substring_clause(field_name, substring, case_insensitive)
+                end
+
+                sub_expressions << {bool: {minimum_should_match: 1, should: should_sub_expressions}}
+              end
+
+              if ored_substrings&.empty?
+                BooleanQuery::ALWAYS_FALSE_FILTER
+              elsif sub_expressions.size > 0
+                BooleanQuery.filter(*sub_expressions)
+              end
+            },
+
+            schema_names.starts_with => ->(field_name, value) {
+              case_insensitive = value[schema_names.ignore_case] || false
+              ored_prefixes = value[schema_names.any_prefix_of]
+
+              sub_expressions = (ored_prefixes || []).map do |prefix|
+                {prefix: {field_name => {
+                  value: prefix,
+                  case_insensitive: case_insensitive
+                }}}
+              end
+
+              if ored_prefixes&.empty?
+                BooleanQuery::ALWAYS_FALSE_FILTER
+              elsif sub_expressions.size > 0
+                BooleanQuery.filter({bool: {minimum_should_match: 1, should: sub_expressions}})
+              end
             },
 
             # This filter operator wraps a geo distance query:
@@ -163,6 +194,15 @@ module ElasticGraph
           }.freeze
         end
 
+        def substring_clause(field_name, substring, case_insensitive)
+          {wildcard: {field_name => {
+            # We squeeze("*") to convert "**" to "*", which is not needed for correctness but is a bit simpler.
+            # There's no point in two consecutive "*" wildcards.
+            value: "*#{substring}*".squeeze("*"),
+            case_insensitive: case_insensitive
+          }}}
+        end
+
         def to_datastore_value(value)
           case value
           when ::Array

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

@@ -15,31 +15,30 @@ module ElasticGraph
     class QueryAdapter
       class Filters < Support::MemoizableData.define(:schema_element_names, :filter_args_translator, :filter_node_interpreter)
         def call(field:, query:, args:, lookahead:, context:)
-          filter_from_args = filter_args_translator.translate_filter_args(field: field, args: args)
-          automatic_filter = build_automatic_filter(filter_from_args: filter_from_args, query: query)
-          filters = [filter_from_args, automatic_filter].compact
-          return query if filters.empty?
+          client_filter = filter_args_translator.translate_filter_args(field: field, args: args)
+          internal_filter = build_automatic_filter(client_filter: client_filter, query: query)
+          return query if client_filter.nil? && internal_filter.nil?
 
-          query.merge_with(filters: filters)
+          query.merge_with(client_filters: [client_filter].compact, internal_filters: [internal_filter].compact)
         end
 
         private
 
-        def build_automatic_filter(filter_from_args:, query:)
+        def build_automatic_filter(client_filter:, query:)
           # If an incomplete document could be hit by a search with our filters against any of the
           # index definitions, we must add a filter that will exclude incomplete documents.
           exclude_incomplete_docs_filter if query
             .search_index_definitions
-            .any? { |index_def| search_could_hit_incomplete_docs?(index_def, filter_from_args || {}) }
+            .any? { |index_def| search_could_hit_incomplete_docs?(index_def, client_filter || {}) }
         end
 
         def exclude_incomplete_docs_filter
           {"__sources" => {schema_element_names.equal_to_any_of => [SELF_RELATIONSHIP_NAME]}}
         end
 
-        # Indicates if a search against the given `index_def` using the given `filter_from_args`
+        # Indicates if a search against the given `index_def` using the given `client_filter`
         # could hit an incomplete document.
-        def search_could_hit_incomplete_docs?(index_def, filter_from_args)
+        def search_could_hit_incomplete_docs?(index_def, client_filter)
           # If the index definition doesn't allow any searches to hit incomplete documents, we
           # can immediately return `false` without checking the filters.
           return false unless index_def.searches_could_hit_incomplete_docs?
@@ -53,7 +52,7 @@ module ElasticGraph
           #
           # Here we determine what field paths we need to check (e.g. only those field paths that are against
           # self-sourced fields).
-          paths_to_check = determine_paths_to_check(filter_from_args, index_def.fields_by_path)
+          paths_to_check = determine_paths_to_check(client_filter, index_def.fields_by_path)
 
           # If we have no paths to check, then our filters don't exclude incomplete documents and we must return `true`.
           return true if paths_to_check.empty?
@@ -61,7 +60,7 @@ module ElasticGraph
           # Finally, we look over each path. If all our filters allow the search to match documents that have `nil`
           # at that path, then the search can hit incomplete documents. But if even one path excludes documents
           # that have a `null` value for the field, we can safely return `false` for a more efficient query.
-          paths_to_check.all? { |path| can_match_nil_values_at?(path, filter_from_args) }
+          paths_to_check.all? { |path| can_match_nil_values_at?(path, client_filter) }
         end
 
         # Figures out which field paths we need to check to see if a filter on it could match an incomplete document.