WIQL(작업 항목 쿼리 언어) 구문 참조

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

WIQL 구문을 사용하여 쿼리를 하이퍼링크로 정의하거나 REST API(작업 항목 쿼리 언어)를 사용할 때 사용할 수 있습니다.

WIQL 구문은 웹 포털 쿼리 편집기 통해 사용할 수 있는 모든 함수와 몇 가지 기능을 추가로 지원합니다. 반환할 필드를 지정하고 쿼리 절의 논리적 그룹을 지정할 수 있습니다. 또한 절을 ASOF 사용하여 이전 날짜를 기준으로 할당을 기준으로 필터링할 수 있습니다.

필수 조건

쿼리는 이 노드 권한에서 작업 항목 보기 또는 작업 항목 보기가 있는 작업 항목만 반환합니다. 일반적으로 이러한 권한은 각 팀 프로젝트에 대한 읽기 권한자 및 기여자 그룹의 구성원에게 부여됩니다. 자세한 내용은 사용 권한 및 그룹을 참조 하세요.

쿼리 언어 개요

작업 항목 쿼리 언어에는 다음 구문 코드 조각에 표시된 5개의 부분이 있으며 다음 표에 설명되어 있습니다. WIQL 구문은 대/소문자를 구분하지 않습니다.

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'

날짜 및 시간 패턴

DateTime 필드에 입력하는 날짜 및 시간 패턴은 프로필을 통해 선택한 날짜 및 시간 패턴과 일치해야 합니다. 선택 항목을 보거나 변경하려면 사용자 기본 설정 설정을 참조하세요.

따옴표(작은따옴표 또는 큰따옴표 지원) 비교에 사용되는 DateTime 리터럴입니다. 쿼리를 실행하는 로컬 클라이언트 컴퓨터의 .NET DateTime 형식이어야 합니다. 표준 시간대를 지정하지 않는 한 DateTime 리터럴은 로컬 컴퓨터의 표준 시간대에 있습니다.

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

DateTime 리터럴에서 시간을 생략하고 dayPrecision 매개 변수가 false인 경우 시간은 0(자정)으로 간주됩니다. dayPrecision 매개 변수의 기본 설정은 false입니다.

또는 로캘에 관계없이 유효한 ISO 8601 형식을 지정할 수 있습니다. ISO 8601은 연도부터 시작하여 월, 일, 시간, 분, 초 및 밀리초까지의 날짜와 시간을 나타냅니다. 예를 들어 2021-12-10 15:00:00.000은 현지 시간으로 오후 3시에 2021년 12월 10일을 나타냅니다. ISO 8601 형식을 사용하는 예제는 다음과 같습니다.

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

사용자 지정 필드

필터 절 지정(WHERE)

이 절은 WHERE 필터 조건을 지정합니다. 쿼리는 지정된 조건을 충족하는 작업 항목만 반환합니다. 예를 들어 다음 예제 WHERE 절은 활성 상태이고 사용자에게 할당된 사용자 스토리를 반환합니다.

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

논리 연산자를 괄호 안에 묶어 필터 조건을 그룹화하여 계산되는 순서를 제어할 수 있습니다. 예를 들어 사용자에게 할당되거나 닫힌 작업 항목을 반환하려면 다음 예제와 일치하도록 쿼리 필터를 변경합니다.

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

필터 조건

각 필터 조건은 세 부분으로 구성되며 각각은 다음 규칙을 따라야 합니다.

• 필드: 참조 이름 또는 친숙한 이름을 지정할 수 있습니다. 다음 예제는 유효한 WIQL 구문입니다.
  • 참조 이름: SELECT [System.AssignedTo] ...
  • 공백이 있는 이름: SELECT [Assigned To] ...
  • 공백이 없는 이름에는 대괄호가 필요하지 않습니다. SELECT ID, Title ...
• 연산자: 유효한 값은 이 문서의 뒷부분에 있는 연산자 섹션에서 지정됩니다.
• 필드 값: 지정된 필드에 따라 다음 세 값 중 하나를 지정할 수 있습니다.
  • 리터럴 값은 필드 값 의 데이터 형식과 일치해야 합니다.
  • 특정 값을 나타내는 *변수 또는 매크로입니다. 예를 들어 @Me 쿼리를 실행하는 사람을 나타냅니다. 자세한 내용은 이 문서의 뒷부분에 있는 매크로 및 변수를 참조하세요.
  • 다른 필드의 이름입니다. 예를 들어 가장 최근에 작업 항목을 변경한 사람에게 할당된 작업 항목을 찾는 데 사용할 [Assigned to] = [Changed by] 수 있습니다.

모든 시스템 정의 필드 의 설명 및 참조 이름은 작업 항목 필드 인덱스입니다.

연산자

