TracQuery documentation on Query Language operators is incorrect

[kamil@…]

The documentation at TracQuery regarding the operators is incorrect.

It says:

The available operators are:
|| '''`=`''' || the field content exactly matches the one of the values ||
|| '''`~=`''' || the field content contains one or more of the values ||
|| '''`^=`''' || the field content starts with one of the values ||
|| '''`$=`''' || the field content ends with one of the values ||

All of these operators can also be negated:
|| '''`!=`''' || the field content matches none of the values ||
|| '''`!~=`''' || the field content does not contain any of the values ||
|| '''`!^=`''' || the field content does not start with any of the values ||
|| '''`!$=`''' || the field content does not end with any of the values ||

However, these operators don't seem to work in a query. In fact, when selecting their equivalent from the custom query dropdown it seems the generated operators are in fact the other way around, with a leading = instead of a trailing one.

It seems it really should be:

The available operators are:
|| '''`=`''' || the field content exactly matches the one of the values ||
|| '''`=~`''' || the field content contains one or more of the values ||
|| '''`=^`''' || the field content starts with one of the values ||
|| '''`=$`''' || the field content ends with one of the values ||

All of these operators can also be negated:
|| '''`=!`''' || the field content matches none of the values ||
|| '''`=!~`''' || the field content does not contain any of the values ||
|| '''`=!^`''' || the field content does not start with any of the values ||
|| '''`=!$`''' || the field content does not end with any of the values ||

[ebray]

You're confusing the Trac query language with the URL arguments to the query module. In a URL the modifiers have to go on the other side of the = operator. The query language itself requires that they be written as documented.

I can understand how this can be confusing though, especially since saving a custom query just saves the URL arguments. Ideally it would save the query in the Trac query language. I believe there's a note to that effect in the code somewhere.

[kamil@…]

Well, when I was constructing a query through the "Edit Query" button, I had to rearrange the options to match the way the URL is generated, and not the way described in the documentation.

For example, the following query (somewhat reduced for brevity):

query:?status=assigned
&
status=new
&
status=in_progress
&
group=status
&
order=priority
&
col=id
&
col=summary
&
keywords~=resnet

returned all tickets that matched the status, regardless of keyword.

However, when I changed the query to:

query:?status=assigned
&
status=new
&
status=in_progress
&
group=status
&
order=priority
&
col=id
&
col=summary
&
keywords=~resnet

it only returns tickets with the 'resnet' keyword.

The documentation above the textbox for the report says:

Query for Report: (can be either SQL or, if starting with query:, a TracQuery expression)

so I would expect that if it's a TracQuery expression, it should follow the syntax described in on the TracQuery page, and not what's put in to the URLs.

[Remy Blank]

Replying to kamil@…:

so I would expect that if it's a TracQuery expression, it should follow the syntax described in on the TracQuery page, and not what's put in to the URLs.

You can use both syntaxes with query:. If the expression starts with a ?, it is interpreted as URL arguments (that is, with the operator following the =), and if it doesn't, it's in query syntax (with the operator before the =). See TracQuery#UsingTracLinks.

In your case, your expression starts with a ?, so you have to use URL syntax.

I wonder if it would be possible to have the same syntax for both URL and query? What happens if you have a parameter named keywords~ with a value of resnet, instead of a parameter named keywords and a value of ~resnet? I'll do a few tests to validate that.

[Remy Blank]

Patch against trunk allowing to put the operator before the = in query URL syntax

[Remy Blank]

The patch above allows putting the operator before the = sign in ticket query URLs, in the same way as for the query syntax, so you can now write:

[query:?keywords!~=important]

as well as the usual:

[query:?keywords=!~important]

The patch converts the former into the latter when parsing the URL parameters.

I find that having the constraint mode (e.g. !~) in the constraint value is tricky, as it leads to ambiguity (see comment:16:ticket:1467). Having the mode in the field name does not have this disadvantage.

I would like to modify the query system so that the mode is never combined with the value internally, and that the !~= notation becomes the default in query URLs. We could still accept the old =!~ format for compatibility (possibly through a configuration option).

We could even go one step further and remove the distinction between query syntax and query URL altogether, as both support almost the same features. Anyway, what are the features supported only by query URLs?

Thoughts?

[Christian Boos]

The query URL is simply there for those not wanting to learn the syntax of the Query language: you can create a query: link by simply copy/pasting the current URL when you're viewing a custom query (see #909). I think it would be nice to keep this possibility, so if we change the syntax (which would be nice), we should change the generated URLs. If it's possible to actually generate an URL which adheres to the normal Query syntax, then we could effectively get rid of that alternative syntax. Even more so now that there's no speed difference between them anymore (#6436).

[Remy Blank]

Replying to cboos:

I think it would be nice to keep this possibility, so if we change the syntax (which would be nice), we should change the generated URLs.

That's what I meant with "the default in query URLs", sorry for being unclear.

If it's possible to actually generate an URL which adheres to the normal Query syntax, then we could effectively get rid of that alternative syntax.

I think we can get pretty close. I'll try to see how far I can go.

[Remy Blank]

Should not block 0.12.

[Remy Blank]

That's not something for a minor release.

[Ryan J Ollos]

Retargetting tickets to narrow focus for milestone:1.2. Please move the ticket back to milestone:next-dev-1.1.x if you intend to resolve it by milestone:1.2.