Referens för WIQL-syntax (Work Item Query Language)

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Du kan använda WIQL-syntax för att definiera en fråga som en hyperlänk eller när du använder REST API (Work Item Query Language).

WIQL stöder alla funktioner som är tillgängliga via webbportalens frågeredigerare plus några fler. Du kan ange fälten som ska returneras och logisk gruppering av frågesatser. Du kan också använda en ASOF sats för att filtrera baserat på tilldelningar från och med ett tidigare datum.

Prerequisites

Översikt över frågespråk

WIQL har fem delar, enligt följande syntaxfragment och beskrivs i tabellen. WIQL-syntaxen är inte skiftlägeskänslig.

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

Datum- och tidsmönster

Datum- och tidsmönstret som du anger för DateTime-fälten ska matcha det som du väljer via din profil. Information om hur du visar eller ändrar ditt val finns i Ange användarinställningar.

Citattecken (enkla eller dubbla citattecken stöds) DateTime literaler som används i jämförelser. De måste vara i .NET-format DateTime för den lokala klientdatorn som kör frågan. Om inte en tidszon anges DateTime finns literaler i tidszonen för den lokala datorn.

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

När tiden utelämnas i en DateTime literal och parametern dayPrecision är lika med false antas tiden vara noll (midnatt). Standardinställningen för parametern dayPrecision är false.

Eller så kan du ange ISO 8601-format, vilket är giltigt oavsett språkvariant. ISO 8601 representerar datum och tid genom att börja med året, följt av månad, dag, timme, minuter, sekunder och millisekunder. Representerar till exempel 2025-12-10 15:00:00.000 den 10 december 2025 kl. 15.00 lokal tid. Ett exempel på hur du använder ISO 8601-format är följande:

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

Anpassade fält

Ange filtersatser (WHERE)

Satsen WHERE anger filtervillkoren. Frågan returnerar endast arbetsobjekt som uppfyller de angivna kriterierna. Följande exempel-sats WHERE returnerar till exempel användarberättelser som är aktiva och som har tilldelats dig.

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

Du kan styra i vilken ordning logiska operatorer utvärderas genom att omsluta dem inom parenteser för att gruppera filtervillkoren. Om du till exempel vill returnera arbetsobjekt som antingen har tilldelats dig eller som du har stängt använder du följande exempel.

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

Filtervillkor

Varje filtervillkor består av tre delar, som var och en måste följa följande regler:

• Fält: Du kan ange antingen referensnamnet eller det egna namnet. Följande exempel är giltig WIQL-syntax:
  • Referensnamn: SELECT [System.AssignedTo] ...
  • Eget namn med blanksteg: SELECT [Assigned To] ...
  • Namn utan blanksteg kräver inte hakparenteser: SELECT ID, Title ...
• Operator: Giltiga värden anges i avsnittet Operatorer senare i den här artikeln.
• Fältvärde: Du kan ange något av följande tre värden beroende på vilket fält som anges.
  • Ett literalvärde måste matcha datatypen för fältvärdet.
  • En variabel eller ett makro som anger ett visst värde. Anger till exempel @Me den person som kör frågan. Mer information finns i Makron och variabler.
  • Namnet på ett annat fält. Du kan till exempel använda [Assigned to] = [Changed by] för att hitta arbetsobjekt som har tilldelats till den person som senast ändrade arbetsobjektet.

En beskrivning och referensnamn för alla systemdefinierade fält finns i Index för arbetsobjektfält.

Operators

Frågor använder logiska uttryck för att kvalificera resultatuppsättningar. Dessa logiska uttryck utgörs av en eller flera samtidiga åtgärder.

Några enkla frågeåtgärder är följande:

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

I följande tabell sammanfattas alla operatorer som stöds för olika fälttyper. Mer information om varje fälttyp finns i Fält och attribut för arbetsobjekt.

Operatorerna =, <>, >, <, >=och <= fungerar som förväntat. Till exempel System.ID > 100 frågor för alla arbetsobjekt med fler ID än 100. System.ChangedDate > '01-01-25 12:00:00' frågor för alla arbetsobjekt som ändrats efter kl. 12.00 den 1 januari 2025.

Utöver dessa grundläggande operatorer finns det vissa beteenden och operatorer som är specifika för vissa fälttyper.

Logiska grupper

