Como Usar a Sintaxe de Consulta Avançada Programaticamente

Sintaxe de consulta avançada (AQS) é a sintaxe de consulta padrão usada pelo Windows Search para consultar o índice e para refinar e restringir os parâmetros de pesquisa. A AQS é empregada por desenvolvedores para criar consultas de forma programática (e por usuários para restringir seus parâmetros de pesquisa). A AQS canônica foi introduzida no Windows 7 e deve ser usada no Windows 7 e posterior para gerar consultas AQS programaticamente.

Este tópico é organizado da seguinte maneira:

• Sobre a sintaxe de consulta avançada
  • Exemplos
  • Propriedades
• Uso de palavras-chave em idiomas locais
• Sintaxe de consulta avançada canônica no Windows 7
  • Exemplos
  • Operadores de Consulta
  • Valores de consulta
• Restrições de escopo
• Recursos adicionais
• Tópicos relacionados

Sobre a sintaxe de consulta avançada

Uma consulta consiste em consultas básicas conectadas com AND, OR e NOT, conforme mostrado no exemplo de sintaxe a seguir:

<query> ::=
     <basic query>
| ( <query> )
| <query> AND <query>  
| <query> <query>    // Same as <query> AND <query>
| <query> OR <query> 
| NOT <query>

Observação

AQS não diferencia maiúsculas de minúsculas, com exceção de AND, OR e NOT, que devem estar em letras maiúsculas.

 

Se uma consulta tiver dois ou mais usos de AND ou OR, eles serão vinculados da esquerda para a direita, independentemente de ser AND ou OR. Ou seja, a consulta "maçã E pera OR ameixa" será interpretada como se estivesse escrita como "(maçã AND pera) OR ameixa", e a consulta "maçã OR pera AND ameixa" será interpretada como se fossem escritos como "(maçã OR pera) AND ameixa". Portanto, se um documento contém a palavra ameixa, mas não contém maçã nem pera, a primeira consulta a retornará, mas a segunda consulta não. Portanto, recomendamos que você use parênteses explícitos para qualquer consulta que misture AND e OR para evitar erros ou interpretações errôneas.

Uma consulta básica procura itens que satisfaçam uma restrição sobre uma propriedade. A única parte obrigatória de uma consulta básica é a restrição ou valor de pesquisa. Se você não especificar uma propriedade, o Windows Search pesquisará todas as propriedades. <restr> representa a restrição de pesquisa.

Os seguintes formulários para uma consulta básica são válidos:

<basic query> ::=
     <prop>:<basic restr>
| <restr>

Uma propriedade é designada por uma palavra-chave como autor ou tamanho, ou por um nome de propriedade canônico como System.DateModified. Os formulários válidos para uma propriedade são os seguintes:

<prop> ::= 
     <canonical property name>
| <property label in UI language>

Um operador indica uma operação como < ou =. Para obter uma lista de operadores válidos, consulte a seção Operadores de consulta posteriormente neste tópico.

Uma restrição básica é uma restrição simples a uma propriedade que pode ser escrita sem parênteses:

<basic restr> ::=
     <value>
| <op><value>
| NOT <basic restr>
| ( <restr> )

Uma restrição é um valor de pesquisa, como um valor numérico ou um valor de cadeia de caracteres, opcionalmente com um operador. Os formulários válidos para uma restrição são os seguintes:

<restr> ::=
    <basic restr>
| <restr> AND <restr>
| <restr> <restr>      // Same as <restr> AND <restr>
| <restr> OR <restr>

Se você não especificar um operador, o Windows Search escolherá o operador mais apropriado para sua consulta:

• Para uma propriedade de cadeia de caracteres, o operador COP_WORD_STARTSWITH $< é assumido.
• Para todas as outras propriedades, o operador COP_EQUAL = é assumido.

Para o uso programático do AQS, recomendamos que você tenha sempre um operador explícito. A forma válida para pesquisar um valor simples ou intervalo de valores é a seguinte:

<value> ::=
    <simplevalue>
| <simplevalue> .. <simplevalue>

Um valor simples pode consistir em qualquer um dos seguintes tipos:

<simplevalue> ::=
  []         // No value, or a null value
| <word>     // A sequence of characters without whitespace
| <number>   // An integer or a floating point number
| <datetime> // A relative date, or an absolute date and/or time
| <Boolean>
| "..."      // A phrase
| <enumeration range>

Exemplos

Uma consulta que busca um documento contendo a fase “último trimestre”, de autoria de Theresa ou Lee, e que foi salvo na pasta MeusDocs, combina três consultas básicas da seguinte forma:

"last quarter" author:(theresa OR lee) folder:MyDocs

As três consultas básicas são:

• "último trimestre"
• author:(theresa OR lee)
• folder:MyDocs

Uma consulta básica que usa sintaxe canônica é:

