Bagikan melalui

Referensi sintaksis Work Item Query Language (WIQL)

  • Artikel

Layanan Azure DevOps | Azure DevOps Server 2022 - Azure DevOps Server 2019

Anda bisa menggunakan sintaks WIQL untuk menentukan kueri sebagai hyperlink atau saat menggunakan Bahasa Kueri Item Kerja (REST API).

Sintaks WIQL mendukung semua fungsi yang tersedia melalui portal web Editor Kueri ditambah beberapa lagi. Anda dapat menentukan bidang yang akan dikembalikan dan menentukan pengelompokan logis klausa kueri. Selain itu, Anda dapat menggunakan klausul ASOF untuk memfilter berdasarkan penugasan berdasarkan tanggal sebelumnya.

Penting

Sintaks WIQL digunakan untuk menjalankan Query By Wiql REST API. Saat ini, tidak ada cara untuk memanggil API untuk mengembalikan informasi item kerja terperinci dari kueri WIQL secara langsung. Tidak peduli bidang mana yang Anda sertakan dalam pernyataan SELECT, API hanya mengembalikan ID item kerja. Untuk mendapatkan informasi lengkap, Anda perlu melakukan dua langkah: (1) mendapatkan ID item kerja dari WIQL, dan (2) mendapatkan item kerja melalui Dapatkan daftar item kerja berdasarkan ID dan untuk bidang tertentu.

Prasyarat

Kueri hanya mengembalikan item kerja yang Anda miliki izin Tampilkan item kerja atau Tampilkan item kerja dalam simpul ini. Biasanya, izin ini diberikan kepada anggota grup Pembaca dan Kontributor untuk setiap proyek tim. Untuk informasi selengkapnya, lihat Izin dan grup.

Gambaran umum bahasa kueri

Bahasa kueri item kerja memiliki lima bagian yang diperlihatkan dalam cuplikan sintaks berikut dan dijelaskan dalam tabel berikut. Sintaks WIQL tidak peka huruf besar/kecil.

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

Dengan menginstal ekstensi Marketplace Editor Wiql, Anda dapat membuat kueri menggunakan Editor Kueri lalu melihat sintaks WIQL. Anda kemudian dapat menyalin dan memodifikasi sintaks WIQL dan menjalankan kueri menggunakan hub Wiql Playground yang ditambahkan ke Papan.

Klausul

Contoh

SELECT

Mengidentifikasi bidang yang akan dikembalikan untuk setiap item kerja yang dikembalikan oleh kueri. Anda dapat menentukan nama yang mudah diingat atau nama referensi. Gunakan kurung siku ([]) jika nama berisi kosong atau titik.

FROM

Menunjukkan apakah Anda ingin kueri menemukan item kerja atau tautan di antara item kerja.

  • Gunakan FROM WorkItems untuk mengembalikan item kerja.
  • Gunakan FROM workItemLinks untuk mengembalikan tautan antar item kerja. Untuk informasi selengkapnya, lihat Kueri untuk tautan antar item kerja nanti di artikel ini.

WHERE

Menentukan kriteria filter untuk kueri. Untuk informasi selengkapnya, lihat Kondisi filter (WHERE) nanti di artikel ini.

ORDER BY

Menentukan urutan pengurutan item kerja yang dikembalikan. Anda dapat menentukan Naik (Asc) atau Turun (Turun) untuk satu atau beberapa bidang. Contohnya:
ORDER BY [State] Asc, [Changed Date] Desc

ASOF

Menentukan kueri historis dengan menunjukkan tanggal kapan filter akan diterapkan. Misalnya, kueri ini mengembalikan semua cerita pengguna yang didefinisikan sebagai Aktif pada 11 Februari 2020. Tentukan tanggal sesuai dengan panduan yang disediakan dalam pola Tanggal dan waktu. ASOF '02-11-2020'

Catatan

