Menu Docs
Página inicial do Docs
/ /
opções de pesquisa
Página inicial do Docs
/ /
Referência de query
/
opções de pesquisa
Página inicial do Docs
/
Desenvolvimento
/
Pesquisa
/
Queries e índices
/
Referência de query
/
opções de pesquisa

Realçar termos de pesquisa nos resultados

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

highlight Limitações de opção

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

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 *

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 MongoDB 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 MongoDB 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 MongoDB Search com indexOptions configurado como offsets (padrão).

Exemplos

Você pode tentar os exemplos a seguir no MongoDB Search Playground ou em seu cluster.

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 seguintes queries demonstram a opção $search highlight nas queries do MongoDB 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.

➤ Tente fazer isso no playground do MongoDB Search.

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 MongoDB Search examinou apenas 40 caracteres para realce. Da mesma forma, a palavra includ é truncada porque o MongoDB Search examinou apenas 40 caracteres no campo de pesquisa para realce. No terceiro documento, embora várias passagens contenham o termo de pesquisa , o MongoDB Search retorna apenas uma passagem nos resultados de highlights porque a query exigia apenas 1 passagem por documento nos resultados de highlights.

➤ Tente fazer isso no playground do MongoDB Search.

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.

➤ Tente fazer isso no playground do MongoDB Search.

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 MongoDB Search, os campos que começam com des ficam em realce.

➤ Tente fazer isso no playground do MongoDB Search.

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]

➤ Tente fazer isso no playground do MongoDB Search.

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 MongoDB Search retorna uma correspondência nos documentos com _id: 1 e id_: 2 para a string de query var porque o campo description na collection fruit contém os caracteres var no início de uma palavra. O MongoDB Search corresponde um destaque hit de maneira mais grosseira aos termos da sua consulta quando um caminho destacado é referenciado apenas nos operadores de preenchimento automático da consulta destacada.

➤ Tente fazer isso no playground do MongoDB Search.

Nesta página