Overview

Currently Cross Tracker Search (XTS) relies on Tracker Query Language (TQL) in order to express the searches (queries). It turns out that TQL is likely to be a good "intermediate representation" to express data selection more broadly:

• Selection of fields to display
• Selection of trackers to search on
• Selection of fields to sort on

TQL is already deeply inspired from SQL (the WHERE part), we push this one step further, TQL would like:

SELECT <list of fields> FROM <selection of trackers> WHERE <search criteria> ORDER BY <field to sort on>

We talk about "intermediate representation" because it's a rather tech savvy approach that would not be suitable for all users. However, due to the nature of XTS, some user interactions are rather complex to design. For instance, let say you want to run a query on all "request" tracker of "helpdesk" projects, that might represent 50 trackers with potentially hundreds of different fields. So before we come up with the appropriate UX/UI to deal with those cases extended TQL would allows to use the feature for advanced users at least. When the UI is there we would have UI -> TQL -> Execution instead of UI -> Execution & TQL -> Execution that we have today for trackers.

SELECT < list of fields >

Example: SELECT @id, @title, category WHERE @status = OPEN() will render @id Always There Field, @title semantic and category duck typed field.

There are three categories of fields to take into account:

• Always There Fields
  • @id => int
  • @submitted_on => date time
  • @last_update_date => date time
  • @submitted_by => user
  • @last_update_by => user
• Semantics
  • @title => string
  • @description => text
  • @status => static value
  • @assigned_to => user
• Duck-typing (referred by their name without @, eg category)
  • numeric fields (int| float)
  • text fields (string|text)
  • list fields with same bind incl. open lists
  • date fields
  • date time fields
  • Under discussion / to be defined
    • Computed fields
    • File attachment
    • Cross references
    • Artifact Links
    • Permissions on artifacts
• Special fields
  • @project.name
  • @tracker.name
  • @pretty_title (corresponds to concatenation of @tracker.name #@id @title)

Excluded fields:

• charts: Burnup, Burndown
• rank: it's unlikely that this fields is useful in table reports (esp if we allow to sort on fields with ORDER BY).
• TTM fields (steps definition & steps executions): we don't know how to represent them in table report at the moment
• Per tracker id: it's unlikely to make sense in this context

When no SELECT is present, the default display is equivalent to SELECT @pretty_title, @project, @status, @last_update_date, @submitted_by, @assigned_to

FROM < selection of trackers >

Example: FROM project.name = 'gpig' and tracker.name = 'sla' WHERE @status = OPEN() will return all open artifacts of SLA tracker of gpig project.

• project.name = 'gpig' and tracker.name = 'sla': one tracker in one project
• project.name = 'gpig': all trackers of one project
• project.name IN ('gpig', 'red', 'foo') and tracker.name = 'sla': sla tracker of several projects.
• project.name = 'gpig' and tracker.name IN (sla, request): sla or request tracker in gpig project
• project.name IN ('gpig', 'red', 'foo') and tracker.name IN ('sla', 'request'): sla and request tracker in gpig, red and foo projects
• project.category = 'helpdesk': all trackers of all projects withhelpdesk category
• project.category = 'topic::power' : all trackers of all projects withtopic -> power category (topic is parent of power)
• project = 'self'

Rules:

• Supported selector:
  • project.name = 'string' : select one project based on it's short name
  • project.name IN (string, ...): select projects based on their short name
  • project.category = 'string': select projects that match given project category
  • project.category IN (string, ...): select projects based on their project categories
  • project = 'self': select current project
  • project = 'aggregated': select all aggregated projects (program management)
  • tracker.name = 'string': select one tracker inside selection of projects
  • tracker.name IN (string, ...): select all trackers based on their short name inside selection of projects
• It's possible to have zero or one project rule per FROM:
  • OK: project.name = 'gpig'
  • OK: project.category = 'topic::power'
  • NOK: project.category = 'helpdesk' AND project.name = 'foo'
• It's possible to have zero or one tracker rule per FROM:
  • OK: tracker.name = 'sla'
  • NOK: tracker.name = 'sla' AND tracker.name = 'request'
• When no FROM is defined, it corresponds to project = 'self'

ORDER BY < field to sort on >

Example: @status = OPEN() ORDER BY @last_update_date DESC: will return all open artifacts, the newest first

Rules:

• Sort can be on any field that is present in all involved tracker (displayed or not, while it's un common to sort on a criteria not displayed with a Table rendering, it's quite common for Kanban rendering)
• Sort is possible only on one field at time
• It's possible to choose the order: ASC (aka ascending) or DESC (aka descending)