Panjang kueri WIQL yang dibuat terhadap Azure Boards tidak boleh melebihi 32K karakter. Sistem tidak akan mengizinkan Anda membuat atau menjalankan kueri yang melebihi panjang tersebut.

Pola tanggal dan waktu

Pola tanggal dan waktu yang Anda masukkan untuk bidang DateTime harus cocok dengan yang Anda pilih melalui profil Anda. Untuk melihat atau mengubah pilihan Anda, lihat Mengatur preferensi pengguna untuk Waktu dan Lokal.

Cuplikan layar yang memperlihatkan opsi dropdown Pola Tanggal pada panel Waktu dan Lokal.Cuplikan layar yang memperlihatkan opsi dropdown Pola Waktu pada panel Waktu dan Lokal.

Cuplikan layar yang memperlihatkan panel Waktu dan Lokal dengan pola Tanggal dan bidang pola Waktu.

Kuotasi (tanda kutip tunggal atau ganda didukung) Literal DateTime yang digunakan sebagai perbandingan. Mereka harus dalam format DateTime .NET dari komputer klien lokal yang menjalankan kueri. Kecuali zona waktu ditentukan, literal DateTime berada di zona waktu komputer lokal.

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

Ketika waktu dihilangkan dalam literal DateTime dan parameter dayPrecision sama dengan false, waktu diasumsikan nol (tengah malam). Pengaturan default untuk parameter dayPrecision adalah false.

Atau, Anda dapat menentukan format ISO 8601 yang valid apa pun lokalnya. ISO 8601 mewakili tanggal dan waktu dengan dimulai dengan tahun, diikuti oleh bulan, hari, jam, menit, detik, dan milidetik. Misalnya, 2021-12-10 15:00:00.000, mewakili tanggal 10 Desember 2021 pukul 15.00 di waktu setempat. Contoh penggunaan format ISO 8601 adalah sebagai berikut.

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

Bidang isian kustom

Anda bisa menambahkan bidang kustom ke klausa kueri. Dengan WIQL, Anda harus menentukan nama referensi untuk bidang kustom. Untuk proyek yang menggunakan model proses Yang Diwariskan, bidang kustom biasanya diberi label Kustom. diawali dengan namanya, dan spasi dihapus. Contohnya:

Nama yang mudah diingat Nama referensi
Pemberi Izin Custom.Approver
Jenis permintaan Custom.RequestType
Perkiraan Cakupan Custom.CustomEstimate

Untuk proyek yang menggunakan model proses XML lokal, nama referensinya seperti yang didefinisikan oleh definisi jenis item kerja XML.

Untuk informasi selengkapnya, lihat Bidang dan atribut item kerja.

Tentukan klausa filter (WHERE)

Klausa WHERE menentukan kriteria filter. Kueri hanya mengembalikan item kerja yang memenuhi kriteria yang ditentukan. Misalnya, contoh WHERE klausa berikut mengembalikan cerita pengguna yang aktif dan yang ditetapkan untuk Anda.

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

Anda dapat mengontrol urutan di mana operator logis dievaluasi dengan menyertakannya dalam tanda kurung untuk mengelompokkan kriteria filter. Misalnya, untuk mengembalikan item kerja yang ditetapkan untuk Anda atau yang Anda tutup, ubah filter kueri agar sesuai dengan contoh berikut.

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

Kondisi filter

Setiap kondisi filter terdiri dari tiga bagian, yang masing-masing harus sesuai dengan aturan berikut:

  • Bidang: Anda dapat menentukan nama referensi atau nama yang mudah diingat. Contoh berikut adalah sintaks WIQL yang valid:
    • Nama referensi: SELECT [System.AssignedTo] ...
    • Nama yang mudah diingat dengan spasi: SELECT [Assigned To] ...
    • Nama tanpa spasi tidak memerlukan tanda kurung siku: SELECT ID, Title ...
  • Operator: Nilai yang valid ditentukan di bagian Operator nanti di artikel ini.
  • Nilai bidang: Anda dapat menentukan salah satu dari tiga nilai berikut tergantung pada bidang yang ditentukan.
    • Nilai harfiah harus cocok dengan jenis data nilai bidang.
    • *variabel atau makro yang menunjukkan nilai tertentu. Misalnya, @Me menunjukkan orang yang menjalankan kueri. Untuk informasi selengkapnya, lihat Makro dan variabel nanti di artikel ini.
    • Nama bidang lain. Misalnya, Anda dapat menggunakan [Assigned to] = [Changed by] untuk menemukan item kerja yang ditetapkan ke orang yang paling baru mengubah item kerja.

