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


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.


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


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.


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


select * from WorkItemLinks where

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

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

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


 Same has One Hop Query.


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.


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

Comments (4)

  1. Grzegorz Wilczura says:


    How can i execute such query from C# code? I tried WorkItemStore.Query() but i got:

    "You have specified a query string that is not valid when you use the query method for a flat list of work items. You cannot specify a parameterized query or a query string for linked work items with the query method you specified."


  2. 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();




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


  3. Rene Guder says:

    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.

  4. Garry English says:

    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:


Skip to main content