Compartilhar via


Refinamento de consulta no SharePoint

Saiba como usar os recursos de refinamento de consulta do SharePoint programaticamente quando estiver trabalhando com consultas e resultados de pesquisa.

Você pode usar recursos de refinamento de consulta para fornecer aos usuários finais opções de refinamento que são relevantes para as consultas. Esses recursos permitem que o usuário final detalhar os resultados da pesquisa usando os dados de refinamento computados para os resultados. Dados de refinamento são calculados pelo componente de índice, com base na agregação de estatísticas de propriedade gerenciada para todos os resultados de uma consulta de pesquisa.

Normalmente, refinamento de consulta é usado para os metadados associados com os itens indexados, como data de criação, autor ou tipos de arquivo que aparecem no item. Usando as opções de refinamento, você pode refinar sua consulta para exibir somente os itens criados durante um determinado período de tempo ou exibir apenas itens de um tipo de arquivo específico.

Usar refinadores no modelo de objeto de consulta

Há duas consultas envolvidas na refinamento de consulta:

  1. Você pode solicitar que um conjunto de refinarias seja retornado nos resultados da pesquisa adicionando uma especificação de refinaria à consulta do usuário final. Uma especificação de refinador é a entrada para a propriedade Refiners . Esta consulta é executada no índice de pesquisa. Os resultados da pesquisa consistirá resultados relevantes e dados de refinamento.
  2. Você pode usar os dados de refinamento para detalhar os resultados da pesquisa criando uma consulta refinada. Adicione a propriedade RefinementFilters à consulta para que os resultados finais da pesquisa atendam aos requisitos do texto de consulta original do usuário final e à opção de refinamento selecionada dos dados de refinamento.

As seções a seguir descrevem essas etapas detalhadamente e fornecem exemplos de código.

Adicionar refinadores à consulta do usuário final usando as especificações do refinador

Você pode especificar os refinadores de consulta solicitados usando a propriedade Refiners da classe KeywordQuery . Use a seguinte sintaxe para especificar os refinadores consulta solicitada:

<refiner>[,<refiner>]*

Cada refiner tem o seguinte formato:

<refiner-name>[(parameter=value[,parameter=value]*)]?

Onde:

  • <refiner-name> é o nome da propriedade gerenciada associado no refinador. Esta propriedade gerenciada deve ser definida como Refinable ou Sortable no esquema de pesquisa.
  • A lista opcional de pares de parameter=value especifica valores de configuração não-padrão para o refinador nomeado. Se um parâmetro para um refinador não estiver listado dentro dos parênteses, a configuração de esquema de pesquisa lhe a configuração padrão. A tabela 1 lista os valores possíveis para os pares de parameter=value .

Observação

Quando você especifica refinadores, o requisito mínimo é especificar um refiner-name, que é uma propriedade gerenciada.

Exemplo

Refiners = "FileType"

Ou então, você também pode usar a sintaxe avançada para ajustar as configurações de refinador:

Refiners = "FileType,Write(discretize=manual/2013-01-01/2013-08-22/2013-09-15/2013-09-21/2013-09-22),companies"

Tabela 1: Lista de parâmetros para refinadores

Parâmetro Descrição
deephits
Substitui o número padrão de acertos que for usado como base para cálculo de refinamento. Quando refinadores são produzidos, todos os resultados da consulta serão avaliados. Normalmente, o uso deste parâmetro irá melhorar o desempenho de pesquisa.
Sintaxe
deephits=<integer value>
Exemplo
price(deephits=1000)
Observação: esse limite se aplica dentro de cada partição de índice. O número real de acertos que são avaliadas será maior que esse valor devido a agregação nas partições de pesquisa.
discretize
Especifica os intervalos personalizados (bandejas refinamento) para refinadores numéricos.
Sintaxe
discretize=manual/<threshold>/<threshold>[/<threshold>]*
Exemplo
write(discretize=manual/2013-01-01/2013-08-22/2013-09-15/2013-09-21/2013-09-22)
O atributo <threshold> Especifica o limite para cada bandeja de refinamento.
Não há um intervalo de tudo abaixo do limiar primeiro especificado, um intervalo entre cada limite consecutiva e um intervalo para tudo, acima do limite de último.
Para um refinamento de tipo DateTime, especifique o limite de acordo com um dos seguintes formatos ISO 8601 compatíveis:
  • YYYY-MM-DD
  • AAAA-MM-DDThh:mm:ss
  • YYYY-MM-DDThh:mm:ss:Z
Os valores de formato especificam o seguinte:
  • YYYY - ano com quatro dígitos. Anos de quatro dígitos somente são suportados.
  • MM - mês com dois dígitos. 01 = January.
  • DD - dia de dois dígitos do mês (01 a 31).
  • T - a letra "T".
  • hh - hora de dois dígitos (00 a 23). Indicação de A.M. ou P.M. não é permitida.
  • mm - dois dígitos minuto (00 a 59).
  • ss - dois dígitos segundo (00 a 59).
