Make the MongoDB docs better! We value your opinion. Share your feedback for a chance to win $100.
Click here >
Menu Docs
Página inicial do Docs
/ /
Operadores e coletores
Página inicial do Docs
/ /
Referência de query
/
Operadores e coletores
Página inicial do Docs
/
Desenvolvimento
/
Pesquisa
/
Queries e índices
/
Referência de query
/
Operadores e coletores

near ( Operador de pesquisa MongoDB )

near Limitações do operador

Você não pode usar o operador near para consultar valores numéricos ou de data armazenados em uma array, mesmo que você tenha um índice do MongoDB Search. Você pode utilizar o intervalo somente para consultar valores numéricos indexados ou de data dentro de arrays.

Definição

near

O operador near suporta consultar e classificar valores numéricos, de data e de ponto GeoJSON. Este operador pode ser usado para realizar uma pesquisa sobre:

  • Campos numéricos dos tipos de dados BSON int32, int64 e double.

  • Os campos de data do BSON date tipo no formatoISODate .

  • Campos de localização geográfica definidos usando coordenadas de latitude e longitude.

Você pode usar o operador near para encontrar resultados próximos a um número ou data. O operador near pontua os resultados da MongoDB Search por proximidade do número ou da data.

Sintaxe

near tem a seguinte sintaxe:

{
   $search: {
      "index": <index name>, // optional, defaults to "default"
      "near": {
         "path": "<field-to-search>",
         "origin": <date-or-number>,
         "pivot": <pivot-distance>,
         "score": <score-options>
      }
   }
}

Opções

near usa os seguintes termos para construir uma consulta:

Campo
Tipo
Descrição
necessidade

origin

data, número ou localidade

Número, data ou ponto geográfico para pesquisar próximo. Esta é a origem da qual a proximidade dos resultados é medida.

  • Para campos numéricos, o valor deve ser de BSON int32, int64ou double tipos de dados.

  • Para campos de data, o valor deve ser uma data formatada ISODate.

  • Para campos geo. o valor deve ser um ponto GeoJSON.

sim

path

cadeia de caracteres ou matriz de cadeias de caracteres

Campos indexados a serem pesquisados.

sim

pivot

número

Valor a ser usado para calcular as pontuações dos documentos de resultados da MongoDB Search. A pontuação é calculada usando a seguinte fórmula:

              pivot
score = ------------------
         pivot + distance

onde distance é a diferença entre origin e o valor de campo indexado.

Os resultados têm uma pontuação igual a 1/2 (ou 0.5) quando o valor do campo indexado está a pivot unidades de distância de origin. O valor de pivot deve ser maior que (ou seja, >) 0.

Se origin for um:

  • Número, pivot pode ser especificado como um número inteiro ou número de ponto flutuante.

  • Data, pivot deve ser especificado em milissegundos e pode ser especificado como um inteiro de 32 ou 64 bits. Por exemplo:

    • 1 minuto é igual a 60,000 ms

    • 1 hora é igual a 3,600,000 ms

    • 1 dia é igual a 86,400,000 ms

    • 1 mês (ou 30 dias) é igual a 2,592,000,000 ms

  • Ponto GeoJSON, pivot é medido em metros e deve ser especificado como um número inteiro ou ponto flutuante.

sim

score

objeto

Pontuação a ser atribuída aos resultados de pesquisa correspondentes. Você pode modificar a pontuação padrão usando as seguintes opções:

  • boost: multiplique a pontuação do resultado pelo número fornecido.

  • constant: substitui a pontuação do resultado pelo número fornecido.

  • function: substitua a pontuação do resultado pela expressão fornecida.

Para obter informações sobre como utilizar o score em sua consulta, consulte Classificar os documentos nos resultados.

Para saber mais, consulte Comportamento de pontuação.

no

Comportamento de pontuação

A Pesquisa do MongoDB score é uma medida da proximidade dos resultados da Pesquisa do MongoDB para origin. O score é dimensionado entre 0 e 1 com 1 sendo uma correspondência exata e 0 sendo uma correspondência distante. A pontuação é igual a 0.5 quando a distância do resultado da Pesquisa MongoDB de origin é igual à distância longe da origem como calculado utilizando pivot.

O operador near usa a seguinte função de decaimento de distância para calcular a pontuação do documento:

              pivot
score = ------------------
         pivot + distance

onde cada termo é definido da seguinte forma:

