Menu Docs
Página inicial do Docs
/
MongoDB Atlas
/
Atlas Search
/
Crie e execute consultas
/
Crie uma consulta
/
5. Defina opções adicionais de pesquisa

Realçar termos de pesquisa nos resultados

Nesta página

  • Sintaxe
  • Opções
  • Saída
  • Pré-requisitos
  • Limitações
  • Exemplos
  • Coleção de amostras
  • Índice de amostra
  • Exemplos de queries

A opção highlight do Atlas Search adiciona campos ao conjunto de resultados que exibem os termos de pesquisa em seu contexto original. Você pode usá-lo em conjunto com todos os operadores $search para exibir os termos de pesquisa conforme eles aparecem nos documentos retornados, junto com o conteúdo de texto adjacente (se houver). Os resultados de highlight são retornados como parte do campo $meta.

Sintaxe

highlight tem a seguinte sintaxe:

{
  $search: {
    "index": "<index name>", // optional, defaults to "default"
    "<operator>": { // such as "text", "compound", or "phrase"
      <operator-specification>
    },
    "highlight": {
      "path": "<field-to-search>",
      "maxCharsToExamine": "<number-of-chars-to-examine>", // optional, defaults to 500,000
      "maxNumPassages": "<number-of-passages>" // optional, defaults to 5
    }
  }
},
{
  $project: {
    "highlights": { "$meta": "searchHighlights" }
  }
}

Opções

Campo
Tipo
Descrição
Obrigatório?

path

string

Campo de documento a ser pesquisado. O campo path pode conter:

  • Um string

  • Um array de strings

  • Uma especificação de multianalisador

  • Uma array contendo uma combinação de strings e especificações de vários analisadores

  • Personagem curinga *

Para mais informações, consulte Construir um caminho de query.

sim

maxCharsToExamine

int

Número máximo de caracteres a serem examinados em um documento quando se está realçando um campo. Se omitido, o padrão é 500,000, o que significa que o Atlas Search examina apenas os primeiros 500.000 caracteres no campo de pesquisa em cada documento para realce.

no

maxNumPassages

int

Número de passagens de alta pontuação para retornar por documento nos resultados highlights de cada campo. Uma passagem tem aproximadamente o comprimento de uma frase. Se omitido, o padrão é 5, o que significa que, para cada documento, o Atlas Search retorna as 5 passagens de maior pontuação que correspondem ao texto de pesquisa.

no

O campo "$meta": "searchHighlights" contém os resultados realçados. Esse campo não faz parte do documento original, então é necessário usar um estágio de pipeline$project para adicioná-lo à saída da consulta.

Saída

O campo highlights é uma array contendo os seguintes campos de saída:

Campo
Tipo
Descrição

path

string

Campo de documento que retornou uma correspondência.

texts

matriz de documentos

Cada correspondência de pesquisa retorna um ou mais objetos, contendo o texto correspondente e o texto do entorno (se houver).

texts.value

string

Texto do campo que retornou uma correspondência.

texts.type

string

Tipo de resultado. O valor pode ser um dos seguintes:

  • hit - Os resultados contêm o termo correspondente à query.

  • text - Os resultados contêm o conteúdo de texto adjacente ao termo correspondente.

score

float

Pontuação atribuída ao resultado correspondente. A pontuação highlights é uma medida da relevância do objeto highlights para a consulta. Se vários objetos highlights forem retornados, o objeto highlights mais relevante terá a pontuação mais alta.

Pré-requisitos

Você deve indexar o campo que deseja realçar como um tipo de string do Atlas Search com indexOptions configurado como offsets (padrão).

Limitações

Você não pode utilizar a opção highlight do Atlas Search em conjunto com o operador embeddedDocument.

Exemplos

Você pode tentar os seguintes exemplos no Atlas Search Playground ou no seu cluster do Atlas.

Coleção de amostras

Os exemplos nesta página usam uma collection chamada fruit que contém os seguintes documentos:

{
  "_id" : 1,
  "type" : "fruit",
  "summary" : "Apple varieties",
  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.",
  "category": "organic"
},
{
  "_id" : 2,
  "type" : "fruit",
  "summary" : "Banana",
  "description" : "Bananas are usually sold in bunches of five or six.",
  "category": "nonorganic"
},
{
  "_id" : 3,
  "type" : "fruit",
  "summary" : "Pear varieties",
  "description" : "Bosc and Bartlett are the most common varieties of pears.",
  "category": "nonorganic"
}