Untuk deskripsi dan nama referensi semua bidang yang ditentukan sistem, lihat Indeks bidang item kerja.

Operator

Kueri menggunakan ekspresi logis untuk memenuhi syarat tataan hasil. Ekspresi logis ini dibentuk oleh satu atau beberapa operasi bersamaan.

Beberapa operasi kueri sederhana tercantum di bawah ini.

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

Tabel di bawah ini meringkas semua operator yang didukung untuk berbagai jenis bidang. Untuk informasi selengkapnya tentang setiap jenis bidang, lihat Bidang dan atribut item kerja.

Operator =, <>, >, <, >=, and <= berfungsi seperti yang diharapkan. Misalnya, System.ID > 100 kueri untuk semua item kerja dengan ID yang lebih besar dari 100. System.ChangedDate > '01-01-19 12:00:00' kueri untuk semua item kerja diubah setelah siang 1 Januari 2019.

Di luar operator dasar ini, ada beberapa perilaku dan operator khusus untuk jenis bidang tertentu.

Catatan

Operator yang tersedia untuk Anda bergantung pada platform dan versi Anda. Untuk informasi selengkapnya, lihat Referensi cepat kueri.

Jenis bidang

Operator yang didukung

Boolean

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

DateTime

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

Ganda, GUID, Bilangan Bulat

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

Identitas