Fator
Descrição

pivot

Valor especificado como ponto de referência para tornar a pontuação igual a 0.5 se a distância entre fieldValue e origin for igual a ele. Isso define a rapidez com que a pontuação diminui à medida que a distância entre fieldValue e origin aumenta. Para uma determinada distância entre fieldValue e origin, se pivot diminuir, a pontuação também diminui.

distance

Distância absoluta entre fieldValue e origin. O MongoDB Search calcula esse valor usando a seguinte fórmula:

abs(fieldValue - origin)

onde:

  • fieldValue é o valor do campo que você está consultando no documento.

  • origin é o número, data ou ponto geográfico para pesquisar próximo.

Você pode modificar a pontuação padrão utilizando a opção score em sua query. Para saber mais sobre as opções, Modifique a pontuação.

Exemplos

Os exemplos de número e data utilizam a coleção movies no banco de dados do sample_mflix . O exemplo Ponto GeoJSON utiliza a coleção listingsAndReviews no banco de dados sample_airbnb .

If you load the sample data on your cluster, you can create the static indexes using the index definitions in the examples below or the dynamic index and run the example queries on your cluster.

Dica

If you've already loaded the sample dataset, refer to the MongoDB Search Quick Start tutorial to create an index definition and run MongoDB Search queries.

Exemplo de número

O exemplo seguinte utiliza o operador near para consultar um campo de número. As queries a seguir usam um índice chamado runtimes que indexa dinamicamente todos os campos na coleção movies. A query pesquisa documentos na coleção movies com um valor de campo runtime que está próximo de 279.

Exemplo básico

A seguinte query retorna todos os documentos que correspondem aos critérios de pesquisa. Inclui um estágio do $limit para limitar o resultado para 7 resultados e um estágio do $project para:

  • Excluir todos os campos, exceto title e runtime

  • Adicione um campo chamado score

O score é calculado utilizando pivot.

1db.movies.aggregate([
2  {
3    $search: {
4      "index": "runtimes",
5      "near": {
6        "path": "year",
7        "origin": 2000,
8        "pivot": 2
9      }
10    }
11  },
12  {
13    $limit: 7
14  },
15  {
16    $project: {
17      "_id": 0,
18      "title": 1,
19      "runtime": 1,
20      score: { $meta: "searchScore" }
21    }
22  }
23])
[
  { runtime: 279, title: 'The Kingdom', score: 1 },
  { runtime: 279, title: 'The Kingdom', score: 1 },
  { runtime: 279, title: 'The Jinx: The Life and Deaths of Robert Durst', score: 1  },
  { runtime: 281, title: 'Les Misèrables', score: 0.5 },
  { runtime: 277, title: 'Tokyo Trial', score: 0.5 },
  { runtime: 283, title: 'Scenes from a Marriage', score: 0.3333333432674408 },
  { runtime: 274, title: 'The Crimson Petal and the White', score: 0.2857142984867096 }
]

Nos resultados do MongoDB Search, os filmes The Kingdom e The Jinx: The Life and Deaths of Robert Durst recebem uma pontuação de 1.0 porque seu valor de campo runtime de 279 é uma correspondência exata. Os filmes Les Misèrables e Tokyo Trial recebem uma pontuação de 0.5 porque seu valor de campo runtime está a 2 unidades de 279.

Exemplo de metadados

A query a seguir retorna os resultados de metadados para os critérios de pesquisa. Ou seja, ela usa o estágio $searchMeta para obter o número de filmes nos seguintes intervalos (anos) que correspondem aos critérios de pesquisa:

  • 2000, limite inferior inclusivo para este bucket

  • 2005, limite superior exclusivo para o bucket 2000 e limite inferior inclusivo para esse bucket

  • 2010, limite superior exclusivo para o bucket 2005 e limite inferior inclusivo para esse bucket

  • 2010, limite superior exclusivo para o bucket 2010

1db.movies.aggregate([
2  {
3    "$searchMeta": {
4      "facet": {
5        "operator": {
6          "near": {
7            "path": "runtime",
8            "origin": 279,
9            "pivot": 2
10          }
11        },
12        "facets": {
13          "yearFacet": {
14            "type": "number",
15            "path": "year",
16            "boundaries": [2000, 2005, 2010, 2015 ]
17          }
18        }
19      }
20    }
21  }
22])
[
  {
    count: { lowerBound: Long('20910') },
    facet: {
      yearFacet: {
        buckets: [
          { _id: 2000, count: Long('3058') },
          { _id: 2005, count: Long('4012') },
          { _id: 2010, count: Long('4669') }
        ]
      }
    }
  }
]