Índice de amostra

A coleção fruit também tem uma definição de índice que utiliza o analisador inglês e mapeamentos de campo dinâmicos.

{
  "analyzer": "lucene.english",
  "searchAnalyzer": "lucene.english",
  "mappings": {
    "dynamic": true
  }
}

Observação

Um aspecto útil do realce é que ele revela o texto original que a query de pesquisa retornou, que pode não ser exatamente igual ao termo pesquisado. Por exemplo, se você usar um analisador específico de idioma, suas pesquisas de texto retornarão todas variações de radicais dos seus termos de pesquisa.

Outro aspecto útil do realce é que ele pode ser utilizado para destacar qualquer campo, dentro ou fora da query path. Por exemplo, ao pesquisar um termo, você pode executar o realce para o termo da query no campo da query e em quaisquer outros campos especificados usando a opção highlight. Para saber mais, consulte Exemplo de vários campos.

Exemplos de queries

As queries a seguir demonstram a opção $search highlight nas queries do Atlas Search.

Exemplo básico

A seguinte query pesquisa variety e bunch no campo description da collection fruit com a opção highlight habilitada.

O estágio do pipeline $project restringe a saída ao campo description e adiciona um novo campo chamado highlights, que contém informações de destaque.

1db.fruit.aggregate([
2  {
3    $search: {
4      "text": {
5        "path": "description",
6        "query": ["variety", "bunch"]
7      },
8      "highlight": {
9        "path": "description"
10      }
11    }
12  },
13  {
14    $project: {
15      "description": 1,
16      "_id": 0,
17      "highlights": { "$meta": "searchHighlights" }
18    }
19  }
20])
1{
2  "description" : "Bananas are usually sold in bunches of five or six. ",
3  "highlights" : [
4    {
5      "path" : "description",
6      "texts" : [
7        {
8          "value" : "Bananas are usually sold in ",
9          "type" : "text"
10        },
11        {
12          "value" : "bunches",
13          "type" : "hit"
14        },
15        {
16          "value" : " of five or six. ",
17          "type" : "text"
18        }
19      ],
20      "score" : 1.2841906547546387
21    }
22  ]
23}
24{
25  "description" : "Bosc and Bartlett are the most common varieties of pears.",
26  "highlights" : [
27    {
28      "path" : "description",
29      "texts" : [
30        {
31          "value" : "Bosc and Bartlett are the most common ",
32          "type" : "text"
33        },
34        {
35          "value" : "varieties",
36          "type" : "hit"
37        },
38        {
39          "value" : " of pears.",
40          "type" : "text"
41        }
42      ],
43      "score" : 1.2691514492034912
44    }
45  ]
46}
47{
48  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith. ",
49  "highlights" : [
50    {
51      "path" : "description",
52      "texts" : [
53        {
54          "value" : "Apples come in several ",
55          "type" : "text"
56        },
57        {
58          "value" : "varieties",
59          "type" : "hit"
60        },
61        {
62          "value" : ", including Fuji, Granny Smith, and Honeycrisp. ",
63          "type" : "text"
64        }
65      ],
66      "score" : 1.0330637693405151
67    },
68    {
69      "path" : "description",
70      "texts" : [
71        {
72          "value" : "The most popular ",
73          "type" : "text"
74        },
75        {
76          "value" : "varieties",
77          "type" : "hit"
78        },
79        {
80          "value" : " are McIntosh, Gala, and Granny Smith. ",
81          "type" : "text"
82        }
83      ],
84      "score" : 1.0940992832183838
85    }
86  ]
87}

O termo de pesquisa bunch retorna uma correspondência no documento com _id: 2, pois o campo description contém a palavra bunches. O termo de pesquisa variety retorna uma correspondência nos documentos com _id: 3 e _id: 1, pois o campo description contém a palavra varieties.

➤ Experimente isso no Atlas Search Playground.

Exemplo avançado

