/ /

Referência de query

Estágios de pipeline

Página inicial do Docs

`$search`

$search: The $search stage performs a full-text search on the specified field or fields. The field or fields must be covered by an MongoDB Search index.

Compatibilidade

O estágio $search está disponível nos seguintes ambientes:

MongoDB Atlas
MongoDB Enterprise deployments running version 8.2 or later with the Kubernetes Operator.
MongoDB Community deployments running version 8.2 or later

Sintaxe

Um estágio de pipeline do $search tem a seguinte forma de protótipo:

{
  $search: {
    "index": "<index-name>",
    "<operator-name>"|"<collector-name>": {
      <operator-specification>|<collector-specification>
    },
    "highlight": {
      <highlight-options>
    },
    "concurrent": true | false,
    "count": {
      <count-options>
    },
    "searchAfter"|"searchBefore": "<encoded-token>",
    "scoreDetails": true| false,
    "sort": {
      <fields-to-sort>: 1 | -1
    },
    "returnScope": {
      "path": "<embedded-documents-field-to-retrieve>"
    },
    "returnStoredSource": true | false,
    "searchNodePreference": {
      "key": <preference-string>
    }
  }
}

Campos

O estágio $search recebe um documento com os seguintes campos:

Campo	Tipo	necessidade	Descrição
`<collector-name>`	objeto	Condicional	Nome do coletor para utilizar com a query. Você pode fornecer um documento que contenha as opções específicas do coletor como valor para esse campo. Isto ou `<operator-name>` é obrigatório.
`concurrent`	booleano	Opcional	Paralelize a procura entre segmentos em nós de pesquisa dedicados. Se você não tiver nós de pesquisa separados no seu cluster, a Pesquisa MongoDB ignorará esta sinalização. Se omitido, o padrão é `false`. Para saber mais, consulte Parallelize Query Execution Across Segments.
`count`	objeto	Opcional	Documento que especifica as opções de contagem para recuperar uma contagem dos resultados. Para saber mais, consulte Resultados da pesquisa de contagem do MongoDB.
`highlight`	objeto	Opcional	Documento que especifica as opções de destaque para exibir os termos de pesquisa em seu contexto original.
`index`	string	Opcional	Nome do índice do MongoDB Search a ser usado. Se omitido, o padrão é `default`. If you name your index `default`, you don't need to specify an `index` parameter in the `$search` pipeline stage. If you give a custom name to your index, you must specify this name in the `index` parameter. A pesquisa do MongoDB não retorna resultados se você digitar incorretamente o nome do índice ou se o índice especificado ainda não existir no cluster.
`<operator-name>`	objeto	Condicional	Nome do operador com o qual pesquisar. Você pode fornecer um documento que contenha as opções específicas do operador como o valor para este campo. Isto ou `<collector-name>` é obrigatório. Use o operador composto para executar uma consulta composta com múltiplos operadores.
`returnScope`	Objeto	Opcional	Objeto que define o contexto da query para o campo de documento incorporado especificado. Você também deve especificar `returnStoredSource` e defini-la para `true`.
`returnStoredSource`	booleano	Condicional	Sinalizador que especifica se uma pesquisa completa de documentos deve ser executada no banco de dados de backend ou se deseja retornar apenas campos de origem armazenados diretamente do MongoDB Search. Se omitido, o padrão é `false`. Deve ser `true` se você especificar `returnScope`. Para saber mais, consulte Devolver campos de origem armazenados.
`searchAfter`	string	Opcional	Reference point for retrieving results. `searchAfter` returns documents starting immediately following the specified reference point. The reference point must be a Base64-encoded token generated by the `$meta` keyword `searchSequenceToken`. To learn more, see Paginate the Results. This field is mutually exclusive with the `searchBefore` field.
`searchBefore`	string	Opcional	Reference point for retrieving results. `searchBefore` returns documents starting immediately before the specified reference point. The reference point must be a Base64-encoded token generated by the `$meta` keyword `searchSequenceToken`. To learn more, see Paginate the Results. This field is mutually exclusive with the `searchAfter` field.
`searchNodePreference`	objeto	Opcional	Documento que habilita o roteamento preferencial para esta query. Se você definir um valor para esse campo, o Atlas executará essa query no mesmo nó de pesquisa todas as vezes, desde que o valor permaneça o mesmo, substituindo o comportamento padrão de roteamento de query. Este documento contém um par de valores-chave onde o valor de `key` é uma string arbitrária. IMPORTANTE: ativar essa configuração pode melhorar a consistência dos resultados da sua pesquisa, mas não oferece garantias de consistência perpétua. As alterações em seu conjunto de dados, estrutura de índice, topologia de cluster ou disponibilidade de nó preferencial ainda podem causar inconsistências.
`scoreDetails`	booleano	Opcional	Flag that specifies whether to retrieve a detailed breakdown of the score for the documents in the results. If omitted, defaults to `false`. To view the details, you must use the `$meta` expression in the `$project` stage. To learn more, see Return the Score Details.
`sort`	objeto	Opcional	Documento que especifica os campos para classificar os resultados do MongoDB Search em ordem crescente ou decrescente. Você pode classificar por data, número (inteiro, float e valores duplos) e valores de string. Para saber mais, consulte Classificar resultados da pesquisa do MongoDB.