Exemplo de data

O exemplo seguinte utiliza o operador near para consultar um campo de data.

Exemplo

A seguinte definição de índice chamada releaseddate indexa os valores de campo released na coleção movies :

1{
2   "mappings": {
3      "dynamic": false,
4      "fields": {
5         "released": {
6            "type": "date"
7         }
8      }
9   }
10}

A query a seguir procura filmes lançados perto de 13 de setembro de 1. Inclui um estágio do $limit para limitar o resultado para 3 resultados e um estágio do $project para:

  • Excluir todos os campos, exceto title e released

  • Adicione um campo chamado score

O score dos resultados é calculado utilizando pivot.

Observação

pivot é medido aqui em milissegundos e 7,776,000,000 ms é igual a aproximadamente três meses.

1db.movies.aggregate([
2   {
3      $search: {
4         "index": "releaseddate",
5         "near": {
6            "path": "released",
7            "origin": ISODate("1915-09-13T00:00:00.000+00:00"),
8            "pivot": 7776000000
9         }
10      }
11   },
12   {
13      $limit: 3
14   },
15   {
16      $project: {
17         "_id": 0,
18         "title": 1,
19         "released": 1,
20         score: { $meta: "searchScore" }
21      }
22   }
23])

A query acima retorna os seguintes resultados de pesquisa:

{ "title" : "Regeneration", "released" : ISODate("1915-09-13T00:00:00Z"), "score" : 1 }
{ "title" : "The Cheat", "released" : ISODate("1915-12-13T00:00:00Z"), "score" : 0.49723756313323975 }
{ "title" : "Hell's Hinges", "released" : ISODate("1916-03-05T00:00:00Z"), "score" : 0.34090909361839294 }

Nos resultados do MongoDB Search acima, o filme Regeneration recebe uma pontuação de 1 porque o valor do campo released de 1915-09-13 é uma correspondência exata. O filme The Cheat, que foi lançado em 1915-12-13, recebe uma pontuação de aproximadamente 0.5 porque a distância do valor do campo released em relação a origin é de aproximadamente 7,776,000,000 milissegundos em relação a 1915-09-13.

Exemplos de Pontos GeoJSON

Os exemplos seguintes utilizam o operador near para consultar um objeto de ponto GeoJSON na coleção sample_airbnb.listingsAndReviews . A seguinte definição de índice indexa os campos address.location e property_type na coleção listingsAndReviews.

Exemplo

1{
2  "mappings": {
3    "fields": {
4      "address": {
5        "fields": {
6          "location": {
7            "type": "geo"
8          }
9        },
10        "type": "document"
11      },
12      "property_type": {
13        "type": "string"
14      }
15    }
16  }
17}

Exemplo básico

Os exemplos seguintes utilizam o operador near para consultar o campo address.location na coleção do sample_airbnb.listingsAndReviews.

Exemplo

The following query searches for properties in Portugal. It includes a $limit stage to limit the output to 3 results and a $project stage to:

  • Excluir todos os campos, exceto name e address

  • Adicione um campo chamado score

O score dos resultados é calculado usando pivot. Observe que pivot é medido aqui em metros e 1.000 metros é igual a 1 quilômetro.

1db.listingsAndReviews.aggregate([
2  {
3    "$search": {
4      "near": {
5        "origin": {
6          "type": "Point",
7          "coordinates": [-8.61308, 41.1413]
8        },
9        "pivot": 1000,
10        "path": "address.location"
11      }
12    }
13  },
14  {
15    $limit: 3
16  },
17  {
18    $project: {
19      "_id": 0,
20      "name": 1,
21      "address": 1,
22      score: { $meta: "searchScore" }
23    }
24  }
25])

A query acima retorna os seguintes resultados de pesquisa:

