Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
A pesquisa estruturada e de texto combina correspondência de texto classificada por relevância com valores exatos, intervalos numéricos e de datas, e outras condições numa só $search etapa. Mapeie campos de texto e campos estruturados no mesmo índice de pesquisa e, em seguida, use compound para combinar as condições.
Use esta abordagem para catálogos de produtos, bases de conhecimento e outras coleções onde o texto correspondente não seja suficiente. Por exemplo, procure uma descrição de produto, exigindo um produto em stock dentro de um intervalo de preços.
Note
A pesquisa de texto completo está em pré-visualização. Antes de utilizar estes exemplos, ative a pesquisa de texto completo no seu cluster.
Mapeamentos de campos suportados
Declare campos pesquisáveis em mappings.fields. Escolha um tipo que corresponda aos valores armazenados e às consultas de que necessita.
| Tipo de campo | Purpose | Consultas e ordenação suportadas |
|---|---|---|
string |
Texto analisado. |
text, difusa text, e phrase. |
document |
Contêiner para campos aninhados. | As consultas visam os seus campos de folha explicitamente mapeados. |
token |
Termos de strings exatas, como identificadores e categorias. |
equals, range, exists, in, e ordenação em linha. |
number |
Valores numéricos. |
equals, range, exists, in, e ordenação em linha. |
date |
Valores de data/hora. |
equals, range, exists, in, e ordenação em linha. |
boolean |
Valores booleanos. |
equals, exists, in, e ordenação em linha. |
Utilize string para texto de língua analisado e token para comparações exatas de cadeias de textos. Para campos numéricos, defina representation como double ou int64 conforme apropriado para os seus dados.
Os campos aninhados utilizam mapeamentos recursivos document.fields. Enderece campos folha mapeados com caminhos pontilhados, como details.region.
Os arrays não requerem um tipo de mapeamento separado. Mapeie o tipo dos seus elementos. Os valores do array são indexados quando o seu tipo corresponde ao mapeamento de campo; elementos com outros tipos não são indexados para esse campo.
Criar um índice de pesquisa para texto e campos estruturados
Os exemplos seguintes utilizam a sintaxe do MongoDB Shell e um cluster Azure DocumentDB ligado com a pesquisa de texto completo ativada. Utilize uma nova coleção chamada products.
Adicionar documentos de exemplo
Crie a coleção e adicione documentos com texto, identificadores, preços, disponibilidade e datas.
db.createCollection("products");
db.products.insertMany([
{
_id: 1,
title: "Bracket controller",
description: "Steel mounting bracket for a controller",
partNumber: "SKU-BRACKET-001",
category: "hardware",
price: 49.0,
inStock: true,
publishedAt: ISODate("2026-09-01T00:00:00Z"),
details: { region: "west" }
},
{
_id: 2,
title: "Bracket assembly",
description: "Heavy-duty bracket for an industrial controller",
partNumber: "SKU-BRACKET-002",
category: "hardware",
price: 129.0,
inStock: true,
publishedAt: ISODate("2026-10-01T00:00:00Z"),
details: { region: "east" }
},
{
_id: 3,
title: "Lightweight bracket",
description: "Compact bracket for a controller",
partNumber: "SKU-BRACKET-003",
category: "accessories",
price: 29.0,
inStock: false,
publishedAt: ISODate("2026-10-15T00:00:00Z"),
details: { region: "west" }
}
]);
Mapear os campos pesquisáveis
Crie um único índice que cubra todos os campos utilizados pelas consultas.
db.runCommand({
createSearchIndexes: "products",
indexes: [
{
name: "idx_products_filters",
definition: {
mappings: {
dynamic: false,
fields: {
title: { type: "string" },
description: { type: "string" },
partNumber: { type: "token" },
category: { type: "token" },
price: { type: "number", representation: "double" },
inStock: { type: "boolean" },
publishedAt: { type: "date" },
details: {
type: "document",
fields: {
region: { type: "token" }
}
}
}
}
}
}
]
});
Confirme que o índice está pronto
A criação do índice pode continuar depois de o comando terminar. Espere até que o índice reporte status: "READY" e queryable: true.
db.products.aggregate([
{ $listSearchIndexes: { name: "idx_products_filters" } }
]);
Combinar texto e condições estruturadas
Utilize compound para combinar documentos do operador. Cada cláusula contém um conjunto de condições.
| Clause | Behavior |
|---|---|
must |
Cada condição deve corresponder e contribuir para a relevância. |
should |
As condições de correspondência podem melhorar a relevância. Numa consulta com condições obrigatórias, elas não têm de corresponder. |
mustNot |
Os documentos correspondentes são excluídos. |
filter |
Todas as condições têm de corresponder. As condições podem atualmente afetar a relevância. |
A seguinte consulta pesquisa ambos os campos de texto, requer um produto em stock com preços de 20 a 100 e prefere uma frase exata no título:
db.products.aggregate([
{
$search: {
index: "idx_products_filters",
compound: {
must: [
{
text: {
query: "bracket controller",
path: ["title", "description"],
matchCriteria: "all"
}
}
],
should: [
{
phrase: {
query: "bracket controller",
path: "title",
slop: 0
}
}
],
filter: [
{ equals: { path: "inStock", value: true } },
{ range: { path: "price", gte: 20, lte: 100 } },
{ in: { path: "category", value: ["hardware", "accessories"] } },
{ exists: { path: "publishedAt" } }
],
mustNot: [
{ equals: { path: "details.region", value: "retired" } }
]
}
}
},
{ $limit: 10 },
{
$project: {
_id: 0,
title: 1,
partNumber: 1,
price: 1,
inStock: 1,
score: { $meta: "searchScore" }
}
}
]);
Para os dados de exemplo, a consulta devolve Bracket controller. A montagem mais cara e o suporte esgotado não satisfazem as condições exigidas.
Importante
compound.minimumShouldMatch não é atualmente suportado. As condições em compound.filter podem contribuir para a pontuação de relevância, bem como para restringir as correspondências. Não assuma que um filtro não altera as pontuações.
Utilizar operadores estruturados
Os operadores estruturados correspondem aos valores indexados e não ao texto analisado. Os tipos de valor da consulta devem corresponder ao mapeamento dos campos.
| Operator | Purpose | Opções necessárias |
|---|---|---|
equals |
Corresponde a um valor exato. |
path e value. |
range |
Corresponde aos valores delimitados num campo number, date ou token. |
path e pelo menos um de gt, gte, lt, ou lte. |
exists |
Corresponde aos documentos que têm um valor indexado no caminho. |
path. |
in |
Corresponde a um valor de um conjunto. |
path e um value array. |
Por exemplo, procure um número de peça exato com equals:
db.products.aggregate([
{
$search: {
index: "idx_products_filters",
equals: {
path: "partNumber",
value: "SKU-BRACKET-001"
}
}
},
{ $limit: 10 },
{ $project: { _id: 0, title: 1, partNumber: 1 } }
]);
Para intervalos de datas, use valores de data em vez de cadeias de caracteres:
db.products.aggregate([
{
$search: {
index: "idx_products_filters",
range: {
path: "publishedAt",
gte: ISODate("2026-10-01T00:00:00Z"),
lt: ISODate("2026-11-01T00:00:00Z")
}
}
},
{ $limit: 10 },
{ $project: { _id: 0, title: 1, publishedAt: 1 } }
]);
Pesquisar em múltiplos campos de texto
Passe um array explícito de caminhos mapeados para pesquisar múltiplos campos com text. Utilize matchCriteria: "any" para corresponder a qualquer termo de consulta analisado ou "all" para exigir todos os termos de consulta analisados.
db.products.aggregate([
{
$search: {
index: "idx_products_filters",
text: {
query: "bracket controller",
path: ["title", "description"],
matchCriteria: "all"
}
}
},
{ $limit: 20 },
{
$project: {
_id: 0,
title: 1,
description: 1,
score: { $meta: "searchScore" }
}
}
]);
Deve incluir todos os caminhos no índice de pesquisa selecionado. Uma text consulta aceita uma cadeia de consulta não vazia, não um array de cadeias de consulta. Para pesquisar múltiplos campos identificadores com diferentes requisitos de análise, consulte Analisadores personalizados.
Caminhos de consulta com wildcard não são suportados. Especifique explicitamente cada caminho mapeado.
Ordenar e limitar os resultados da pesquisa
Os resultados da pesquisa são ordenados por relevância decrescente por predefinição. Defina sort dentro $search para ordenar os resultados por campos escalares indexados.
db.products.aggregate([
{
$search: {
index: "idx_products_filters",
text: {
query: "bracket",
path: "description"
},
sort: {
inStock: -1,
price: 1,
score: { $meta: "searchScore" }
}
}
},
{ $limit: 20 },
{
$project: {
_id: 0,
title: 1,
price: 1,
inStock: 1,
score: { $meta: "searchScore" }
}
}
]);
A ordenação de campos em linha aceita 1 para ordem ascendente ou -1 decrescente em campos mapeados token, boolean, date, e number . A ordenação de pontuação é apenas decrescente. Evite a ordenação inline em campos com valores de array quando precisar da mesma semântica de ordenação de array que um $sort downstream.
Coloque $limit imediatamente depois de $search, sempre que possível. O limite é aplicado na execução da pesquisa para que o mecanismo possa parar após recolher os principais resultados solicitados.
Se uma condição não puder ser expressa com um operador de pesquisa suportado, utilize um filtro a jusante $match antes do $limit final. Limitar candidatos antes de aplicar um filtro empresarial pode omitir resultados elegíveis.
Limitações atuais
As seguintes restrições aplicam-se à pesquisa estruturada e composta:
- Os mapeamentos são estáticos. Deve declarar cada consulta e caminhos de ordenação inline no índice de pesquisa selecionado.
- Os tipos de campo
objectId,uuideembeddedDocumentnão são suportados. - O
nearoperador não é suportado. - Os
regexoperadores ewildcardoperadores no interior de$searchnão são suportados. - A fase
$searchMeta, a variável$$SEARCH_META, contagens, facetas, realce e aumentos de pontuação personalizados não são suportados. - Use o comando
dropIndexespara eliminar um índice de pesquisa. As APIs dedicadas de atualização de índice de pesquisa não fazem parte da superfície de gestão atualmente suportada.