/ /

Referência de query

Operadores e coletores

Página inicial do Docs

Operadores e coletores

`equals` ( Operador de pesquisa MongoDB )

Definição

equals

O operador equals verifica se algum campo corresponde a um valor que você especificou. O equals pode fazer queries dos seguintes tipos de dados:

booleano
ObjectId
número, incluindo int32, int64 e double
data
string, indexado como tipo de token de pesquisa MongoDB token
uuid
null

Você pode usar o operador equals para fazer query de booleans, objectIds, números, datas e strings (indexados como token tipo) em arrays. Se pelo menos um elemento na array corresponder ao campo "valor" no operador equals, o MongoDB Search adicionará o documento ao conjunto de resultados.

Observação

O operador equals aceita números com até 15 casas decimais. Casas decimais adicionais em documentos ou queries podem causar problemas de precisão ou erros na query.

Sintaxe

equals tem a seguinte sintaxe:

{
   $search: {
      "index": <index name>, // optional, defaults to "default"
      "equals": {
         "path": "<field-to-search>",
         "value": <boolean-value>|<objectId>|<number>|<date>|<string>,
         "score": <score-options>,
         "doesNotAffect": "<facet-to-exclude>" | [<array-of-facets>]
      }
   }
}

Opções

equals usa os seguintes termos para construir uma consulta:

