Menu Docs

Página inicial do Docs → Iniciar e gerenciar o MongoDB → MongoDB Atlas

perto

Nesta página

  • Definição
  • Sintaxe
  • Opções
  • Comportamento de pontuação
  • Limitação
  • Exemplos

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 de BSON date digitam o 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 Atlas 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
Campo ou campos indexados a serem pesquisados. Veja Construção de caminhos.
sim
pivot
número

Valor a ser usado para calcular as pontuações dos documentos de resultados da Atlas 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.

  • A data pivot deve ser especificada em milissegundos e pode ser especificada como um número inteiro de 32 ou 64 bits.

    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.

Não

Comportamento de pontuação

A o Atlas Search score é uma medida da proximidade dos resultados da o Atlas Search 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 Atlas Search de origin é igual à distância longe da origem como calculado utilizando pivot.

A pontuação é calculada usando a seguinte fórmula:

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

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

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.

Limitação

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

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 no seu Atlas cluster, você poderá criar os índices estáticos utilizando as definições de índice nos exemplos abaixo ou o índice dinâmico e executar as queries de exemplo no seu cluster.

Dica

Se você já carregou o conjunto de dados de amostra, siga o tutorial Iniciar com Atlas Search para criar uma definição de índice e executar queries de Atlas Search.

Exemplo de número

O exemplo seguinte utiliza o operador near para consultar um campo de número.

Exemplo

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

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

A seguinte query procura documentos na coleção movies com um valor de campo runtime próximo a 279. 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": "runtime",
7            "origin": 279,
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])

A query acima retorna os seguintes resultados:

1{ "runtime" : 279, "title" : "The Kingdom", "score" : 1 }
2{ "runtime" : 279, "title" : "The Jinx: The Life and Deaths of Robert Durst", "score" : 1 }
3{ "runtime" : 280, "title" : "Shoah", "score" : 0.6666666865348816 }
4{ "runtime" : 281, "title" : "Les Misèrables", "score" : 0.5 }
5{ "runtime" : 277, "title" : "Tokyo Trial", "score" : 0.5 }
6{ "runtime" : 276, "title" : "Warriors of the Rainbow: Seediq Bale", "score" : 0.4000000059604645 }
7{ "runtime" : 283, "title" : "Scenes from a Marriage", "score" : 0.3333333432674408 }

Nos resultados do Atlas Search acima, 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 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 Atlas 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. 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 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 de pesquisa, 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}
← moreLikeThis
frase →

Nesta página