Referenční informace k syntaxi jazyka WIQL (Work Item Query Language)

  • Článek

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

Pomocí syntaxe WIQL můžete definovat dotaz jako hypertextový odkaz nebo při použití rozhraní REST API (Work Item Query Language).

Syntaxe WIQL podporuje všechny funkce dostupné prostřednictvím webového portálu Editor Power Query a ještě několik dalších. Můžete zadat pole, která se mají vrátit, a zadat logické seskupení klauzulí dotazu. Kromě toho můžete použít ASOF klauzuli k filtrování na základě přiřazení na základě předchozího data.

Důležité

Syntaxe WIQL se používá ke spuštění dotazu pomocí rozhraní REST API Wiql. V současné době neexistuje způsob, jak volat rozhraní API, aby se podrobné informace o pracovní položce vrátily přímo z dotazu WIQL. Bez ohledu na to, která pole zahrnete do příkazu SELECT, vrátí rozhraní API jenom ID pracovních položek. Pokud chcete získat úplné informace, musíte provést dva kroky: (1) získat ID pracovních položek z WIQL a (2) získat pracovní položky prostřednictvím získání seznamu pracovních položek podle ID a pro konkrétní pole.

Požadavky

Dotaz vrátí pouze ty pracovní položky, pro které máte v oprávnění k uzlu Zobrazit pracovní položky nebo Zobrazit pracovní položky. Tato oprávnění jsou obvykle udělena členům skupin Čtenáři a Přispěvatelé pro každý týmový projekt. Další informace najdete v tématu Oprávnění a skupiny.

Přehled dotazovacího jazyka

Dotazovací jazyk pracovní položky má pět částí zobrazených v následujícím fragmentu syntaxe a popsané v následující tabulce. Syntaxe WIQL nerozlišuje malá a velká písmena.

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'

Tip

Instalací rozšíření Wiql Editor Marketplace můžete vytvářet dotazy pomocí Editor Power Query a pak zobrazit syntaxi WIQL. Potom můžete zkopírovat a upravit syntaxi WIQL a spustit dotaz pomocí centra Wiql Playground přidaného do Boards.

Klauzule

Příklad

SELECT

Identifikuje pole, která se mají vrátit pro každou pracovní položku vrácenou dotazem. Můžete zadat popisný název nebo název odkazu. Pokud název obsahuje mezery nebo tečky, použijte hranaté závorky ([]).

FROM

Určuje, jestli má dotaz najít pracovní položky nebo propojení mezi pracovními položkami.

WHERE

Určuje kritéria filtru pro dotaz. Další informace najdete v tématu Podmínky filtru (WHERE) dále v tomto článku.

ORDER BY

Určuje pořadí řazení vrácených pracovních položek. Pro jedno nebo více polí můžete zadat vzestupně (Asc) nebo Sestupně (Desc). Příklad:
ORDER BY [State] Asc, [Changed Date] Desc

ASOF

Určuje historický dotaz tím, že označuje datum, kdy se má filtr použít. Tento dotaz například vrátí všechny uživatelské scénáře definované jako Aktivní 11. února 2020. Zadejte datum podle pokynů uvedených ve vzoru data a času. ASOF '02-11-2020'

Poznámka:

Délka WIQL dotazů provedených v Azure Boards nesmí překročit 32 tisíc znaků. Systém vám nedovolí vytvářet ani spouštět dotazy, které tuto délku překračují.

Vzor data a času

Vzor data a času, který zadáte pro pole DateTime , by se měl shodovat s tím, který vyberete v profilu. Pokud chcete zobrazit nebo změnit výběr, přečtěte si téma Nastavení uživatelských předvoleb pro čas a národní prostředí.

Snímek obrazovky s možnostmi rozevíracího seznamu Vzor data v podokně Čas a národní prostředíSnímek obrazovky s možnostmi rozevíracího seznamu Časové vzory v podokně Čas a národní prostředí

Snímek obrazovky znázorňující podokno Čas a národní prostředí s poli Vzor data a Času

Uvozovky (jednoduché nebo dvojité uvozovky jsou podporovány) Literály DateTime používané ve srovnáních. Musí být ve formátu .NET DateTime místního klientského počítače se spuštěným dotazem. Pokud není zadané časové pásmo, literály DateTime jsou v časovém pásmu místního počítače.

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

Pokud je čas vynechán v literálu DateTime a parametr dayPrecision se rovná false, předpokládá se, že čas bude nula (půlnoc). Výchozí nastavení parametru dayPrecision je false.

