Campos, operadores e macros de consulta

Serviços Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Dica

Fazendo uma consulta pela primeira vez? Comece com Defina uma consulta para instruções passo a passo ou Referência rápida de consultas para exemplos.

Use este guia de referência para pesquisar tipos de dados de campo, operadores de consulta, macros e variáveis ao criar consultas no Editor de Consultas. Todos os operadores e macros têm suporte no Azure Boards; alguns se aplicam apenas a versões Azure DevOps Server específicas.

Para obter exemplos rápidos e tarefas do editor, consulte Consulta de referência rápida e Gerenciar e organizar consultas.

Pré-requisitos

Categoria Requisitos
Membro do projeto Você deve ser adicionado como membro do projeto.
Níveis de Acesso – Para exibir e executar consultas compartilhadas: você deve ser um membro Project.
- Para adicionar e salvar uma consulta compartilhada: você deve ter pelo menos acesso Básico.
Permissões Verifique se a permissão Contribuir está definida como Permitir para a pasta em que você deseja adicionar uma consulta. Talvez sua organização precise configurar manualmente o grupo Colaboradores para conceder essa permissão.

Observação

Você precisa de um nível de acesso suficiente e permissão do Contribute para salvar consultas compartilhadas. O acesso básico não é suficiente.

Categoria Requisitos
Membro do projeto Você deve ser adicionado como membro do projeto.
Níveis de Acesso – Para exibir e executar consultas compartilhadas: você deve ser um membro Project.
- Para adicionar e salvar uma consulta compartilhada: você deve ter pelo menos acesso Básico.
Permissões Verifique se a permissão Contribuir está definida como Permitir para a pasta em que você deseja adicionar uma consulta. Talvez sua organização precise configurar manualmente o grupo Colaboradores para conceder essa permissão.

Observação

Você precisa de um nível de acesso suficiente e permissão do Contribute para salvar consultas compartilhadas. O acesso básico não é suficiente.

Valores e tipos de dados do campo de consulta

Especifique um valor que corresponda ao tipo de dados de um campo. A tabela a seguir lista os tipos de dados com suporte:

Observação

Para Azure Boards (nuvem), o tipo de dados corresponde ao campo mostrado na página Process > Fields. Para implantações locais, o tipo de dados corresponde ao type atributo em uma FIELD definição. Consulte os campos de item de trabalho e os atributos de campo para obter detalhes.

Tipo de dados Description
Booleano Armazena um valor Verdadeiro/Falso.
DateTime ou Date/Time Use uma variável de data (por exemplo, @Today ou @Today-1) ou uma data explícita como 01/01/2025. Insira as datas no formato definido em seu perfil. Para obter exemplos de consulta, consulte Query by date or @CurrentIteration. Para consultas WIQL, você também pode especificar datas em UTC. Consulte sintaxe para a linguagem de consulta de item de trabalho (WIQL).
Double ou Decimal Armazena um número real, como 0.2 ou 3.5. Consulte Consulta por campos numéricos para obter exemplos.
GUID Armazena uma cadeia de caracteres de identificador exclusiva.
Histórico Campo formatado personalizado usado para informações históricas (o campo Histórico ). Quando a pesquisa de texto completo está disponível, esse campo é indexado para consultas de texto completo. Consulte Histórico e auditoria.
HTML Armazena texto formatado, como Etapas de Descrição ou Reprodução. Quando a pesquisa de texto completo está disponível, esses campos são indexados. Para consultar campos de rich text, consulte Consultar por títulos, IDs e campos de rich text.
Identidade Armazena uma cadeia de caracteres de texto curta que identifica uma identidade de usuário.
Inteiro Armazena um inteiro com sinal de 32 bits, como 0, 1, 2 ou 34.
PlainText ou Campo de texto (várias linhas) Armazena valores de texto longos, como Informações de Início do Aplicativo. Esses campos são indexados para pesquisa de texto completo quando é suportado. Consulte Consulta por títulos, IDs e campos de rich-text.
picklistDouble Campo personalizado que contém uma lista de seleção de valores decimais.
picklistInteger Campo personalizado que contém uma lista de seleção de valores inteiros.
picklistString Campo personalizado que contém uma lista de seleção de valores de texto curto (255 caracteres ou menos).
Cadeia de caracteres ou Campo de texto (linha única) Armazena texto curto com até 255 caracteres Unicode. As equipes geralmente usam esses campos para listas de seleção ou menus suspensos.
TreePath Representa uma árvore de ramificação, como caminho de área ou caminho de iteração. Escolha um valor de nó válido. Você pode filtrar por igualdade, desigualdade, "Abaixo de" ou "Não abaixo de". Use os operadores In e Not In para especificar vários valores. Defina estruturas de árvore para um projeto - caminhos de área e caminhos de iteração - e selecione os nós a serem associados às equipes. Para obter exemplos de consulta, consulte Consulta por área ou caminho de iteração e Consulta por data ou iteração atual.