System.Size:>1kb

Propriedades

As propriedades são referidas por uma palavra-chave, que pode ser um nome de propriedade canônico no Windows 7 e posterior. AQS na UI do Windows pode usar o rótulo em vez do nome da propriedade canônica, como autor em vez de System.Author. No Windows Vista e versões anteriores, era possível usar rótulos em inglês, independentemente do idioma da interface do usuário. No Windows 7 e posterior, o Windows Search reconhece palavras-chave apenas no idioma da interface do usuário padrão atual.

Suporte para propriedades personalizadas

No Windows Vista e versões anteriores, as propriedades personalizadas não estavam disponíveis no AQS. No Windows 7 e posterior, a AQS funciona com propriedades personalizadas registradas no sistema de propriedades. Para obter mais informações sobre como criar propriedades personalizadas, consulte Sistema de propriedades.

Propriedades DateTime no Windows 8

A partir do Windows 8, as propriedades DateTime (como System.DateModified) suportam o formato canônico de data e hora especificado por ISO-8601, incluindo opcionalmente o fuso horário UTC.

• Windows 8 e versões anteriores, data e hora sem fuso horário UTC: YYYY-MM-DDThh:mm:ss

  Este formato especifica uma hora local, independentemente da localidade do usuário ou do sistema.

• Windows 8, data e hora com fuso horário UTC: YYYY-MM-DDThh:mm:ssTZD

  Este formato especifica uma hora no fuso horário UTC especificado.

Uso de palavras-chave em idiomas locais

No Windows 7 e posterior, as palavras-chave mnemônicas funcionam apenas no idioma do sistema, como as palavras-chave em alemão somente em um sistema operacional alemão e as palavras-chave em inglês apenas em um sistema operacional em inglês. System.Author é uma palavra-chave canônica e o valor mnemônico da propriedade System.Author é Autor, por exemplo. A introdução de palavras-chave canônicas compensa o fato de que as palavras-chave mnemônicas em inglês não são mais reconhecidas universalmente em todos os sistemas operacionais, independentemente do idioma, como acontecia no Windows Vista e versões anteriores.

Observação

No Windows 7 e posterior, o Windows Search reconhece palavras-chave apenas no idioma padrão atual e não em inglês, a menos que inglês seja o padrão atual. Recomendamos que os desenvolvedores sempre usem sintaxe canônica para que seus aplicativos não tenham problemas de linguagem com palavras-chave.

 

Sintaxe de consulta avançada canônica no Windows 7

A sintaxe canônica foi introduzida para palavras-chave no Windows 7. Um exemplo de consulta com propriedade canônica é System.Message.FromAddress:=me@microsoft.com. Ao codificar consultas em aplicativos em execução no Windows 7 e posterior, você deve usar a sintaxe canônica para gerar consultas AQS programaticamente. Se você não usar sintaxe canônica e seu aplicativo for implementado em um código de idioma ou idioma da interface do usuário diferente do idioma no código do aplicativo, suas consultas não serão interpretadas corretamente.

As convenções para sintaxe de palavras-chave canônicas são as seguintes:

• A sintaxe canônica de uma propriedade é seu nome canônico, como System.Photo.LightSource. Os nomes canônicos não diferenciam maiúsculas de minúsculas.
• A sintaxe canônica para os operadores booleanos consiste nas palavras-chave AND, OR e NOT, todas em letras maiúsculas.
• Os operadores <, >, = e assim por diante não estão localizados e, portanto, também fazem parte da sintaxe canônica.
• Se uma propriedade P tiver valores ou intervalos enumerados denominados N₁ a Nₖ, a sintaxe canônica para o I I-ésimo valor ou intervalo é o nome canônico de P, seguido pelo caractere #, seguido por N_I, conforme ilustrado no exemplo a seguir:
  • System.Photo.LightSource#Daylight, System.Photo.LightSource#StandardA e assim por diante.
• Para um tipo semântico definido T com valores ou intervalos denominados N₁ a Nₖ, a sintaxe canônica para o I-ésimo valor ou intervalo é o nome canônico para T, seguido pelo caractere #, seguido por N_I, conforme ilustrado no exemplo a seguir:
  • System.Devices.LaunchDeviceStageFromExplorer:=System.StructuredQueryType.Boolean#True
• Para valores literais, como palavras ou frases, a sintaxe canônica é igual à sintaxe regular. Exemplos de consultas com valores literais na sintaxe canônica são:
  • System.Author:sanjay
  • System.Keywords:"Animal"
  • System.FileCount:>100

Observação

Não há sintaxe canônica para números no Windows 7 e versões posteriores. Como os formatos de ponto flutuante variam entre as localidades, não há suporte para o uso de uma consulta canônica que envolva uma constante de ponto flutuante. As constantes inteiras, por outro lado, podem ser escritas usando apenas dígitos (sem separadores para milhares) e podem ser usadas com segurança em consultas canônicas no Windows 7 e versões posteriores.

 