Nebo můžete zadat formát ISO 8601, který je platný bez ohledu na národní prostředí. ISO 8601 představuje datum a čas od roku, za kterým následuje měsíc, den, hodina, minuty, sekundy a milisekundy. Například 2021-12-10 15:00:00.000 představuje 10. prosince 2021 v místním čase. Příklad použití formátu ISO 8601 je následující.

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

Vlastní pole

Do klauzule dotazu můžete přidat vlastní pole. U technologie WIQL je nutné zadat název odkazu pro vlastní pole. U projektů, které používají model zděděného procesu, jsou vlastní pole obvykle označená vlastními poli. Před jejich názvem a odeberou se mezery. Příklad:

Popisný název Referenční název
Schvalovatel Custom.Approver
Typ žádosti Custom.RequestType
Odhad rozsahu Custom.CustomEstimate

U projektů, které používají místní model procesu XML, je název odkazu definovaný definicemi typu pracovní položky XML.

Další informace naleznete v tématu Pole a atributy pracovní položky.

Určení klauzulí filtru (WHERE)

Klauzule WHERE určuje kritéria filtru. Dotaz vrátí pouze pracovní položky, které splňují zadaná kritéria. Například následující příklad WHERE klauzule vrátí uživatelské scénáře, které jsou aktivní a které jsou přiřazeny vám.

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

Pořadí, ve kterém se logické operátory vyhodnocují, můžete řídit tak, že je uzavřete do závorek a seskupíte kritéria filtru. Pokud chcete například vrátit pracovní položky, které jsou vám přiřazeny nebo které jste zavřeli, změňte filtr dotazu tak, aby odpovídal následujícímu příkladu.

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

Podmínky filtru

Každá podmínka filtru se skládá ze tří částí, z nichž každá musí odpovídat následujícím pravidlům:

  • Pole: Můžete zadat název odkazu nebo popisný název. Následující příklady jsou platná syntaxe WIQL:
    • Název odkazu: SELECT [System.AssignedTo] ...
    • Popisný název s mezerami: SELECT [Assigned To] ...
    • Názvy bez mezer nevyžadují hranaté závorky: SELECT ID, Title ...
  • Operátor: Platné hodnoty jsou uvedeny v části Operátory dále v tomto článku.
  • Hodnota pole: V závislosti na zadaném poli můžete zadat jednu z následujících tří hodnot.
    • Hodnota literálu musí odpovídat datovému typu hodnoty pole.
    • Proměnná nebo makro označující určitou hodnotu. Například @Me označuje osobu, která dotaz spouští. Další informace naleznete v tématu Makra a proměnné dále v tomto článku.
    • Název jiného pole. Můžete například najít [Assigned to] = [Changed by] pracovní položky, které jsou přiřazené osobě, která pracovní položku naposledy změnila.

Popis a referenční názvy všech systémově definovaných polí naleznete v tématu Index polí pracovní položky.

Operátory

Dotazy používají logické výrazy k opravňujícím sadám výsledků. Tyto logické výrazy jsou tvořeny jednou nebo více konjoinovanými operacemi.

Níže jsou uvedeny některé jednoduché operace dotazu.

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

Následující tabulka shrnuje všechny podporované operátory pro různé typy polí. Další informace o jednotlivých typech polí najdete v tématu Pole a atributy pracovní položky.

Operátory =, <>, >, <, >=, and <= fungují podle očekávání. Například System.ID > 100 dotazy na všechny pracovní položky s ID větší než 100. System.ChangedDate > '01-01-19 12:00:00' dotazy na všechny pracovní položky se změnily po poledne 1. ledna 2019.

Kromě těchto základních operátorů existují určité chování a operátory specifické pro určité typy polí.

Poznámka:

Operátory, které máte k dispozici, závisí na vaší platformě a verzi. Další informace najdete v tématu Stručná referenční příručka k dotazům.

Typ pole

Podporované operátory

Logická hodnota

= , <> , =[Field] , <>[Field]

DateTime

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever

Double, GUID, Integer

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever

Identita

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever

PlainText

Contains Words, Not Contains Words, Is Empty, Is Not Empty

String

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Not Contains, In, Not In, In Group, Not In Group, Was Ever

TreePath

=, <>, In, Not In, Under, Not Under

Logické seskupení

