Edgewall Software
Modify

Opened 11 years ago

Last modified 4 years ago

#7699 new defect

TracQuery documentation on Query Language operators is incorrect

Reported by: kamil@… Owned by:
Priority: normal Milestone: next-major-releases
Component: general Version: 0.11-stable
Severity: normal Keywords: query
Cc: Branch:
Release Notes:
API Changes:

Description

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 ||

Attachments (1)

7699-query-url-syntax-r7668.patch (1.0 KB ) - added by Remy Blank 11 years ago.
Patch against trunk allowing to put the operator before the = in query URL syntax

Download all attachments as: .zip

Change History (13)

comment:1 by ebray, 11 years ago

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.

comment:2 by kamil@…, 11 years ago

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.

in reply to:  2 comment:3 by Remy Blank, 11 years ago

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.

comment:4 by Remy Blank, 11 years ago

Milestone: 0.12
Owner: set to Remy Blank

by Remy Blank, 11 years ago

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

comment:5 by Remy Blank, 11 years ago

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?

comment:6 by Christian Boos, 11 years ago

Keywords: query added

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).

in reply to:  6 comment:7 by Remy Blank, 11 years ago

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.

comment:8 by Remy Blank, 10 years ago

Milestone: 0.120.12.1

Should not block 0.12.

comment:9 by Remy Blank, 9 years ago

Milestone: next-minor-0.12.x0.13

That's not something for a minor release.

comment:10 by Remy Blank, 9 years ago

Milestone: 0.130.14

comment:11 by Ryan J Ollos, 5 years ago

Milestone: next-dev-1.1.xnext-major-releases

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.

comment:12 by Ryan J Ollos, 4 years ago

Owner: Remy Blank removed

Modify Ticket

Change Properties
Set your email in Preferences
Action
as new The ticket will remain with no owner.
The ticket will be disowned. Next status will be 'new'.
as The resolution will be set. Next status will be 'closed'.
The owner will be changed from (none) to anonymous. Next status will be 'assigned'.

Add Comment


E-mail address and name can be saved in the Preferences .
 
Note: See TracTickets for help on using tickets.