= , <> , > , < , >= , <= , =[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

Pengelompokan logis

Anda dapat menggunakan istilah AND dan OR dalam arti khas Boolean untuk mengevaluasi dua klausul. Anda dapat menggunakan istilah AND EVER dan OR EVER saat menentukan WAS EVER operator. Anda dapat mengelompokkan ekspresi logis dan selanjutnya menggabungkannya, sesuai kebutuhan. Contohnya ditunjukkan di bawah ini.

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

Anda dapat meniadakan contains, under, operator dan in dengan menggunakan not. Anda tidak dapat meniadakan ever operator. Contoh di bawah ini mengkueri untuk semua item kerja yang tidak ditetapkan di bawah subtree Fabrikam Fiber\Account Management.

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

Contoh kueri, pernah ditetapkan ke

Contoh Editor Kueri berikut menemukan semua item kerja yang pernah ditetapkan ke Jamal Hartnett.

Cuplikan layar Editor Kueri, kueri daftar datar, pernah ditetapkan.

Dan, berikut adalah sintaks WIQL yang sesuai.

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

Makro atau variabel

Tabel berikut mencantumkan makro atau variabel yang bisa Anda gunakan dalam kueri WIQL.

Makro Penggunaan
@Me Gunakan variabel ini untuk mencari alias pengguna saat ini secara otomatis di bidang yang berisi alias pengguna. Misalnya, Anda dapat menemukan item kerja yang Anda buka jika Anda mengatur kolom Bidang ke Diaktifkan Oleh, kolom Operator ke =, dan kolom Nilai ke @Me.
@CurrentIteration Gunakan variabel ini untuk memfilter item kerja yang ditetapkan secara otomatis ke sprint saat ini untuk tim yang dipilih berdasarkan konteks tim yang dipilih.
@Project Gunakan variabel ini untuk mencari item kerja dalam proyek saat ini. Misalnya, Anda dapat menemukan semua item kerja dalam proyek saat ini jika Anda mengatur kolom Bidang ke Proyek Tim, kolom Operator ke =, dan kolom Nilai ke @Project.
@StartOfDay
@StartOfWeek
@StartOfMonth
@StartOfYear		 Gunakan makro ini untuk memfilter bidang DateTime berdasarkan awal hari, minggu, bulan, tahun, atau offset saat ini ke salah satu nilai ini. Misalnya, Anda dapat menemukan semua item yang dibuat dalam 3 bulan terakhir jika Anda mengatur kolom Bidang ke Tanggal Dibuat, kolom Operator ke >=, dan kolom Nilai ke @StartOfMonth - 3.
@Today Gunakan variabel ini untuk mencari item kerja yang terkait dengan tanggal saat ini atau ke tanggal sebelumnya. Anda juga dapat mengubah variabel @Today dengan mengurangi hari. Misalnya, Anda dapat menemukan semua item yang diaktifkan dalam seminggu terakhir jika Anda mengatur kolom Bidang ke Tanggal Diaktifkan, kolom Operator ke >=, dan kolom Nilai ke @Today - 7.
[Apa saja] Gunakan variabel ini untuk mencari item kerja yang terkait dengan nilai apa pun yang ditentukan untuk bidang tertentu.

@me makro

@me Makro menggantikan nama akun Windows Integrated pengguna yang menjalankan kueri. Contoh di bawah ini menunjukkan cara menggunakan makro dan pernyataan statis yang setara. Makro ditujukan untuk digunakan dengan bidang identitas seperti Assigned To.

WHERE  
   [System.AssignedTo] = @Me

@today makro

Anda dapat menggunakan @today makro dengan bidang DateTime apa pun. Makro ini menggantikan tengah malam tanggal saat ini pada komputer lokal yang menjalankan kueri. Anda juga dapat menentukan @today+x atau @today-y menggunakan offset bilangan bulat untuk x hari setelah @today dan y hari sebelum @today, masing-masing. Kueri yang menggunakan @today makro dapat mengembalikan tataan hasil yang berbeda tergantung pada zona waktu yang dijalankannya.

Contoh di bawah ini mengasumsikan bahwa hari ini adalah 1/3/19.

WHERE  
   [System.CreatedDate] = @today

Setara dengan:

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

Dan

WHERE  
   [System.CreatedDate] > @today-2

Setara dengan:

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

@StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear makro

Anda dapat menggunakan @StartOf... makro dengan bidang DateTime apa pun. Makro ini menggantikan tengah malam hari saat ini, awal minggu, awal bulan, atau awal tahun di komputer lokal yang menjalankan kueri.

Catatan

Memerlukan Azure DevOps Server 2019 Update 1 atau versi yang lebih baru.

Makro ini menerima string pengubah yang memiliki format (+/-)nn(y|M|w|d|h|m). Mirip @Today dengan makro, Anda dapat menentukan offset bilangan bulat plus atau minus. Jika kualifikasi unit waktu dihilangkan, maka default ke periode alami fungsi. Misalnya, @StartOfWeek("+1") sama dengan @StartOfWeek("+1w"). Jika tanda plus/minus (+/-) dihilangkan, plus diasumsikan.

Sintaks ini memungkinkan Anda untuk menumpuk pengubah dan mengimbangi kueri Anda dua kali. Misalnya, klausa Closed Date >= @StartOfYear - 1, memfilter item kerja yang telah ditutup sejak tahun lalu. Dengan memodifikasinya menjadi Closed Date >= @StartOfYear('+3M') - 1, item kerja tidak termasuk item kerja yang ditutup dalam tiga bulan pertama tahun lalu. Sintaks WIQL seperti yang ditunjukkan dalam contoh berikut.

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

Contoh berikut mengasumsikan bahwa hari ini adalah 4/5/19.

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

Setara dengan:


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

Dan

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

Setara dengan:

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

Makro kustom

WIQL juga mendukung makro kustom arbitrer. Setiap string yang @ diawali oleh diperlakukan sebagai makro kustom dan diganti. Nilai penggantian untuk makro kustom diambil dari parameter konteks metode kueri dalam model objek. Metode berikut adalah API yang digunakan untuk makro:

public WorkItemCollection Query(string wiql, IDictionary context)

Parameter konteks berisi pasangan kunci-nilai untuk makro. Misalnya, jika konteks berisi pasangan kunci-nilai (proyek, MyProject), maka @project digantikan oleh MyProject di WIQL. Penggantian ini adalah cara penyusun kueri item kerja menangani makro @project di Visual Studio.

Tentukan kueri historis (ASOF)

Anda bisa menggunakan ASOF klausa dalam kueri untuk memfilter item kerja yang memenuhi kondisi filter yang ditentukan saat ditentukan pada tanggal dan waktu tertentu.

Catatan

Anda tidak dapat membuat ASOF kueri di penyusun kueri di Visual Studio. Jika Anda membuat file kueri (.wiq) yang menyertakan ASOF klausa, lalu memuatnya di Visual Studio, ASOF klausa diabaikan.

Misalkan item kerja diklasifikasikan di bawah Jalur Fabrikam Fiber\Release 1 Iterasi dan ditetapkan ke 'Jamal Hartnett' sebelum 5/05/2022. Namun, item kerja baru-baru ini ditetapkan ke 'Raisa Pokrovskaya' dan pindah ke jalur iterasi baru Rilis 2. Contoh kueri berikut mengembalikan item kerja yang ditetapkan ke Jamal Hartnett karena kueri didasarkan pada status item kerja pada tanggal dan waktu sebelumnya.

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'

Catatan

Jika tidak ada waktu yang ditentukan, WIQL menggunakan tengah malam. Jika tidak ada zona waktu yang ditentukan, WIQL menggunakan zona waktu komputer klien lokal.

Mengatur urutan pengurutan (ORDER BY)

Anda bisa menggunakan ORDER BY klausa untuk mengurutkan hasil kueri menurut satu atau beberapa bidang dalam urutan naik atau turun.

Catatan

Preferensi pengurutan server SQL pada tingkat data menentukan urutan pengurutan default. Namun, Anda dapat menggunakan asc parameter atau desc untuk memilih urutan pengurutan eksplisit.

Contoh berikut mengurutkan item kerja terlebih dahulu menurut Prioritas dalam urutan naik (default), lalu berdasarkan Tanggal Dibuat dalam urutan menurut (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

Untuk mengembalikan tautan antar item kerja, Anda menentukan FROM WorkItemLinks. Kondisi filter dalam WHERE klausa mungkin berlaku untuk tautan atau ke item kerja apa pun yang merupakan sumber atau target tautan. Misalnya, kueri berikut mengembalikan tautan antara Item Backlog Produk dan item anak aktifnya.

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)

Tabel berikut ini meringkas perbedaan antara kueri item kerja dan kueri untuk tautan antar item kerja.

Klausul

Item kerja

Tautan antar item kerja

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

tidak berlaku

Tentukan salah satu hal berikut ini:

  • MODE (MustContain): (Default) Hanya mengembalikan rekaman WorkItemLinkInfo di mana kriteria sumber, target, dan tautan semuanya terpenuhi.
  • MODE (MayContain): Mengembalikan rekaman WorkItemLinkInfo untuk semua item kerja yang memenuhi kriteria sumber dan tautan, meskipun tidak ada item kerja tertaut yang memenuhi kriteria target.
  • MODE (DoesNotContain): Mengembalikan rekaman WorkItemLinkInfo untuk semua item kerja yang memenuhi sumbernya, hanya jika tidak ada item kerja tertaut yang memenuhi kriteria tautan dan target.
  • MODE (Recursive): Gunakan untuk Kueri pohon([System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'). Jenis tautan harus topologi Pohon dan arah ke depan. Mengembalikan rekaman WorkItemLinkInfo untuk semua item kerja yang memenuhi sumber, secara rekursif untuk target. ORDER BY dan ASOF tidak kompatibel dengan kueri pohon.

RETURNS

WorkItemQueryResult

WorkItemLink

Anda dapat menentukan salah satu nama jenis tautan sistem berikut.

Anda dapat menentukan salah satu nama jenis tautan sistem, yang tercantum di bawah ini, atau jenis tautan kustom yang telah Anda tentukan dengan proses XML lokal.

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

Untuk informasi selengkapnya, lihat Referensi jenis tautan.

Contoh kueri jenis pohon

Kueri berikut mengembalikan semua tipe item kerja yang ditentukan dalam proyek saat ini. Kueri seperti yang diperlihatkan dalam Editor Kueri muncul seperti yang diperlihatkan dalam gambar berikut.

Cuplikan layar Editor Kueri, kueri pohon, semua item dan status kerja.

Sintaks WIQL yang setara ditunjukkan di bawah ini.

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)

Kueri berikut mengembalikan semua tipe item kerja yang ditentukan dalam proyek saat ini. Kueri seperti yang diperlihatkan dalam Editor Kueri muncul seperti yang diperlihatkan dalam gambar berikut.

Cuplikan layar Editor Kueri, kueri tautan langsung, semua item kerja dan status.

Sintaks WIQL yang setara seperti yang ditunjukkan.

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)

Contoh kueri lainnya

Contoh kueri WIQL umum berikut menggunakan nama referensi untuk bidang. Kueri memilih item kerja (tidak ada tipe item kerja yang ditentukan) dengan Priority=1. Kueri mengembalikan ID dan Judul kumpulan pengembalian sebagai kolom. Hasilnya diurutkan menurut ID dalam urutan naik.

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

Pola tanggal-waktu

Anda menentukan pola tanggal-waktu sesuai dengan salah satu dari dua pola:

  • Format Pola Tanggal dan Pola Waktu berasal dari preferensi pengguna, Waktu, dan Lokal Anda
  • Pola yang ditentukan oleh UTC, yang mengikuti pola ini (dengan Z ditambahkan ke tanggal-waktu).

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

Contoh klausa

Contoh pernyataan berikut menunjukkan klausul kualifikasi tertentu.

Klausul

Contoh

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 (Filter waktu)

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

Literal string kutipan (tanda kutip tunggal atau ganda didukung) dalam perbandingan dengan string atau bidang teks biasa. Literal string mendukung semua karakter Unicode.

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

Anda dapat menggunakan operator berisi untuk mencari substring di mana saja dalam nilai bidang.

WHERE [System.Description] contains 'WIQL'

Area dan Iterasi (TreePath)

Anda dapat menggunakan UNDER operator untuk bidang Area dan Jalur Iterasi. Operator UNDER mengevaluasi apakah nilai berada dalam subtree dari node klasifikasi tertentu. Misalnya, ekspresi di bawah ini akan mengevaluasi ke true jika Jalur Area adalah 'MyProject\Server\Administration', 'MyProject\Server\Administration\Feature 1', 'MyProject\Server\Administration\Feature 2\SubFeature 5', atau node lain dalam subtree.

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

Pengubah dan operator khusus

Anda dapat menggunakan beberapa pengubah dan operator khusus dalam ekspresi kueri.

IN Gunakan operator untuk mengevaluasi apakah nilai bidang sama dengan salah satu set nilai. Operator ini didukung untuk jenis bidang String, Bilangan Bulat, Ganda, dan DateTime. Lihat contoh berikut bersama dengan setara semantiknya.

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

Operator EVER digunakan untuk mengevaluasi apakah nilai bidang sama atau pernah sama dengan nilai tertentu di semua revisi item kerja sebelumnya. Jenis bidang String, Bilangan Bulat, Ganda, dan DateTime mendukung operator ini. Ada sintaks alternatif untuk EVER operator. Misalnya, cuplikan di bawah kueri apakah semua item kerja pernah ditetapkan ke Jamal, Raise, atau 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>'
    )