Du kan använda termerna AND och OR i typisk boolesk mening för att utvärdera två satser. Du kan använda termerna AND EVER och OR EVER när du anger en WAS EVER operator. Du kan gruppera logiska uttryck och ytterligare förena dem efter behov. Följande exempel visar.

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

Du kan negera operatorerna contains, underoch in med hjälp notav . Du kan inte negera operatorn ever . Följande exempel frågar efter alla arbetsobjekt som inte har tilldelats under underträdet Fabrikam Fiber\Account Managementför .

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

Exempelfråga, har någonsin tilldelats till

I följande exempel på frågeredigeraren hittar du alla arbetsobjekt som någonsin har tilldelats Till Jamal Hartnett.

Motsvarande WIQL-syntax är följande:

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

Makron eller variabler

I följande tabell visas de makron eller variabler som du kan använda i en WIQL-fråga.

@me makro

Makrot @me ersätter windowsintegrerade kontonamnet för den användare som kör frågan. I följande exempel visas hur du använder makrot och motsvarande statiska uttryck. Makrot är avsett för användning med identitetsfält som Assigned To.

WHERE  
   [System.AssignedTo] = @Me 

@today makro

Du kan använda makrot @today med valfritt DateTime fält. Det här makrot ersätter midnatt för det aktuella datumet på den lokala dator som kör frågan. Du kan också ange @today+x eller @today-y använda heltalsförskjutningar för x dagar efter @today respektive y dagar före @today. En fråga som använder makrot @today kan returnera olika resultatuppsättningar beroende på vilken tidszon det körs i.

I följande exempel förutsätts att dagens datum är 2025-01-03.

WHERE  
   [System.CreatedDate] = @today

Motsvarar:

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

And

WHERE  
   [System.CreatedDate] > @today-2

Motsvarar:

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

@StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear makron

Du kan använda makrona @StartOf... med valfritt DateTime fält. Det här makrot ersätter midnatt för den aktuella dagen, början av veckan, början av månaden eller början av året på den lokala dator som kör frågan.

Dessa makron accepterar en modifierarsträng som har formatet (+/-)nn(y|M|w|d|h|m). På samma sätt som makrot @Today kan du ange plus- eller minus heltalsförskjutningar. Om tidsenhetskvalificeraren utelämnas används funktionens naturliga period som standard. Är till exempel @StartOfWeek("+1") samma som @StartOfWeek("+1w"). Om plus-/minustecknet (+/-) utelämnas antas plustecknet.

Med den här syntaxen kan du kapsla modifierare och förskjuta frågan två gånger. Satsen Closed Date >= @StartOfYear - 1 filtrerar till exempel arbetsobjekt som stängts sedan förra året. När du ändrar den till Closed Date >= @StartOfYear('+3M') - 1exkluderar den arbetsobjekt som stängts under de första tre månaderna av det senaste året. Följande WIQL-syntax visar:

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

I följande exempel förutsätts att dagens datum är 2025-04-05.

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

Motsvarar:

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

And

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

Motsvarar:

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

Anpassade makron

WIQL stöder också godtyckliga anpassade makron. Alla strängar som föregås av ett @ behandlas som ett anpassat makro och ersätts. Ersättningsvärdet för det anpassade makrot hämtas från kontextparametern för frågemetoden i objektmodellen. Följande metod är det API som används för makron:

public WorkItemCollection Query(string wiql, IDictionary context)

Kontextparametern innehåller nyckel/värde-par för makron. Om kontexten till exempel innehåller ett nyckel/värde-par av (project, MyProject), ersätts du @project av MyProject i WIQL. Den här ersättningen är hur frågeverktyget för arbetsobjekt hanterar makrot @project i Visual Studio.

Ange historiska frågor (ASOF)

Du kan använda en ASOF sats i en fråga för att filtrera efter arbetsobjekt som uppfyller de angivna filtervillkoren som de definierades vid ett visst datum och en viss tid.

Anta att ett arbetsobjekt klassificerades under en Iteration Path av Fabrikam Fiber\Release 1 och tilldelades till "Jamal Hartnett" före 2025-05-05. Arbetsobjektet tilldelades dock nyligen till "Raisa Pokrovskaya" och flyttades till en ny iterationssökväg i version 2. Följande exempelfråga returnerar arbetsobjekt som tilldelats Jamal Hartnett eftersom frågan baseras på tillståndet för arbetsobjekt från och med ett tidigare datum och en tidigare tid.

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-2025 00:00:00.0000000'

Ange sorteringsordningen (ORDER BY)

