/ /

Operadores e coletores

Página inicial do Docs

/ /

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>
      }
   }
}

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

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 Search atribui a mesma pontuação, independentemente de quantos valores na array correspondem à 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
      }
    }
  }
])

A query anterior retorna o documento para "Jim Hall" porque esse documento contém "new_user": true no objeto account.

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")
      }
    }
  }
])

A query anterior retorna o documento para "Fred Osgood" porque esse documento contém ObjectId("5a9427648b0beebeb69589a1") na array teammates.

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")
      }
    }
  }
])

A query anterior retorna o documento para "Ellen Smith" porque esse documento contém "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
      }
    }
  }
])

A query anterior retorna o documento para "Fred Osgood" porque esse documento contém "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"
      }
    }
  }
])

A query anterior retorna o documento para "Jim Hall" porque esse documento contém Jim Hall no campo name. O MongoDB Search corresponde a query em letra minúscula ao valor em letra maiúscula no documento porque normaliza o termo para letra minúscula conforme especificado na definição do índice para o campo name.

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")
      }
    }
  }
])

A query anterior retorna o documento de "Jim Hall" porque esse documento contém o UUID especificado no campo uuid.

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
      }
    }
  }
])

A query anterior retorna os documentos de "Ellen Smith" e Fred Osgood porque esses documentos contêm o valor nulo no campo job_title .

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