Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Referência
/
Operadores
/
Consulta e projeção
/
Consulta de avaliação

$where

Nesta página

  • Definição
  • Compatibilidade
  • Sintaxe
  • Comportamento
  • Propriedades e funções JavaScript disponíveis
  • elemMatch
  • Considerações
  • JavaScript Enablement
  • Funções de array e string não suportadas
  • Exemplo

Definição

$where

Importante

JavaScript do lado do servidor obsoleto

A partir do MongoDB 8.0, as funções JavaScript do lado do servidor$accumulator, $function $where estão obsoletas. O MongoDB exibe um aviso quando você executa essas funções.

Utilize o operador $where para transmitir uma string contendo uma expressão JavaScript ou uma função JavaScript completa para o sistema de query. O $where oferece maior flexibilidade, mas exige que o banco de dados processe a expressão JavaScript para cada documento na coleção. Consulte o documento na expressão ou função JavaScript usando this ou obj.

Compatibilidade

Você pode utilizar o $where para implantações hospedadas nos seguintes ambientes:

  • MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

  • MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB

  • MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

O operador $where tem o seguinte formato:

{ $where: <string|JavaScript Code> }

Observação

$where não é mais compatível com o código JavaScript do tipo BSON descontinuado com escopo (BSON Tipo 15). O operador $where suporta apenas a string do tipo BSON (BSON tipo 2) ou JavaScript do tipo BSON (BSON tipo 13). O uso do JavaScript do tipo BSON com escopo para $where foi descontinuado a partir do MongoDB 4.2.1.

Observação

Alternativas de aggregation preferidas

O operador $expr permite o uso de expressões de agregação dentro da linguagem de query. O $function e o $accumulator permitem que os usuários definam expressões de agregação personalizadas em JavaScript se os operadores de pipeline fornecidos não atenderem às necessidades do seu aplicativo.

Considerando os operadores de aggregation disponíveis:

  • O uso de $expr com operadores de agregação que não utilizam JavaScript (ou seja, operadores não$function e não$accumulator) é mais rápido que $where porque não executa JavaScript e deve receber prioridade, se possível.

  • No entanto, se você precisar criar expressões personalizadas, $function é preferível a $where.

Comportamento

Propriedades e funções JavaScript disponíveis

As expressões de operador map-reduce operations e $where não podem acessar determinadas funções ou propriedades globais, como db, que estão disponíveis no mongosh.

As seguintes funções e propriedades do JavaScript estão disponíveis para as expressões de operador map-reduce operations e $where:

Propriedades disponíveis
Funções disponíveis
args
MaxKey
MinKey
assert()
BinData()
DBPointer()
DBRef()
doassert()
emit()
gc()
HexData()
hex_md5()
isNumber()
isObject()
ISODate()
isString()
Map()
MD5()
NumberInt()
NumberLong()
ObjectId()
print()
printjson()
printjsononeline()
sleep()
Timestamp()
tojson()
tojsononeline()
tojsonObject()
UUID()
version()

elemMatch

Aplique apenas o operador de query $where a documentos de nível superior. O operador de query $where não funcionará dentro de um documento agrupado, por exemplo, em uma query $elemMatch.

Considerações

  • Não use variáveis globais.

  • $where avalia JavaScript e não pode aproveitar os índices. Portanto, o desempenho da consulta melhora quando você a expressa usando os operadores padrão do MongoDB (p. ex., $gt, $in).

  • Em geral, você deve usar $where somente quando não puder expressar sua query usando outro operador. Se você deve utilizar $where, tente incluir pelo menos um outro operador de query padrão para filtrar o conjunto de resultados. O uso apenas de $where requer uma verificação de collection.

O uso de declarações de consulta normais não $where fornece as seguintes vantagens de desempenho:

  • O MongoDB avaliará componentes que não sejam$where de consulta antes das declarações $where. Se as declarações que não sejam $where não corresponderem a nenhum documento, o MongoDB não realizará nenhuma avaliação de consulta usando $where.

  • As declarações de consulta que não sejam$where podem usar um índice.

JavaScript Enablement

Para usar $where (ou $function, $accumulator ou mapReduce), você deve ter o script do lado do servidor habilitado (padrão).

No entanto, se você não usar essas operações, desabilite os scripts do lado do servidor:

Consulte também ➤ Executar o MongoDB com opções de configuração seguras.

Funções de array e string não suportadas

O MongoDB 6.0 atualiza o mecanismo JavaScript interno utilizado para expressões de JavaScript do lado do servidor, $accumulator, $function e $where e de MozJS-60 para MozJS-91. Várias funções de array e string obsoletas e não padrão que existiam no MozJS-60 foram removidas no MozJS-91.

Para obter a lista completa das funções de array e string removidas, consulte as notas de compatibilidade da versão 6.0.

Exemplo

Considere os seguintes documentos na collection players:

db.players.insertMany([
   { _id: 12378, name: "Steve", username: "steveisawesome", first_login: "2017-01-01" },
   { _id: 2, name: "Anya", username: "anya", first_login: "2001-02-02" }
])

O exemplo seguinte utiliza $where e a função JavaScript hex_md5() para comparar o valor do campo name com um hash MD5 e retorna qualquer documento correspondente.

db.players.find( { $where: function() {
   return (hex_md5(this.name) == "9b53e667f30cd329dca1ec9e6a83e994")
} } );

A operação retorna o seguinte resultado:

{
   "_id" : 2,
   "name" : "Anya",
   "username" : "anya",
   "first_login" : "2001-02-02"
}

Como alternativa, o exemplo anterior pode ser reescrito utilizando $expr e $function. Você pode definir uma expressão de agregação personalizada em JavaScript com o operador de agregação $function. Para acessar $function e outros operadores de agregação em db.collection.find(), use com $expr:

db.players.find( {$expr: { $function: {
      body: function(name) { return hex_md5(name) == "9b53e667f30cd329dca1ec9e6a83e994"; },
      args: [ "$name" ],
      lang: "js"
} } } )

Se você precisar criar expressões personalizadas, $function é preferível a $where.

Voltar

$regex

Próximo

Consulta geoespacial