Termíny AND a OR v typickém logickém smyslu můžete použít k vyhodnocení dvou klauzulí. Můžete použít podmínky AND EVER a OR EVER při zadávání operátoru WAS EVER . Logické výrazy můžete podle potřeby seskupit a dále je spojit. Příklady jsou uvedené níže.

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

Operátory a in operátory contains, under, můžete negovat pomocí .not Operátor nelze negovat ever . Následující příklad se dotazuje na všechny pracovní položky, které nejsou přiřazeny pod podstrom .Fabrikam Fiber\Account Management

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

Příklad dotazu, kdy byl přiřazen

Následující Editor Power Query příklad najde všechny pracovní položky, které byly někdy přiřazeny Jamal Hartnett.

Snímek obrazovky s dotazem Editor Power Query, plochým seznamem, byl někdy přiřazený.

A tady je odpovídající syntaxe 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>'

Makra nebo proměnné

Následující tabulka uvádí makra nebo proměnné, které můžete použít v dotazu WIQL.

Makro Využití
@Me Pomocí této proměnné můžete automaticky vyhledat alias aktuálního uživatele v poli, které obsahuje aliasy uživatelů. Můžete například najít pracovní položky, které jste otevřeli, pokud nastavíte sloupec Pole na hodnotu Aktivovaný podle, sloupec Operátor na =hodnotu a sloupec Hodnota na @Me.
@CurrentIteration Tato proměnná slouží k automatickému filtrování pracovních položek přiřazených aktuálnímu sprintu pro vybraný tým na základě vybraného kontextu týmu.
@Project Tato proměnná slouží k hledání pracovních položek v aktuálním projektu. Můžete například najít všechny pracovní položky v aktuálním projektu, pokud nastavíte sloupec Pole na Týmový projekt, sloupec Operátor na =hodnotu a sloupec Hodnota na @Project.
@StartOfDay
@StartOfWeek
@StartOfMonth
@StartOfYear		 Pomocí těchto maker můžete filtrovat pole DateTime na základě začátku aktuálního dne, týdne, měsíce, roku nebo posunu na jednu z těchto hodnot. Například všechny položky vytvořené za posledních 3 měsíců můžete najít, pokud nastavíte sloupec Pole na Datum vytvoření, sloupec Operátor na >hodnotu = a sloupec Hodnota @StartOfMonth - 3.
@Today Tato proměnná slouží k hledání pracovních položek, které souvisejí s aktuálním datem nebo dřívějším datem. Proměnnou @Today můžete také upravit odečtením dnů. Například všechny položky aktivované v posledním týdnu můžete najít, pokud nastavíte sloupec Pole na aktivované datum, sloupec Operátor na >hodnotu = a sloupec Hodnota na @Today - 7.
[Libovolná] Tato proměnná slouží k hledání pracovních položek, které se vztahují k libovolné hodnotě definované pro konkrétní pole.

@me Makro

Makro @me nahradí název integrovaného účtu systému Windows uživatele, který spustí dotaz. Následující příklad ukazuje, jak použít makro a ekvivalentní statický příkaz. Makro je určeno pro použití s poli identit, jako Assigned Toje například .

WHERE  
   [System.AssignedTo] = @Me

@today Makro

Makro můžete použít @today s libovolným polem DateTime . Toto makro nahrazuje půlnoc aktuálního data v místním počítači, na kterém se spouští dotaz. Můžete také zadat @today+x nebo @today-y použít celočíselné posuny po x dnech po @today a y před @today, v uvedeném pořadí. Dotaz, který makro používá @today , může v závislosti na časovém pásmu, ve kterém se spouští, vrátit různé sady výsledků.

Následující příklady předpokládají, že dnes je 1.3.19.

WHERE  
   [System.CreatedDate] = @today

Je ekvivalentem:

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

And

WHERE  
   [System.CreatedDate] > @today-2

Je ekvivalentem:

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

@StartOfDay, , @StartOfWeek, @StartOfYear@StartOfMonthmakra

Makra můžete použít @StartOf... s libovolným polem DateTime . Toto makro nahrazuje půlnoc aktuálního dne, začátek týdne, začátek měsíce nebo začátek roku v místním počítači, na kterém se dotaz spouští.

Poznámka:

Vyžaduje Azure DevOps Server 2019 Update 1 nebo novější verzi.

