What is the semantics of filter composition? I'm assuming if we specify multiple filters they are all going to be AND-ed together.

So are OR queries not possible?

Ideally we want to have both (although I do not know if that is supported by the search backend).

If we do have both AND and OR queries we will need:

• different conjunction operators
• an explicit statement in the doc about the precedence of the two operators
• parentheses to disambiguate

Drop this note about how "intelligent" the parser is. Just say that spaces can be added around operators.
BTW, I suspect that in some cases they are mandatory, e.g., around the "in" operator, so I'm not sure this description is entirely correct.

I don't understand the point of the ":" operator in the concrete syntax (both here and many other places in the grammar).
It is used to mean "equal" and we already use the "=" operator in other context in the syntax.
I don't think we should have two different symbols for the same notion.

Even though ":" is more common in some search languages, we should then use "=" everywhere.

please use "quotation marks" which is a more common expression for "inverted commas"

"url" is a datatype in our context, not an information entity.
It would be better to call it "origin_url", but I prefer even more to just use "origin" as it is what would make the most intuitive sense to users. The documentation will then explain that origin are identified by URLs

I don't understand the semantic of these. Do they just mean that metadata should contain the provided string anywhere?

better: "visited"

better: "visits" ("number" is redundant and adds to visual clutter)

drop the trailing "s" in all of these and use "language" instead of "programming_language" (we are a source code archive, so it's the most natural notion of "language" we have)

drop the trailing "s"

except for "any", this list is going to become obsolete soon. We need to point here to an external list that is guaranteed to be more up-to-date, maybe swh-web can provide one? (I don't know if we have another good answer to this problem.)

these field names appear also elsewhere in the doc, we need to find a way to deduplicate the list, so that it does not appear in multiple places. (I'm gonna comment on the specific field names elsewhere.)

drop "date_" (or "_date") everywhere in these, it's clutter that doesn't add much

"YYYY-MM-DD" is the standard ISO date format, so we can drop everything starting with "or..." here?

you should briefly explain the semantics here, e.g., "limits the number of results to at most N"

this is a more general comment, each of the previous sections could benefit from one such sentence

Thanks for adding the explicit AND/OR operators. However, I think the C-like choice of && and || is bad for users. It's too programmer-oriented, and we will have users from other domains. They are also unusual in web search languages, where words are more common. Finally, they are hard to type on some keyboard layouts.

I propose to use explicit and and or instead (and in the future not for negation).

They are common stop words, so in most cases not being able to use them as search terms will not be a big deal.
But we need a way to allow to search for them if someone really wants to. One way would be to say that when they appear in quotes they are not operators but terms, e.g., one will be allowed to search for "and" and "or" in order to search for origins that contain both "and" and "or" as strings.

Alternatively we will need an explicit escape symbol, like \and, \or, \not.

I don't particularly care between these two alternatives.

Note that two points of my previous review are still relevant and not addressed yet:

• you need to tell say what are the precedence rules so that users can understand what foo and bar or baz means (it should mean (foo and bar) or baz
• you need to have explicit parentheses in the language so that users can override default precedence rules (e.g., write foo and (bar or baz))