Observação

Os picklist... tipos se aplicam somente a campos personalizados definidos para um processo herdado.

Padrão de data e hora

O padrão de data e hora inserido para campos DateTime deve corresponder ao selecionado em seu perfil. Para exibir ou alterar sua seleção, consulte Definir preferências do usuário.

Captura de tela que mostra as opções suspensas Padrão de Data no painel Hora e Localidade. Captura de tela que mostra as opções suspensas Padrão de Hora no painel Hora e Localidade.

Captura de tela que mostra o painel Hora e Localidade com os campos Padrão de data e Padrão de hora.

Operadores de consulta

Use operadores para definir como um valor de cláusula deve se relacionar com o valor de campo de um item de trabalho. Para tipos de dados de campo, consulte a referência de campos de itens de trabalho. Para obter ajuda para criar consultas, consulte Definir uma consulta.

Operador de consulta Quando o operador retorna itens de trabalho correspondentes Tipos de dados aplicáveis
= Corresponde ao valor da cláusula. Número (Double/Decimal/GUID/Integer), String, DateTime, TreePath
<> Não corresponde ao valor da cláusula. Número, Cadeia de Caracteres, DateTime, TreePath
> É maior que o valor da cláusula. Número, String (Cadeia de caracteres), DateTime (Data e hora)
< É menor que o valor da cláusula. Número, String (Cadeia de caracteres), DateTime (Data e hora)
>= É maior ou igual ao valor da cláusula. Número, String (Cadeia de caracteres), DateTime (Data e hora)
<= É menor ou igual ao valor da cláusula. Número, String (Cadeia de caracteres), DateTime (Data e hora)
=[Field] Corresponde ao valor em outro campo especificado (deve ser o mesmo tipo de dados). Nome de um campo do mesmo tipo de dados (campos boolianos comparam a igualdade com outros campos).
<>[Campo] Não corresponde ao valor em outro campo especificado. Nome de um campo do mesmo tipo de dados.
>[Campo] É maior que o valor em outro campo especificado. Nome de um campo do mesmo tipo de dados.
<[Campo] É menor que o valor em outro campo especificado. Nome de um campo do mesmo tipo de dados.
>=[Campo] É maior ou igual ao valor em outro campo especificado. Nome de um campo do mesmo tipo de dados.
<=[Campo] É menor ou igual ao valor em outro campo especificado. Nome de um campo do mesmo tipo de dados.
Contém Contém uma correspondência de texto exata ou parcial. String
Não contém Não contém uma correspondência de texto exata ou parcial. String
Contém Palavras Corresponde a uma frase ou palavras exatas (compatível com curinga à direita *). Limite: 100 caracteres. Esse operador usa a indexação de texto completo; consulte a seção De texto completo neste artigo para requisitos de servidor e ordenação. Campos de texto longo indexados para pesquisa de texto completo (PlainText, HTML, Histórico e Título).
Não Contém Palavras Exclui itens que contêm a frase ou as palavras especificadas. Limite: 100 caracteres. Use Contains Words em expressões associadas para incluir ou excluir palavras-chave. Campos de texto indexados para pesquisa de texto completo.
No Corresponde a qualquer valor em um conjunto delimitado (use o separador de lista regional do sistema operacional, normalmente uma vírgula). Número, Cadeia de Caracteres, DateTime, TreePath
Está Vazio Corresponde a itens em que um campo HTML não contém conteúdo (nenhum valor especificado). Com suporte para Azure Boards e Azure DevOps Server. HTML
Não Está Vazio Corresponde a itens em que um campo HTML contém conteúdo. Com suporte para Azure Boards e Azure DevOps Server. HTML
Não está em Exclui valores em um conjunto delimitado (use o separador de lista regional). Com suporte para Azure Boards e Azure DevOps Server. Número, Cadeia de Caracteres, DateTime, TreePath
Em Grupo Corresponde aos valores membros de um grupo nomeado (equipe, grupo de segurança ou categoria). Por exemplo, use o grupo Colaboradores ou um grupo de equipe nomeado no padrão [Project Name]\Team Name. Consulte Consulta por atribuição ou alterações de fluxo de trabalho para obter exemplos. Use In Group apenas com campos do tipo Cadeia de caracteres ou tipo de item de trabalho. Você pode usar grupos de Microsoft Entra ID quando sua conta usa Microsoft Entra ID, ou grupos de Active Directory para ambientes locais. Cadeia de caracteres (corresponde ao nome do grupo ou da equipe) ou tipo de item de trabalho
Fora do grupo Exclui membros de um grupo nomeado. Cadeia de caracteres que corresponde a um grupo de usuários ou categoria de projeto.
Não está em Exclui itens iguais ao nó de árvore especificado ou contidos abaixo dele. TreePath
Em Corresponde a itens iguais ou contidos no nó de árvore especificado. TreePath
Was Ever Corresponde a um valor que um campo manteve em qualquer momento anterior. (Editor de Consultas: somente campos de cadeia de caracteres. O suporte ao DateTime requer consultas WIQL diretas.) Texto, Data e Hora

