Referencia de sintaxis del lenguaje de consultas de elemento de trabajo (WIQL)

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Puede usar la sintaxis WIQL para definir una consulta como hipervínculo o cuando se usa el lenguaje de consultas de elemento de trabajo (API de REST).

La sintaxis WIQL admite todas las funciones disponibles a través del Editor de consultas del portal web, y algunas más. Puede especificar los campos que se van a devolver y especificar la agrupación lógica de cláusulas de consulta. Además, puede usar una cláusula ASOF para filtrar según las asignaciones basadas en una fecha anterior.

Requisitos previos

Una consulta devuelve solo los elementos de trabajo para los que tenga el permiso Ver elementos de trabajo o Ver los elementos de trabajo en este nodo. Normalmente, estos permisos se conceden a los miembros de los grupos Lectores y Colaboradores de cada proyecto de equipo. Para obtener más información, consulte Permisos y grupos.

Información general del lenguaje de consulta

El lenguaje de consulta de elementos de trabajo tiene cinco partes que se muestran en el siguiente fragmento de sintaxis y se describen en la tabla siguiente. La sintaxis WIQL no distingue mayúsculas de minúsculas.

SELECT
    [System.Id],
    [System.AssignedTo],
    [System.State],
    [System.Title],
    [System.Tags]
FROM workitems
WHERE
    [System.TeamProject] = 'Design Agile'
    AND [System.WorkItemType] = 'User Story'
    AND [System.State] = 'Active'
ORDER BY [System.ChangedDate] DESC
ASOF '02-11-2020'

Patrón de fecha y hora

El patrón de fecha y hora que escriba para los campos DateTime debe coincidir con el que seleccione mediante el perfil. Para ver o cambiar la selección, consulte Establecimiento de preferencias de usuario.

Colocar entre comillas (se admiten comillas simples o dobles) literales de DateTime utilizados en las comparaciones. Deben estar en el formato DateTime de .NET del equipo cliente local que ejecuta la consulta. A menos que se especifique una zona horaria, los literales DateTime se encuentran en la zona horaria del equipo local.

WHERE 
   AND [System.ChangedDate] >= '01-18-2019 GMT'
   AND ([Closed Date] < '01-09-2022 GMT'
   OR [Resolved Date] >= '01-18-2019 14:30:01')  

Cuando la hora se omite en un literal DateTime y el parámetro dayPrecision es false, se supone que la hora es cero (medianoche). La configuración predeterminada para el parámetro dayPrecision es false.

O bien, puede especificar el formato ISO 8601 que es válido independientemente de la configuración regional. ISO 8601 representa la fecha y hora empezando por el año, el mes, el día, la hora, los minutos, los segundos y los milisegundos. Por ejemplo, 2021-12-10 15:00:00.000, representa el 10 de diciembre de 2021 a las 15:00 de la hora local. Un ejemplo de uso del formato ISO 8601 es el siguiente.

WHERE 
   AND [System.ChangedDate] >= '2019-01-18T00:00:00.0000000'
   AND ([Closed Date] < '2022-01-09T00:00:00.0000000'
   OR [Resolved Date] >= '2019-01-18T00:00:00.0000000')  

Custom Fields

Especificar cláusulas de filtro (WHERE)

La cláusula WHERE especifica los criterios de filtro. La consulta devuelve solo los elementos de trabajo que cumplen estas condiciones. Por ejemplo, la siguiente cláusula de ejemplo WHERE devuelve casos de usuario activos que tiene asignados.

WHERE [Work Item Type] = 'User Story'
   AND [State] = 'Active'
   AND [Assigned to] = @Me

Puede controlar el orden en el que se evalúan los operadores lógicos al incluirlos entre paréntesis para agrupar los criterios de filtro. Por ejemplo, para devolver elementos de trabajo que tiene asignados o que haya cerrado, cambie el filtro de la consulta para que coincida con el ejemplo siguiente.

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] = 'Product Backlog Item'
        AND (
            [System.AssignedTo] = @me
            OR [Microsoft.VSTS.Common.ClosedBy] = @me
        )
    )

Condiciones de filtro

Cada condición de filtro se compone de tres partes, cada una de las cuales debe cumplir las siguientes reglas:

• Campo: puede especificar el nombre de referencia o el nombre descriptivo. Los siguientes ejemplos son sintaxis WIQL válida:
  • Nombre de referencia: SELECT [System.AssignedTo] ...
  • Nombre descriptivo con espacios: SELECT [Assigned To] ...
  • Los nombres sin espacios no requieren corchetes: SELECT ID, Title ...
