CINXE.COM

<!DOCTYPE html> <html lang="en-US"> <head>   <title> TracQuery – The Trac Project </title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" />  <link rel="search" href="/search" /> <link rel="help" href="/wiki/TracGuide" /> <link rel="alternate" href="/wiki/TracQuery?format=txt" title="Plain Text" type="text/x-trac-wiki" /> <link rel="start" href="/wiki" /> <link rel="stylesheet" href="/chrome/common/css/trac.css" type="text/css" /> <link rel="stylesheet" href="/chrome/common/css/wiki.css" type="text/css" /> <link rel="stylesheet" href="/chrome/wikiextras/css/phrases.css" type="text/css" /> <link rel="stylesheet" href="/chrome/wikiextras/css/boxes.css" type="text/css" /> <link rel="stylesheet" href="/wikiextras/dynamicboxes.css" type="text/css" /> <link rel="stylesheet" href="/chrome/vote/css/tracvote.css" type="text/css" /> <link rel="icon" href="/favicon.ico" type="image/x-icon" /> <noscript> <style> .trac-noscript { display: none !important } </style> </noscript> <link type="application/opensearchdescription+xml" rel="search" href="/search/opensearch" title="Search The Trac Project"/> <script src="/chrome/common/js/jquery.js"></script> <script src="/chrome/common/js/babel.js"></script> <script src="/chrome/common/js/trac.js"></script> <script src="/chrome/common/js/search.js"></script> <script src="/chrome/common/js/folding.js"></script> <script src="/chrome/common/js/wiki.js"></script> <script> jQuery(function($) { $(".trac-autofocus").focus(); $(".trac-target-new").attr("target", "_blank"); if ($.ui) { /* is jquery-ui added? */ $(".trac-datepicker:not([readonly])") .prop("autocomplete", "off").datepicker(); // Input current date when today is pressed. var _goToToday = $.datepicker._gotoToday; $.datepicker._gotoToday = function(id) { _goToToday.call(this, id); this._selectDate(id) }; $(".trac-datetimepicker:not([readonly])") .prop("autocomplete", "off").datetimepicker(); $("#main").addClass("trac-nodatetimehint"); } $(".trac-disable").disableSubmit(".trac-disable-determinant"); setTimeout(function() { $(".trac-scroll").scrollToTop() }, 1); $(".trac-disable-on-submit").disableOnSubmit(); }); </script>  <link rel="stylesheet" type="text/css" href="//www.edgewall.org/css/projects013.css" /> <script type="text/javascript"></script> <script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/cookieconsent2/1.0.9/cookieconsent.min.js"></script> <script type="text/javascript"> jQuery(function($) { var $ntg = $("#newticketguide"); if ($ntg.length) $("#propertyform").prepend($ntg.detach()); }); </script>   <link rel="alternate" type="application/x-wiki" href="/wiki/TracQuery?action=edit&version=" title="Edit this page"/> <script> jQuery(function($) { wikiColumn($("#wikipage")); }); </script>  </head> <body>    <div id="wrapper"> <div id="topbar"> <a id="home-link" href="//www.edgewall.org/">Edgewall Software</a> </div> <div id="ew-header"> <div id="topnav"><ul> <li><a href="//www.edgewall.org/">Home</a></li> <li class="active"> <a class="trac" href="//trac.edgewall.org/">Trac</a> </li> <li> <a href="//trac-hacks.org/">Trac Hacks</a> </li> <li class=""> <a class="genshi" href="//genshi.edgewall.org/">Genshi</a> </li> <li class=""> <a class="babel" href="//babel.edgewall.org/">Babel</a> </li> <li class=""> <a class="bitten" href="//bitten.edgewall.org/">Bitten</a> </li></ul> </div> </div> <div id="ew-main"> <div id="ew-content"> <div> <script src="//www.google-analytics.com/urchin.js" type="text/javascript"></script> <script type="text/javascript">_uacct = "UA-598265-1";urchinTracker();</script> <div id="left"> <div class="block"> <ul> <li><a href="/">Home</a></li> <li><a href="/wiki/TracDownload">Download</a></li> <li><a href="/wiki/TracGuide">Documentation</a></li> <li><a href="/wiki/MailingList">Mailing Lists</a></li> <li><a href="/wiki/TracLicense">License</a></li> <li><a href="/wiki/TracFaq">FAQ</a></li> </ul> </div> </div> </div>  <div id="banner"> <div id="header"> <a id="logo" href="//trac.edgewall.org/"> <img alt="Trac" height="73" src="//www.edgewall.org/gfx/trac_logo.png" width="236" /></a> </div> <form id="search" action="/search" method="get"> <div> <label for="proj-search">Search:</label> <input type="text" id="proj-search" name="q" size="18" value="" /> <input type="submit" value="Search" /> </div> </form> <div id="metanav" class="nav"> <ul><li class="first"><a href="/login">Login</a></li><li ><a href="/prefs">Preferences</a></li><li ><a href="/wiki/TracGuide">Help/Guide</a></li><li class="last"><a href="/about">About Trac</a></li></ul> </div> </div> <div id="mainnav" class="nav"> <ul><li class="active first"><a href="/wiki">Wiki</a></li><li ><a href="/timeline">Timeline</a></li><li ><a href="/roadmap">Roadmap</a></li><li ><a href="/browser">Browse Source</a></li><li ><a href="/report">View Tickets</a></li><li ><a href="/wiki/NewTicket">New Ticket</a></li><li class="last"><a href="/search">Search</a></li></ul> </div> <div id="main" > <div id="pagepath" class="noprint"> <a class="pathentry first" title="View WikiStart" href="/wiki">wiki:</a><a href="/wiki/TracQuery" title="View TracQuery" class="pathentry">TracQuery</a></div> <div id="ctxtnav" class="nav"> <h2>Context Navigation</h2> <ul> <li class="first"><span id="vote" title="Vote count (+2, -1)"><img alt="Up-vote" src="/chrome/vote/aupgray.png" /><span id="votes">+1</span><img alt="Down-vote" src="/chrome/vote/adownmod.png" /></span></li> <li ><a href="/wiki/WikiStart">Start Page</a></li> <li ><a href="/wiki/TitleIndex">Index</a></li> <li class="last"><a href="/wiki/TracQuery?action=history">History</a></li> </ul> <hr /> </div>  <div id="content" class="wiki narrow"> <div class="wikipage searchable"> <div id="wikipage" class="trac-content borderless"><div class="wikiextras box shadow icon information yellow"><p> This page documents the 1.4 (latest stable) release. Documentation for other releases can be found <a class="wiki" href="/wiki/TitleIndex#TracGuide:BackupandTranslations">here</a>. </p> </div><h1 class="section" id="TracTicketQueries">Trac Ticket Queries</h1> <p> </p><div class="wiki-toc"><h4>Table of Contents</h4><ul><li class="False"><a class="False" href="/wiki/TracGuide">Index</a></li><li class="False"><a class="False" href="/wiki/TracInstall">Installation</a></li><li class="False"><a class="False" href="/wiki/TracInterfaceCustomization">Customization</a></li><li class="False"><a class="False" href="/wiki/TracPlugins">Plugins</a></li><li class="False"><a class="False" href="/wiki/TracUpgrade">Upgrading</a></li><li class="False"><a class="False" href="/wiki/TracIni">Configuration</a></li><li class="False"><a class="False" href="/wiki/TracAdmin">Administration</a></li><li class="False"><a class="False" href="/wiki/TracBackup">Backup</a></li><li class="False"><a class="False" href="/wiki/TracLogging">Logging</a></li><li class="False"><a class="False" href="/wiki/TracPermissions">Permissions</a></li><li class="False"><a class="False" href="/wiki/TracWiki">The Wiki</a></li><li class="False"><a class="False" href="/wiki/WikiFormatting">Wiki Formatting</a></li><li class="False"><a class="False" href="/wiki/TracTimeline">Timeline</a></li><li class="False"><a class="False" href="/wiki/TracBrowser">Repository Browser</a></li><li class="False"><a class="False" href="/wiki/TracRevisionLog">Revision Log</a></li><li class="False"><a class="False" href="/wiki/TracChangeset">Changesets</a></li><li class="False"><a class="False" href="/wiki/TracTickets">Tickets</a></li><li class="False"><a class="False" href="/wiki/TracWorkflow">Workflow</a></li><li class="False"><a class="False" href="/wiki/TracRoadmap">Roadmap</a></li><li class="active"><a class="False" href="/wiki/TracQuery">Ticket Queries</a></li><li class="False"><a class="False" href="/wiki/TracBatchModify">Batch Modify</a></li><li class="False"><a class="False" href="/wiki/TracReports">Reports</a></li><li class="False"><a class="False" href="/wiki/TracRss">RSS Support</a></li><li class="False"><a class="False" href="/wiki/TracNotification">Notification</a></li></ul></div><p> </p> <div class="wiki-toc trac-nav" style="clear:both"> <h4>Languages:</h4> <ul><li><a class="wiki" href="/wiki/TranslationDe/TracQuery">Deutsch</a> </li><li><strong>English</strong> </li></ul> </div><p> </p> <p> In addition to <a class="wiki" href="/wiki/TracReports">reports</a>, Trac provides <em>custom ticket queries</em>, which display tickets meeting specified criteria. </p> <p> To configure and execute a custom query, navigate to the <em>View Tickets</em> module from the navigation bar, and select the <em>New Custom Query</em> link. </p> <h2 class="section" id="Filters">Filters</h2> <p> When you first go to the query page, the default filter will display tickets relevant to you: </p> <ul><li>If logged in, all open tickets assigned to you. </li><li>If not logged in, but you have specified a name or email address in the preferences, all open tickets where your name or email is in the CC list. </li><li>If not logged in and no name/email is defined in the preferences, then all open issues. </li></ul><p> New filters are added using the dropdown lists at the bottom corners of the filters box; 'And' conditions on the left, 'Or' conditions on the right. Filters are removed by clicking the button to the left with the minus sign on the label. </p> <p> After you have edited your filters, click the <em>Update</em> button to refresh your results. </p> <p> Filters with either a text box or a dropdown menu of options can be added multiple times to perform an <em>Or</em> on the criteria. Add additional 'Or's by Clicking the 'And' Dropdown and selecting an item that you have already selected. For example, to select "Milestone is X <em>Or</em> Milestone is Y", Select 'Milestone', Select 'X', then click the 'And' Dropdown, select 'Milestone' a second time and select 'Y'. </p> <p> For text fields such as Keywords and CC the <code>-</code> operator can be used to negate a match and double quotes (<em>since 1.2.1</em>) can be used to match a phrase. For example, a <em>contains</em> match for <code>word1 word2 -word3 "word4 word5"</code> matches tickets containing <code>word1</code> and <code>word2</code>, not <code>word3</code> and <code>word4 word5</code>. </p> <p> You can use the controls just below the filters box to group the results based on a field, or display the full description for each ticket. </p> <p> Keyboard shortcuts are available for manipulating the <em>checkbox</em> filters: </p> <ul><li>Clicking on a filter row label toggles all checkboxes. </li><li>Pressing the modifier key while clicking on a filter row label inverts the state of all checkboxes. </li><li>Pressing the modifier key while clicking on a checkbox selects the checkbox and deselects all other checkboxes in the filter. Since 1.2.1 this also works for the <em>Columns</em> checkboxes. </li></ul><p> The modifier key is platform and browser dependent. On Mac the modified key is Option/Alt or Command. On Linux the modifier key is Ctrl + Alt. Opera on Windows seems to use Ctrl + Alt, while Alt is effective for other Windows browsers. </p> <h2 class="section" id="NavigatingTickets">Navigating Tickets</h2> <p> Clicking on one of the query results will take you to that ticket. You can navigate through the results by clicking the <em>Next Ticket</em> or <em>Previous Ticket</em> links just below the main menu bar, or click the <em>Back to Query</em> link to return to the query page. </p> <p> You can safely edit any of the tickets and continue to navigate through the results using the <em>Next/Previous/Back to Query</em> links after saving your results. When you return to the query <em>any tickets which were edited</em> will be displayed with italicized text. If one of the tickets was edited such that <span style="color: grey">it no longer matches the query criteria </span>, the text will also be greyed. If <strong>a new ticket matching the query criteria has been created</strong>, it will be shown in bold. </p> <p> The query results can be refreshed and cleared of these status indicators by clicking the <em>Update</em> button again. </p> <h2 class="section" id="SavingQueries">Saving Queries</h2> <p> Trac allows you to save the query as a named query accessible from the reports module. To save a query ensure that you have <em>Updated</em> the view and then click the <em>Save query</em> button displayed beneath the results. You can also save references to queries in Wiki content, as described below. </p> <p> <strong>Note:</strong> One way to easily build queries like the ones below is to create and test the queries using Custom Query module. Clicking <em>Save query</em> will display the query string for you, all you need to do is remove the extra line breaks. </p> <p> <strong>Note:</strong> You must have the <code>REPORT_CREATE</code> permission to save queries to the list of default reports. The <em>Save query</em> button will only appear if you are logged in as a user that has been granted this permission. If your account does not have permission to create reports, you can still use the methods below to save a query. </p> <h2 class="section" id="TracLinkstoQueries"><a class="wiki" href="/wiki/TracLinks">TracLinks</a> to Queries</h2> <p> You can make a link to a query from any Wiki page using a simple <a class="wiki" href="/wiki/TracQuery#QueryLanguage">query language</a> to specify the criteria. </p> <pre class="wiki">[query:status=new|assigned|reopened&version=1.4 Active tickets against 1.4] </pre><p> Which is displayed as: </p> <blockquote> <p> <a class="query" href="/query?status=new&status=assigned&status=reopened&version=1.4&order=priority">Active tickets against 1.4</a> </p> </blockquote> <p> Alternatively, you can copy the query string from the browser URL box and paste it into the Wiki link, including the leading <code>?</code> character: </p> <pre class="wiki">[query:?status=new&status=assigned&status=reopened&group=owner Assigned tickets by owner] </pre><p> Which is displayed as: </p> <blockquote> <p> <a class="query" href="/query?status=new&status=assigned&status=reopened&group=owner">Assigned tickets by owner</a> </p> </blockquote> <h2 class="section" id="QueryLanguage">Query Language</h2> <p> The <code>query:</code> <a class="wiki" href="/wiki/TracLinks">TracLinks</a> and the <a class="wiki" href="/wiki/TicketQuery">[[TicketQuery]]</a> macro both use a mini “query language” for specifying query filters. Filters are separated by ampersands (<code>&</code>), the <code>[[TicketQuery]]</code> macro additionally also accepts commas (<code>,</code>). Each filter consists of the ticket field name, an operator and one or more values. Multiple values are separated using a pipe (<code>|</code>), meaning the filter matches any of the values. To include a literal <code>&</code> or <code>|</code> in a value, escape the character with a backslash (<code>\</code>). </p> <p> The available operators are: </p> <table class="wiki"> <tr><td> <strong><code>=</code></strong> </td><td> the field content exactly matches one of the values </td></tr><tr><td> <strong><code>~=</code></strong> </td><td> the field content contains one or more of the values </td></tr><tr><td> <strong><code>^=</code></strong> </td><td> the field content starts with one of the values </td></tr><tr><td> <strong><code>$=</code></strong> </td><td> the field content ends with one of the values </td></tr></table> <p> All of these operators can also be negated: </p> <table class="wiki"> <tr><td> <strong><code>!=</code></strong> </td><td> the field content matches none of the values </td></tr><tr><td> <strong><code>!~=</code></strong> </td><td> the field content does not contain any of the values </td></tr><tr><td> <strong><code>!^=</code></strong> </td><td> the field content does not start with any of the values </td></tr><tr><td> <strong><code>!$=</code></strong> </td><td> the field content does not end with any of the values </td></tr></table> <p> Filters combining matches matches can be constructed for text fields such as Keywords and CC using the <em>contains</em> (<code>~=</code>) operator. The <code>!</code> operator is used to negate a match. </p> <p> Note that for <code>query:</code> the match operator <code>=</code> needs to be on first position when combined with other operators, for example <code>=!</code> or <code>=~</code>. The <code>[[TicketQuery]]</code> macro on the other side accepts both syntax variants, for example <code>!=</code> or <code>~=</code> as well as <code>=!</code> or <code>=~</code>. </p> <p> Double quotes (<em>since Trac 1.2.1</em>) are used for whitespace-separated words in a phrase. For example, <code>keywords~=word1 word2 -word3 "word4 word5"</code> matches tickets containing <code>word1</code> and <code>word2</code>, not <code>word3</code> and also <code>word4 word5</code>. </p> <table class="wiki"> <tr><td> <strong><code>status=closed,keywords~=firefox</code></strong> </td><td> query closed tickets that contain keyword <code>firefox</code> </td></tr><tr><td> <strong><code>status=closed,keywords~=opera</code></strong> </td><td> query closed tickets that contain keyword <code>opera</code> </td></tr><tr><td> <strong><code>status=closed,keywords~=firefox opera</code></strong> </td><td> query closed tickets that contain keywords <code>firefox</code> and <code>opera</code> </td></tr><tr><td> <strong><code>status=closed,keywords~=firefox|opera</code></strong> </td><td> query closed tickets that contain keywords <code>firefox</code> or <code>opera</code> </td></tr><tr><td> <strong><code>status=closed,keywords~=firefox,or,keywords~=opera</code></strong> </td><td> query closed tickets that contain keyword <code>firefox</code>, or (closed or unclosed) tickets that contain keyword <code>opera</code> </td></tr><tr><td> <strong><code>status=closed,keywords~=firefox -opera</code></strong> </td><td> query closed tickets that contain keyword <code>firefox</code>, but not <code>opera</code> </td></tr><tr><td> <strong><code>status=closed,keywords~=opera -firefox</code></strong> </td><td> query closed tickets that contain keyword <code>opera</code>, but no <code>firefox</code> </td></tr></table> <p> The date fields <code>created</code> and <code>modified</code> and custom fields of type <code>time</code> can be constrained by using the <code>=</code> operator and specifying a value containing two dates separated by two dots (<code>..</code>). Either end of the date range can be left empty, meaning that the corresponding end of the range is open. The date parser understands a few natural date specifications like "3 weeks ago", "last month", "in 2 years", "yesterday" and "now", as well as Bugzilla-style date specifications like "1d", "2w", "3m" or "4y" for 1 day, 2 weeks, 3 months and 4 years, respectively. Spaces in date specifications can be omitted to avoid having to quote the query string. </p> <table class="wiki"> <tr><td> <strong><code>created=2017-01-01..2018-01-01</code></strong> </td><td> query tickets created in 2017 </td></tr><tr><td> <strong><code>created=lastmonth..thismonth</code></strong> </td><td> query tickets created during the previous month </td></tr><tr><td> <strong><code>modified=1weekago..</code></strong> </td><td> query tickets that have been modified in the last week </td></tr><tr><td> <strong><code>modified=..30daysago</code></strong> </td><td> query tickets that have been inactive for the last 30 days </td></tr></table> <p> Note that <code>modified</code> is the <em>last modified time</em>, so <code>modified</code> with a date range shows ticket that were <em>last modified</em> in that date range. If a ticket was modified in the date range, but modified again after the end date, it will not be included in the results. </p> <hr /> <p> See also: <a class="wiki" href="/wiki/TracTickets">TracTickets</a>, <a class="wiki" href="/wiki/TracReports">TracReports</a>, <a class="wiki" href="/wiki/TicketQuery">TicketQuery</a> </p> </div> <div class="trac-modifiedby"> <span> <a href="/wiki/TracQuery?action=diff&version=63" title="Version 63 by Clemens: Added some "natural date specifications" in section "Query Language". In particular it was not clear to me how to compose a future date, namely with keyword "in" (similar to "ago" for past dates). Note that future dates become important if you have a custom date field "due date" or similar. ">Last modified</a> <a class="timeline" href="/timeline?from=2024-05-14T10%3A14%3A48%2B02%3A00&precision=second" title="See timeline at May 14, 2024, 10:14:48 AM">7 months ago</a> </span> <span class="trac-print"> Last modified on May 14, 2024, 10:14:48 AM </span> </div> </div> <div id="attachments"> </div> <div class="buttons"> <form method="get" action="/wiki/TracQuery" id="modifypage"> <div> <input type="hidden" name="action" value="edit" /> <input type="submit" value="Edit this page" /> </div> </form> <form method="get" action="/attachment/wiki/TracQuery/" id="attachfile"> <div> <input type="hidden" name="action" value="new" /> <input type="submit" id="attachfilebutton" value="Attach file"/> </div> </form> </div> <div class="trac-help"> <strong>Note:</strong> See <a href="/wiki/TracWiki">TracWiki</a> for help on using the wiki. </div> </div>  <div id="altlinks"> <h3>Download in other formats:</h3> <ul> <li class="last first"> <a rel="nofollow" href="/wiki/TracQuery?format=txt" class=""> Plain Text</a> </li> </ul> </div>   </div> <div id="footer"><hr/> <a id="tracpowered" href="https://trac.edgewall.org/" ><img src="/chrome/common/trac_logo_mini.png" height="30" width="107" alt="Trac Powered"/></a> <p class="left"> Powered by <a href="/about"><strong>Trac 1.4.3</strong></a> <br /> By <a href="http://www.edgewall.org/">Edgewall Software</a> . </p> <p class="right">Visit the Trac open source project at<br /><a href="//trac.edgewall.org/">https://trac.edgewall.org/</a></p> </div>   </div> </div> </div> <div id="ew-footer"> <p><a href="mailto:info@edgewall.com">info@edgewall.com</a></p> <p>Copyright © 2003-2024 Edgewall Software. All rights reserved.</p> </div> <div id="right"> <div id="ohloh-badge"> <a href="//www.openhub.net/p/trac"> <img src="//www.openhub.net/p/trac/widgets/project_thin_badge.gif" /> </a> </div> <script type="text/javascript"></script> <script type="text/javascript" src="//pagead2.googlesyndication.com/pagead/show_ads.js"> </script> </div>    </body> </html>