Dica

Você pode construir consultas WIQL usando operadores (por exemplo, Was Ever) em outros tipos de dados, como Caminho de Iteração. Veja lista de itens de trabalho removidos de um sprint como exemplo.

Exemplos comuns de operadores

Aqui estão exemplos de consulta representativos que usam vários operadores:

Query Returns
State = Active Itens de trabalho com o estado "Ativo"
Priority <> Low Todos os itens, exceto aqueles com baixa prioridade
Created Date >= @Today-7 Itens de trabalho criados nos últimos 7 dias
Assigned To = @Me Itens atribuídos ao usuário atual
Tags Contains "frontend" Itens com uma tag que contenham "frontend"
State In (Active, In Progress) Itens em um dos estados
Area Path Under "Project\Web" Todos os itens na área da Web, incluindo subáreas
Assigned To In Group "[Project]\Developers" Itens atribuídos a qualquer pessoa no grupo Desenvolvedores
Description Contains Words "urgent" Itens em que a descrição contém a palavra "urgente"

Pesquisas de texto completo e de palavras parciais

Use Contains ou Does Not Contain para pesquisar correspondências exatas ou parciais em campos de texto longo. Esses operadores usam o índice de consulta. Use Contém palavras ou Não contém palavras para pesquisar por frases exatas ou usar um caractere curinga no final (*). Esses operadores exigem o índice de texto completo.

Você pode usar somente o curinga no final de uma palavra ou frase parcial. Para obter exemplos, consulte Exemplo de consultas de item de trabalho e Consultar itens de trabalho usando o campo Histórico.

Observação

