Documentos

Visão geral

The Scala driver includes two Scala-specific representations for BSON documents. Following the convention from the Scala collections library, there are immutable and mutable implementations of the Document type. The underlying implementations of Document use the type-safe BsonDocument class. The BSON classes are available from the org.mongodb.scala.bson namespace, which includes type aliases and companion objects. These objects should suffice for many use cases, but for advanced use cases you may need to use classes from the org.bson namespace directly.

BsonValue é a representação segura de tipo de um tipo BSON da biblioteca org.bson e representa tipos de valor específicos. Os tipos de valor mais comumente usados são os seguintes:

É possível alterar ou estender esses mapeamentos, um processo descrito nas seções a seguir.

As seções a seguir descrevem as duas classes principais de Document .

Documentos imutáveis

Semelhante à biblioteca de coleções Scala, a classe imutável é a classe preferida. Para conveniência, ele tem nomes alternativos de org.mongodb.scala.Document e org.mongodb.scala.bson.Document , além de estar disponível em org.mongodb.scala.bson.collection.immutable.Document.

As instâncias desse tipo são imutáveis para todos. Essa coleção nunca mudará depois de criada. Portanto, você pode confiar no fato de que acessar o mesmo valor de coleção repetidamente em diferentes pontos no tempo sempre produzirá uma coleção com os mesmos elementos.

import org.mongodb.scala.bson._
val doc1 = Document("AL" -> BsonString("Alabama"))
val doc2 = doc1 + ("AK" -> BsonString("Alaska"))
val doc3 = doc2 ++ Document("AR" -> BsonString("Arkansas"), "AZ" -> BsonString("Arizona"))

Documentos mutáveis

Para obter o tipo Document mutável, você precisa importá-lo explicitamente de org.mongodb.scala.collections.mutable.Document. O Document mutável pode ser atualizado ou estendido no local. Isso significa que você pode alterar, adicionar ou remover elementos do Document como um efeito colateral. Semelhante às coleções Scala, ao lidar com tipos mutáveis, você precisa entender qual código muda qual coleção e quando.

import org.mongodb.scala.bson._
import org.mongodb.scala.bson.collection.mutable.Document
val doc = Document("AL" -> BsonString("Alabama"))
val doc1 = doc + ("AK" -> BsonString("Alaska"))   // doc not mutated but new doc created
doc1 ++= Document("AR" -> BsonString("Arkansas"),
                  "AZ" -> BsonString("Arizona"))  // doc1 mutated as ++= changes in place.

Conversões implícitas

Para muitos dos tipos de BsonValue , existem mapeamentos diretos lógicos de um tipo de Scala. Por exemplo, um String mapeia para BsonString, um Int mapeia para BsonInt32 e um Long mapeia para um BsonInt64. Por conveniência, esses tipos podem ser usados diretamente com tipos Document e são convertidos pelas características de contrato no objeto BsonMagnets . Desde que haja um BsonTransformer implícito no escopo para qualquer tipo, esse tipo pode ser convertido em um BsonValue.

Os seguintes BsonTransformers estão no escopo por padrão:

import org.mongodb.scala.Document
val doc1 = Document("AL" -> "Alabama")
val doc2 = doc1 + ("AK" -> "Alaska")
val doc3 = doc2 ++ Document("AR" -> "Arkansas", "population" -> 2.966)

This is achieved by making use of the Magnet Pattern, which you can learn more about in the Magnet Pattern blog post on spray.io.

Na API, onde normalmente esperariamos um único valor ou um par de valores-chave ou muitos pares de valores de chaves, como BsonValue, (String, BsonValue) ou Iterable[(String, BsonValue)], exigimos qualquer coisa que possa se tornar aqueles tipos por meio de características CanBeX que lidam com as conversões implícitas necessárias para estar em conformidade com os tipos corretos. Essas características são CanBeBsonValue, CanBeBsonElement e CanBeBsonElements.

Um desses exemplos é adicionar um par de valores-chave a um Document ou uma lista de valores:

val doc1 = Document("AL" -> "Alabama")
val doc2 = Document("codes" -> List("AL", "AK", "AR"))

collection.find(Document("x" -> 1))
collection.find(Filters.eq("x", 1))