Operações de expressão de aggregation

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.

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ê deseja 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 do campo 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:

val month = current().getDate("date").month(of("UTC"))
val precip = current().getInteger("precipitation")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.group(
            month,
            Accumulators.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.

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 usando o método lt() . O método project() armazena esses resultados filtrados como um novo campo de array availableShowtimes .

O seguinte código mostra o pipeline para essa agregação:

val showtimes = current().getArray<MqlDocument>("showtimes")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.project(
            Projections.fields(
                Projections.computed("availableShowtimes", showtimes
                    .filter { showtime ->
                        val seats = showtime.getArray<MqlInteger>("seats")
                        val totalSeats = seats.sum { n -> n }
                        val ticketsBought = showtime.getInteger("ticketsBought")
                        val isAvailable = ticketsBought.lt(totalSeats)
                        isAvailable
                    })
            )
        )
    )
)

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 utilizando os métodos lt() e gt() . O método project() registra este resultado no campo extremeTemp .

O seguinte código mostra o pipeline para essa agregação:

val temperature = current().getInteger("temperature")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.project(
            Projections.fields(
                Projections.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.

O exemplo a seguir mostra um pipeline que corresponde a todos os documentos onde o campo location tem o valor "California":

val location = current().getString("location")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.match(
            Filters.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.

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, a 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:

val member = current().getField("member")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.project(
            Projections.fields(
                Projections.computed("membershipLevel",
                    member.switchOn { field ->
                        field
                            .isString { s -> s }
                            .isBoolean { b -> b.cond(of("Gold"), of("Guest")) }
                            .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, você não pode encadear métodos estáticos diretamente no Kotlin. O método passTo() permite encadear valores em métodos estáticos personalizados.

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:

fun gradeAverage(students: MqlArray<MqlDocument>, fieldName: String): MqlNumber {
    val sum = students.sum { student -> student.getInteger(fieldName) }
    val avg = sum.divide(students.size())
    return avg
}
fun evaluate(grade: MqlNumber, cutoff1: MqlNumber, cutoff2: MqlNumber): MqlString {
    val message = grade.switchOn { on ->
        on
            .lte(cutoff1) { g -> of("Needs improvement") }
            .lte(cutoff2) { g -> of("Meets expectations") }
            .defaults { g -> of("Exceeds expectations") }
    }
    return message
}

O método passArrayTo() pega uma array de todos os alunos e calcula a pontuação média usando o método gradeAverage() . Em seguida, o método passNumberTo() utiliza o método evaluate() para determinar o desempenho das salas de aula. Este exemplo armazena o resultado como o campo evaluation utilizando o método project() .

O seguinte código mostra o pipeline para essa agregação:

val students = current().getArray<MqlDocument>("students")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.project(
            Projections.fields(
                Projections.computed("evaluation", students
                    .passArrayTo { s -> gradeAverage(s, "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.

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:

val students = current().getArray<MqlDocument>("students")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.project(
            Projections.fields(
                Projections.computed("evaluation", students
                    .passArrayTo { s -> gradeAverage(s, "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:

[ { $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.

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 dia da semana é uma data e, em seguida, converte-a em um número. A atribuição de número usa 0 para média domingo ao usar o fuso horário "America/New_York" . O método eq() compara esse valor com 2, ou segunda-feira.

O seguinte código mostra o pipeline para essa agregação:

val deliveryDate = current().getString("deliveryDate")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.match(
            Filters.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.

Digamos que você tenha um conjunto de dados de cliente legado que contém endereços como documentos secundários no campo mailing.address . Você deseja encontrar todos os clientes que vivem 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:

val address = current().getDocument("mailing.address")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.match(
            Filters.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.

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 em seu inventário do item. Você deseja determinar o número total de cópias de itens que você tem em todos os armazéns. Um documento desse conjunto poderia ser como o exemplo abaixo:

{
  "_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:

val warehouses = current().getMap<MqlNumber>("warehouses")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.project(
            Projections.fields(
                Projections.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.

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 lastName e employeeID 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:

val lastName = current().getString("lastName")
val employeeID = current().getString("employeeID")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.project(
            Projections.fields(
                Projections.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. Para programar lógica de ramificação com base no tipo de dados, consulte switchOn().

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:

val rating = current().getField("rating")
val results = collection.aggregate<Document>(
    listOf(
        Aggregates.project(
            Projections.fields(
                Projections.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
        } }
} } ]