A seguinte consulta pesquisa por variety e bunch no campo description da coleção fruit, com a opção highlight habilitada, número máximo de caracteres a ser examinado definido como 40 e somente 1 passagem de pontuação alta para retornar por documento.

O estágio do pipeline $project restringe a saída ao campo description e adiciona um novo campo chamado highlights, que contém informações de destaque.

1db.fruit.aggregate([
2  {
3    $search: {
4      "text": {
5        "path": "description",
6        "query": ["variety", "bunch"]
7      },
8      "highlight": {
9        "path": "description",
10        "maxNumPassages": 1,
11        "maxCharsToExamine": 40
12      }
13    }
14  },
15  {
16    $project: {
17      "description": 1,
18      "_id": 0,
19      "highlights": { "$meta": "searchHighlights" }
20    }
21  }
22])
1{
2  "description" : "Bananas are usually sold in bunches of five or six. ",
3  "highlights" : [
4    {
5      "path" : "description",
6      "texts" : [
7        {
8          "value" : "Bananas are usually sold in ",
9          "type" : "text"
10        },
11        {
12          "value" : "bunches",
13          "type" : "hit"
14        },
15        {
16          "value" : " of f",
17          "type" : "text"
18        }
19      ],
20      "score" : 1.313065767288208
21    }
22  ]
23}
24{
25  "description" : "Bosc and Bartlett are the most common varieties of pears.",
26  "highlights" : [ ]
27}
28{
29  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.",
30  "highlights" : [
31    {
32      "path" : "description",
33      "texts" : [
34        {
35          "value" : "Apples come in several ",
36          "type" : "text"
37        },
38        {
39          "value" : "varieties",
40          "type" : "hit"
41        },
42        {
43          "value" : ", includ",
44          "type" : "text"
45        }
46      ],
47      "score" : 0.9093900918960571
48    }
49  ]
50}

O segundo documento nos resultados acima contém um array highlights vazio, embora o campo de pesquisa contenha o termo de pesquisa varieties porque o Atlas Search examinou apenas 40 caracteres para realce. Da mesma forma, a palavra includ é truncada porque o Atlas Search examinou apenas 40 caracteres no campo de pesquisa para realce. No terceiro documento, embora várias passagens contenham o termo de pesquisa, o Atlas Search retorna apenas uma passagem nos resultados dehighlights porque a query exigia apenas 1 passagem por documento nos resultados de highlights.

➤ Experimente isso no Atlas Search Playground.

Exemplo de vários campos

A query a seguir pesquisa varieties no campo description da collection fruit, com a opção highlight habilitada para os campos description e summary.

O estágio do pipeline $project adiciona um novo campo chamado highlights, que contém informações de destaque para o termo da query em todos os campos na opção highlight.

1db.fruit.aggregate([
2  {
3    $search: {
4      "text": {
5        "path": "description",
6        "query": "varieties"
7      },
8      "highlight": {
9        "path": ["description", "summary" ]
10      }
11    }
12  },
13  {
14    $project: {
15      "description": 1,
16      "summary": 1,
17      "_id": 0,
18      "highlights": { "$meta": "searchHighlights" }
19    }
20  }
21])
1{
2  "summary" : "Pear varieties",
3  "description" : "Bosc and Bartlett are the most common varieties of pears.",
4  "highlights" : [
5    {
6      "path" : "summary",
7      "texts" : [
8        {
9          "value" : "Pear ",
10          "type" : "text"
11        },
12        {
13          "value" : "varieties",
14          "type" : "hit"
15        }
16      ],
17      "score" : 1.3891443014144897 },
18    {
19      "path" : "description",
20      "texts" : [
21        {
22          "value" : "Bosc and Bartlett are the most common ",
23          "type" : "text"
24        },
25        {
26          "value" : "varieties",
27          "type" : "hit"
28        },
29        {
30          "value" : " of pears.",
31          "type" : "text"
32        }
33      ],
34      "score" : 1.2691514492034912
35    }
36  ]
37}
38{
39  "summary" : "Apple varieties",
40  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.",
41  "highlights" : [
42    {
43      "path" : "summary",
44      "texts" : [
45        {
46          "value" : "Apple ",
47          "type" : "text"
48        },
49        {
50          "value" : "varieties",
51          "type" : "hit"
52        }
53      ],
54      "score" : 1.3859853744506836
55    },
56    {
57      "path" : "description",
58      "texts" : [
59        {
60          "value" : "Apples come in several ",
61          "type" : "text"
62        },
63        {
64          "value" : "varieties",
65          "type" : "hit"
66        },
67        {
68          "value" : ", including Fuji, Granny Smith, and Honeycrisp. ",
69          "type" : "text"
70        }
71      ],
72      "score" : 1.0330637693405151
73    },
74    {
75      "path" : "description",
76      "texts" : [
77        {
78          "value" : "The most popular ",
79          "type" : "text"
80        },
81        {
82          "value" : "varieties",
83          "type" : "hit"
84        },
85        {
86          "value" : " are McIntosh, Gala, and Granny Smith.",
87          "type" : "text"
88        }
89      ],
90      "score" : 1.0940992832183838
91    }
92  ]
93}