Nem todas as implantações dão suporte à pesquisa de texto completo. Por exemplo, o SQL Express e algumas configurações de SQL de nuvem não dão suporte à pesquisa de texto completo. Nessas implantações, somente os operadores Contains e Does Not Contain estão visíveis.

Azure DevOps Server indexa campos de texto longo (PlainText e HTML) e o campo Título para pesquisa de texto completo quando o SQL Server subjacente dá suporte à indexação de texto completo.

A pesquisa de texto completo também requer uma ordenação SQL com um separador de palavras registrado para o idioma que você usa. Se a ordenação do banco de dados de coleção não corresponder a um idioma com suporte, os resultados poderão não corresponder às expectativas. Nesses casos, use Contém ou Não Contém em vez disso.

Para obter mais informações, confira Consultas de pesquisa de texto completo e configurações de ordenação.

Combinar operadores

As consultas usam a lógica AND para combinar várias cláusulas. Cada cláusula adicional filtra ainda mais os resultados. Por exemplo:

  • State = Active AND Priority = High retorna itens de trabalho que estão ativos E têm alta prioridade.
  • State = Active AND State <> Closed retorna itens ativos, excluindo aqueles marcados como fechados.
  • Assigned To = @Me AND State <> Done retorna itens atribuídos a você que não estão concluídos.

Você pode usar parênteses para agrupar condições para consultas complexas na sintaxe WIQL direta:

  • (State = Active OR State = In Progress) AND Priority = High retorna itens de alta prioridade em estados ativos ou em andamento.

Para obter mais exemplos e detalhes da sintaxe de WIQL, consulte Sintaxe da Linguagem de Consulta de Itens de Trabalho (WIQL).

Solução de problemas e erros comuns

Problema Causa provável Solução
A macro não retorna resultados @CurrentIteration funciona apenas no portal da Web; APIs REST e CLI podem retornar resultados vazios Em vez disso, use datas diretas em scripts ou APIs. Para obter alternativas, consulte Consulta por data ou iteração atual.
@TeamAreas consulta retorna resultados inesperados A macro funciona apenas com o campo Caminho da Área ; usá-lo com outros campos não tem efeito Verifique se você está filtrando por Caminho da área. Em vez disso, use outros campos de caminho da árvore (Caminho da Iteração) com o operador Under.
Erro do operador Contains Words A consulta excede o limite de 100 caracteres ou usa o posicionamento de curinga inválido Reduza o texto da consulta para menos de 100 caracteres. Use curinga somente no final do termo (por exemplo, feature*), não no início.
Falha na consulta In Group Formato de nome de grupo incorreto ou grupo não existe Use o formato exato: Assigned To In Group "[Project]\\Team Name" para equipes. Verifique o nome do grupo nas configurações do projeto.
O operador Was Ever não estava funcionando em datas Editor de Consultas não dá suporte Was Ever a campos DateTime Use a sintaxe WIQL direta em vez do editor de consultas visuais. Para obter mais informações, confira Sintaxe para a Work Item Query Language (WIQL).
A consulta de campo booliano não retorna resultados O valor faz distinção entre maiúsculas e minúsculas em consultas WIQL Use o caso exato: CustomBoolField = True ou CustomBoolField = False (T/F maiúsculo no WIQL).

Consultar macros e variáveis

Use as seguintes macros para filtrar consultas dinamicamente.

Observação

As macros a seguir só têm suporte no portal da Web: @CurrentIteration, @CurrentIteration +/- n, @Follows, @MyRecentActivity, @RecentMentions, @RecentProjectActivity e @TeamAreas. As consultas que contêm essas macros não funcionarão quando abertas no Visual Studio/Team Explorer, Microsoft Excel ou Microsoft Project.

