Rewrite documentation for empty filters/predicates

config/site/examples/music/queries/filtering/IgnoredFilters.graphql → config/site/examples/music/queries/filtering/EmptyFilters.graphql

@@ -1,4 +1,4 @@
-query IgnoredFilters {
+query NullOrEmptyFilters {
   artists(filter: {
     name: {equalToAnyOf: null}
     bio: {yearFormed: {}}

config/site/src/_includes/filtering_predicate_definitions/comparison.md

@@ -1,19 +1,19 @@
 [`gt`]({% link query-api/filtering/comparison.md %})
 : Matches records where the field value is greater than (>) the provided value.
 
-  Will be ignored when `null` is passed.
+  When `null` is passed, matches all documents.
 
 [`gte`]({% link query-api/filtering/comparison.md %})
 : Matches records where the field value is greater than or equal to (>=) the provided value.
 
-  Will be ignored when `null` is passed.
+  When `null` is passed, matches all documents.
 
 [`lt`]({% link query-api/filtering/comparison.md %})
 : Matches records where the field value is less than (<) the provided value.
 
-  Will be ignored when `null` is passed.
+  When `null` is passed, matches all documents.
 
 [`lte`]({% link query-api/filtering/comparison.md %})
 : Matches records where the field value is less than or equal to (<=) the provided value.
 
-  Will be ignored when `null` is passed.
+  When `null` is passed, matches all documents.

config/site/src/_includes/filtering_predicate_definitions/conjunctions.md

@@ -6,11 +6,11 @@
   filters that can't be provided on a single filter input because of collisions between key names.
   For example, if you want to provide multiple `anySatisfy: ...` filters, you could do `allOf: [{anySatisfy: ...}, {anySatisfy: ...}]`.
 
-  Will be ignored when `null` or an empty list is passed.
+  When `null` or an empty list is passed, matches all documents.
 
 [`anyOf`]({% link query-api/filtering/conjunctions.md %})
 : Matches records where any of the provided sub-filters evaluate to true.
   This works just like an `OR` operator in SQL.
 
-  Will be ignored when `null` is passed. When an empty list is passed, will
-  cause this part of the filter to match no documents.
+  When `null` is passed, matches all documents.
+  When an empty list is passed, this part of the filter matches no documents.

config/site/src/_includes/filtering_predicate_definitions/equality.md

@@ -2,6 +2,6 @@
 : Matches records where the field value is equal to any of the provided values.
   This works just like an `IN` operator in SQL.
 
-  Will be ignored when `null` is passed.
-  When an empty list is passed, will cause this part of the filter to match no documents.
-  When `null` is passed in the list, will match records where the field value is `null`.
+  When `null` is passed, matches all documents.
+  When an empty list is passed, this part of the filter matches no documents.
+  When `null` is passed in the list, this part of the filter matches records where the field value is `null`.

config/site/src/_includes/filtering_predicate_definitions/fulltext.md

@@ -3,11 +3,11 @@
   full text search. This is stricter than `matchesQuery`: all terms must match
   and be in the same order as the provided phrase.
 
-  Will be ignored when `null` is passed.
+  When `null` is passed, matches all documents.
 
 [`matchesQuery`]({% link query-api/filtering/full-text-search.md %})
 : Matches records where the field value matches the provided query using full text search.
   This is more lenient than `matchesPhrase`: the order of terms is ignored, and, by default,
   only one search term is required to be in the field value.
 
-  Will be ignored when `null` is passed.
+  When `null` is passed, matches all documents.

config/site/src/_includes/filtering_predicate_definitions/list.md

@@ -1,9 +1,9 @@
 [`anySatisfy`]({% link query-api/filtering/list.md %})
 : Matches records where any of the list elements match the provided sub-filter.
 
-  Will be ignored when `null` or an empty object is passed.
+  When `null` or an empty object is passed, matches all documents.
 
 [`count`]({% link query-api/filtering/list.md %})
 : Used to filter on the number of non-null elements in this list field.
 
-  Will be ignored when `null` or an empty object is passed.
+  When `null` or an empty object is passed, matches all documents.

config/site/src/_includes/filtering_predicate_definitions/near.md

@@ -2,4 +2,4 @@
 : Matches records where the field's geographic location is within a specified distance
   from the location identified by `latitude` and `longitude`.
 
-  Will be ignored when `null` or an empty object is passed.
+  When `null` or an empty object is passed, matches all documents.

config/site/src/_includes/filtering_predicate_definitions/not.md

@@ -2,4 +2,4 @@
 : Matches records where the provided sub-filter evaluates to false.
   This works just like a `NOT` operator in SQL.
 
-  Will be ignored when `null` or an empty object is passed.
+  When `null` or an empty object is passed, matches no documents.

config/site/src/_includes/filtering_predicate_definitions/time_of_day.md

@@ -1,4 +1,4 @@
 [`timeOfDay`]({% link query-api/filtering/date-time.md %})
 : Matches records based on the time-of-day of the DateTime values.
 
-  Will be ignored when `null` of an empty object is passed.
+  When `null` or an empty object is passed, matches no documents.

config/site/src/query-api/filtering.md

@@ -17,12 +17,13 @@ As shown here, filters have two basic parts:
   you'll need to provide a nested object matching the field structure.
 * A _filtering predicate_: this specifies a filtering operator to apply at the field path.
 
-### Ignored Filters
+### Empty Filters
 
-Filters with a value of `null` or empty object (`{}`) are ignored. The filters in this query are all ignored:
+Filters with a value of `null` or empty object (`{}`) match all documents. When negated with `not`, no documents are matched.
+The filters in this query match all documents:
 
 {% highlight graphql %}
-{{ site.data.music_queries.filtering.IgnoredFilters }}
+{{ site.data.music_queries.filtering.EmptyFilters }}
 {% endhighlight %}
 
 This particularly comes in handy when using [query variables](https://graphql.org/learn/queries/#variables).

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/factory.rb

@@ -141,16 +141,16 @@ def new_filter_input_type(source_type, name_prefix: source_type, category: :filt
           t.documentation <<~EOS
             Input type used to specify filters on `#{source_type}` fields.
 
-            Will be ignored if passed as an empty object (or as `null`).
+            Will match all documents if passed as an empty object (or as `null`).
           EOS
 
           t.field @state.schema_elements.any_of, "[#{t.name}!]" do |f|
             f.documentation <<~EOS
               Matches records where any of the provided sub-filters evaluate to true.
               This works just like an OR operator in SQL.
 
-              Will be ignored when `null` is passed. When an empty list is passed, will cause this
-              part of the filter to match no documents.
+              When `null` is passed, matches all documents.
+              When an empty list is passed, this part of the filter matches no documents.
             EOS
           end
 
@@ -159,7 +159,7 @@ def new_filter_input_type(source_type, name_prefix: source_type, category: :filt
               Matches records where the provided sub-filter evaluates to false.
               This works just like a NOT operator in SQL.
 
-              Will be ignored when `null` or an empty object is passed.
+              When `null` or an empty object is passed, matches no documents.
             EOS
           end
 
@@ -303,7 +303,7 @@ def new_list_filter_input_type(source_type, name_prefix:, any_satisfy_type_categ
             f.documentation <<~EOS
               Matches records where any of the list elements match the provided sub-filter.
 
-              Will be ignored when `null` or an empty object is passed.
+              When `null` or an empty object is passed, matches all documents.
             EOS
           end
 
@@ -315,7 +315,7 @@ def new_list_filter_input_type(source_type, name_prefix:, any_satisfy_type_categ
               be provided on a single `#{t.name}` input because of collisions between key names. For example, if you want to provide
               multiple `#{any_satisfy}: ...` filters, you could do `#{all_of}: [{#{any_satisfy}: ...}, {#{any_satisfy}: ...}]`.
 
-              Will be ignored when `null` or an empty list is passed.
+              When `null` or an empty list is passed, matches all documents.
             EOS
           end
 
@@ -330,7 +330,7 @@ def new_list_element_filter_input_type(source_type, name_prefix:)
           t.documentation <<~EOS
             Input type used to specify filters on elements of a `[#{source_type}]` field.
 
-            Will be ignored if passed as an empty object (or as `null`).
+            Will match all documents if passed as an empty object (or as `null`).
           EOS
 
           # While we support `not: {any_satisfy: ...}` we do not support `any_satisfy: {not ...}` at this time.
@@ -374,7 +374,7 @@ def new_fields_list_filter_input_type(source_type_name, name_prefix:)
             or transitively from a list field that has been configured to index each leaf field as
             its own flattened list of values.
 
-            Will be ignored if passed as an empty object (or as `null`).
+            Will match all documents if passed as an empty object (or as `null`).
           EOS
 
           source_type.graphql_fields_by_name.each do |field_name, field|
@@ -424,7 +424,7 @@ def define_list_counts_filter_field_on(type)
           f.documentation <<~EOS
             Used to filter on the number of non-null elements in this list field.
 
-            Will be ignored when `null` or an empty object is passed.
+            When `null` or an empty object is passed, matches all documents.
           EOS
         end
       end

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/built_in_types.rb

@@ -216,7 +216,7 @@ def register_standard_elastic_graph_types
               f.documentation <<~EOS
                 Matches records where the field value matches the provided value using full text search.
 
-                Will be ignored when `null` is passed.
+                When `null` is passed, matches all documents.
               EOS
 
               f.directive "deprecated", reason: "Use `#{names.matches_query}` instead."
@@ -228,7 +228,7 @@ def register_standard_elastic_graph_types
                 This is more lenient than `#{names.matches_phrase}`: the order of terms is ignored, and,
                 by default, only one search term is required to be in the field value.
 
-                Will be ignored when `null` is passed.
+                When `null` is passed, matches all documents.
               EOS
             end
 
@@ -238,15 +238,15 @@ def register_standard_elastic_graph_types
                 full text search. This is stricter than `#{names.matches_query}`: all terms must match
                 and be in the same order as the provided phrase.
 
-                Will be ignored when `null` is passed.
+                When `null` is passed, matches all documents.
               EOS
             end
           end.each do |input_type|
             field_type = input_type.type_ref.list_filter_input? ? "[String]" : "String"
             input_type.documentation <<~EOS
               Input type used to specify filters on `#{field_type}` fields that have been indexed for full text search.
 
-              Will be ignored if passed as an empty object (or as `null`).
+              Will match all documents if passed as an empty object (or as `null`).
             EOS
 
             register_input_type(input_type)
@@ -256,7 +256,7 @@ def register_standard_elastic_graph_types
             t.documentation <<~EOS
               Input type used to specify parameters for the `#{names.matches_query}` filtering operator.
 
-              Will be ignored if passed as `null`.
+              When `null` is passed, matches all documents.
             EOS
 
             t.field names.query, "String!" do |f|
@@ -292,7 +292,7 @@ def register_standard_elastic_graph_types
             t.documentation <<~EOS
               Input type used to specify parameters for the `#{names.matches_phrase}` filtering operator.
 
-              Will be ignored if passed as `null`.
+              When `null` is passed, matches all documents.
             EOS
 
             t.field names.phrase, "String!" do |f|
@@ -341,7 +341,7 @@ def register_standard_elastic_graph_types
                 Matches records where the field's geographic location is within a specified distance from the
                 location identified by `#{names.latitude}` and `#{names.longitude}`.
 
-                Will be ignored when `null` or an empty object is passed.
+                When `null` or an empty object is passed, matches all documents.
               EOS
             end
           end.each { |input_filter| register_input_type(input_filter) }
@@ -675,7 +675,7 @@ def register_custom_elastic_graph_scalars
                 f.documentation <<~EOS
                   Matches records based on the time-of-day of the `DateTime` values.
 
-                  Will be ignored when `null` or an empty list is passed.
+                  When `null` is passed, matches all documents.
                 EOS
               end
             end
@@ -693,7 +693,7 @@ def register_custom_elastic_graph_scalars
               t.documentation <<~EOS
                 Input type used to specify filters on the time-of-day of `DateTime` fields.
 
-                Will be ignored if passed as an empty object (or as `null`).
+                Will match all documents if passed as an empty object (or as `null`).
               EOS
 
               fixup_doc = ->(doc_string) do

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/field.rb

@@ -742,7 +742,7 @@ def to_filter_field(parent_type:, for_single_value: !type_for_derived_types.list
           schema_def_state.factory.new_field(**params).tap do |f|
             f.documentation derived_documentation(
               "Used to filter on the `#{name}` field",
-              "Will be ignored if `null` or an empty object is passed"
+              "When `null` or an empty object is passed, matches all documents"
             )
 
             filter_customizations.each { |c| c.call(f) }

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/schema_elements/scalar_type.rb

@@ -200,33 +200,33 @@ def indexed?
           Matches records where the field value is equal to any of the provided values.
           This works just like an IN operator in SQL.
 
-          Will be ignored when `null` is passed. When an empty list is passed, will cause this
-          part of the filter to match no documents. When `null` is passed in the list, will
-          match records where the field value is `null`.
+          When `null` is passed, matches all documents. When an empty list is passed,
+          this part of the filter matches no documents. When `null` is passed in the
+          list, this part of the filter matches records where the field value is `null`.
         EOS
 
         GT_DOC = <<~EOS
           Matches records where the field value is greater than (>) the provided value.
 
-          Will be ignored when `null` is passed.
+          When `null` is passed, matches all documents.
         EOS
 
         GTE_DOC = <<~EOS
           Matches records where the field value is greater than or equal to (>=) the provided value.
 
-          Will be ignored when `null` is passed.
+          When `null` is passed, matches all documents.
         EOS
 
         LT_DOC = <<~EOS
           Matches records where the field value is less than (<) the provided value.
 
-          Will be ignored when `null` is passed.
+          When `null` is passed, matches all documents.
         EOS
 
         LTE_DOC = <<~EOS
           Matches records where the field value is less than or equal to (<=) the provided value.
 
-          Will be ignored when `null` is passed.
+          When `null` is passed, matches all documents.
         EOS
 
         def to_input_filters