Exemplos

A tabela a seguir mostra alguns exemplos de propriedades canônicas e a sintaxe para usá-las.

Tipo de propriedade canônica	Exemplo	Sintaxe
Valor da cadeia de caracteres	System.Author	O valor da cadeia de caracteres é procurado na propriedade do autor: System.Author:Jacobs
Intervalo de enumeração	System.Priority	A propriedade de prioridade pode ter uma faixa de valores numéricos: System.Priority:System.Priority#High
Booliano	System.IsDeleted	Valores booleanos podem ser usados ​​com qualquer propriedade booleana: System.IsDeleted:System.StructuredQueryType.Boolean#True e System.IsDeleted:System.StructuredQueryType.Boolean#False
Numérico	System.Size	Não é possível escrever com segurança uma consulta canônica que envolva uma constante de ponto flutuante, porque os formatos de ponto flutuante variam entre as localidades. Os números inteiros devem ser escritos sem separadores de milhares. Por exemplo: System.Size:<12345

 

Para obter mais informações sobre propriedades canônicas e o sistema de propriedades em geral, consulte Propriedades do sistema. Como alternativa, consulte os arquivos de cabeçalho público.

Operadores de Consulta

Se uma propriedade, p, tiver vários valores para algum item, uma consulta AQS para p:<restr> devolve o item se <restr> for true para pelo menos um dos valores. (<restr> representa uma restrição.)

A sintaxe listada na tabela a seguir consiste em um operador, símbolo de operador, exemplo e descrição de exemplo. O operador e o símbolo podem ser usados ​​em qualquer idioma e incluídos em qualquer consulta. Não utilize os operadores COP_IMPLICIT or COP_APPLICATION_SPECIFIC. Alguns dos operadores possuem símbolos intercambiáveis.

Operador	Símbolo	Exemplo	Descrição
COP_EQUAL	=	System.FileExtension:=".txt"	O valor é a cadeia de caracteres ".txt".
COP_NOTEQUAL	≠ - <> NOT - -	System.Kind:≠picture System.Photo.DateTaken:-[]¹ System.Kind:<>picture System.Kind:NOT picture System.Kind:- -picture	A propriedade System.Kind não é uma imagem. A propriedade System.Photo.DateTaken tem um valor. A propriedade System.Kind não é uma imagem. A propriedade System.Kind não é uma imagem. Os operadores NOT duplos aplicados à mesma propriedade não são cancelados. Portanto, System.Kind:- -picture é equivalente a System.Kind:-picture e System.Kind:NOT picture.
COP_LESSTHAN	<	System.Size:<1kb	Este valor é menor que 1kb.
COP_GREATERTHAN	>	System.ItemDate:>System.StructuredQueryType.DateTime#Today	Este valor é superior a hoje.
COP_LESSTHANOREQUAL	<= ≤	System.Size:<=1kb	Este valor é menor ou igual a 1kb.
COP_GREATERTHANOREQUAL	>= ≥	System.Size:>=1kb	Este valor é igual ou maior que 1kb.
COP_VALUE_STARTSWITH	~<	System.FileName:~<"C++ Primer"	Encontra itens onde o nome do arquivo começa com os caracteres "C++ Primer".
COP_VALUE_ENDSWITH	~>	System.Photo.CameraModel:~>non	Encontra itens onde o valor da propriedade termina com os caracteres non.
COP_VALUE_CONTAINS	~= ~~	System.Subject.~=round System.Search.Autosummary:~~round	Encontra uma mensagem que tem esta cadeia de caracteres no assunto e corresponderá a "ground rules", por exemplo. Encontra todos os itens com um Autosummary que contém os caracteres round.
COP_VALUE_NOTCONTAINS	~!	System.Author:~!"sanjay"	Encontra autores que não possuem a sequência de caracteres "sanjay" neles.
COP_DOSWILDCARDS	~	System.FileName:~"Mic?osoft W*d"	Encontra arquivos onde o nome do arquivo começa com Mic, seguido por algum caractere, seguido por osoft w, seguido por quaisquer caracteres que terminem com d. O ? e * caracteres não são interpretados literalmente e funcionam como caracteres curinga no estilo DOS: ? corresponde a um caractere arbitrário. * corresponde a zero ou mais caracteres arbitrários.
COP_WORD_EQUAL	$= $$	System.StructuredQuery.Virtual.From:$="Sanjay Jacobs"	Para Windows 7 e posterior. Encontra a frase "Sanjay Jacobs" em todas as propriedades From. A palavra Sanjay deve ser seguida pela palavra Jacobs.
COP_WORD_STARTSWITH	$<	System.Author:$<"San" System.Filename:$<"Micro Exe"	Para Windows 7 e posterior. Encontra qualquer item onde Autor contém uma palavra começando com os caracteres "San". Encontra qualquer arquivo cujo nome contenha uma palavra começando com micro, seguido por uma palavra começando com exe.

 