Importante: Todos os valores de data/hora devem ser especificados de acordo com a zona UTC (Horário Universal Coordenado), também conhecida como fuso horário médio de Greenwich (GMT). O identificador da zona UTC (um caractere "Z" precedente) é opcional.
sort
Define como classificar as lixeiras dentro de um refinador de cadeia de caracteres.
Sintaxe
sort=<property>/<direction>
Os atributos executam o seguinte:
  • <property> – especifica os algoritmo de classificação. Esses valores minúsculos são válidos:
    • frequency - pedidos por ocorrência dentro as lixeiras.
    • name - pedidos por nome de rótulo.
    • number - trata as cadeias de caracteres como numérico e usa a classificação numérica. Esse valor pode ser útil para especificar valores discretos, por exemplo, para executar uma classificação numérica de um valor que está contido em uma propriedade gerenciada de tipo String.
  • <direction> – especifica a direção de classificação. Esses valores minúsculos são válidos:
    • descending
    • ascending
Exemplo
sort=name/ascending
Default: freqüência/decrescente
filter
Define como bandejas dentro de um refinador do tipo String são filtradas antes que eles são retornados ao cliente.
Sintaxe
filter=<bins>/<freq>/<prefix>[<levels>]
Os atributos executam o seguinte:
  • <bins> – especifica o número máximo de compartimentos devolvidos.
    Após a classificação as lixeiras dentro do refinador, use esse atributo truncar qualquer bins à direita. Por exemplo, se bins = 10, somente as primeiros 10 bandejas forem retornadas, de acordo com o algoritmo de classificação especificado.
  • <freq> – limita o número de compartimentos devolvidos.
    Use este atributo para remover bins cuja contagens de baixa freqüência. Por exemplo, freq= 2 indica que apenas as bandejas com 2 ou mais membros serão retornados.
  • <prefix> – especifica que apenas os compartimentos com um nome que começa com esse prefixo são devolvidos.
    O caractere curinga "*" corresponderá a todos os nomes.
    Exemplo
    filter=30/2/*
  • <levels> – especifica os níveis de taxonomia.
    Use este atributo para filtrar a saída de refinador hierárquico com base nos níveis de taxonomia. O atributo deve ser um inteiro positivo n. O valor de default é n= 0. Se n>0, somente entradas de refinaria que contenham menos de n símbolos separadores de caminho de taxonomia ("/") serão retornadas. Se n= 0, nenhum nível de filtragem é executada. O separador de nível é o caractere de barra ("/").
    Lembre-se do custo de desempenho do uso de um navegador de taxonomia grande. A filtragem é realizada como parte do processamento de resultado.
Observação: esse parâmetro aplica a filtragem do lado do resultado específica do aplicativo. Isso difere do parâmetro corte, que aplicará limitações em cada partição de índice por motivos de desempenho.
cutoff
Limita os dados que devem ser transferidos e processados para refinadores de profundidade de cadeia de caracteres. Você pode configurar os refinadores para retornar apenas os valores mais relevantes (bandejas).
Observação: essa filtragem de corte é executada em cada partição de índice. This differs from the filter parameter, which performs result-side filtering only. You can combine the two parameters.
Sintaxe
cutoff=<frequency>/<minbins>/<maxbins>
Os atributos executam o seguinte:
  • <maxbins> – limita o número de compartimentos.
    Esse parâmetro limita o número de valores exclusivos (bandejas) que será retornada para um refinador. É a maneira preferencial para aumentar o desempenho de pesquisa quando refinadores de cadeia de caracteres com um grande número de bandejas são retornados. "0" indica que o valor padrão especificado no esquema de pesquisa é usado.
  • <frequency> – limita o número de compartimentos pela frequência.
    Se o número de ocorrências de um valor de refinador em um conjunto de resultados for menor ou igual ao valor frequência, o valor de refinador não será retornado. "0" indica que o valor padrão de acordo com o esquema de pesquisa é usado.
  • <minbins> – especifica o valor mínimo para o corte de frequência.
    Se o número de valores de refinador exclusivo para a consulta for menor que esse valor, nenhuma frequência corte é executada e todos os valores de refinador são retornados da partição pesquisa. Quando é usado o corte por frequência, esse parâmetro pode ser usado para especificar um número mínimo de valores de refinador exclusivo que serão retornados, independentemente do número de ocorrências. O valor padrão deste atributo é "0", indicando que freqüência corte é executada, independentemente do número de valores exclusivos de navegador. "0" indica que o valor padrão especificado no esquema de índice é usado.
Observação: use <frequência> e <minbinas> com cuidado. Recomendamos que use apenas <maxbins>.

Exemplo: adicionar refinadores

O exemplo a seguir CSOM mostra como solicitar programaticamente três refinadores: FileType, Writee Companies. Write representa a data da última modificação para o item e usa a sintaxe avançada para retornar o tamanho fixo bandejas de data/hora.

using (var context = new ClientContext("http://<serverName>/<siteCollectionPath>"))
{
    var query = new KeywordQuery(context)
    {
        QueryText = "home",
        Refiners = "FileType,Write(discretize=manual/2013-01-01/2013-08-22/2013-09-
            15/2013-09-21/2013-09-22),companies"
    };

    var executor = new SearchExecutor(context);
    var results = executor.ExecuteQuery(query);

    context.ExecuteQuery();

    ResultTable relevantResultsTable = results.Value[0];
    ResultTable refinerResultsTable = results.Value[1];
    Console.WriteLine(refinerResultsTable.RowCount + " refinement options:");
    foreach (var refinementOption in refinerResultsTable.ResultRows)
    {
        Console.WriteLine("RefinerName: '{0}' RefinementName: '{1}'
            RefinementValue: '{2}' RefinementToken: '{3}' RefinementCount: '{4}'",
            refinementOption["RefinerName"],
            refinementOption["RefinementName"],
            refinementOption["RefinementValue"],
            refinementOption["RefinementToken"],
            refinementOption["RefinementCount"]
        );
    }
}

Compreensão sobre o refinamento de dados no resultado da pesquisa

Se você tiver habilitado o refinamento de consulta para uma propriedade gerenciada em sua consulta, o resultado da consulta conterá dados de refinamento divididos em lixeiras de refinamento. Esses dados estão localizados na tabela RefinementResults ( RefinementResults ) dentro do ResultTableCollection . Uma lixeira de refinamento representa um valor ou intervalo de valor específico para a propriedade gerenciada. A tabela RefinementResults contém uma linha por lixeira de refinamento e contém as colunas, conforme especificado na Tabela 2.

Tabela 2: Os dados retornados para as lixeiras de refinamento

Parâmetro Descrição
RefinerName O nome do refinador a consulta.
RefinementName A cadeia de caracteres que representa a bandeja de refinamento. Esta cadeia de caracteres geralmente é usada quando estiver apresentando as opções de refinamento aos usuários em uma página de resultados de pesquisa.
RefinementValue Um implementação específicos formatado string que representa o refinamento. Esses dados são retornados para depuração e geralmente não é necessários para o cliente.
RefinementToken Uma string que representa a bandeja de refinamento a ser usada com RefinerName quando você executa uma consulta refinada.
RefinementCount A contagem de resultados para este compartimento de refinamento. Esses dados representam o número de itens (incluindo duplicatas) no resultado da pesquisa, com um valor para a propriedade gerenciada determinado que se encaixam este compartimento de refinamento.

Exemplo: dados de refinamento

A tabela 3 abaixo contém duas linhas de dados de refinamento. A primeira linha contém dados de refinamento de itens indexados, onde o tipo de arquivo é HTML. A segunda linha contém refinamento dados para itens indexados, onde a última modificação tempo são de 21/09/2013 até 22/09/2013.

Tabela 3: Formato e conteúdo de dados de refinamento

RefinerName RefinementName RefinementValue RefinementToken RefinementCount
FileType Html Html "????68746d6c" 50553
Gravar De 2013-09-21T00:00:00Z até 2013-09-22T00:00:00Z Do 2013-09-21T00:00:00Z até 2013-09-22T00:00:00Z intervalo (2013-09-21T00:00:00Z, 2013-09-22T00:00:00Z) 37

Criar uma consulta refinada

Um resultado de pesquisa apresenta opções de refinamento na forma de valores de cadeia de caracteres ou intervalos de valor. Cada valor de cadeia de caracteres ou um intervalo de valores numéricos é chamado uma bandeja de refinamentoe cada bin refinamento possui um valor de associado RefinementToken. Uma opção de refinamento é associada uma propriedade gerenciada, que é fornecida pelo valor RefinerName.

Os valores de RefinementToken e RefinerName forem concatenados para criar uma cadeia de caracteres refinement filter. Esta cadeia de caracteres representa um filtro que pode ser usado para limitar os itens de resultado de pesquisa para incluir somente os itens onde uma propriedade gerenciada tem um valor em um compartimento de refinamento. No short:

refinement filter = <RefinerName>:<RefinementToken>

Você pode fornecer um ou mais filtros de refinamento para uma consulta refinada adicionando filtros de refinamento à propriedade RefinementFilters da classe KeywordQuery . Vários filtros de refinamento permitem que você para fornecer vários níveis detalhamento em resultados da pesquisa e aplicar refinamento nas propriedades de valores múltiplos. Por exemplo, você pode refinar a consulta para itens que tenham dois autores - cada um representado por um compartimento de refinamento - mas excluir itens que possuem apenas um dos autores.

Exemplo 1: Criar uma consulta refinada para tipos de arquivo HTML

O exemplo CSOM a seguir mostra como realizar um refinamento programaticamente, para limitar os resultados da pesquisa apenas a esses tipos de arquivo HTML. Conforme mencionado em Exemplo: dados de refinamento, os dados de refinamento relacionados a essa opção de refinamento têm RefinerName definido como Filetype e RefinementToken definidos como "???? 68746d6c".

using (var context = new ClientContext("http://<serverName>/<siteCollectionPath>"))
{
    var query = new KeywordQuery(context)
    {
        QueryText = "home"
    };

    query.RefinementFilters.Add("FileType:\\"????68746d6c\\"");
    var executor = new SearchExecutor(context);
    var results = executor.ExecuteQuery(query);

    context.ExecuteQuery();

    ResultTable relevantResultsTable = results.Value[0];
    var resultCount = 1;
    foreach (var relevantResult in relevantResultsTable.ResultRows)
    {
        Console.WriteLine("Relevant result number {0} has file type {1}.",
            resultCount, relevantResult["FileType"]);
            resultCount++;
    }
}

Exemplo 2: Criar uma consulta refinada usando dados de refinamento obtidos anteriormente

O exemplo a seguir CSOM mostra como executar uma consulta com uma especificação de refinador para criar dados de refinamento que subsequentemente são usados para executar o refinamento. Este exemplo simula o processo de um usuário final selecionando a opção de refinamento primeira.

using (var context = new ClientContext("http://<serverName>/<siteCollectionPath>"))
{
    // Step 1: Run the query with refiner spec to provide refinement data in search result
    var query = new KeywordQuery(context)
    {
        QueryText = "home",
        Refiners = "FileType,Write(discretize=manual/2013-01-01/2013-08-22/2013-09-15/2013-09-21/2013-09-22),companies"
    };

    Console.WriteLine("Run query '{0}' with refiner spec '{1}'.", query.QueryText, query.Refiners);
    var executor = new SearchExecutor(context);
    var results = executor.ExecuteQuery(query);
    context.ExecuteQuery();

    // The query has been run and we can now look at the refinement data, to view the
    // refinement options
    ResultTable relevantResultsTable = results.Value[0];
    ResultTable refinerResultsTable = results.Value[1];
    Console.WriteLine("Got back {0} refinement options in the result:",
        refinerResultsTable.RowCount);

    foreach (var refinementOption in refinerResultsTable.ResultRows)
    {
        Console.WriteLine("RefinerName: '{0}' RefinementName: '{1}'
            RefinementValue: '{2}' RefinementToken: '{3}' RefinementCount: '{4}'",
            refinementOption["RefinerName"],
            refinementOption["RefinementName"],
            refinementOption["RefinementValue"],
            refinementOption["RefinementToken"],
            refinementOption["RefinementCount"]
        );
    }

    // Step 2: Run the refined query with refinement filter to drill down into
    // the search results. This example uses the first refinement option in the refinement
    // data, if available. This simulates an end user selecting this refinement option.
    var refinementOptionArray = refinerResultsTable.ResultRows.ToArray();

    if (refinementOptionArray.Length > 0)
    {
        var firstRefinementOption = refinementOptionArray[6];
        // Construct the refinement filter by concatenation
        var refinementFilter = firstRefinementOption["RefinerName"] + ":" +
            firstRefinementOption["RefinementToken"];
        var refinedQuery = new KeywordQuery(context)
        {
            QueryText = query.QueryText
        };
        refinedQuery.RefinementFilters.Add(refinementFilter);
        refinedQuery.SelectProperties.Add("FileType");
        refinedQuery.SelectProperties.Add("Write");
        refinedQuery.SelectProperties.Add("Companies");
        Console.WriteLine("Run query '{0}' with refinement filter '{1}'",
            refinedQuery.QueryText, refinementFilter);
        var refinedResults = executor.ExecuteQuery(refinedQuery);
        context.ExecuteQuery();
        ResultTable refinedRelevantResultsTable = refinedResults.Value[0];
        var resultCount = 1;
        foreach (var relevantResult in refinedRelevantResultsTable.ResultRows)
        {
            Console.WriteLine("Relevant result number {0} has FileType='{1}',
                Write='{2}', Companies='{3}'",
                resultCount,
                relevantResult["FileType"],
                relevantResult["Write"],
                relevantResult["Companies"]
            );
            resultCount++;
        }
    }
}

Confira também

Outros recursos