O termo de pesquisa varieties retorna uma correspondência em documentos com _id: 1 e _id: 3 porque o campo de consulta description em ambos os documentos contém o termo de consulta varieties. Além disso, a matriz highlights inclui o campo summary porque o campo contém o termo de consulta varieties.

➤ Experimente isso no Atlas Search Playground.

Exemplo de curinga

A query abaixo pesquisa o termo varieties em campos que começam com des na collection fruit, com a opção highlight habilitada para campos que começam com des.

O estágio do pipeline $project adiciona um novo campo chamado highlights, que contém informações de destaque.

1db.fruit.aggregate([
2  {
3    "$search": {
4      "text": {
5        "path": {"wildcard": "des*"},
6        "query": ["variety"]
7      },
8      "highlight": {
9        "path": {"wildcard": "des*"}
10      }
11    }
12  },
13  {
14    "$project": {
15      "description": 1,
16      "_id": 0,
17      "highlights": { "$meta": "searchHighlights" }
18    }
19  }
20])
1{
2  "description" : "Bosc and Bartlett are the most common varieties of pears.",
3  "highlights" : [
4    {
5      "path" : "description",
6      "texts" : [
7        {
8          "value" : "Bosc and Bartlett are the most common ",
9          "type" : "text"
10        },
11        {
12          "value" : "varieties",
13          "type" : "hit"
14        },
15        {
16          "value" : " of pears.",
17          "type" : "text"
18        }
19      ],
20      "score" : 1.2691514492034912
21    }
22  ]
23},
24{
25  "description" : "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.",
26  "highlights" : [
27    {
28      "path" : "description",
29      "texts" : [
30        {
31          "value" : "Apples come in several ",
32          "type" : "text"
33        },
34        {
35          "value" : "varieties",
36          "type" : "hit"
37        },
38        {
39          "value" : ", including Fuji, Granny Smith, and Honeycrisp. ",
40          "type" : "text"
41        }
42      ],
43      "score" : 1.0330637693405151
44    },
45    {
46      "path" : "description",
47      "texts" : [
48        {
49          "value" : "The most popular ",
50          "type" : "text"
51        },
52        {
53          "value" : "varieties",
54          "type" : "hit"
55        },
56        {
57          "value" : " are McIntosh, Gala, and Granny Smith.",
58          "type" : "text"
59        }
60      ],
61      "score" : 1.0940992832183838
62    }
63  ]
64}

Nos resultados do Atlas Search, os campos que começam com des são destacados.

➤ Experimente isso no Atlas Search Playground.

Exemplo composto

A seguinte consulta procura o termo organic no campo category e variety no campo description. A opção highlight na consulta composta $searchsolicita informações de realce apenas para a consulta de texto em relação ao campo description. Observe que a opção highlight dentro do estágio $search deve ser filha do estágio $search, e não de qualquer operador dentro do estágio $search.

O estágio do pipeline $project adiciona um novo campo chamado highlights, que contém informações de destaque.