Macro Description
[Any] Use com o Tipo de Item de Trabalho ou o Estado para pesquisar em todos os tipos ou estados. Por exemplo, Work Item Type=[Any] remove a filtragem baseada em tipo.
@CurrentIteration Use com o Caminho da Iteração para filtrar itens de trabalho no sprint atual com base no contexto atual da equipe. Consulte a consulta por data ou iteração atual para obter exemplos. @CurrentIteration funciona somente quando executado no portal da Web (não em APIs REST ou em algumas operações de cópia/clonagem).
@CurrentIteration +/- n Use com o Caminho da Iteração para incluir sprints relativos à iteração atual (por exemplo, @CurrentIteration-1 ou @CurrentIteration+2). Com suporte no portal web para Azure Boards e Azure DevOps Server.
@Follows Use o ID e o In operador para listar itens de trabalho que você acompanha no projeto. Consulte Seguir um item de trabalho ou uma pull request. Essa macro funciona somente no portal da Web.
@Me Use com campos de identidade para filtrar itens vinculados à sua conta (por exemplo, Created By=@Me). Consulte Pesquisar por atribuição, fluxo de trabalho ou mudanças no quadro.
@MyRecentActivity Use com ID e In para listar os itens de trabalho que você visualizou ou atualizou nos últimos 30 dias. Consulte o pivô Minha atividade da página Itens de trabalho para a mesma lista.
@Project Use com o Team Project para filtrar itens de trabalho no projeto atual (por exemplo, Team Project=@Project). Confira Consulta entre vários projetos.
@RecentMentions Use com ID e In para listar itens de trabalho onde você é mencionado em Discussões. Consulte o pivô Mencionado da página Itens de trabalho.
@RecentProjectActivity Use ID e In para listar itens de trabalho atualizados recentemente em diferentes partes do projeto. A macro retorna até 5.000 itens; a janela real depende da atividade do projeto.
@StartOfDay Use com campos DateTime para filtrar em relação a hoje (por exemplo, Closed Date>=@StartOfDay-7).
@StartOfMonth Use com campos DateTime para filtrar em relação ao início do mês (por exemplo, Created Date>=@StartOfMonth-3).
@StartOfWeek Use com campos DateTime para filtrar em relação ao início da semana (por exemplo, Changed Date>=@StartOfWeek-2).
@StartOfYear Use com campos DateTime para filtrar em relação ao início do ano (por exemplo, Target Date>=@StartOfYear).
@TeamAreas Use apenas com o Caminho da Área e o operador = para localizar itens atribuídos aos caminhos de área de uma equipe (por exemplo, Area Path=@TeamAreas [Fabrikam Fiber]\Web). Com suporte no portal web para Azure Boards e Azure DevOps Server.
@Today Use com campos DateTime para filtrar em relação a hoje (por exemplo, Created Date>=@Today-7). Consulte Consulta por data ou iteração atual.

Exemplos comuns de macro

Aqui estão exemplos de consulta representativos que usam macros para tornar as consultas dinâmicas:

Query Devoluções (Portal Web)
Iteration Path = @CurrentIteration Itens de trabalho no sprint atual
Iteration Path = @CurrentIteration-1 Itens de trabalho no sprint anterior
Assigned To = @Me Itens atribuídos ao usuário atual
Created Date >= @Today-30 Itens criados nos últimos 30 dias
State = Active AND Area Path = @TeamAreas [Project]\MyTeam Itens ativos na área da sua equipe
Work Item Type = [Any] Todos os tipos de item de trabalho (remove o filtro por tipo)
Assigned To In Group @Follows Itens atribuídos às pessoas que você segue

Observação

Macros como@CurrentIteration, @Mee @Follows@TeamAreas funcionam apenas no portal da Web. Para APIs REST, CLI e Power BI, use datas diretas e IDs de usuário. Para obter alternativas, consulte Consulta por data ou iteração atual.

Conteúdo relacionado

API REST

Para interagir programaticamente com consultas, confira um destes recursos da API REST:

  • Last updated on