• Operador: los valores válidos se especifican en la sección Operadores más adelante en este artículo.
• Valor de campo: puede especificar uno de los tres valores siguientes en función del campo especificado.
  • Un valor literal debe coincidir con el tipo de datos del valor de campo.
  • *Variable o macro que indica un valor determinado. Por ejemplo, @Me indica la persona que ejecuta la consulta. Para obtener más información, consulte Macros y variables, más adelante en este tema.
  • El nombre de otro campo. Por ejemplo, puede usar [Assigned to] = [Changed by] para buscar elementos de trabajo asignados a la persona que modificó el elemento de trabajo por última vez.

Para obtener una descripción y nombres de referencia de todos los campos definidos por el sistema, consulte Índice de campo de elementos de trabajo.

Operadores

Las consultas usan expresiones lógicas para calificar conjuntos de resultados. Estas expresiones lógicas están formadas por una o varias operaciones de unión.

A continuación, se enumeran algunas operaciones de consulta simples.

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
    AND [Microsoft.VSTS.Common.Severity] <> '1 - Critical'

En la tabla siguiente se resumen todos los operadores admitidos para distintos tipos de campo. Para obtener más información sobre cada tipo de campo, consulte Campos y atributos de elementos de trabajo.

Los operadores =, <>, >, <, >=, and <= funcionan según lo previsto. Por ejemplo, System.ID > 100 consulta todos los elementos de trabajo con un id. superior a 100. Las consultas System.ChangedDate > '01-01-19 12:00:00' de todos los elementos de trabajo cambiaron después de las 12:00 del 1 de enero de 2019.

Además de estos operadores básicos, existen algunos comportamientos y operadores específicos de determinados tipos de campo.

Agrupaciones lógicas

Puede usar los términos AND y OR en el sentido booleano típico para evaluar dos cláusulas. Puede usar los términos AND EVER y OR EVER al especificar un operador WAS EVER. Puede agrupar expresiones lógicas y unirlas aún más, según sea necesario. A continuación se muestran ejemplos.

WHERE
    [System.TeamProject] = @project
    AND (
        [System.WorkItemType] <> ''
        AND [System.State] IN ('Active', 'Approved', 'Committed', 'In Progress')
        AND (
            [System.CreatedBy] = ''
            OR [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        )
    )

Puede negar los operadores contains, under, y in mediante not. No se puede negar el operador ever. En el ejemplo siguiente se consultan todos los elementos de trabajo que no están asignados en el subárbol de Fabrikam Fiber\Account Management.

WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND NOT [System.AreaPath] UNDER 'Fabrikam Fiber\Account Management'

Consulta de ejemplo, Se asignó alguna vez a

En el ejemplo de Editor de consultas siguiente se buscan todos los elementos de trabajo asignados a Jamal Hartnett.

Aquí está la sintaxis WIQL correspondiente.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'

Macros o variables

En la tabla siguiente se enumeran las macros o variables que puede usar en una consulta WIQL.

@meMacro

La macro @me reemplaza el nombre de la cuenta integrada de Windows del usuario que ejecuta la consulta. En el ejemplo siguiente se muestra cómo usar la macro y la instrucción estática equivalente. La macro está pensada para su uso con campos de identidad como Assigned To.

WHERE  
   [System.AssignedTo] = @Me 

@todayMacro

Puede usar la macro @today con cualquier campo DateTime. Esta macro reemplaza la medianoche de la fecha actual en el equipo local que ejecuta la consulta. También puede especificar @today+x o @today-y mediante desplazamientos enteros durante X días después de @today, y Y días antes de @today, respectivamente. Una consulta que usa la macro @today puede devolver diferentes conjuntos de resultados en función de la zona horaria en la que se ejecuta.

En los ejemplos siguientes se supone que hoy es 1/3/19.

WHERE  
   [System.CreatedDate] = @today

Es el equivalente de:

WHERE  
   [System.CreatedDate] = '01-03-2019'

Y

WHERE  
   [System.CreatedDate] > @today-2

Es el equivalente de:

WHERE  
   [System.CreatedDate] > '01-01-2019'

WHERE 
   [Microsoft.VSTS.Common.ClosedDate] >=@StartOfYear('+3M') - 1

WHERE  
   [Microsoft.VSTS.Common.CreatedDate] >= @StartOfMonth-3

WHERE 
   [Microsoft.VSTS.Common.CreatedDate] >= '01-01-2019'

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate] > @StartOfYear