1{
2  "name" : "Ribeira Charming Duplex",
3  "address" : {
4    "street" : "Porto, Porto, Portugal",
5    "suburb" : "",
6    "government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
7    "market" : "Porto",
8    "country" : "Portugal",
9    "country_code" : "PT",
10    "location" : {
11      "type" : "Point",
12      "coordinates" : [ -8.61308, 41.1413 ],
13      "is_location_exact" : false
14    }
15  },
16  "score" : 1
17}
18{
19  "name" : "DB RIBEIRA - Grey Apartment",
20  "address" : {
21    "street" : "Porto, Porto, Portugal",
22    "suburb" : "",
23    "government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
24    "market" : "Porto",
25    "country" : "Portugal",
26    "country_code" : "PT",
27    "location" : {
28      "type" : "Point",
29      "coordinates" : [ -8.61294, 41.14126 ],
30      "is_location_exact" : true
31    }
32  },
33  "score" : 0.9876177310943604
34}
35{
36  "name" : "Ribeira 24 (4)",
37  "address" : {
38    "street" : "Porto, Porto, Portugal",
39    "suburb" : "",
40    "government_area" : "Cedofeita, Ildefonso, Sé, Miragaia, Nicolau, Vitória",
41    "market" : "Porto",
42    "country" : "Portugal",
43    "country_code" : "PT",
44    "location" : {
45      "type" : "Point",
46      "coordinates" : [ -8.61318, 41.14107 ],
47      "is_location_exact" : false
48    }
49  },
50  "score" : 0.973789632320404
51}

Os resultados mostram que as propriedades que estão mais distantes das coordenadas especificadas têm uma pontuação mais baixa.

Exemplo composto

O exemplo a seguir usa o operador compound para consultar os campos property_type e address.location na coleção sample_airbnb.listingsAndReviews .

Exemplo

The following query searches for apartments in Hong Kong near a specified GeoJSON point. The query uses must to specify the search condition, which must be met, and should to specify preference for location. It includes a $limit stage to limit the output to 3 results and a $project stage to:

  • Excluir todos os campos, exceto property_type e address

  • Adicione um campo chamado score

O score é calculado utilizando o campo pivot. Observe que pivot é medido aqui em metros e 1000 metros é igual a 1 quilômetro.

1db.listingsAndReviews.aggregate([
2  {
3    $search: {
4      "compound": {
5        "must": {
6          "text": {
7            "query": "Apartment",
8            "path": "property_type"
9          }
10        },
11        "should": {
12          "near": {
13            "origin": {
14              "type": "Point",
15              "coordinates": [114.15027, 22.28158]
16            },
17            "pivot": 1000,
18            "path": "address.location"
19          }
20        }
21      }
22    }
23  },
24  {
25    $limit: 3
26  },
27  {
28    $project: {
29      "_id": 0,
30      "property_type": 1,
31      "address": 1,
32      score: { $meta: "searchScore" }
33    }
34  }
35])

A query acima retorna os seguintes resultados de pesquisa:

1{
2  "property_type" : "Apartment",
3  "address" : {
4    "street" : "Hong Kong, Hong Kong Island, Hong Kong",
5    "suburb" : "Central & Western District",
6    "government_area" : "Central & Western",
7    "market" : "Hong Kong",
8    "country" : "Hong Kong",
9    "country_code" : "HK",
10    "location" : {
11      "type" : "Point",
12      "coordinates" : [ 114.15027, 22.28158 ],
13      "is_location_exact" : true
14    }
15  },
16  "score" : 1.177286982536316
17}
18{
19  "property_type" : "Apartment",
20  "address" : {
21    "street" : "Hong Kong, Hong Kong Island, Hong Kong",
22    "suburb" : "Central & Western District",
23    "government_area" : "Central & Western",
24    "market" : "Hong Kong",
25    "country" : "Hong Kong",
26    "country_code" : "HK",
27    "location" : {
28      "type" : "Point",
29      "coordinates" : [ 114.15082, 22.28161 ],
30      "is_location_exact" : true
31    }
32  },
33  "score" : 1.1236450672149658
34}
35{
36  "property_type" : "Apartment",
37  "address" : {
38    "street" : "Hong Kong,
39    Hong Kong Island, Hong Kong",
40    "suburb" : "Mid-Levels",
41    "government_area" : "Central & Western",
42    "market" : "Hong Kong",
43    "country" : "Hong Kong",
44    "country_code" : "HK",
45    "location" : {
46      "type" : "Point",
47      "coordinates" : [ 114.15007, 22.28215 ],
48      "is_location_exact" : true
49    }
50  },
51  "score" : 1.114811897277832
52}

Voltar

moreLikeThis

Próximo

frase

Nesta página