Clarify filter fields usage in javadocs

[bjacobowitz]

Description

To resolve #14427

Update documentation for Lucene Monitor to make clear that filter fields should appear only in the query metadata and incoming documents, and should not appear in the query itself.

Problem

This is described in more detail in #14427 -- a rough summary is given below:

When TermFilteredPresearcher builds a presearcher query, it separates out filter fields into their own clause (with BooleanClause.Occur.FILTER), ANDed with a clause for all other terms. If a stored monitor query is a conjunction of fields including the filter field, it's possible that the filter field may be chosen as the indexed field for the document in the monitor's index, in which case the presearcher query will need to search for the filter field in order to match. However, since the filter field is deliberately omitted from the terms clause, the terms clause will never contain that filter field and can never match that stored monitor query. Although the filter clause will match the query, since the two clauses are ANDed together, the stored query doesn't match the presearcher query as a whole, so the stored query is not returned from presearching (and therefore does not match).

Supporting this would potentially cause more queries to run than before, and it's debatable that allowing the filter field to float freely in the stored query (where it could have, for example, a NOT applied to it) would lead to inconsistency.

Solution

Side-stepping the larger question of whether there is a path forward with filter fields appearing in the query directly, this PR updates the documentation around filter fields to clarify that a user should not have the filter field(s) appear in the stored query itself, only in its metadata.

For reasons described in the linked issue (#14427), I think supporting filter fields in the query would introduce a performance penalty, so it seems preferable to leave that behavior as-is and augment the documentation to help users avoid problems with it.

Merge Request

If this PR gets merged, can you please use my [email protected] email address for the squash+merge? Thank you.

[github-actions]

This PR does not have an entry in lucene/CHANGES.txt. Consider adding one. If the PR doesn't need a changelog entry, then add the skip-changelog-check label to it and you will stop receiving this reminder on future updates to the PR.

[github-actions]

This PR has not had activity in the past 2 weeks, labeling it as stale. If the PR is waiting for review, notify the [email protected] list. Thank you for your contribution!