Comportamento

$search must be the first stage of any pipeline it appears in. $search cannot be used in:

uma definição de visualização
a $facet pipeline stage

Variável de agregação

$search returns only the results of your query. The metadata results of your $search query are saved in the $$SEARCH_META aggregation variable. You can use the $$SEARCH_META variable to view the metadata results for your $search query.

The $$SEARCH_META aggregation variable can be used anywhere after a $search stage in any pipeline, but it can't be used after the $lookup or $unionWith stage in any pipeline. The $$SEARCH_META aggregation variable can't be used in any subsequent stage after a $searchMeta stage.

Exemplo

Suponha o seguinte índice na coleção sample_mflix.movies .

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "released": {
        "type": "date"
      }
    }
  }
}

The following query searches for movies released near September 01, 2011 using the $search stage. The query includes a:

$project stage to exclude all fields in the documents except title and released.
$facet estágio que produz um:
- docs campo com uma array dos 5 principais resultados de pesquisa
- meta campo com o valor de $$SEARCH_META variável

db.movies.aggregate([
  {
    "$search": {
      "near": {
        "path": "released",
        "origin": ISODate("2011-09-01T00:00:00.000+00:00"),
        "pivot": 7776000000
      }
    }
  },
  {
    $project: {
      "_id": 0,
      "title": 1,
      "released": 1
    }
  },
  { "$limit": 5 },
  {
    "$facet": {
      "docs": [],
      "meta": [
        {"$replaceWith": "$$SEARCH_META"},
        {"$limit": 1}
      ]
    }
  }
])

{
  "docs" : [
    {
      "title" : "Submarino",
      "released" : ISODate("2011-09-01T00:00:00Z")
    },
    {
      "title" : "Devil's Playground",
      "released" : ISODate("2011-09-01T00:00:00Z")
    },
    {
      "title" : "Bag It",
      "released" : ISODate("2011-09-01T00:00:00Z")
    },
    {
      "title" : "Dos",
      "released" : ISODate("2011-09-01T00:00:00Z")
    },
    {
      "title" : "We Were Here",
      "released" : ISODate("2011-09-01T00:00:00Z")
    }
  ],
  "meta" : [
    { "count" : { "lowerBound" : NumberLong(17373) } }
  ]
}

Para saber mais sobre a variável $$SEARCH_META e seu uso, consulte:

Solução de problemas

If you are experiencing issues with your MongoDB Search $search queries, see Troubleshoot Queries.

Voltar

Estágios de pipeline

Metadados: $searchMeta