Tato makra přijímají modifikační řetězec, který má formát (+/-)nn(y|M|w|d|h|m). Podobně jako u @Today makra můžete zadat celočíselné posuny plus nebo minus. Pokud kvalifikátor časových jednotek vynecháte, ve výchozím nastavení se nastaví přirozené období funkce. Například trasa @StartOfWeek("+1") je stejná jako @StartOfWeek("+1w"). Pokud je znaménko plus/minus (+/-) vynecháno, předpokládá se plus.

Tato syntaxe umožňuje vnořit modifikátory a vysazení dotazu dvakrát. Klauzule Closed Date >= @StartOfYear - 1například filtruje pracovní položky, které byly uzavřeny od minulého roku. Tím, že Closed Date >= @StartOfYear('+3M') - 1ho upravíte na , vyloučí pracovní položky uzavřené během prvních tří měsíců minulého roku. Syntaxe WIQL je znázorněná v následujícím příkladu.

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

Následující příklady předpokládají, že dnes je 4.5.19.

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

Je ekvivalentem:


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

And

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

Je ekvivalentem:

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

Vlastní makra

TECHNOLOGIE WIQL také podporuje libovolná vlastní makra. Jakýkoli řetězec, který je předponou, @ se považuje za vlastní makro a nahradí se. Hodnota nahrazení vlastního makra se načte z kontextového parametru metody dotazu v objektovém modelu. Následující metoda je rozhraní API používané pro makra:

public WorkItemCollection Query(string wiql, IDictionary context)

Kontextový parametr obsahuje páry klíč-hodnota pro makra. Pokud například kontext obsahuje dvojici klíč-hodnota (projekt, MyProject), @project se nahradí MyProject v jazyce WIQL. Toto nahrazení spočívá v tom, jak tvůrce dotazů pracovních položek zpracovává makro @project v sadě Visual Studio.

Určení historických dotazů (ASOF)

Klauzuli ASOF v dotazu můžete použít k filtrování pracovních položek, které splňují zadané podmínky filtru, jak byly definovány v určitém datu a čase.

Poznámka:

V tvůrci dotazů v sadě Visual Studio nemůžete vytvářet ASOF dotazy. Pokud vytvoříte soubor dotazu (.wiq), který obsahuje ASOF klauzuli, a pak tuto klauzuli načtete v sadě Visual Studio, ASOF bude klauzule ignorována.

Předpokládejme, že pracovní položka byla klasifikována v rámci iterační cestyFabrikam Fiber\Release 1 a přiřazena k Jamal Hartnett před 5. 5. 2022. Pracovní položka byla však nedávno přiřazena k Raisa Pokrovskaya a přesunula se na novou iterační cestu vydané verze 2. Následující příklad dotazu vrátí pracovní položky přiřazené Jamal Hartnett, protože dotaz je založen na stavu pracovních položek od předchozího data a času.

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'

Poznámka:

Pokud není zadán žádný čas, technologie WIQL používá půlnoc. Pokud není zadáno žádné časové pásmo, technologie WIQL použije časové pásmo místního klientského počítače.

Nastavení pořadí řazení (ORDER BY)

Klauzuli můžete použít ORDER BY k seřazení výsledků dotazu podle jednoho nebo více polí ve vzestupném nebo sestupném pořadí.

Poznámka:

Předvolby řazení sql serveru na datové vrstvě určují výchozí pořadí řazení. Pomocí parametrů ascdesc ale můžete zvolit explicitní pořadí řazení.

Následující příklad seřadí pracovní položky jako první podle priority ve vzestupném pořadí (výchozí) a potom podle data vytvoření v sestupném pořadí (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

Chcete-li vrátit propojení mezi pracovními položkami, zadáte FROM WorkItemLinks. Podmínky filtru v WHERE klauzuli se můžou vztahovat na odkazy nebo na jakoukoli pracovní položku, která je zdrojem nebo cílem propojení. Například následující dotaz vrátí odkazy mezi položkami backlogu produktů a aktivními podřízenými položkami.

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)

Následující tabulka shrnuje rozdíly mezi dotazy pracovních položek a dotazy na propojení mezi pracovními položkami.

Klauzule

Pracovní položky

Propojení mezi pracovními položkami

FROM

FROM WorkItems

FROM WorkItemLinks

WHERE

[FieldName] = Value

Specify one or more of the following:
[Source].[FieldName] = Value
[Target].[FieldName] = Value
[System.Links.LinkType] = 'LinkName'

MODE

nejde použít

