$where

Nesta página

Definição

Compatibilidade
Sintaxe
Comportamento
Propriedades e funções JavaScript disponíveis
elemMatch
Considerações
JavaScript Enablement
Exemplo

O MongoDB 5.0 é o fim da vida útil a partir de de 2024 outubro. Esta versão da documentação não é mais suportada. Para atualizar sua 5.0 implantação do, consulte o MongoDB 6.0 procedimentos de atualização.

Definição

$where: 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:

Para uma instância mongod, consulte opção de configuração security.javascriptEnabled ou opção de linha de comando --noscripting.
Para instâncias do mongos, consulte a opção de configuração security.javascriptEnabled ou a opção de linha de comando --noscripting.

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

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

Consulta geoespacial