쿼리는 논리 식을 사용하여 결과 집합을 한정합니다. 이러한 논리 식은 하나 이상의 결합된 연산에 의해 형성됩니다.

몇 가지 간단한 쿼리 작업은 아래에 나열되어 있습니다.

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

아래 표에는 다양한 필드 형식에 대해 지원되는 모든 연산자가 요약됩니다. 각 필드 유형에 대한 자세한 내용은 작업 항목 필드 및 특성을 참조 하세요.

연산자는 =, <>, >, <, >=, and <= 예상대로 작동합니다. 예를 들어 System.ID > 100 ID가 100보다 큰 모든 작업 항목에 대한 쿼리입니다. System.ChangedDate > '01-01-19 12:00:00' 모든 작업 항목에 대한 쿼리가 2019년 1월 1일 정오 이후 변경되었습니다.

이러한 기본 연산자 외에도 특정 필드 형식과 관련된 몇 가지 동작과 연산자가 있습니다.

논리 그룹화

용어 AND 와 OR 일반적인 부울 의미로 두 절을 평가할 수 있습니다. 사용 약관 및 OR EVER 연산자를 AND EVER 지정할 때 사용할 수 있습니다WAS EVER. 필요에 따라 논리 식을 그룹화하고 추가로 연결할 수 있습니다. 예제는 다음과 같습니다.

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

를 사용하여 not연산자를 in 부정할 contains, under, 수 있습니다. 연산자를 ever 부정할 수 없습니다. 아래 예제에서는 하위 트리 아래에 할당되지 않은 모든 작업 항목에 대해 쿼리합니다 Fabrikam Fiber\Account Management.

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

예제 쿼리, 혹시 할당된 쿼리

다음 쿼리 편집기 예제에서는 Jamal Hartnett에 할당된 모든 작업 항목을 찾습니다.

그리고 여기에 해당하는 WIQL 구문이 있습니다.

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

매크로 또는 변수

다음 표에서는 WIQL 쿼리 내에서 사용할 수 있는 매크로 또는 변수를 나열합니다.

@me 매크로

매크로는 @me 쿼리를 실행하는 사용자의 Windows 통합 계정 이름을 바꿉니다. 아래 예제에서는 매크로와 동등한 정적 문을 사용하는 방법을 보여 주세요. 매크로는 다음과 같은 Assigned ToID 필드에 사용하기 위한 것입니다.

WHERE  
   [System.AssignedTo] = @Me 

@today 매크로

모든 DateTime 필드에 매크로를 @today 사용할 수 있습니다. 이 매크로는 쿼리를 실행하는 로컬 컴퓨터에서 현재 날짜의 자정을 바꿉니다. 또한 각각 x일 후 @today 및 y일 전@today의 정수 오프셋을 지정 @today+x 하거나 @today-y 사용할 수 있습니다. 매크로를 사용하는 쿼리는 매크로가 @today 실행되는 표준 시간대에 따라 다른 결과 집합을 반환할 수 있습니다.

아래 예제에서는 오늘이 1/3/19라고 가정합니다.

WHERE  
   [System.CreatedDate] = @today

다음과 같습니다.

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

및

WHERE  
   [System.CreatedDate] > @today-2

다음과 같습니다.

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'

사용자 지정 매크로

WIQL은 임의의 사용자 지정 매크로도 지원합니다. 접두사로 접두사로 @ 지정된 모든 문자열은 사용자 지정 매크로로 처리되고 대체됩니다. 사용자 지정 매크로의 대체 값은 개체 모델에서 쿼리 메서드의 컨텍스트 매개 변수에서 검색됩니다. 다음 메서드는 매크로에 사용되는 API입니다.

public WorkItemCollection Query(string wiql, IDictionary context)

컨텍스트 매개 변수는 매크로에 대한 키-값 쌍을 포함합니다. 예를 들어 컨텍스트에 키-값 쌍(프로젝트, MyProject) 이 포함된 경우 @project WIQL에서 바뀝 MyProject 니다. 이 대체는 작업 항목 쿼리 작성기가 Visual Studio에서 @project 매크로를 처리하는 방법입니다.

기록 쿼리 지정(ASOF)

쿼리의 절을 ASOF 사용하여 특정 날짜 및 시간에 정의된 대로 지정된 필터 조건을 충족하는 작업 항목을 필터링할 수 있습니다.

작업 항목이 2022년 5월 5일 이전에 반복 경로로 Fabrikam Fiber\Release 1 분류되어 'Jamal Hartnett'에 할당되었다고 가정합니다. 그러나 작업 항목은 최근에 'Raisa Pokrovskaya'에 할당되어 릴리스 2의 새 반복 경로로 이동되었습니다. 다음 예제 쿼리는 지난 날짜 및 시간을 기준으로 작업 항목의 상태를 기반으로 하기 때문에 Jamal Hartnett에 할당된 작업 항목을 반환합니다.

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'