Campo	Tipo	Descrição	Obrigatório?
`path`	string	Campo indexado para pesquisar.	sim
`value`	boolean, objectId, number, date, string, uuid ou null.	Valor para query.	sim
`score`	objeto	Pontuação para atribuir aos resultados do termo de pesquisa correspondente. Use uma das opções seguintes para modificar a pontuação: `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.	no
`doesNotAffect`	cadeia de caracteres ou matriz de cadeias de caracteres	Faceta ou lista de facetas a serem excluídos do novo cálculo de contagem com base nesta query. O valor deve ser um ou mais nomes de uma faceta definidos em `$search.facets` ou `$searchMeta.facets`. O operador usa as facetas especificadas para filtrar documentos para corresponder a essa query, mas não recalcula as contagens para eles. Para obter mais informações, consulte Facetas de seleção múltipla.	no

Comportamento de pontuação

Por padrão, equals utiliza pontuação constant. Cada documento correspondente recebe a pontuação 1.

Ao executar query de valores de array, o MongoDB Pesquisa atribui pontuações mais altas se mais valores na array corresponderem à query.

Consulte a seção Exemplos para ver exemplos de pontuação.

Exemplos

Os exemplos a seguir usam uma coleção de amostra users.

Collection de amostras

A coleção users contém os três documentos a seguir:

 db.users.insertMany([
  {
    "_id" : ObjectId("5ed698faa1199b471010d70c"),
    "name" : "Jim Hall",
    "verified_user" : true,
    "account" : {
      "new_user" : true,
      "active_user" : true
    },
    "teammates" : [
      ObjectId("5ed6990aa1199b471010d70d"),
      ObjectId("59b99dbdcfa9a34dcd7885c8")
    ],
    "region" : "East",
    "account_created" : ISODate("2021-12-12T10:18:27.000+00:00"),
    "employee_number" : 257,
    "uuid" : UUID("fac32260-b511-4c69-8485-a2be5b7dda9e"),
    "job_title": "engineer"
  },
  {
    "_id" : ObjectId("5ed6990aa1199b471010d70d"),
    "name" : "Ellen Smith",
    "verified_user" : true,
    "account" : {
      "new_user" : false,
      "active_user" : true
    },
    "teammates" : [
      ObjectId("5a9427648b0beebeb69537a5"),
      ObjectId("59b99dbdcfa9a34dcd7881d1")
    ],
    "region" : "Southwest",
    "account_created" : ISODate("2022-05-04T05:01:08.000+00:00"),
    "employee_number" : 258,
    "job_title": null
  },
  {
    "_id" : ObjectId("5ed6994fa1199b471010d70e"),
    "name" : "Fred Osgood",
    "verified_user" : false,
    "account" : {
      "new_user" : false,
      "active_user" : false
    },
    "teammates" : [
      ObjectId("5a9427648b0beebeb69589a1"),
      ObjectId("59b99dbdcfa9a34dcd7897d3")
    ],
    "region" : "Northwest",
    "account_created" : ISODate("2022-01-19T08:22:15.000+00:00"),
    "employee_number" : 259,
    "job_title": null
  }
])

{
   "_id" : ObjectId("5ed698faa1199b471010d70c"),
   "name" : "Jim Hall",
   "verified_user" : true,
   "account" : {
     "new_user" : true,
     "active_user" : true
   },
   "teammates" : [
     ObjectId("5ed6990aa1199b471010d70d"),
     ObjectId("59b99dbdcfa9a34dcd7885c8")
   ],
   "region" : "East",
   "account_created" : ISODate("2021-12-12T10:18:27.000+00:00"),
   "employee_number" : 257,
   "uuid" : UUID("fac32260-b511-4c69-8485-a2be5b7dda9e"),
   "job_title": "engineer"
}

{
   "_id" : ObjectId("5ed6990aa1199b471010d70d"),
   "name" : "Ellen Smith",
   "verified_user" : true,
   "account" : {
     "new_user" : false,
     "active_user" : true
   },
   "teammates" : [
     ObjectId("5a9427648b0beebeb69537a5"),
     ObjectId("59b99dbdcfa9a34dcd7881d1")
   ],
   "region" : "Southwest",
   "account_created" : ISODate("2022-05-04T05:01:08.000+00:00"),
   "employee_number" : 258,
   "job_title": null
}

{
   "_id" : ObjectId("5ed6994fa1199b471010d70e"),
   "name" : "Fred Osgood",
   "verified_user" : false,
   "account" : {
     "new_user" : false,
     "active_user" : false
   },
   "teammates" : [
     ObjectId("5a9427648b0beebeb69589a1"),
     ObjectId("59b99dbdcfa9a34dcd7897d3")
   ],
   "region" : "Northwest",
   "account_created" : ISODate("2022-01-19T08:22:15.000+00:00"),
   "employee_number" : 259,
   "job_title": null
}

Índice de amostra

A collection users é indexada com a seguinte definição de índice:

{
  "mappings": {
    "dynamic": true,
    "fields": {
      "name": {
        "type": "token",
        "normalizer": "lowercase"
      },
      "region": [
       {
         "type": "string"
       },
       {
         "type": "token"
       }
      ]
    }
  }
}

A definição de índice especifica o seguinte:

Indexe automaticamente todos os campos indexáveis dinamicamente.
Indexe o campo name como tipo token para conseguir fazer a pesquisa da string utilizando o operador equals.
Indexe o campo region como tipos string para suporte à pesquisa de string e token para suporte à pesquisa facet.

Para saber como criar um índice do MongoDB Search, consulte Gerenciar índices de pesquisa do MongoDB.

Queries de exemplo básicos

Exemplos de booleans

O exemplo a seguir usa o operador equals para pesquisar a collection users em busca de documentos nos quais o campo verified_user esteja definido como true.

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "verified_user",
        "value": true
      }
    }
  },
  {
    "$project": {
      "name": 1,
      "_id": 0,
      "score": { "$meta": "searchScore" }
    }
  }
])

A query acima retorna os seguintes resultados:

{ "name" : "Jim Hall", "score" : 1 }
{ "name" : "Ellen Smith", "score" : 1 }

Os documentos de "Jim Hall" e "Ellen Smith" recebem uma pontuação de 1 porque esses documentos têm o campo verified_user definido como true.

O exemplo abaixo usa o operador equals para pesquisar documentos na collection users em que o campo account.new_user contém o valor boolean de true.

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "account.new_user",
        "value": true
      }
    }
  }
])

The preceding query returns the document for "Jim Hall" because that document contains "new_user": true in the account object.

Exemplo de ObjectId

O exemplo abaixo usa o operador equals para pesquisar a collection users para documentos nos quais o campo teammates contém o valor ObjectId("5a9427648b0beebeb69589a1").

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "teammates",
        "value": ObjectId("5a9427648b0beebeb69589a1")
      }
    }
  }
])

The preceding query returns the document for "Fred Osgood" because that document contains ObjectId("5a9427648b0beebeb69589a1") in the teammates array.

Exemplo de data

O exemplo seguinte utiliza o operador equals para pesquisar documentos na collection users em que o campo account_created contenha o valor que corresponde a ISODate("2022-05-04T05:01:08.000+00:00").

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "account_created",
        "value": ISODate("2022-05-04T05:01:08.000+00:00")
      }
    }
  }
])

The preceding query returns the document for "Ellen Smith" because that document contains "account_created": 2022-05-04T05:01:08.000+00:00.

Exemplo de número

O exemplo seguinte utiliza o operador equals para pesquisar documentos na collection users em que o campo employee_number contenha o valor que corresponde a 259.

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "employee_number",
        "value": 259
      }
    }
  }
])

The preceding query returns the document for "Fred Osgood" because that document contains "employee_number": 259.

Exemplo de string

O exemplo seguinte utiliza o operador equals para pesquisar documentos na collection users em que o campo name contenha o valor que corresponde a Jim Hall.

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "name",
        "value": "jim hall"
      }
    }
  }
])

The preceding query returns the document for "Jim Hall" because that document contains Jim Hall in the name field. MongoDB Search matches the lowercase query to the uppercase value in the document because it normalizes the term to lowercase as specified in the index definition for the name field.

Exemplo de UUID

O exemplo a seguir usa o operador equals para pesquisar documentos nos quais o campo uuid contém o valor que corresponde a um UUID específico na coleção users.

db.users.aggregate([
  {
    "$search": {
      "equals": {
        "path": "uuid",
        "value": UUID("fac32260-b511-4c69-8485-a2be5b7dda9e")
      }
    }
  }
])

The preceding query returns the document for "Jim Hall" because that document contains the specified UUID in the uuid field.

Exemplo nulo

O exemplo a seguir usa o operador equals para pesquisar documentos na coleção users em que o campo job_title contém o valor nulo.

db.users.aggregate([
  {
    $search: {
      "equals": {
        "path": "job_title",
        "value": null
      }
    }
  }
])

The preceding query returns the documents for "Ellen Smith" and Fred Osgood because that documents contain the null value in the job_title field.

Exemplos de queries compostas

O exemplo a seguir usa o operador composto em conjunto com must, mustNot e equals para pesquisar documentos nos quais o campo region é Southwest e o campo verified_user não é false.

db.users.aggregate([
  {
    "$search": {
      "compound": {
        "must": {
          "text": {
            "path": "region",
            "query": "Southwest"
          }
        },
        "mustNot": {
          "equals": {
            "path": "verified_user",
            "value": false
          }
        }
      }
    }
  }
])

A query acima retorna o documento para "Ellen Smith", que é a única na collection que atende aos critérios da pesquisa.

O seguinte exemplo de query tem estes critérios de pesquisa:

O campo verified_user deve ser definido como true
Uma das seguintes opções deve ser verdadeira:
- O array teammates contém o valor ObjectId("5ed6990aa1199b471010d70d")
- O campo region é definido como Northwest

db.users.aggregate([
  {
    "$search": {
      "compound": {
        "must": {
          "equals": {
            "path": "verified_user",
            "value": true
          }
        },
        "should": [
          {
            "equals": {
              "path": "teammates",
              "value": ObjectId("5ed6990aa1199b471010d70d")
            }
          },
          {
            "text": {
              "path": "region",
              "query": "Northwest"
            }
          }
        ],
        "minimumShouldMatch": 1
        }
      }
    },
    {
      "$project": {
        "name": 1,
        "_id": 0,
        "score": { "$meta": "searchScore" }
      }
    }
])

A query acima retorna os seguintes resultados:

{ "name" : "Jim Hall", "score" : 2 }

O documento para "Jim Hall" recebe uma pontuação de 2 porque cumpre os requisitos para a cláusula must e a primeira das duas cláusulas should.

Você pode pesquisar vários ObjectIDs com uma query composta. O seguinte exemplo de query utiliza o operador compound com uma cláusula should para pesquisar três ObjectIDs diferentes, sendo que pelo menos dois devem aparecer para satisfazer a query.

db.users.aggregate([
  {
    "$search": {
      "compound": {
        "should": [
          {
            "equals": {
              "path": "teammates",
              "value": ObjectId("5a9427648b0beebeb69537a5")
            }
          },
          {
            "equals": {
              "path": "teammates",
              "value": ObjectId("59b99dbdcfa9a34dcd7881d1")
            }
          },
          {
            "equals": {
              "path": "teammates",
              "value": ObjectId("5a9427648b0beebeb69579d0")
            }
          }
        ],
        "minimumShouldMatch": 2
        }
      }
    },
    {
      "$project": {
        "name": 1,
        "_id": 0,
        "score": { "$meta": "searchScore" }
      }
    }
])

A query acima retorna os seguintes resultados:

{ "name" : "Ellen Smith", "score" : 2 }

O documento para "Ellen Smith" recebe uma pontuação de 2 porque contém dois dos ObjectIDs especificados em sua array teammates.

Exemplos de metadados

A consulta a seguir usa a fase $searchMeta para recuperar o número de regiões em que verified_users é verdadeiro na coleção users.

db.users.aggregate([
  {
    "$searchMeta": {
      "facet": {
        "operator": {
          "equals": {
            "path": "verified_user",
            "value": true
          }
        },
        "facets": {
          "regionFacet": {
            "type": "string",
            "path": "region"
          }
        }
      }
    }
  }
])

[
  {
    count: { lowerBound: Long('2') },
    facet: {
      regionFacet: {
        buckets: [
          { _id: 'East', count: Long('1') },
          { _id: 'Southwest', count: Long('1') }
        ]
      }
    }
  }
]

A seguinte query usa a variável de agregação $$SEARCH_META para retornar os metadados e os resultados da pesquisa para recuperar o número de regiões em que verified_users é verdadeiro na coleção users.

db.users.aggregate([
  {
    "$search": {
      "facet": {
        "operator": {
          "equals": {
            "path": "verified_user",
            "value": true
          }
        },
        "facets": {
          "regionFacet": {
            "type": "string",
            "path": "region"
          }
        }
      }
    }
  },
  { "$limit": 2 },
  {
    "$facet": {
      "docs": [
        { "$project":
          {
            "type": 1,
            "description": 1
          }
        }
      ],
      "meta": [
        {"$replaceWith": "$$SEARCH_META"},
        {"$limit": 1}
      ]
    }
  },
  {
    "$set": {
      "meta": {
        "$arrayElemAt": ["$meta", 0]
      }
    }
  }
])

[
  {
    docs: [
      {
        _id: ObjectId('5ed698faa1199b471010d70c'),
        name: 'Jim Hall',
        region: 'East'
      },
      {
        _id: ObjectId('5ed6990aa1199b471010d70d'),
        name: 'Ellen Smith',
        region: 'Southwest'
      }
    ],
    meta: {
      count: { lowerBound: Long('2') },
      facet: {
        regionFacet: {
          buckets: [
            { _id: 'East', count: Long('1') },
            { _id: 'Southwest', count: Long('1') }
          ]
        }
      }
    }
  }
]

Voltar

documento incorporado

existe

equals ( Operador de pesquisa MongoDB )

Definição

Observação

Sintaxe

Opções

Comportamento de pontuação

Exemplos

Collection de amostras

Índice de amostra

Queries de exemplo básicos

Exemplos de booleans

Exemplo de ObjectId

Exemplo de data

Exemplo de número

Exemplo de string

Exemplo de UUID

Exemplo nulo

Exemplos de queries compostas

Exemplos de metadados

`equals` ( Operador de pesquisa MongoDB )