As expressões são componentes doMQL que resolvem para um valor sem modificar suas entradas. Você pode usá-las nos seguintes contextos:
Alguns estágios do pipeline de agregação, como
$project,$addFieldse$groupPredicados de query que usam
$exprEncontrar projeçõesde comando
Na MongoDB Query Language, você pode criar expressões a partir dos seguintes componentes:
Componente | Exemplo |
|---|---|
Constantes |
|
Operadores | |
Expressões de caminho de campo |
|
Por exemplo, { $add: [ 3, "$inventory.total" ] } é uma expressão que consiste no operador $add e dois operandos:
A constante
3A expressão do caminho do campo
"$inventory.total"
A expressão retorna o resultado da adição de 3 ao valor no caminho inventory.total do documento de entrada.
Os operadores de expressão usam uma array de argumentos e têm o seguinte formato:
{ <operator>: [ <argument1>, <argument2> ... ] }
Se um operador aceitar um único argumento, você poderá omitir a array externa:
{ <operator>: <argument> }
Operadores aritméticos
Expressões aritméticas executam operações matemáticas em números. Algumas expressões aritméticas também podem suportar aritmética de datas.
Nome | Descrição |
|---|---|
Retorna o valor absoluto de um número. | |
Adiciona números para retornar a soma ou adiciona números e uma data para retornar uma nova data. Se adicionar números e uma data, trata os números como milissegundos. Aceita qualquer número de expressões de argumentos, mas, no máximo, uma expressão pode ser resolvida para uma data. | |
Retorna o menor número inteiro maior ou igual ao número especificado. | |
Retorna o resultado da divisão do primeiro número pelo segundo. Aceita duas expressões de argumento. | |
Aumenta e para o expoente especificado. | |
Retorna o maior número inteiro menor ou igual ao número especificado. | |
Calcula o registro natural de um número. | |
Calcula o registro de um número na base especificada. | |
Calcula a base de log 10 de um número. | |
Retorna o restante do primeiro número dividido pelo segundo. Aceita duas expressões de argumento. | |
Multiplica números para devolver o produto. Aceita qualquer número de expressões de argumento. | |
Cria um número para o expoente especificado. | |
Arredonda um número para um inteiro inteiro ou para uma casa decimal especificada. | |
Calcula a raiz quadrada. | |
Retorna o resultado da subtração do segundo valor do primeiro. Se os dois valores forem números, retorne a diferença. Se os dois valores forem datas, retorne a diferença em milissegundos. Se os dois valores forem uma data e um número em milissegundos, retorne a data resultante. Aceita duas expressões de argumentos. Se os dois valores forem uma data e um número, especifique o argumento de data primeiro, pois ele não é significativo para subtrair uma data de um número. | |
Trunca um número para um inteiro ou para uma casa decimal especificada. |
Operadores de array
Nome | Descrição |
|---|---|
Retorna o elemento no índice de array especificado. | |
Converte uma array de pares de valores chave em um documento. | |
Concatena arrays para retornar a array concatenada. | |
Seleciona um subconjunto da matriz para retornar uma matriz com apenas os elementos que correspondem à condição do filtro. | |
Retorna um número especificado de elementos desde o início de uma array. Diferente do accumulator | |
Retorna um booleano indicando se um valor especificado está em uma matriz. | |
Procura uma matriz para uma ocorrência de um valor especificado e retorna o índice da matriz da primeira ocorrência. Os índices da matriz começam em zero. | |
Determina se o operando é um array. Retorna um booleano. | |
Retorna um número especificado de elementos do final de uma matriz. Distinto do acumulador | |
Aplica uma subexpressão a cada elemento de uma matriz e retorna a matriz de valores resultantes em ordem. Aceita parâmetros nomeados. | |
Retorna os maiores valores de | |
Retorna os menores valores de | |
Converte um documento em uma matriz de documentos representando pares chave/valor. | |
Entrai uma matriz contendo uma sequência de inteiros de acordo com entradas definidas pelo usuário. | |
Aplica uma expressão para cada elemento em uma matriz e a combina em um único valor. | |
Retorna uma array com os elementos em ordem inversa. | |
Retorna o número de elementos na matriz. Aceita uma única expressão como argumento. | |
Retorna um subconjunto de uma array. | |
Classifica os elementos de uma array. | |
Mesclar dois arrays juntos. |
Operadores bitwise
Nome | Descrição |
|---|---|
Retorna o resultado de uma operação bitwise Novidades na versão 6.3. | |
Retorna o resultado de uma operação bitwise Novidades na versão 6.3. | |
Retorna o resultado de uma operação bitwise Novidades na versão 6.3. | |
Retorna o resultado de uma operação bitwise Novidades na versão 6.3. |
Operadores booleanos
Expressões booleanas avaliam suas expressões argumentais como booleanas e retornam um booleano como resultado.
Além do valor booleano false, a expressão booleana avalia como false os seguintes valores: null, 0 e undefined. A expressão booleana avalia todos os outros valores como true, incluindo valores numéricos diferentes de zero e arrays.
Nome | Descrição |
|---|---|
Retorna | |
Retorna o valor booleano que é o oposto da expressão do seu argumento. Aceita uma única expressão de argumento. | |
Retorna |
Operadores de comparação
As expressões de comparação retornam um booleano, exceto para $cmp que retorna um número.
As expressões de comparação usam duas expressões de argumento e comparam valor e tipo, usando a ordem de comparação BSON especificada para valores de tipos diferentes.
Nome | Descrição |
|---|---|
Retorna | |
Retorna | |
Retorna | |
Retorna | |
Retorna | |
Retorna | |
Retorna |
Operadores condicionais
Nome | Descrição |
|---|---|
Um operador ternário que avalia uma expressão e, dependendo do resultado, retorna o valor de uma das outras duas expressões. Aceita três expressões em uma lista ordenada ou três parâmetros nomeados. | |
Retorna o resultado não nulo da primeira expressão ou o resultado da segunda expressão se a primeira expressão resultar em um resultado nulo. O resultado nulo engloba instâncias de valores indefinidos ou campos ausentes. Aceita duas expressões como argumentos. O resultado da segunda expressão pode ser nulo. | |
Avalia uma série de expressões de caso. Quando encontra uma expressão que avalia para |
Operadores de agregação personalizada
Nome | Descrição |
|---|---|
Define uma função de acumulação personalizada. | |
Define uma função personalizada. |
Operadores de Tamanho de Dados
Os seguintes operadores retornam o tamanho de um elemento de dados:
Nome | Descrição |
|---|---|
Retorna o tamanho de uma determinada string ou o conteúdo do valor dos dados binários em bytes. | |
Retorna o tamanho em bytes de determinado documento (ou seja, bsontype |
Operadores de datas
Os seguintes operadores retornam objetos de data ou componentes de um objeto de data:
Nome | Descrição |
|---|---|
Adiciona uma série de unidades de tempo a um objeto de data. | |
Retorna a diferença entre duas datas. | |
Constrói um objeto BSON Date considerando as peças constituintes da data. | |
Converte uma string de data/hora em um objeto de data. | |
Subtrai uma série de unidades de tempo de um objeto de data. | |
Retorna um documento contendo as partes constituintes de uma data. | |
Retorna a data como uma string formatada. | |
Trunca uma data. | |
Retorna o dia do mês para uma data como um número entre 1 e 31. | |
Retorna o dia da semana para uma data como um número entre 1 (Domingo) e 7 (Sábado). | |
Retorna o dia do ano para uma data como um número entre 1 e 366 (ano bissexto). | |
Retorna a hora para uma data como um número entre 0 e 23. | |
Retorna o número do dia da semana no formato ISO 8601, que varia de | |
Retorna o número da semana no formato ISO 8601, que varia de | |
Retorna o número do ano no formato ISO 8601. O ano começa com a segunda-feira da semana 1 (ISO 8601) e termina com o domingo da última semana (ISO 8601). | |
Retorna milissegundos de uma data como um número entre 0 e 999. | |
Retorna o minuto para uma data como um número entre 0 e 59. | |
Retorna o mês para uma data como um número entre 1 (janeiro) e 12 (dezembro). | |
Retorna os segundos para uma data como um número entre 0 e 60 (segundos bissextos). | |
Converte o valor para uma data. | |
Retorna o número da semana para uma data como um número entre 0 (a semana parcial que precede o primeiro domingo do ano) e 53 (ano bissexto). | |
Retorna o ano para uma data como um número (por exemplo, 2014). |
Os seguintes operadores aritméticos podem tomar operandos de data:
Nome | Descrição |
|---|---|
Adiciona números e uma data para retornar uma nova data. Se adicionar números e uma data, trata os números como milissegundos. Aceita qualquer número de expressões de argumento, mas, no máximo, uma expressão pode ser resolvida para uma data. | |
Retorna o resultado da subtração do segundo valor do primeiro. Se os dois valores forem datas, retorne a diferença em milissegundos. Se os dois valores forem uma data e um número em milissegundos, retorne a data resultante. Aceita duas expressões de argumentos. Se os dois valores forem uma data e um número, especifique o argumento de data primeiro, pois não é significativo subtrair uma data de um número. |
Expressões associadas a acumuladores
Alguns acumuladores também estão disponíveis como expressões que calculam um valor sobre argumentos de entrada ou uma array de $group entrada.
Os seguintes operadores são acumuladores, mas também estão disponíveis como expressões que aceitam uma array de valores como entrada.
Nome | Descrição |
|---|---|
Retorna uma média da expressão especificada ou lista de expressões para cada documento. Ignora valores não numéricos. | |
Retorna o resultado de uma expressão para o primeiro documento em um grupo. | |
Retorna o resultado de uma expressão para o último documento em um grupo. | |
Retorna o máximo da expressão especificada ou lista de expressões para cada documento. | |
Retorna o mínimo da expressão especificada ou lista de expressões para cada documento. | |
Retorna uma array de valores escalares que correspondem aos valores percentuais especificados. Novidades na versão 7.0. | |
Retorna o desvio padrão da população dos valores de entrada. | |
Retorna o desvio padrão da amostra dos valores de entrada. | |
Retorna uma soma de valores numéricos. Ignora valores não numéricos. |
Operadores de expressão literal
Operadores diversos
Nome | Descrição |
|---|---|
Retorna o valor de um campo especificado de um documento. Você pode usar | |
Retorna uma flutuação aleatória entre 0 e 1 | |
Selecione documentos aleatoriamente a uma determinada taxa. Embora o exato número de documentos selecionados varie em cada execução, a quantidade escolhida aproxima-se da taxa de amostragem expressa em percentagem do número total de documentos. | |
Calcula e retorna o hash da expressão de entrada usando a mesma função de hash que o MongoDB usa para criar um índice hash. |
Operadores de objetos
Nome | Descrição |
|---|---|
Combina vários documentos em um único documento. | |
Converte um documento em uma matriz de documentos representando pares chave/valor. | |
Adiciona, atualiza ou remove um campo especificado em um documento. Você pode usar Novidades na versão 5.0. |
Definir operadores
Expressões de conjunto executam operações de conjunto em matrizes, tratando matrizes como conjuntos. Definir expressões ignora as entradas duplicadas em cada matriz de entrada e a ordem dos elementos.
Se a operação de definição retornar um conjunto, a operação filtrará duplicatas no resultado para gerar uma matriz que contenha apenas entradas exclusivas. A ordem dos elementos na matriz de saída não é especificada.
Se um conjunto contiver um elemento de array aninhada, a expressão set não desce para a array aninhada, mas avalia a array no nível superior.
Nome | Descrição |
|---|---|
Retorna | |
Retorna | |
Retorna um conjunto com elementos que aparecem no primeiro conjunto mas não no segundo conjunto; ou seja, executa um complemento relativo do segundo conjunto em relação ao primeiro. Aceita exatamente duas expressões de argumento. | |
Retorna | |
Retorna um conjunto com elementos que aparecem em todos os conjuntos de entrada. Aceita qualquer número de expressões de argumento. | |
Retorna | |
Retorna um conjunto com elementos que aparecem em qualquer conjunto de entrada. |
Operadores de strings
As expressões de string, com exceção de $concat, só têm um comportamento bem definido para string ASCII.
$concat o comportamento é bem definido independentemente dos
caracteres usados.
Nome | Descrição |
|---|---|
Concatena qualquer número de strings. | |
Converte uma string de data/hora em um objeto de data. | |
Retorna a data como uma string formatada. | |
Pesquisa uma string para uma ocorrência de uma substring e retorna
o índice de bytes UTF-8 da primeira ocorrência. Se a substring não for encontrada, retorna | |
Procura uma string para uma ocorrência de uma substring e retorna
o índice de ponto do código UTF-8 da primeira ocorrência. Se a
substring não for encontrada, retorna | |
Remove o espaço em branco ou os caracteres especificados do início de uma string. | |
Aplica uma expressão regular (regex) a uma string e retorna informações sobre a primeira substring correspondente. | |
Aplica uma expressão regular (regex) a uma string e retorna informações sobre todas as substrings correspondentes. | |
Aplica uma expressão regular (regex) a uma string e retorna um booleano que indica se uma correspondência foi encontrada ou não. | |
Substitui a primeira instância de uma string correspondente em uma determinada entrada. | |
Substitui todas as instâncias de uma string correspondente em uma determinada entrada. | |
Remove o espaço em branco ou os caracteres especificados do final de uma string. | |
Divide uma string em substrings com base em um delimitador. Retorna uma matriz de substrings. Se o delimitador não for encontrado dentro da string, retorna uma matriz contendo a string original. | |
Retorna o número de bytes codificados UTF-8 em uma string. | |
Retorna o número de pontos de código UTF-8 em uma string. | |
Executa a comparação de string sem distinção de maiúsculas e minúsculas e retorna: | |
Obsoleto. Use | |
Retorna a substring de uma string. Começa com o caractere no índice de byte UTF-8 especificado (baseado em zero) na string e continua pelo número de bytes especificado. | |
Retorna a substring de uma string. Começa com o caractere no índice (baseado em zero) do ponto de código (code point) UTF-8 especificado na string e continua com o número de pontos de código especificado. | |
Converte uma string em minúsculas. Aceita uma única expressão de argumento. | |
Converte o valor para uma string. | |
Remove o espaço em branco ou os caracteres especificados do início e fim de uma string. | |
Converte uma string em maiúsculas. Aceita uma única expressão de argumento. |
Operadores de texto
Nome | Descrição |
|---|---|
Acesse os metadados disponíveis por documento relacionados à operação de agregação. |
Operadores de registros de data e hora
Os operadores de expressão de registro de data/hora retornam valores de um registro de data/hora.
Nome | Descrição |
|---|---|
Retorna o ordinal incrementado de um carimbo de data/hora como Novidades na versão 5.1. | |
Retorna os segundos de um carimbo de data/hora como Novidades na versão 5.1. |
Operadores de trigonometria
Expressões de trigonometria executam operações trigonométricas em números. Os valores que representam ângulos são sempre de entrada ou saída em radianos. Use $degreesToRadians e $radiansToDegrees para converter entre medidas de grau e radianos.
Nome | Descrição |
|---|---|
Retorna o seno de um valor que é medido em radianos. | |
Retorna o cosseno de um valor medido em radianos. | |
Retorna a tangente de um valor que é medido em radianos. | |
Retorna o seno inverso (arco seno) de um valor em radianos. | |
Retorna o cosseno inverso (arco cosseno) de um valor em radianos. | |
Retorna a tangente inversa (arco tangente) de um valor em radianos. | |
Retorna a tangente inversa (arco tangente) de | |
Retorna o seno hiperbólico inverso (arco seno hiperbólico) de um valor em radianos. | |
Retorna o cosseno hiperbólico inverso (arco cosseno hiperbólico) de um valor em radianos. | |
Retorna a tangente hiperbólica inversa (arco tangente hiperbólico) de um valor em radianos. | |
Retorna o seno hiperbólico de um valor medido em radianos. | |
Retorna o cosseno hiperbólico de um valor medido em radianos. | |
Retorna a tangente hiperbólica de um valor medido em radianos. | |
Converte um valor de graus para radianos. | |
Converte um valor de radianos para graus. |
Operadores de tipo
Nome | Descrição |
|---|---|
Converte um valor para um tipo especificado. | |
Converte o valor em booleano. | |
Converte o valor para uma data. | |
Converte o valor para um Decimal128. | |
Converte o valor em double. | |
Converte o valor para um número inteiro. | |
Converte o valor para um longo. | |
Converte o valor para um ObjectId. | |
Converte o valor para uma string. | |
Retorne o tipo de dados BSON do campo. |
Operadores variáveis
Nome | Descrição |
|---|---|
Define variáveis para uso dentro do escopo de uma subexpressão e retorna o resultado da subexpressão. Aceita parâmetros nomeados. Aceita qualquer número de expressões de argumento. |
Operadores de Janela
Os operadores de janelas retornam valores de uma extensão definida de documentos de uma coleção, conhecida como janela. Uma janela é definida no estágio $setWindowFields, disponível a partir do MongoDB 5.0.
Os seguintes operadores de janela estão disponíveis na etapa $setWindowFields.
Nome | Descrição |
|---|---|
Retorna uma array de todos os valores únicos que resultam da aplicação de uma expressão a cada documento. Alterado na versão 5.0: Disponível no estágio | |
Retorna a média da expressão especificada. Ignora valores não numéricos. Alterado na versão 5.0: Disponível no estágio | |
Retorna o elemento inferior de um grupo de acordo com a ordem de classificação especificada. Novidades na versão 5.2. Disponível nos estágios | |
Retorna uma agregação dos campos Novidades na versão 5.2. Disponível nos estágios | |
Retorna o número de documentos no grupo ou janela. Diferente do estágio Novidades na versão 5.0. | |
Retorna a covariância populacional de duas expressões numéricas. Novidades na versão 5.0. | |
Retorna a covariância de amostra de duas expressões numéricas. Novidades na versão 5.0. | |
Retorna a posição do documento (conhecida como classificação) relativa a outros documentos na Novidades na versão 5.0. | |
Retorna a taxa média de alteração dentro da janela especificada. Novidades na versão 5.0. | |
Retorna a posição de um documento (conhecido como o número do documento) na partição de estágio Novidades na versão 5.0. | |
Retorna a média móvel exponencial da expressão numérica. Novidades na versão 5.0. | |
Retorna o resultado de uma expressão para o primeiro documento em um grupo ou janela. Alterado na versão 5.0: Disponível no estágio | |
Retorna a aproximação da área abaixo de uma curva. Novidades na versão 5.0. | |
Retorna o resultado de uma expressão para o último documento em um grupo ou janela. Alterado na versão 5.0: Disponível no estágio | |
Preenche Disponível no estágio Novidades na versão 5.3. | |
Última observação levada adiante. Define valores para Disponível no estágio Novidades na versão 5.2. | |
Retorna o valor máximo resultante da aplicação de uma expressão a cada documento. Alterado na versão 5.0: Disponível no estágio | |
Retorna o valor mínimo que resulta da aplicação de uma expressão a cada documento. Alterado na versão 5.0: Disponível no estágio | |
Retorna uma agregação dos Novidades na versão 5.2. Disponível em | |
Retorna uma array de valores que resultam da aplicação de uma expressão a cada documento. Alterado na versão 5.0: Disponível no estágio | |
Retorna a posição do documento (conhecida como classificação) em relação a outros documentos na partição Novidades na versão 5.0. | |
Retorna o valor de uma expressão aplicada a um documento em uma posição especificada em relação ao documento atual na Novidades na versão 5.0. | |
Retorna o desvio padrão da população a partir de uma expressão numérica aplicada a cada documento. Alterado na versão 5.0: Disponível no estágio | |
Retorna o desvio padrão da amostra a partir de uma expressão numérica aplicada a cada documento. Alterado na versão 5.0: Disponível no estágio | |
Retorna a soma dos resultados ao aplicar uma expressão numérica a cada documento. Alterado na versão 5.0: Disponível no estágio | |
Retorna o principal elemento de um grupo de acordo com a ordem de classificação especificada. Novidades na versão 5.2. Disponível nos estágios | |
Retorna uma agregação dos principais campos Novidades na versão 5.2. Disponível nos estágios |