Zadejte jednu z následujících možností:

  • MODE (MustContain): (Default) Vrátí pouze záznamy WorkItemLinkInfo, kde jsou splněna kritéria zdroje, cíle a propojení.
  • MODE (MayContain): Vrátí záznamy WorkItemLinkInfo pro všechny pracovní položky, které splňují kritéria zdroje a propojení, i když žádná propojená pracovní položka nesplňuje cílová kritéria.
  • MODE (DoesNotContain): Vrátí záznamy WorkItemLinkInfo pro všechny pracovní položky, které vyhovují zdroji, pouze pokud žádná propojená pracovní položka nesplňuje kritéria propojení a cíle.
  • MODE (Recursive): Používá se pro stromové dotazy([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'). Typ odkazu musí být topologie stromové struktury a směr dopředu. Vrátí záznamy WorkItemLinkInfo pro všechny pracovní položky, které vyhovují zdroji, rekurzivně pro cíl. ORDER BY a ASOF nejsou kompatibilní se stromovými dotazy.

RETURNS

WorkItemQueryResult

WorkItemLink

Můžete zadat jeden z následujících názvů typů systémových propojení.

Můžete zadat jeden z názvů typů systémových odkazů, které jsou uvedené níže, nebo vlastní typ odkazu, který jste definovali pomocí místního procesu XML.

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

Další informace naleznete v tématu Odkaz na typ odkazu.

Příklad dotazu typu stromu

Následující dotaz vrátí všechny typy pracovních položek definované v aktuálním projektu. Dotaz, jak je znázorněno v Editor Power Query, jak je znázorněno na následujícím obrázku.

Snímek obrazovky Editor Power Query, stromového dotazu, všech pracovních položek a stavů

Ekvivalentní syntaxe WIQL je znázorněna níže.

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)

Následující dotaz vrátí všechny typy pracovních položek definované v aktuálním projektu. Dotaz, jak je znázorněno v Editor Power Query, jak je znázorněno na následujícím obrázku.

Snímek obrazovky s Editor Power Query, dotazem direct-link, všemi pracovními položkami a stavy

Ekvivalentní syntaxe WIQL je znázorněná.

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)

Další příklady dotazů

Následující typický příklad dotazu WIQL používá názvy odkazů pro pole. Dotaz vybere pracovní položky (není zadaný žádný typ pracovní položky) s hodnotou Priority=1. Dotaz vrátí ID a název návratové sady jako sloupce. Výsledky jsou seřazené podle ID ve vzestupném pořadí.

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

Model data a času

Vzor data a času zadáte podle jednoho ze dvou vzorů:

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

Ukázkové klauzule

Následující ukázkové příkazy zobrazují konkrétní opravňující klauzule.

Klauzule

Příklad

AND

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

OR

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

NOT

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

EVER

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

UNDER

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'

ORDER BY

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]

ASOF (Časový filtr)

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

Řetězcové literály uvozovek (jednoduché nebo dvojité uvozovky jsou podporovány) ve srovnání s řetězcovým nebo prostým textovým polem. Řetězcové literály podporují všechny znaky Unicode.

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

Operátor contains můžete použít k vyhledání podřetězece kdekoli v hodnotě pole.

WHERE [System.Description] contains 'WIQL'

Oblast a iterace (TreePath)

Operátor můžete použít UNDER pro pole Cesta oblasti a iterace. Operátor UNDER vyhodnotí, jestli je hodnota v podstromu konkrétního uzlu klasifikace. Například následující výraz by se vyhodnotil jako true, pokud by cesta k oblasti byla MyProject\Server\Správa istrace, MyProject\Server\Správa istration\Feature 1, MyProject\Server\Správa istration\Feature 2\SubFeature 5 nebo jakýkoli jiný uzel v podstromu.

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

Modifikátory a speciální operátory

Ve výrazu dotazu můžete použít některé modifikátory a speciální operátory.

Pomocí operátoru IN můžete vyhodnotit, jestli je hodnota pole rovna libovolné sadě hodnot. Tento operátor je podporován pro typy polí String, Integer, Double a DateTime. Podívejte se na následující příklad spolu s jeho sémantický ekvivalent.

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

Operátor EVER se používá k vyhodnocení, jestli se hodnota pole rovná nebo se někdy rovná určité hodnotě ve všech předchozích revizích pracovních položek. Typy polí String, Integer, Double a DateTime podporují tento operátor. Operátor má alternativní syntaxe EVER . Například následující fragmenty kódu se dotazují, jestli byly všechny pracovní položky někdy přiřazeny Jamalovi, Raise nebo 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>'
    )