정렬 순서 설정(ORDER BY)

이 절을 ORDER BY 사용하여 쿼리 결과를 하나 이상의 필드를 오름차순 또는 내림차순으로 정렬할 수 있습니다.

다음은 작업 항목을 우선 순위로 오름차순(기본값)으로 정렬한 다음 만든 날짜를 내림차순(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

작업 항목 간의 링크 쿼리

작업 항목 간에 링크를 반환하려면 .를 지정합니다 FROM WorkItemLinks. 절의 WHERE 필터 조건은 링크 또는 링크의 원본 또는 대상인 작업 항목에 적용될 수 있습니다. 예를 들어 다음 쿼리는 제품 백로그 항목과 해당 활성 자식 항목 사이의 링크를 반환합니다.

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)

다음 표에는 작업 항목 쿼리와 작업 항목 간의 링크에 대한 쿼리 간의 차이점이 요약되어 있습니다.

• System.LinkTypes.Hierarchy-Forward
• System.LinkTypes.Related
• System.LinkTypes.Dependency-Predecessor
• System.LinkTypes.Dependency-Successor
• Microsoft.VSTS.Common.Affects-Forward (CMMI 프로세스)

자세한 내용은 링크 형식 참조를 참조하세요.

트리 형식 쿼리 예제

다음 쿼리는 현재 프로젝트에 정의된 모든 작업 항목 형식을 반환합니다. 쿼리 편집기 표시된 쿼리는 다음 이미지와 같이 표시됩니다.

해당하는 WIQL 구문은 다음과 같습니다.

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)

직접 연결 쿼리 예제

다음 쿼리는 현재 프로젝트에 정의된 모든 작업 항목 형식을 반환합니다. 쿼리 편집기 표시된 쿼리는 다음 이미지와 같이 표시됩니다.

해당하는 WIQL 구문이 표시된 것처럼 표시됩니다.

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)

추가 쿼리 예제

다음은 필드에 대한 참조 이름을 사용하는 일반적인 WIQL 쿼리 예제입니다. 쿼리는 Priority=1을 사용하여 작업 항목(작업 항목 유형이 지정되지 않음)을 선택합니다. 쿼리는 반환 집합의 ID 와 제목 을 열로 반환합니다. 결과는 ID별로 오름차순으로 정렬됩니다.

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

날짜-시간 패턴

다음 두 패턴 중 하나에 따라 날짜-시간 패턴을 지정합니다.

• 날짜 패턴 및 시간 패턴 형식은 사용자 기본 설정, 시간 및 로캘에서 가져옵니다.
• UTC에서 지정한 패턴으로, 이 패턴을 따릅니다(날짜-시간에 Z가 추가됨).

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

예제 절

다음 예제 문은 특정 정규화 절을 보여 줍니다.

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 및 PlainText

문자열 또는 일반 텍스트 필드와 비교하여 따옴표 문자열 리터럴(작은따옴표 또는 큰따옴표가 지원됨)입니다. 문자열 리터럴은 모든 유니코드 문자를 지원합니다.

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

contains 연산자를 사용하여 필드 값의 아무 곳이나 부분 문자열을 검색할 수 있습니다.

WHERE [System.Description] contains 'WIQL' 

영역 및 반복(TreePath)

영역 및 반복 경로 필드에 연산자를 사용할 UNDER 수 있습니다. 연산자는 UNDER 값이 특정 분류 노드의 하위 트리 내에 있는지 여부를 평가합니다. 예를 들어 영역 경로가 'MyProject\Server\Administration', 'MyProject\Server\Administration\Feature 1', 'MyProject\Server\Administration\Feature 2\SubFeature 5' 또는 하위 트리 내의 다른 노드인 경우 아래 식은 true로 평가됩니다.

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

한정자 및 특수 연산자

쿼리 식에서 일부 한정자와 특수 연산자를 사용할 수 있습니다.

연산자를 IN 사용하여 필드 값이 값 집합과 같은지 여부를 평가합니다. 이 연산자는 String, Integer, Double 및 DateTime 필드 형식에 대해 지원됩니다. 의미 체계와 함께 다음 예제를 참조하세요.

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

연 EVER 산자는 필드 값이 작업 항목의 모든 이전 수정 버전에서 특정 값과 같은지 여부를 평가하는 데 사용됩니다. String, Integer, Double 및 DateTime 필드 형식은 이 연산자를 지원합니다. 연산자에 대한 대체 구문이 있습니다 EVER . 예를 들어 아래 코드 조각은 모든 작업 항목이 Jamal, Raise 또는 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>'
    )

관련된 문서

• 쿼리 필드, 연산자, 값 및 변수
• 작업 항목 필드 및 특성
• 관리되는 쿼리 정보
• 쿼리 정의