¹ Colchetes vazios ([]) denotam "sem valor".

Para propriedades de cadeia de caracteres, a operação padrão é COP_WORD_STARTS_WITH ou COP_WORD_EQUAL.

Valores de consulta

Exemplos úteis de como os valores de consulta podem ser restringidos estão listados na tabela a seguir.

Valor/símbolo	Exemplos	Descrição
String	auto	Qualquer sequência de caracteres que possa ser pesquisada. A cadeia de caracteres não deve conter espaços em branco ou combinações de caracteres que façam parte da sintaxe. Este exemplo procura uma palavra que começa com auto.
Cadeia de caracteres entre aspas ""	"Conclusions: valid" "The ""blue"" team"	Qualquer sequência de caracteres. A cadeia de caracteres não é interpretada como parte da sintaxe. As aspas podem ser incluídas em uma consulta se forem duplicadas. Este exemplo procura The "blue" team.
Inteiro	5678	Use apenas dígitos para números inteiros. Não use separadores de milhares.
Número de ponto flutuante	5678.1234	Como os formatos de ponto flutuante variam entre localidades, uma consulta canônica não pode usar uma constante de ponto flutuante. O uso de sintaxe canônica com números de ponto flutuante não é seguro para localização.
Booleano true/false	System.IsRead:=System.StructuredQueryType.Boolean#True System.IsEncrypted:-System.StructuredQueryType.Boolean#False	O valor booleano TRUE. O valor booleano FALSE.
[]	System.Keywords:=[]	Colchetes vazios indicam que não há valor. Este exemplo encontra todos os itens que não foram marcados.
Datas absolutas	System.ItemDate:1/26/2010 SystemDateModified 10/15/2002 19:00	Encontra itens com data de 26 de janeiro de 2010. Encontra itens que foram modificados em 15 de outubro de 2002 entre 19:00:00 e 19:00:59. Observação: Como os formatos de data (como formatos de ponto flutuante) variam entre localidades, o uso de sintaxe canônica com datas absolutas não é compatível e não é seguro para localização.
Datas relativas	System.ItemDate:System.StructuredQueryType.DateTime#Today System.DateAcquired:System.StructuredQueryType.DateTime#NextMonth System.Message.DateReceived:System.StructuredQueryType.DateTime#LastYear	Encontra itens com a data de hoje. Encontra itens com data no próximo mês. Encontra itens com data no último ano. Observação: Além de pesquisar datas e intervalos de datas específicos, a AQS reconhece valores de datas relativos (como today, tomorrow, nextweek, nextmonth) e dia (como Tuesday ou Monday..Wednesday) e mês (February).
..	System.ItemDate:11/05/04..11/10/04 System.Size:5kb..10kb	Os dois pontos finais indicam um intervalo de valores. Encontra itens com data entre 05/11/04 e 10/11/04, inclusive. Encontra itens entre 5 e 10 kb de tamanho.

 

Restrições de escopo

Os usuários podem limitar o escopo de suas pesquisas a locais de pastas ou armazenamentos de dados específicos. Por exemplo, se você usa várias contas de email e deseja limitar uma consulta ao Microsoft Outlook ou ao Microsoft Outlook Express, você pode usar System.Search.Store:mapi ou System.Search.Store:oe respectivamente. A tabela a seguir mostra alguns exemplos de como restringir uma pesquisa por armazenamento de dados.

Restringir a pesquisa por armazenamento de dados	Palavra-chave	Exemplo
Arquivos	arquivo	System.Search.Store:file
Outlook	mapi	System.Search.Store:mapi
Outlook Express	oe	System.Search.Store:oe
Arquivos offline	csc	System.Search.Store:csc
Pasta específica na unidade local	folder	System.ItemFolderNameDisplay:C:"\MyFolder"

 

Recursos adicionais

• No Windows 7 e posterior, uma opção de menu de atalho pode estar disponível com base no atendimento de uma condição AQS. Para obter mais informações, consulte "Como obter comportamento dinâmico para verbos estáticos usando sintaxe de consulta avançada" em Como criar manipuladores de menu de contexto.
• As consultas AQS podem ser limitadas a tipos específicos de arquivos, conhecidos como tipos de arquivo. Para obter mais informações, consulte Tipos de arquivos e associações. Para documentação de referência de propriedade, consulte System.Kind e System.KindText.

Tópicos relacionados

Consulta do índice de maneira programática

Como Usar Abordagens SQL e AQS para Consultar o Índice

Como Consultar o Índice com ISearchQueryHelper

Como Consultar o Índice com o Protocolo search-ms

Como Consultar o Índice com a Sintaxe SQL do Windows Search