WHERE 
   [Microsoft.VSTS.Scheduling.TargetDate]  > '01-01-2019'

Macros personalizadas

WIQL también admite macros personalizadas arbitrarias. Cualquier cadena precedida por un @ se trata como una macro personalizada y se sustituye. El valor de reemplazo de la macro personalizada se recupera del parámetro de contexto del método de consulta en el modelo de objetos. El método siguiente es la API que se usa para macros:

public WorkItemCollection Query(string wiql, IDictionary context)

El parámetro de contexto contiene pares clave-valor para macros. Por ejemplo, si el contexto contiene un par clave-valor de (proyecto, MiProyecto), @proyect o se sustituye por MyProject en el WIQL. Este reemplazo es el modo en que el generador de consultas del elemento de trabajo controla la macro @project en Visual Studio.

Especificar consultas de historial (ASOF)

Puede usar una cláusula ASOF en una consulta para filtrar los elementos de trabajo que cumplan las condiciones de filtro especificadas según se definieron en una fecha y hora específicas.

Supongamos que un elemento de trabajo se clasificó en una ruta de iteración de Fabrikam Fiber\Release 1 y se asignó a "Jamal Hartnett" antes del 5/5/2022. Sin embargo, el elemento de trabajo se asignó recientemente a "Raisa Pokrovskaya" y se movió a una nueva ruta de iteración de la versión 2. El siguiente ejemplo de consulta devuelve los elementos de trabajo asignados a Jamal Hartnett porque la consulta se basa en el estado de los elementos de trabajo a partir de una fecha y hora pasadas.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND ([System.IterationPath] UNDER 'Fabrikam Fiber\Release 1'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>') 
    ASOF  '01-05-2022 00:00:00.0000000'

Establecer el criterio de ordenación (ORDER BY)

Puede usar la cláusula ORDER BY para ordenar los resultados de una consulta por uno o varios campos en orden ascendente o descendente.

En el ejemplo siguiente se ordenan los elementos de trabajo primero por Prioridad en orden ascendente (valor predeterminado) y, a continuación, por Fecha de creación en orden descendente (DESC).

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [System.WorkItemType] <> ''
    AND [System.State] =  'Active'
    AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC

Consulte vínculos entre elementos de trabajo

Para devolver vínculos entre elementos de trabajo, especifique FROM WorkItemLinks. Pueden aplicarse condiciones de filtro en la cláusula WHERE a los vínculos o a cualquier elemento de trabajo que sea el origen o el destino de un vínculo. Por ejemplo, la consulta siguiente devuelve los vínculos entre elementos de trabajo pendiente de producto y sus elementos secundarios activos.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] = 'Product Backlog Item'
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.State] <> 'Closed'
    )
ORDER BY [Microsoft.VSTS.Common.Priority],
    [System.CreatedDate] DESC
MODE (Recursive)

En la tabla siguiente se resumen las diferencias entre las consultas de elementos de trabajo y las consultas de vínculos entre elementos de trabajo.

• System.LinkTypes.Hierarchy-Forward
• System.LinkTypes.Related
• System.LinkTypes.Dependency-Predecessor
• System.LinkTypes.Dependency-Successor
• Microsoft.VSTS.Common.Affects-Forward (Proceso de CMMI)

Para obtener más información, consulte Referencia de tipo de vínculo.

Ejemplo de consulta de tipo de árbol

La consulta siguiente devuelve todos los tipos de elementos de trabajo definidos en el proyecto actual. La consulta que aparece en el Editor de consultas aparece igual en la imagen siguiente.

A continuación se muestra la sintaxis WIQL equivalente.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
    )
MODE (Recursive)

Ejemplo de consulta de vínculo directo

La consulta siguiente devuelve todos los tipos de elementos de trabajo definidos en el proyecto actual. La consulta que aparece en el Editor de consultas aparece igual en la imagen siguiente.

La sintaxis WIQL equivalente es la que se muestra.

SELECT
    [System.Id],
    [System.WorkItemType],
    [System.Title],
    [System.AssignedTo],
    [System.State]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Dependency-Reverse'
        OR [System.Links.LinkType] = 'System.LinkTypes.Related-Forward'
        OR [System.Links.LinkType] = 'System.LinkTypes.Dependency-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.ChangedDate] >= @today - 60
    )
