Update the FullTextSearch docs to provide an example of their optionality

[mattcarp21]

In order to ignore a matchesQuery or matchesPhrase filter predicate, you can supply null to the MatchesQueryFilterInput or MatchesQueryFilterInput types, respectively. However, this is not entirely clear from the docs, as they describe supplying null, but not to which field/value. This documentation update aims to make that more clear, and provides an example to highlight the ability to use a null-able variable with these predicates.

Tested

Ran the site locally. Here are the screenshots of updates:

[myronmarston]

Can you use 2 spaces for each indentation level instead of 4? That's what we use for all the other queries and (at least to my eyes) I think it looks a bit cleaner.

[mattcarp21]

Absolutely. Fixed in the latest commit, PTAL

[myronmarston]

I'm on the fence about including the changes to this file, for a couple reasons:

• This is copied verbatim from the GraphQL docs for the TextInputFilter.matchesPhrase and TextInputFilter.matchesQuery fields. It'd be nice to not diverge from them. If this is needed, we should probably update the GraphQL docs, too.
• The wording Will be ignored when null is passed is used consistently throughout our GraphQL docs (as shown below it shows up 148 times in our .graphql schema file!). If we're going to update this, should we update all of them with a similar clarification?
• Does adding this note about the type bring necessary clarity? "Will be ignored when null is passed" is intended to apply to the input field that's being documented. In this case, the matchesPhrase field--it indicates that matchesPhrase: null will cause it to be ignored.

Thoughts?

[mattcarp21]

That makes sense. I've reverted the change and can see where you're coming from.

The confusion on my side stemmed from the fact that most of the examples show how to populate the matchesQuery parameters, so I was assuming passing null to the query parameter of matchesQuery would cause the filter to be ignored; however, it led to a very vague error about the type being unexpected... So maybe there's something we can do to improve that error, instead? WDYT?

[myronmarston]

however, it led to a very vague error about the type being unexpected...

The type error is the equivalent of a compiler error in a statically typed language such as when the type of an argument doesn't align with the type of the method signature. We're not in control of it (it's provided by the graphql gem and might even be strictly specified by the GraphQL spec), and it's worth noting that it's not unique to this part of the ElasticGraph query API. You'd get a similar error anytime you write a query that attempts to pass a null value for a non-null input field.

I think it's part of the learning curve of GraphQL.

[myronmarston]

Suggested change

	In order to ignore a `matchesPhrase` or `matchesQuery` filter, you can supply `null` to the `MatchesQueryFilterInput` parameter, as such:
	In order to make a `matchesPhrase` or `matchesQuery` filter optional, you can supply `null` to the `MatchesQueryFilterInput` parameter, like this:

We're going to be moving away from the language of "ignoring a filter" with the changes @acerbusace is working on since we very much have to not ignore such a filter when it shows up inside an anyOf. I think speaking of optional filters avoids that misunderstanding.

[mattcarp21]

Fixed, thanks for letting me know. I've readjusted the paragraph to match the phrasing you provided here. Let me know if further updates are required.

[myronmarston]

👍