1db.fruit.aggregate([
2  {
3    "$search": {
4      "compound": {
5        "should": [{
6          "text": {
7            "path": "category",
8            "query": "organic"
9          }
10        },
11        {
12          "text": {
13            "path": "description",
14            "query": "variety"
15          }
16        }]
17      },
18      "highlight": {
19        "path": "description"
20      }
21    }
22  },
23  {
24    "$project": {
25      "description": 1,
26      "category": 1,
27      "_id": 0,
28      "highlights": { "$meta": "searchHighlights" }
29    }
30  }
31])
1[
2  {
3    description: 'Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.',
4    category: 'organic',
5    highlights: [
6      {
7        score: 1.0330637693405151,
8        path: 'description',
9        texts: [
10          { value: 'Apples come in several ', type: 'text' },
11          { value: 'varieties', type: 'hit' },
12          {
13            value: ', including Fuji, Granny Smith, and Honeycrisp. ',
14            type: 'text'
15          }
16        ]
17      },
18      {
19        score: 1.0940992832183838,
20        path: 'description',
21        texts: [
22          { value: 'The most popular ', type: 'text' },
23          { value: 'varieties', type: 'hit' },
24          {
25            value: ' are McIntosh, Gala, and Granny Smith.',
26            type: 'text'
27          }
28        ]
29      }
30    ]
31  },
32  {
33    description: 'Bosc and Bartlett are the most common varieties of pears.',
34    category: 'nonorganic',
35    highlights: [
36      {
37        score: 1.2691514492034912,
38        path: 'description',
39        texts: [
40          {
41            value: 'Bosc and Bartlett are the most common ',
42            type: 'text'
43          },
44          { value: 'varieties', type: 'hit' },
45          { value: ' of pears.', type: 'text' }
46        ]
47      }
48    ]
49  }
50]

➤ Experimente isso no Atlas Search Playground.

Exemplo de preenchimento automático

Neste exemplo, a collection fruit também tem a seguinte definição de índice.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "description": [
       {
        "type": "autocomplete",
        "tokenization": "edgeGram",
        "minGrams": 2,
        "maxGrams": 15,
        "foldDiacritics": true
       }
      ]
    }
  }
}

A seguinte query procura os caracteres var no campo description da collection fruit, com a opção highlight habilitada para o campo description.

O estágio do pipeline $project adiciona um novo campo chamado highlights, que contém informações de destaque.

Importante

Para destacar a versão indexada do preenchimento automático de um caminho, o operador de preenchimento automático deve ser o único operador que usa esse caminho na query.

1db.fruit.aggregate([
2  {
3    "$search": {
4      "autocomplete": {
5        "path": "description",
6        "query": ["var"]
7      },
8      "highlight": {
9        "path": "description"
10      }
11    }
12  },
13  {
14    "$project": {
15      "description": 1,
16      "_id": 0,
17      "highlights": { "$meta": "searchHighlights" }
18    }
19  }
20])
1{
2  "description": "Apples come in several varieties, including Fuji, Granny Smith, and Honeycrisp. The most popular varieties are McIntosh, Gala, and Granny Smith.",
3  "highlights": [
4    {
5      "score": 0.774385392665863,
6      "path": "description",
7      "texts": [
8        { "value": "Apples come in several ", "type": "text" },
9        { "value": "varieties, including Fuji", "type": "hit" },
10        { "value": ", Granny Smith, and Honeycrisp. ", "type": "text" }
11      ]
12    },
13    {
14      "score": 0.7879307270050049,
15      "path": "description",
16      "texts": [
17        { "value": "The most popular ", "type": "text" },
18        { "value": "varieties are McIntosh", "type": "hit" },
19        { "value": ", Gala, and Granny Smith.", "type": "text" }
20      ]
21    }
22  ]
23},
24{
25  "description": "Bosc and Bartlett are the most common varieties of pears.",
26  "highlights": [
27    {
28      "score": 0.9964432120323181,
29      "path": "description",
30      "texts": [
31        {
32          "value": "Bosc and Bartlett are the most common ",
33          "type": "text"
34        },
35        { "value": "varieties of pears", "type": "hit" },
36        { "value": ".", "type": "text" }
37      ]
38    }
39  ]
40}

O Atlas Search retorna uma correspondência nos documentos com _id: 1 e id_: 2 para a string da query var porque o campo description na collection fruit contém os caracteres var no início de uma palavra. O Atlas Search corresponde um realce hit mais grosseiro para os termos da query quando um caminho realçado é referenciado apenas nos operadores com preenchimento automático da query realçada.

➤ Experimente isso no Atlas Search Playground.