ORDER BY [System.Id]
MODE (MustContain)

Más ejemplos de consultas

En el siguiente ejemplo típico de consulta WIQL se usan nombres de referencia para los campos. La consulta selecciona elementos de trabajo (sin ningún tipo de elemento de trabajo especificado) con Prioridad=1. La consulta devuelve el id. y el título del conjunto devuelto como columnas. Los resultados se ordenan por id. en orden ascendente.

SELECT
    [System.Id],
    [System.Title],
    [System.State],
    [System.IterationPath]
FROM workitems
WHERE
    [System.TeamProject] = @project
    AND [Microsoft.VSTS.Common.Priority] <> ''
ORDER BY [System.Id]

Patrón de fecha y hora

Especifique el patrón de fecha y hora según uno de estos dos patrones:

• El formato de patrón de fecha y hora proviene de las preferencias del usuario, la hora y la configuración regional
• El patrón especificado por UTC, que sigue este patrón (con Z anexado a la fecha y hora).

AND [System.ChangedDate] >= '1/1/2019 00:00:00Z'

Cláusulas de ejemplo

En las instrucciones de ejemplo siguientes se muestran cláusulas aptas específicas.

SELECT [System.Id], [System.Title]
FROM WorkItems
WHERE [System.TeamProject] = @project
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND ( [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
OR [System.AssignedTo] = ''Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>' )

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [System.AssignedTo] NOT CONTAINS 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
AND [System.AreaPath] UNDER 'Agile1\Area 0'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
ORDER BY [System.Id] [asc | desc]

SELECT [System.Title] 
FROM workitems 
WHERE [System.IterationPath] = 'MyProject\Beta' 
AND [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>' 
ASOF '3/16/19 12:30'

String y PlainText

Colocar entre comillas (se admiten comillas simples o dobles) literales de cadena en una comparación con un campo de texto sin formato o cadena. Los literales de cadena admiten todos los caracteres Unicode.

WHERE [Custom.Blocking] = 'Not Blocking'
WHERE [Custom.Blocking] <> 'Blocked'

Puede usar el operador contains para buscar una subcadena en cualquier parte del valor del campo.

WHERE [System.Description] contains 'WIQL' 

Área e iteración (TreePath)

Puede usar el operador UNDER para los campos Área y Ruta de iteración. El operador UNDER evalúa si un valor está dentro del subárbol de un nodo de clasificación específico. Por ejemplo, la expresión siguiente se evaluaría como true si la ruta de acceso del área fuera "MyProject\Server\Administration", "MyProject\Server\Administration\Feature 1", "MyProject\Server\Administration\Feature 2\SubFeature 5", o cualquier otro nodo del subárbol.

WHERE [System.AreaPath] UNDER 'MyProject\Server\Administration'

Modificadores y operadores especiales

Puede usar algunos modificadores y operadores especiales en una expresión de consulta.

Use el operador IN para evaluar si un valor de campo es igual a cualquiera de un conjunto de valores. Este operador es compatible con los tipos de campo Cadena, Entero, Doble y DateTime. Vea el ejemplo siguiente junto con su equivalente semántico.

WHERE
    [System.TeamProject] = @project
    AND [System.CreatedBy] IN ('Jamal Hartnett <fabrikamfiber4@hotmail.com>', 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>', 'Christie Church <fabrikamfiber1@hotmail.com>')

or

WHERE
    [System.TeamProject] = @project
    AND (
        [System.CreatedBy] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR [System.CreatedBy] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR [System.CreatedBy] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

El operador EVER se usa para evaluar si un valor de campo es igual o ha igualado un valor determinado en todas las revisiones anteriores de los elementos de trabajo. Los tipos de campo Cadena, Entero, Doble y DateTime admiten este operador. Hay sintaxis alternativa para el operador EVER. Por ejemplo, los fragmentos de código siguientes consultan si todos los elementos de trabajo se asignaron alguna vez a Jamal, Raise o Christie.

WHERE
    [System.TeamProject] = @project
    AND (
        EVER [System.AssignedTo] = 'Jamal Hartnett <fabrikamfiber4@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Raisa Pokrovskaya <fabrikamfiber5@hotmail.com>'
        OR EVER [System.AssignedTo] = 'Christie Church <fabrikamfiber1@hotmail.com>'
    )

Artículos relacionados

• Variables, valores, operadores y campos de consulta
• Atributos y campos de elementos de trabajo
• Acerca de las consultas administradas
• Definir una consulta