Du kan använda ORDER BY -satsen för att sortera resultatet av en fråga efter ett eller flera fält i stigande eller fallande ordning.

I följande exempel sorteras Priority arbetsobjekt först i stigande ordning (standard) och sedan Created Date i fallande ordning (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

Fråga efter länkar mellan arbetsobjekt

Om du vill returnera länkar mellan arbetsobjekt anger du FROM WorkItemLinks. Filtervillkor i WHERE -satsen kan gälla för länkarna eller för alla arbetsobjekt som är källan eller målet för en länk. I följande exempel returneras länkarna mellan Product Backlog Items och deras aktiva underordnade objekt.

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'
    )
MODE (Recursive)

I följande tabell sammanfattas skillnaderna mellan arbetsobjektsfrågor och frågor för länkar mellan arbetsobjekt.

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

Mer information finns i Referens för länktyp.

Frågeexempel för trädtyp

Följande fråga returnerar alla typer av arbetsobjekt som definierats i det aktuella projektet. Frågeredigeraren visar frågan enligt följande bild.

Motsvarande WIQL-syntax är följande:

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)

Exempel på direktlänksfrågor

I följande exempel returneras alla typer av arbetsobjekt som definierats i det aktuella projektet. Frågeredigeraren visar frågan enligt följande bild.

Motsvarande WIQL-syntax är följande:

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)

Fler frågeexempel

I följande typiska WIQL-frågeexempel används referensnamn för fälten. Frågan väljer arbetsobjekt (ingen angiven arbetsobjekttyp) med en Priority=1. Frågan returnerar returuppsättningen ID och Title som kolumner. Resultaten sorteras efter ID i stigande ordning.

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

Datum-tid-mönster

Du anger datum-tid-mönstret enligt ett av två mönster:

• Formatet Datummönster och tidsmönster kommer från dina användarinställningar, tid och nationella inställningar
• Mönstret som anges av UTC, som följer det här mönstret (med Z tillagt till datum-tid).

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

Exempelsatser

Följande exempelinstruktioner visar specifika kvalificerande satser.

Sträng och oformaterad text

Citatsträngliteraler (enkla eller dubbla citattecken stöds) i en jämförelse med ett eller String ett PlainText fält. Strängliteraler stöder alla Unicode-tecken.

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

Du kan använda operatorn contains för att söka efter en delsträng var som helst i fältvärdet.

WHERE [System.Description] contains 'WIQL'

Område och iteration (TreePath)

Du kan använda operatorn UNDER för fälten Area Path och Iteration Path . Operatorn UNDER utvärderar om ett värde ligger inom underträdet för en specifik klassificeringsnod. Till exempel utvärderas följande uttryck till sant om Area Path var MyProject\Server\Administration, MyProject\Server\Administration\Feature 1, MyProject\Server\Administration\Feature 2\SubFeature 5eller någon annan nod i underträdet.

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

Modifierare och särskilda operatorer

Du kan använda vissa modifierare och särskilda operatorer i ett frågeuttryck.

Använd operatorn IN för att utvärdera om ett fältvärde är lika med någon av en uppsättning värden. Den här operatorn stöds för fälttyperna String, Integer, Doubleoch DateTime . Följande exempel och dess semantiska motsvarighet visar detta.

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

Operatorn EVER används för att utvärdera om ett fältvärde är lika med eller någonsin motsvarar ett visst värde under alla tidigare revisioner av arbetsobjekt. Fälttyperna String, Integer, Doubleoch DateTime stöder den här operatorn. Det finns alternativa syntaxer för operatorn EVER . Följande kodfragment frågar till exempel om alla arbetsobjekt någonsin har tilldelats Jamal, Raisa eller 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>'
    )

Använda Copilot för att skriva, åtgärda och optimera WIQL

Du kan använda en AI-assistent (till exempel GitHub Copilot eller andra andrepiloter) för att skapa, korrigera eller optimera WIQL-frågor. Behandla Copilot som ett produktivitetsstöd – inte en auktoritativ källa – och granska och testa alltid alla genererade frågor innan du kör den mot produktionsdata.

Vägledning och metodtips:

• Funktioner: Copilot kan översätta oformaterade krav till WIQL, åtgärda syntaxfel (omatchade hakparenteser, kommatecken som saknas, felaktiga nyckelord), konvertera SELECT-listor mellan egna namn och referensnamn, generera ASOF satser eller datumliteraler och föreslå omskrivningar av satser för att begränsa eller bredda resultatuppsättningar.
• Verifiera: Verifiera alltid genererad WIQL i frågeredigeraren eller ett säkert testprojekt. Kontrollera makron (till exempel @Me, @Today) och språkberoende datumformat före användning.
• Säkerhet: Klistra aldrig in hemligheter, åtkomsttoken eller privata anslutningssträngar i prompter. Ta bort eller redigera eventuella känsliga värden i exempel som du matar till Copilot.
• Prestanda: Be Copilot att minimera resultatnyttolaster (returnera endast nödvändiga fält), lägga till lämpliga WHERE-filter och undvika alltför bred användning av IN eller obundna LIKE sökningar. Kom ihåg gränsen på 32 K tecken för WIQL-frågor.
• Granska gränsfall: Bekräfta beteendet för historiska (ASOF) frågor, träd-/länkfrågor (FROM workItemLinks) och WAS EVER/EVER operatorer som genomsöker revisioner – dessa kan vara mer komplexa och kan behöva manuell justering.

Exempel – Generera WIQL från vanlig engelska:

Fråga: "Return ID and Title for active Bugs assigned to in project 'Fabrikam' and modified in the last 30 days (Returnera ID och Rubrik för aktiva buggar som tilldelats till @Me i projektet Fabrikam" och som ändrats under de senaste 30 dagarna. Sortera efter ChangedDate desc."

Copilot producerar:

SELECT [System.Id], [System.Title]
FROM workitems
WHERE
  [System.TeamProject] = 'Fabrikam'
  AND [System.WorkItemType] = 'Bug'
  AND [System.State] = 'Active'
  AND [System.AssignedTo] = @Me
  AND [System.ChangedDate] >= @Today - 30
ORDER BY [System.ChangedDate] DESC

Automatisera WIQL-frågor med REST API och AI

Du kan använda AI-assistenter, till exempel Copilot, för att automatisera den tvåstegs WIQL REST API-processen:

1. Använd REST-API:et Query By Wiql för att hämta arbetsobjekts-ID:n som matchar din WIQL.
2. Använd API:et Hämta arbetsobjekt för att hämta fullständig information för dessa ID:n.

AI kan hjälpa dig:

• Generera WIQL från vanligt språk och länka sedan de två API-anropen i kod (till exempel Python, PowerShell eller JavaScript).
• Formatera och sammanfatta resultat för instrumentpaneler eller rapporter.

Exempel: Automatisera WIQL med Python och AI

Anta att du vill visa en lista över rubriker och tillstånd för alla aktiva buggar i ett projekt.

Fråga till Copilot:
"Skriv Python-kod som använder Rest-API:et för Azure DevOps för att visa rubriker och tillstånd för alla aktiva buggar i mitt projekt. Använd WIQL för att hämta ID:erna och hämta sedan information om dessa ID:er."

Du kan använda Copilot för att generera kod så här:

import requests

# Azure DevOps organization and project info
org = "your-org"
project = "your-project"
pat = "your-personal-access-token"
headers = {"Authorization": f"Basic {pat}"}

# Step 1: Run WIQL query to get work item IDs
wiql = {
    "query": """
        SELECT [System.Id]
        FROM workitems
        WHERE [System.TeamProject] = '{project}'
          AND [System.WorkItemType] = 'Bug'
          AND [System.State] = 'Active'
    """.format(project=project)
}
wiql_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/wiql?api-version=6.1-preview.2"
resp = requests.post(wiql_url, json=wiql, headers=headers)
ids = [item["id"] for item in resp.json()["workItems"]]

# Step 2: Get work item details
if ids:
    ids_str = ",".join(map(str, ids))
    details_url = f"https://dev.azure.com/{org}/{project}/_apis/wit/workitemsbatch?api-version=6.1-preview.1"
    body = {"ids": ids, "fields": ["System.Title", "System.State"]}
    details_resp = requests.post(details_url, json=body, headers=headers)
    for item in details_resp.json()["value"]:
        print(f"{item['fields']['System.Title']} - {item['fields']['System.State']}")
else:
    print("No active bugs found.")

Relaterat innehåll

• Fråga efter Wiql (REST API)
• Hämta arbetsobjekt (REST API)
• Snabbreferens för sökfrågor
• Fält och attribut för arbetsobjekt
• Referens för länktyp
• Behörigheter och grupper
• Ange dina inställningar