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.

The near operator uses the following distance decay function to calculate document score:

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

where each term is defined as follows:

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 is the value of the field that you are querying in the document.

  • origin is the number, date, or geographic point to search near.

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 .

Se você carregar os dados de amostra em seu cluster, poderá criar os índices estáticos usando as definições de índice nos exemplos abaixo ou o índice dinâmico e executar as queries de exemplo no cluster.

Dica

Se já tiver carregado o conjunto de dados de amostra, consulte o tutorial Início Rápido do MongoDB Search para criar uma definição de índice e executar queries do MongoDB Search.

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

A consulta seguinte procura propriedades em Portugal. Inclui um estágio $limit para limitar o resultado para 3 resultados e um estágio $project para:

  • 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

A seguinte consulta procura apartamentos em Hong Kong perto de um ponto GeoJSON especificado. A query usa must para especificar a condição do Atlas Search , que deve ser atendida, e should para especificar a preferência por localização. Ele inclui um estágio $limit para limitar a saída a 3 resultados e um estágio $project para:

  • 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