WIQL syntax for Link Query

Flat List Query (Old)

The general Syntax:

select <fields> from WorkItems [where <condition>]
[order by <fields>] [asof <date>]

 

Link Query

When querying across links, you specify three filters:

· A filter on the work items (Source)

· A filter on the links themselves (Link)

· A filter on the items being pointed to by the links (Target)

           Work Items --------> Links ----------> Linked Work Items

 

Work Items and Direct Links Query (One Hop Query)

The general syntax:

select <fields> from WorkItemLinks [where <condition>]
[order by <fields>] [asof <date>] [mode(mustcontain|maycontain|doesnotcontain)]

Example:

select * from WorkItemLinks where

([Source].[System.WorkItemType] = ‘Feature’ and [Source].[System.State] = ‘Active’) and

 ([System.Links.LinkType] = ‘System.LinkTypes.Dependency-Forward’) and

 (([Target].[System.WorkItemType = ‘Bug’ and [Target].[System.AssignedTo] = @me) order by [System.Id] mode(mustcontain)

The query will return all active features, which have bugs, assigned to me.

<table>

The main difference is that we are querying from WorkItemLinks, which makes clear separation between regular queries and link queries.

<condition>

The "where" clause, only supports 3 separate sections separated by "and" operator:

<source expression> and <link expression> and <target expression>

where any of them is optional, and they can be in any order.

<mode>

The default mode is “MustContain”, which means that we return links satisfying the criteria, and only them.

The MayContain mode return links satisfying the criteria, but also return items, which satisfy just the source criteria, when target criteria is optional.

The DoesNotContain mode return items, which does not have links specifying by target criteria.

Tree Query

The general syntax:

select <fields> from WorkItemLinks [where <condition>]
mode(recursive)

Example:

select * from WorkItemLinks where

([Source].[System.State] = ‘Resolved’) and

([Target].[System.State] = ‘Resolved’) and

([System.Links.LinkType] = ‘System.LinkTypes.Hierarchy-Forward’) mode(recursive)

<table>

Same has One Hop Query.

<condition>

Almost same as one hope query, except that

· Cannot have complex expression on [Link Type] clause.

· [Link Type] cannot be omitted, meaning it is not optional.

· Link type must be Tree topology and forward direction.

“Order by” and “As Of” are not compatible with tree queries.

<mode>

Tree queries are representing with recursive mode, returning results recursively for target.

Comments

• Anonymous
  July 06, 2010
  The comment has been removed

• Anonymous
  July 08, 2010
  There is a new Query object you will have to use to run linked queries. Below is a sample        public WorkItemLinkInfo[] RunLinkQuery(QueryDefinition  queryDefinition)        {            Query query = null;            WorkItemLinkInfo[] workItemLinkInfoArray = null;            query = GetQueryObjectFromQueryDefinition(queryDefinition);            if (query.IsLinkQuery)            {                workItemLinkInfoArray = query.RunLinkQuery();            }            else            {                throw new Exception("Run link query fail. Query passed is not a link query");            }            return workItemLinkInfoArray;        }       private Query GetQueryObjectFromQueryDefinition(QueryDefinition queryDefinition)        {                string wiql = queryDefinition.QueryText;                //Below code is to replace any macros                System.Collections.Hashtable context = new System.Collections.Hashtable();                context.Add("@project&quot;, m_projectName);                queryReturn = new Query(m_workItemStore, wiql, context);                return queryReturn;        } For full example on how to get QueryDefinition object, please check my another blog at blogs.msdn.com/.../work-item-tracking-queries-object-model-in-2010.aspx

• Anonymous
  August 11, 2010
  Are there any other fields you can use in the <link expression> other than [System.Links.LinkType] ? I would like to filter my WorkItemLinks by their Comment. Using the API and a loop over all WorkItemLinks of a WorkItem is just too slow for my purpose.

• Anonymous
  August 18, 2010
  The following worked for me to run queries: Dictionary<string, string> context = new Dictionary<string, string>(); context .Add( "project", queryDefinition.Project.Name ); return store.Query( queryDefinition.QueryText, context ); When adding variables, you shouldn't add the '@' symbol: msdn.microsoft.com/.../bb130306.aspx