Operações de expressão de aggregation
Nesta página
- Visão geral
- Como usar operações
- Métodos do construtor
- operações
- Operações aritméticas
- Operações de array
- Operações booleanas
- Operações de comparação
- Operações condicionais
- Operações de conveniência
- Operações de conversão
- Operações de datas
- Operações de documentos
- Operações de mapas
- Operações de strings
- Operações de verificação de tipo
Visão geral
Neste guia, você pode aprender como usar o MongoDB Java Driver para construir expressões para uso no pipeline de agregação. Você pode executar operações de expressão com métodos Java detectáveis e seguros por tipo em vez de documentos BSON. Como esses métodos seguem o padrão de interface fluente, você pode encadear operações de agregação para criar um código mais compacto e mais legível.
As operações nesta aba usam métodos do com.mongodb. cliente.model.mql pacote. Esses métodos fornecem uma maneira idiomática de usar a API de query, o mecanismo pelo qual o driver interage com um sistema do MongoDB . Para saber mais sobre a API de consulta, consulte a documentação manual do servidor.
Como usar operações
Os exemplos deste guia pressupõem que você inclua as seguintes importações estáticas em seu código:
import static com.mongodb.client.model.Aggregates.*; import static com.mongodb.client.model.Accumulators.* import static com.mongodb.client.model.Projections.*; import static com.mongodb.client.model.Filters.*; import static com.mongodb.client.model.mql.MqlValues.*; import static java.util.Arrays.asList;
Para acessar os campos do documento em uma expressão, você deve fazer referência ao documento atual que está sendo processado pelo pipeline de agregação. Use o método current()
para fazer referência a este documento. Para acessar o valor de um campo, você deve utilizar o método adequadamente digitado, como getString()
ou getDate()
. Ao especificar o tipo para um campo, certifique-se de que o driver fornece apenas os métodos compatíveis com esse tipo. O seguinte código mostra como referenciar um campo de string denominado name
:
current().getString("name")
Para especificar um valor em uma operação, passe para o método do construtor do of()
para convertê-lo em um tipo válido. O seguinte código mostra como referenciar um valor de 1.0
:
of(1.0)
Para criar uma operação, encadeie um método à sua referência de campo ou valor. Você pode criar operações mais complexas encadeando métodos adicionais.
O exemplo abaixo cria uma operação para encontrar pacientes no estado do Novo México, nos EUA, que foram a um consultório médico pelo menos uma vez. A operação executa as seguintes ações:
Verifica se o tamanho da matriz
visitDates
é maior que0
usando o métodogt()
Verifica se o valor do campo
state
é "Novo México" usando o métodoeq()
O método and()
vincula estas operações para que o estágio do pipeline corresponda apenas a documentos que atendam aos dois critérios.
current() .getArray("visitDates") .size() .gt(of(0)) .and(current() .getString("state") .eq(of("New Mexico")));
Enquanto alguns estágios de agregação, como group()
, aceitam operações diretamente, outros estágios esperam que você primeiro inclua sua operação em um método como computed()
ou expr()
. Esses métodos, que aceitam valores do tipo TExpression
, permitem usar suas expressões em determinadas agregações.
Para concluir o estágio do pipeline de agregação, inclua sua expressão em um método de construtor de agregados. A seguinte lista fornece exemplos de como incluir sua expressão em métodos de construtor de agregados comuns:
match(expr(<expression>))
project(fields(computed("<field name>", <expression>)))
group(<expression>)
Para saber mais sobre esses métodos, consulte Agregates Builders.
Os exemplos utilizam o método asList()
para criar uma lista de estágios de agregação. Esta lista é passada para o método aggregate()
de MongoCollection
.
Métodos do construtor
Você pode utilizar estes métodos do construtor para definir valores para uso em expressões de aggregation Java.
Método | Descrição |
---|---|
Referencia o documento atual sendo processado pela aggregation pipeline. | |
Referencia o documento atual sendo processado pelo pipeline de agregação como um valor de mapa. | |
Retorna um tipo de | |
Retorna uma matriz de | |
Retorna um valor de entrada. | |
Retorna um valor de mapa vazio. | |
Retorna o valor nulo conforme está na API de consulta. |
Importante
Quando você fornece um valor a um desses métodos, o driver o trata literalmente. Por exemplo, of("$x")
representa o valor de string "$x"
, em vez de um campo denominado x
.
Consulte qualquer uma das seções na página Operações para obter exemplos de uso desses métodos.
operações
As seções a seguir fornecem informações e exemplos de operações de expressão de agregação disponíveis no driver. As operações são categorizadas por finalidade e funcionalidade.
Cada seção tem uma tabela que descreve os métodos de agregação disponíveis no driver e os operadores de expressão correspondentes na API de query. Os nomes dos métodos estão vinculados à documentação da API e os nomes dos operadores do pipeline de agregação estão vinculados a descrições e exemplos na documentação do manual do servidor. Embora cada método Java seja efetivamente equivalente à expressão correspondente da API de query, eles podem diferir nos parâmetros esperados e na implementação.
Observação
O driver gera uma expressão de API de query que pode ser diferente da expressão de API de query fornecida em cada exemplo. No entanto, ambas as expressões produzirão o mesmo resultado de agregação.
Importante
O driver não fornece métodos para todos os operadores de pipeline de agregação da query API. Se você precisar usar uma operação sem suporte em uma agregação, será necessário definir a expressão inteira usando o tipo BSON Document
. Para saber mais sobre o tipo Document
, consulte documento.
Operações aritméticas
Você pode executar uma operação aritmética em um valor do tipo MqlInteger
ou MqlNumber
utilizando os métodos descritos nesta seção.
Método Java | Operador de pipeline de agregação |
---|---|
Digamos que você tenha dados meteorológicos de um ano específico que inclua a medição de precipitação (em polegadas) para cada dia. Você quer encontrar a precipitação média, em milímetros, para cada mês.
O operador multiply()
multiplica o campo precipitation
por 25.4
para converter o valor em milímetros. O método acumulador avg()
retorna a média como o campo avgPrecipMM
. O método group()
agrupa os valores por mês fornecidos no campo date
de cada documento.
O seguinte código mostra o pipeline para essa agregação:
var month = current().getDate("date").month(of("UTC")); var precip = current().getInteger("precipitation"); asList(group( month, avg("avgPrecipMM", precip.multiply(25.4)) ));
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $group: { _id: { $month: "$date" }, avgPrecipMM: { $avg: { $multiply: ["$precipitation", 25.4] } } } } ]
Operações de array
Você pode executar uma operação de array em um valor do tipo MqlArray
utilizando os métodos descritos nesta seção.
Método Java | Operador de pipeline de agregação |
---|---|
Suponha que você tenha uma coleção de filmes, cada um dos quais contém uma array de documentos aninhados para os próximos horários de exibição. Cada documento aninhado contém uma array que representa o número total de assentos no teatro, em que a primeira entrada da array é o número de assentos premium e a segunda entrada é o número de assentos regulares. Cada documento aninhado também contém o número de ingressos que já foram comprados para o momento da exibição. Um documento nesta coleção pode se assemelhar ao seguinte:
{ "_id": ..., "movie": "Hamlet", "showtimes": [ { "date": "May 14, 2023, 12:00 PM", "seats": [ 20, 80 ], "ticketsBought": 100 }, { "date": "May 20, 2023, 08:00 PM", "seats": [ 10, 40 ], "ticketsBought": 34 }] }
O método filter()
exibe somente os resultados que correspondem ao predicado fornecido. Nesse caso, o predicado usa sum()
para calcular o número total de assentos e compara esse valor com o número de ticketsBought
com lt()
. O método project()
armazena esses resultados filtrados como uma nova array availableShowtimes
.
Dica
É necessário especificar o tipo da array que você recupera com o método getArray()
se trabalhar com os valores da array como seu tipo específico.
Neste exemplo, especificamos que a array seats
contém valores do tipo MqlDocument
para que possamos extrair campos aninhados de cada entrada da array.
O seguinte código mostra o pipeline para essa agregação:
var showtimes = current().<MqlDocument>getArray("showtimes"); asList(project(fields( computed("availableShowtimes", showtimes .filter(showtime -> { var seats = showtime.<MqlInteger>getArray("seats"); var totalSeats = seats.sum(n -> n); var ticketsBought = showtime.getInteger("ticketsBought"); var isAvailable = ticketsBought.lt(totalSeats); return isAvailable; })) )));
Observação
Para melhorar a legibilidade, o exemplo anterior atribui valores intermediários às variáveis totalSeats
e isAvailable
. Se você não extrair esses valores intermediários em variáveis, o código ainda produzirá resultados equivalentes.
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $project: { availableShowtimes: { $filter: { input: "$showtimes", as: "showtime", cond: { $lt: [ "$$showtime.ticketsBought", { $sum: "$$showtime.seats" } ] } } } } } ]
Operações booleanas
Você pode executar uma operação booleana em um valor do tipo MqlBoolean
utilizando os métodos descritos nesta seção.
Suponha que você queira classificar leituras de temperatura muito baixa ou alta (em graus Fahrenheit) como extremas.
O operador or()
verifica se as temperaturas são extremas comparando o campo temperature
com valores pré-definidos com lt()
e gt()
. O método project()
registra este resultado no campo extremeTemp
.
O seguinte código mostra o pipeline para essa agregação:
var temperature = current().getInteger("temperature"); asList(project(fields( computed("extremeTemp", temperature .lt(of(10)) .or(temperature.gt(of(95)))) )));
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $project: { extremeTemp: { $or: [ { $lt: ["$temperature", 10] }, { $gt: ["$temperature", 95] } ] } } } ]
Operações de comparação
Você pode executar uma operação de comparação em um valor do tipo MqlValue
utilizando os métodos descritos nesta seção.
Dica
O método cond()
é semelhante ao operador ternário em Java e você deve usá-lo para ramificações simples com base em um valor booleano. Você deve usar os métodos switchOn()
para comparações mais complexas, como a realização de correspondência de padrões no tipo de valor ou outras verificações arbitrárias no valor.
Método Java | Operador de pipeline de agregação |
---|---|
O exemplo a seguir mostra um pipeline que corresponde a todos os documentos onde o campo location
tem o valor "California"
:
var location = current().getString("location"); asList(match(expr(location.eq(of("California")))));
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $match: { location: { $eq: "California" } } } ]
Operações condicionais
Você pode executar uma operação condicional utilizando os métodos descritos nesta seção.
Método Java | Operador de pipeline de agregação |
---|---|
Suponha que você tenha uma collection de clientes com suas informações de adesão. Originalmente, os clientes eram membros ou não eram membros. Com o tempo, os níveis de adesão foram introduzidos e usados no mesmo campo. As informações armazenadas nesse campo podem ser de tipos diferentes; e recomendamos criar um valor padronizado que indique o nível de adesão.
O método switchOn()
verifica cada cláusula em ordem. Se o valor corresponder ao tipo indicado pela cláusula, essa cláusula determinará o valor da string correspondente ao nível de associação. Se o valor original for uma string, ele representará o nível de associação e este valor será utilizado. Se o tipo de dados for booleano, ele retornará Gold
ou Guest
para o nível de associação. Se o tipo de dados for uma array, ele retornará a string mais recente da array que corresponde ao nível de associação mais recente. Se o campo member
for um tipo desconhecido, o método switchOn()
fornecerá um valor padrão de Guest
.
O seguinte código mostra o pipeline para essa agregação:
var member = current().getField("member"); asList(project(fields( computed("membershipLevel", member.switchOn(field -> field .isString(s -> s) .isBoolean(b -> b.cond(of("Gold"), of("Guest"))) .<MqlString>isArray(a -> a.last()) .defaults(d -> of("Guest")))) )));
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $project: { membershipLevel: { $switch: { branches: [ { case: { $eq: [ { $type: "$member" }, "string" ] }, then: "$member" }, { case: { $eq: [ { $type: "$member" }, "bool" ] }, then: { $cond: { if: "$member", then: "Gold", else: "Guest" } } }, { case: { $eq: [ { $type: "$member" }, "array" ] }, then: { $last: "$member" } } ], default: "Guest" } } } } ]
Operações de conveniência
Você pode aplicar funções personalizadas aos valores do tipo MqlValue
utilizando os métodos descritos nesta seção.
Para melhorar a legibilidade e permitir a reutilização do código, mova o código redundante para métodos estáticos. No entanto, não é possível encadear métodos estáticos diretamente em Java. O método passTo()
permite encadear valores em métodos estáticos personalizados.
Método Java | Operador de pipeline de agregação |
---|---|
Nenhum operador correspondente |
Suponha que você queira determinar o desempenho de uma turma em relação a alguns parâmetros. Você deseja encontrar a nota final média para cada turma e compará-la com os valores de parâmetro.
O método personalizado gradeAverage()
a seguir recebe uma array de documentos e o nome de um campo inteiro compartilhado entre esses documentos. Ele calcula a média desse campo em todos os documentos da array fornecida e determina a média desse campo em todos os elementos da array fornecida. O método evaluate()
compara um valor fornecido com dois limites de intervalo fornecidos e gera uma string de resposta com base na comparação dos valores:
public static MqlNumber gradeAverage(MqlArray<MqlDocument> students, String fieldName) { var sum = students.sum(student -> student.getInteger(fieldName)); var avg = sum.divide(students.size()); return avg; } public static MqlString evaluate(MqlNumber grade, MqlNumber cutoff1, MqlNumber cutoff2) { var message = grade.switchOn(on -> on .lte(cutoff1, g -> of("Needs improvement")) .lte(cutoff2, g -> of("Meets expectations")) .defaults(g -> of("Exceeds expectations"))); return message; }
Dica
Uma vantagem de utilizar o método passTo()
é que você pode reutilizar seus métodos personalizados para outras agregações. Você pode usar o método gradeAverage()
para encontrar a média das notas de grupos de alunos filtrados, por exemplo, pelo ano de ingresso ou pelo distrito, e não apenas pela turma. Você pode usar o método evaluate()
para avaliar, por exemplo, o desempenho de um aluno específico ou o desempenho de certa escola ou distrito como um todo.
O método passArrayTo()
junta todos os alunos e calcula a pontuação média utilizando o método gradeAverage()
. Em seguida, o método passNumberTo()
utiliza o método evaluate()
para determinar o desempenho da turma. Este exemplo armazena o resultado no campo evaluation
usando o método project()
.
O seguinte código mostra o pipeline para essa agregação:
var students = current().<MqlDocument>getArray("students"); asList(project(fields( computed("evaluation", students .passArrayTo(students -> gradeAverage(students, "finalGrade")) .passNumberTo(grade -> evaluate(grade, of(70), of(85)))) )));
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $project: { evaluation: { $switch: { branches: [ { case: { $lte: [ { $avg: "$students.finalGrade" }, 70 ] }, then: "Needs improvement" }, { case: { $lte: [ { $avg: "$students.finalGrade" }, 85 ] }, then: "Meets expectations" } ], default: "Exceeds expectations" } } } } ]
Operações de conversão
Você pode executar uma operação de conversão para converter entre determinados tipos de MqlValue
utilizando os métodos descritos nesta seção.
Método Java | Operador de pipeline de agregação |
---|---|
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Suponha que você queira ter uma coleção de dados dos alunos que inclua seus anos de graduação, que são armazenados como strings. Você deseja calcular o ano da reunião de cinco anos e armazenar este valor em um novo campo.
O método parseInteger()
converte o graduationYear
para um número inteiro de forma que add()
possa calcular o ano de reunião. O método addFields()
armazena este resultado como um novo campo reunionYear
.
O seguinte código mostra o pipeline para essa agregação:
var graduationYear = current().getString("graduationYear"); asList(addFields( new Field("reunionYear", graduationYear .parseInteger() .add(5)) ));
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $addFields: { reunionYear: { $add: [ { $toInt: "$graduationYear" }, 5 ] } } } ]
Operações de datas
Você pode executar uma operação de data em um valor do tipo MqlDate
usando os métodos descritos nesta seção.
Método Java | Operador de pipeline de agregação |
---|---|
Suponha que você tenha dados sobre entregas de pacote e queira fazer a correspondência entre as entregas que ocorreram em qualquer segunda-feira na zona "America/New_York"
.
Se o campo deliveryDate
contiver qualquer string que represente datas válidas, como "2018-01-15T16:00:00Z"
ou Jan 15, 2018, 12:00
PM EST
, você poderá usar o método parseDate()
para converter as strings em tipos de data.
O método dayOfWeek()
determina qual é o dia da semana e o converte em um número com base em qual dia é uma segunda-feira, de acordo com o parâmetro "America/New_York"
. O método eq()
compara esse valor com 2
, que corresponde a Monday com base no parâmetro de fuso horário fornecido.
O seguinte código mostra o pipeline para essa agregação:
var deliveryDate = current().getString("deliveryDate"); asList(match(expr(deliveryDate .parseDate() .dayOfWeek(of("America/New_York")) .eq(of(2)) )));
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $match: { $expr: { $eq: [ { $dayOfWeek: { date: { $dateFromString: { dateString: "$deliveryDate" } }, timezone: "America/New_York" }}, 2 ] } } } ]
Operações de documentos
Você pode executar uma operação de documento em um valor do tipo MqlDocument
usando os métodos descritos nesta seção.
Método Java | Operador de pipeline de agregação |
---|---|
Nenhum operador correspondente | |
Digamos que você tenha um conjunto de dados de clientes antigos que contém endereços como documentos secundários no campo mailing.address
. Você deseja encontrar todos os clientes que moram atualmente no estado de Washington. Um documento desse conjunto poderia ser como o exemplo abaixo:
{ "_id": ..., "customer.name": "Mary Kenneth Keller", "mailing.address": { "street": "601 Mongo Drive", "city": "Vasqueztown", "state": "CO", "zip": 27017 } }
O método getDocument()
recupera o campo mailing.address
como um documento para que o campo state
aninhado possa ser recuperado com o método getString()
. O método eq()
verifica se o valor do campo state
é "WA"
.
O seguinte código mostra o pipeline para essa agregação:
var address = current().getDocument("mailing.address"); asList(match(expr(address .getString("state") .eq(of("WA")) )));
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $match: { $expr: { $eq: [{ $getField: { input: { $getField: { input: "$$CURRENT", field: "mailing.address"}}, field: "state" }}, "WA" ] }}}]
Operações de mapas
Você pode executar uma operação de mapa em um valor de tipo MqlMap
ou MqlEntry
utilizando os métodos descritos nesta seção.
Dica
Você deve representar dados como um mapa se os dados mapear chaves arbitrárias como datas ou IDs de item para valores.
Método Java | Operador de pipeline de agregação |
---|---|
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente |
Suponha que você tenha uma coleção de dados de estoque em que cada documento representa um item individual que você é responsável por fornecer. Cada documento contém um campo que é um mapa de todos os seus armazéns e quantas cópias eles têm atualmente em seu inventário do item. Você deseja determinar o número total de cópias de itens que você tem em todos os seus armazéns. Um documento nesta coleção pode se assemelhar ao seguinte:
{ "_id": ..., "item": "notebook" "warehouses": [ { "Atlanta", 50 }, { "Chicago", 0 }, { "Portland", 120 }, { "Dallas", 6 } ] }
O método entries()
retorna as entradas do mapa no campo warehouses
como uma array. O método sum()
calcula o valor total dos itens baseado nos valores na array recuperada com o método getValue()
. Este exemplo armazena o resultado como o novo campo totalInventory
utilizando o método project()
.
O seguinte código mostra o pipeline para essa agregação:
var warehouses = current().getMap("warehouses"); asList(project(fields( computed("totalInventory", warehouses .entries() .sum(v -> v.getValue())) )));
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $project: { totalInventory: { $sum: { $getField: { $objectToArray: "$warehouses" }, } } } } ]
Operações de strings
Você pode executar uma operação de string em um valor do tipo MqlString
utilizando os métodos descritos nesta seção.
Método Java | Operador de pipeline de agregação |
---|---|
Suponha que você queira gerar nomes de usuário em letras minúsculas para os funcionários de uma empresa a partir dos sobrenomes e ID dos funcionários.
O método append()
combina os campos firstName
e lastName
em um único nome de usuário, enquanto o método toLower()
torna todo o nome de usuário minúsculo. Este exemplo armazena o resultado como um novo campo username
utilizando o método project()
.
O seguinte código mostra o pipeline para essa agregação:
var lastName = current().getString("lastName"); var employeeID = current().getString("employeeID"); asList(project(fields( computed("username", lastName .append(employeeID) .toLower()) )));
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $project: { username: { $toLower: { $concat: ["$lastName", "$employeeID"] } } } } ]
Operações de verificação de tipo
Você pode executar uma operação de verificação de tipo em um valor do tipo MqlValue
utilizando os métodos descritos nesta seção.
Estes métodos não retornam valores booleanos. Em vez disso, você fornece um valor padrão que corresponde ao tipo especificado pelo método. Se o valor marcado corresponder ao tipo de método, o valor marcado será retornado. Caso contrário, o valor predefinido fornecido é devolvido. Se você deseja programar lógica de ramificação com base no tipo de dados, consulte switchOn()
.
Método Java | Operador de pipeline de agregação |
---|---|
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente | |
Nenhum operador correspondente |
Suponha que você tenha uma collection de dados de classificação. Uma versão anterior do esquema de avaliação permitia que os usuários enviassem avaliações negativas sem uma classificação por estrelas. Recomendamos converter essas avaliações negativas sem uma classificação por estrelas para ter o valor mínimo de 1 estrela.
O método isNumberOr()
retorna o valor de rating
ou um valor de 1
se rating
não for um número ou for nulo. O método project()
retorna este valor como um novo campo numericalRating
.
O seguinte código mostra o pipeline para essa agregação:
var rating = current().getField("rating"); asList(project(fields( computed("numericalRating", rating .isNumberOr(of(1))) )));
O código a seguir fornece um pipeline de agregação equivalente na API de consulta:
[ { $project: { numericalRating: { $cond: { if: { $isNumber: "$rating" }, then: "$rating", else: 1 } } } } ]