mongo4cats

https://kirill5k.github.io/mongo4cats/
Admin
mongo4cats is a MongoDB Java client wrapper for Scala that provides a functional and idiomatic...
Tokens:8,600
Snippets:115
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Quick Start with ZIO

Source: https://kirill5k.github.io/mongo4cats

This example shows how to perform MongoDB operations using ZIO, including connection, insertion, and querying. It utilizes ZLayers for dependency management.

```scala
import mongo4cats.bson.Document
import mongo4cats.bson.syntax._
import mongo4cats.operations.{Filter, Projection}
import mongo4cats.zio.{ZMongoClient, ZMongoCollection, ZMongoDatabase}
import zio._

object Zio extends ZIOAppDefault {

  val client     = ZLayer.scoped[Any](ZMongoClient.fromConnectionString("mongodb://localhost:27017"))
  val database   = ZLayer.fromZIO(ZIO.serviceWithZIO[ZMongoClient](_.getDatabase("my-db")))
  val collection = ZLayer.fromZIO(ZIO.serviceWithZIO[ZMongoDatabase](_.getCollection("docs")))

  val program = for {
    coll <- ZIO.service[ZMongoCollection[Document]]
    _    <- coll.insertMany((0 to 100).map(i => Document("name" := s"doc-$i", "index" := i)))
    docs <- coll.find
      .filter(Filter.gte("index", 10) && Filter.regex("name", "doc-[1-9]0"))
      .projection(Projection.excludeId)
      .sortByDesc("name")
      .limit(5)
      .all
    _ <- Console.printLine(docs.mkString("[", ", ", "]"))
  } yield ()

  override def run = program.provide(client, database, collection)
}
```

--------------------------------

### Quick Start with Cats Effect

Source: https://kirill5k.github.io/mongo4cats

This example demonstrates connecting to MongoDB, inserting documents, and querying them using Cats Effect. Ensure you have a MongoDB instance running on localhost:27017.

```scala
import cats.effect.{IO, IOApp}
import mongo4cats.client.MongoClient
import mongo4cats.operations.{Filter, Projection}
import mongo4cats.bson.Document
import mongo4cats.bson.syntax._

object Quickstart extends IOApp.Simple {

  override val run: IO[Unit] = 
    MongoClient.fromConnectionString[IO]("mongodb://localhost:27017").use { client =>
      for {
        db   <- client.getDatabase("my-db")
        coll <- db.getCollection("docs")
        _    <- coll.insertMany((0 to 100).map(i => Document("name" := s"doc-$i", "index" := i)))
        docs <- coll.find
          .filter(Filter.gte("index", 10) && Filter.regex("name", "doc-[1-9]0"))
          .projection(Projection.excludeId)
          .sortByDesc("name")
          .limit(5)
          .all
        _ <- IO.println(docs.mkString("[", ", ", "]"))
      } yield ()
    }
}
```

--------------------------------

### Add core dependency

Source: https://kirill5k.github.io/mongo4cats/docs

Include the core library in your build.sbt file to get started.

```scala
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-core" % "<version>"
```

--------------------------------

### Define Aggregation Pipeline

Source: https://kirill5k.github.io/mongo4cats/docs/operations/aggregate

Construct an aggregation pipeline using `Aggregate`, `Accumulator`, and `Sort`. This example groups transactions by category, calculates sums, and sorts the results.

```scala
import mongo4cats.operations.{Accumulator, Aggregate, Sort}  
  
// specification for grouping multiple transactions from the same group:  
val accumulator = Accumulator  
  .sum("count", 1) // number of transactions in a given group  
  .sum("totalAmount", "$amount") // total amount  
  .first("categoryId", "$category._id") // id of a category under which all transactions are grouped  
  
val aggregation = Aggregate  
  .group("$category", accumulator) // group all transactions by categoryId and accumulate result into a given specification  
  .lookup("categories", "categoryId", "_id", "category") // find a category for each group of transactions by category id  
  .sort(Sort.desc("totalAmount")) // define the order of the produced results  
```

--------------------------------

### Monitor Collection Changes with Aggregation Pipeline

Source: https://kirill5k.github.io/mongo4cats/docs/operations/watch

Optionally, provide an aggregation pipeline to the `watch` method to filter or transform change events before they are emitted. This example uses a match stage to only receive documents with an 'amount' greater than or equal to 100.

```scala
import mongo4cats.collection.operations.{Aggregate, Filter}
  
val changes: fs2.Stream[IO, Document] = collection.watch(Aggregate.matchBy(Filter.gte("amount", 100))).stream
```

--------------------------------

### Instantiate MongoClient using various connection methods

Source: https://kirill5k.github.io/mongo4cats/docs/gettingstarted/connection

Demonstrates creating a MongoClient instance using connection strings, server addresses, explicit connection objects, or custom settings. All methods return a Resource[F, MongoClient[F]] to ensure proper disposal.

```scala
import cats.effect.IO  
import mongo4cats.models.client._  
import mongo4cats.client._  
  
// From a connection string  
val clientFromConnString = MongoClient.fromConnectionString[IO]("mongodb://localhost:27017")  
  
// By providing ServerAddress  
val clientFromServerAddress = MongoClient.fromServerAddress[IO](ServerAddress("localhost", 27017))  
  
// By providing Connection  
val connection = MongoConnection("localhost", 27017, Some(MongoCredential("username", "password")), MongoConnectionType.Classic)  
val clientFromConnection = MongoClient.fromConnection[IO](connection)  
  
// By providing custom MongoClientSettings object  
val settings = MongoClientSettings.builder().applyConnectionString(ConnectionString("mongodb://localhost:27017")).build()  
val clientFromSettings = MongoClient.create[IO](settings)
```

--------------------------------

### Import ZIO classes

Source: https://kirill5k.github.io/mongo4cats/docs/zio

Import essential ZIO-compatible classes for Mongo4cats.

```scala
import mongo4cats.zio._  
```

--------------------------------

### Import Circe support

Source: https://kirill5k.github.io/mongo4cats/docs/circe

Enable automatic derivation of MongoDB codecs by importing the circe package.

```scala
import mongo4cats.circe._
```

--------------------------------

### Connect to database and collections

Source: https://kirill5k.github.io/mongo4cats/docs/zio

Create ZLayers for ZMongoClient, ZMongoDatabase, and ZMongoCollection.

```scala
import mongo4cats.zio._  
  
val client = ZLayer.scoped[Any](ZMongoClient.fromConnectionString("mongodb://localhost:27017"))  
val database = ZLayer.fromZIO(ZIO.serviceWithZIO[ZMongoClient](_.getDatabase("my-db")))  
val collection = ZLayer.fromZIO(ZIO.serviceWithZIO[ZMongoDatabase](_.getCollection("docs")))  
```

--------------------------------

### Access a MongoDB database instance

Source: https://kirill5k.github.io/mongo4cats/docs/gettingstarted/connection

Shows how to retrieve a MongoDatabase instance from a connected client. The database is created automatically upon the first query if it does not exist.

```scala
import mongo4cats.database.MongoDatabase  
  
MongoClient.fromConnectionString[IO]("mongodb://localhost:27017").use { client =>  
  val database: IO[MongoDatabase[IO]] = client.getDatabase("mydb")  
}
```

--------------------------------

### Create an index with options

Source: https://kirill5k.github.io/mongo4cats/docs/operations/indexes

Apply additional configurations like unique constraints by passing an IndexOptions object to createIndex.

```scala
import mongo4cats.operations.Index  
import mongo4cats.models.collection.IndexOptions  
  
val index = Index.ascending("name", "email")  
val options = IndexOptions().unique(true)  
val result: IO[String] = collection.createIndex(index, options)
```

--------------------------------

### Add ZIO 2 integration

Source: https://kirill5k.github.io/mongo4cats/docs

Include these dependencies for ZIO 2 integration.

```scala
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-zio" % "<version>"
  
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-zio-embedded" % "<version>"
```

--------------------------------

### Create a simple index

Source: https://kirill5k.github.io/mongo4cats/docs/operations/indexes

Use the createIndex method with an index specification object to create a basic index on a field.

```scala
import mongo4cats.operations.Index  
  
val result: IO[String] = collection.createIndex(Index.ascending("field"))
```

--------------------------------

### Enable Circe or Zio-Json Support

Source: https://kirill5k.github.io/mongo4cats

Add optional dependencies for JSON serialization with Circe or Zio-Json to your build.sbt.

```scala
// circe
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-circe" % "<version>"
// zio-json
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-zio-json" % "<version>"
```

--------------------------------

### Create MongoDB Document with BsonValue Constructors

Source: https://kirill5k.github.io/mongo4cats/docs/gettingstarted/documents

Demonstrates creating a MongoDB document using explicit BsonValue constructors for various data types. Ensure all values are wrapped in the appropriate BsonValue type.

```scala
import mongo4cats.bson.{BsonValue, Document, ObjectId}
import java.time.Instant

val doc: Document = Document(
  "_id"            -> BsonValue.objectId(ObjectId.gen),
  "null"           -> BsonValue.Null,
  "string"         -> BsonValue.string("str"),
  "int"            -> BsonValue.int(1),
  "boolean"        -> BsonValue.boolean(true),
  "double"         -> BsonValue.double(2.0),
  "int"            -> BsonValue.int(1),
  "long"           -> BsonValue.long(1660999000L),
  "dateTime"       -> BsonValue.instant(Instant.now),
  "array"          -> BsonValue.array(BsonValue.string("item1"), BsonValue.string("item2"), BsonValue.string("item3")),
  "nestedDocument" -> BsonValue.document(Document("field" -> BsonValue.string("nested")))
)
```

--------------------------------

### Add ZIO 2 Dependencies for mongo4cats

Source: https://kirill5k.github.io/mongo4cats

For ZIO 2 integration, add the specific ZIO core and test dependencies to your build.sbt.

```scala
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-zio" % "<version>"
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-zio-embedded" % "<version>" % Test
```

--------------------------------

### Create MongoDB Document with := Syntax Sugar

Source: https://kirill5k.github.io/mongo4cats/docs/gettingstarted/documents

Utilizes the := syntax from mongo4cats.bson.syntax for more concise document creation, automatically converting common Scala types to BsonValue. Requires importing mongo4cats.bson.syntax._.

```scala
import mongo4cats.bson.syntax._

val doc: Document = Document(
  "_id"            := ObjectId.gen,
  "null"           := BsonValue.Null,
  "string"         := "str",
  "int"            := 1,
  "boolean"        := true,
  "double"         := 2.0,
  "int"            := 1,
  "long"           := 1660999000L,
  "dateTime"       := Instant.now,
  "array"          := List("item1", "item2", "item3"),
  "nestedDocument" := Document("field" := "nested")
)
```

--------------------------------

### Add ZIO dependency

Source: https://kirill5k.github.io/mongo4cats/docs/zio

Include the mongo4cats-zio module in your build configuration.

```scala
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-zio" % "<version>"  
```

--------------------------------

### Convert between JSON and BSON

Source: https://kirill5k.github.io/mongo4cats/docs/circe

Demonstrates converting a Scala case class to a BSON document and back using Circe encoders and decoders.

```scala
import io.circe.generic.auto._  
import mongo4cats.bson.{Document, ObjectId}  
import mongo4cats.circe._  
import mongo4cats.bson.syntax._  
  
import java.time.Instant  
  
final case class MyClass(  
  _id: ObjectId,  
  dateField: Instant,  
  stringField: String,  
  intField: Int,  
  longField: Long,  
  arrayField: List[String],  
  optionField: Option[String]  
)  
  
val myClass = MyClass(  
  _id = ObjectId.gen,  
  dateField = Instant.now(),  
  stringField = "string",  
  intField = 1,  
  longField = 1660999000L,  
  arrayField = List("item1", "item2"),  
  optionField = None  
)  
  
val doc = Document("_id" := ObjectId.gen, "myClasses" := List(myClass))  
val jsonString = doc.toJson  
val retrievedMyClasses = doc.getAs[List[MyClass]]("myClasses")
```

--------------------------------

### Add ZIO Json codec support

Source: https://kirill5k.github.io/mongo4cats/docs

Include this dependency for automatic derivation of Bson codecs via ZIO Json.

```scala
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-zio-json" % "<version>"
```

--------------------------------

### Import Embedded MongoDB

Source: https://kirill5k.github.io/mongo4cats/docs/zio

Import the necessary package for ZIO-based embedded MongoDB.

```scala
import mongo4cats.zio.embedded._  
```

--------------------------------

### Add Circe dependency

Source: https://kirill5k.github.io/mongo4cats/docs/circe

Include the mongo4cats-circe library in your build.sbt file to enable Circe support.

```scala
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-circe" % "<version>"
```

--------------------------------

### Create an index using MongoDB Java builders

Source: https://kirill5k.github.io/mongo4cats/docs/operations/indexes

Leverage standard MongoDB Java library builders to define complex indexes for use with Mongo4cats.

```scala
import com.mongodb.client.model.Indexes  
  
val index = Indexes.compoundIndex(Indexes.ascending("field1"), Indexes.ascending("field2"))  
val result: IO[String] = collection.createIndex(index)
```

--------------------------------

### Execute Aggregation with Codec

Source: https://kirill5k.github.io/mongo4cats/docs/operations/aggregate

Execute an aggregation pipeline and decode the results directly into a specific class using `aggregateWithCodec`.

```scala
val result: fs2.Stream[IO, MyClass] = collection.aggregateWithCodec[MyClass](aggregation).stream  
```

--------------------------------

### Add mongo4cats Dependencies to build.sbt

Source: https://kirill5k.github.io/mongo4cats

Include core and test dependencies for mongo4cats in your build.sbt file. Specify the version according to your project's needs.

```scala
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-core" % "<version>"
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-embedded" % "<version>" % Test
```

--------------------------------

### Create a collection explicitly

Source: https://kirill5k.github.io/mongo4cats/docs/gettingstarted/collection

Creates a new collection in the database, optionally specifying configuration options like capped status or size.

```scala
val collection: IO[Unit] = database.createCollection("mycoll")  
  
// or with options  
import mongo4cats.models.database.CreateCollectionOptions  
  
val options = CreateCollectionOptions().capped(true).sizeInBytes(1024L)  
val collection: IO[Unit] = database.createCollection("mycoll", options)  
```

--------------------------------

### Distinct Operation Basics

Source: https://kirill5k.github.io/mongo4cats/docs/operations/distinct

Demonstrates how to retrieve distinct values for a field as an Iterable or a Stream.

```APIDOC
## Distinct Operation Basics

### Description
Retrieves all distinct values for a specified field across all documents in a collection.

### Method
`distinct`

### Endpoint
N/A (This is a method call on a collection object)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```scala
// Get distinct values as an Iterable
val distinctValues: IO[Iterable[String]] = collection.distinct[String]("field1").all

// Get distinct values as a Stream
val distinctValues: fs2.Stream[IO, String] = collection.distinct[String]("field1").stream
```

### Response
#### Success Response (200)
- **Iterable[T]** or **fs2.Stream[IO, T]**: A collection or stream of distinct values of type T found for the specified field.

#### Response Example
```json
// Example for Iterable response
["value1", "value2", "value3"]

// Example for Stream response (each value would be emitted individually)
```
```

--------------------------------

### Use codec with MongoCollection

Source: https://kirill5k.github.io/mongo4cats/docs/circe

Retrieve a MongoCollection configured with the derived codec provider.

```scala
import cats.effect.IO  
import mongo4cats.collection.MongoCollection  
  
val collection: IO[MongoCollection[IO, MyClass]] = database.getCollectionWithCodec[MyClass]("mycoll")
```

--------------------------------

### Retrieve Values from MongoDB Document

Source: https://kirill5k.github.io/mongo4cats/docs/gettingstarted/documents

Shows various methods for retrieving values from a document by key, including direct BsonValue retrieval, type-specific retrieval, and nested field retrieval. Returns Option types, yielding None if the key is not found.

```scala
val stringField1: Option[BsonValue] = doc.get("string")
val stringField2: Option[String]    = doc.getString("string")
val stringField3: Option[String]    = doc.getAs[String]("string")

val arrayField1: Option[BsonValue]       = doc.get("array")
val arrayField2: Option[List[BsonValue]] = doc.getList("array")
val arrayField3: Option[List[String]]    = doc.getAs[List[String]]("array")

val nestedField1: Option[BsonValue] = doc.getNested("nestedDocument.field")
val nestedField2: Option[String]    = doc.getNestedAs[String]("nestedDocument.field")
```

--------------------------------

### Execute Aggregation Pipeline

Source: https://kirill5k.github.io/mongo4cats/docs/operations/aggregate

Execute a defined aggregation pipeline on a `MongoCollection`. Results can be fetched as the first document, all documents, or a stream.

```scala
import mongo4cats.bson.Document  
  
val result: IO[Option[Document]] = collection.aggregate[Document](aggregation).first  
val result: IO[Iterable[Document]] = collection.aggregate[Document](aggregation).all  
val result: fs2.Stream[IO, Document] = collection.aggregate[Document](aggregation).stream  
```

--------------------------------

### Distinct Operation with Custom Types and Codecs

Source: https://kirill5k.github.io/mongo4cats/docs/operations/distinct

Shows how to retrieve distinct values as complex types like Document or custom classes, including explicit codec handling.

```APIDOC
## Distinct Operation with Custom Types and Codecs

### Description
Retrieves distinct values for a field, allowing upcasting to more complex types like `Document` or custom classes, with support for custom codecs.

### Method
`distinct`, `distinctWithCodec`, `withAddedCodec`

### Endpoint
N/A (This is a method call on a collection object)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```scala
import mongo4cats.bson.Document

// Get distinct values as Documents
val distinctValues: IO[Iterable[Document]] = collection.distinct[Document]("field1").all

// Get distinct values as a custom class MyClass, assuming a MongoCodecProvider[MyClass] is available
val distinctValues: IO[Iterable[MyClass]] = collection.distinctWithCodec[MyClass]("field1").all

// Get distinct values as a custom class MyClass, by explicitly adding codecs
val distinctValues: IO[Iterable[MyClass]] = collection.withAddedCodec(myClassCodecs).distinct[MyClass]("field1").all
```

### Response
#### Success Response (200)
- **Iterable[T]**: A collection of distinct values of type T (e.g., `Document`, `MyClass`) found for the specified field.

#### Response Example
```json
// Example for Iterable[Document] response
[
  {"$oid": "60d5ec49f1e4b3a3b4f8a1b2"},
  {"$oid": "60d5ec49f1e4b3a3b4f8a1b3"}
]

// Example for Iterable[MyClass] response (structure depends on MyClass definition)
[
  {"fieldA": "valueA1", "fieldB": 10},
  {"fieldA": "valueA2", "fieldB": 20}
]
```
```

--------------------------------

### Create a compound index

Source: https://kirill5k.github.io/mongo4cats/docs/operations/indexes

Combine multiple index specifications to create a compound index using chaining or the combinedWith method.

```scala
import mongo4cats.operations.Index  
  
val compoundIndex = Index.ascending("field1").descending("field2")  
  
// or by just combining 2 indexes together  
val index1 = Index.ascending("field1")  
val index2 = Index.descending("field2")  
val compoundIndex = index1.combinedWith(index2)
```

--------------------------------

### Execute Aggregation to Collection

Source: https://kirill5k.github.io/mongo4cats/docs/operations/aggregate

Execute an aggregation pipeline where the final stage is `$out`, writing the results directly to a specified collection using `toCollection`.

```scala
val result: IO[Unit] = collection.aggregate[Document](aggregation).toCollection  
```

--------------------------------

### Obtain a generic MongoCollection

Source: https://kirill5k.github.io/mongo4cats/docs/gettingstarted/collection

Retrieves a collection instance by name using the default Document type.

```scala
import mongo4cats.bson.Document  
import mongo4cats.collection.MongoCollection  
  
val collection: IO[MongoCollection[IO, Document]] = database.getCollection("mycoll")  
```

--------------------------------

### Update documents using Mongo4cats DSL

Source: https://kirill5k.github.io/mongo4cats/docs/operations/update

Uses the native Mongo4cats Update DSL to chain operations and apply them to documents. Supports optional UpdateOptions for configurations like upsert.

```scala
import mongo4cats.operations.{Filter, Update}  
import mongo4cats.models.collection.UpdateOptions  
  
// chain multiple updates together  
val update = Update.set("field1", "foo").currentDate("date")  
  
val result: IO[UpdateResult] = collection.updateOne(Filter.empty, update)
// or with options  
val result: IO[UpdateResult] = collection.updateOne(Filter.empty, update, UpdateOptions().upsert(true))  
```

--------------------------------

### Add embedded MongoDB for testing

Source: https://kirill5k.github.io/mongo4cats/docs

Include this dependency to use embedded MongoDB in your test suite.

```scala
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-embedded" % "<version>" % Test
```

--------------------------------

### Update MongoDB Documents Immutably

Source: https://kirill5k.github.io/mongo4cats/docs/gettingstarted/documents

Demonstrates adding new fields to an existing document. Note that documents are immutable, so these operations return new document instances.

```scala
val updatedDoc1 = doc.add("newField" -> BsonValue.string("string"))
val updatedDoc2 = doc.add("newField" -> "string")
val updatedDoc3 = doc += ("anotherNewField" -> BsonValue.instant(ts))
val updatedDoc4 = doc += ("anotherNewField" := 1)
```

--------------------------------

### Derive MongoCodecProvider

Source: https://kirill5k.github.io/mongo4cats/docs/circe

Create a MongoCodecProvider for a case class to enable its use with MongoDB collections.

```scala
import io.circe.generic.auto._  
import mongo4cats.codecs.MongoCodecProvider  
import mongo4cats.circe._  
  
object MyClass {  
  implicit val myClassCodecProvider: MongoCodecProvider[MyClass] = deriveCirceCodecProvider  
}
```

--------------------------------

### Skip and limit results

Source: https://kirill5k.github.io/mongo4cats/docs/operations/find

Restrict the number of documents returned by applying skip and limit modifiers.

```scala
val data = IO[Iterable[Document]] = collection.find  
  .skip(10) // skip the first 10   
  .limit(100) // take the next 100  
  .all  
```

--------------------------------

### Add mongo4cats-embedded Dependency

Source: https://kirill5k.github.io/mongo4cats/docs/embedded

Add this dependency to your build.sbt file to enable embedded MongoDB support.

```scala
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-embedded" % "<version>"  

```

--------------------------------

### Add Embedded MongoDB dependency

Source: https://kirill5k.github.io/mongo4cats/docs/zio

Include the mongo4cats-zio-embedded module for testing with embedded MongoDB.

```scala
libraryDependencies += "io.github.kirill5k" %% "mongo4cats-zio-embedded" % "<version>"  
```

--------------------------------

### Monitor Collection Changes with Mongo4cats

Source: https://kirill5k.github.io/mongo4cats/docs/operations/watch

Use the `watch` method on a `MongoCollection` instance to create a stream of change event documents. This stream emits events whenever changes occur in the collection.

```scala
import mongo4cats.bson.Document
  
val changes: fs2.Stream[IO, Document] = collection.watch.stream
```

--------------------------------

### Retrieve distinct values with custom types and codecs

Source: https://kirill5k.github.io/mongo4cats/docs/operations/distinct

Handle complex types by upcasting to Document or using custom codecs via distinctWithCodec or withAddedCodec.

```scala
import mongo4cats.bson.Document  
  
val distinctValues: IO[Iterable[Document]] = collection.distinct[Document]("field1").all  
  
// assuming you have an instance of MongoCodecProvider[MyClass] available in the implicit scope  
val distinctValues: IO[Iterable[MyClass]] = collection.distinctWithCodec[MyClass]("field1").all  
  
// or you can add codecs explicitly  
val distinctValues: IO[Iterable[MyClass]] = collection.withAddedCodec(myClassCodecs).distinct[MyClass]("field1").all
```

--------------------------------

### Watch Collection Changes

Source: https://kirill5k.github.io/mongo4cats/docs/tags/watch

Describes the watch operation used to monitor changes in a single collection.

```APIDOC
## WATCH Operation

### Description
The watch operation allows monitoring for changes in a single collection. The change stream can be created by calling the watch method on a MongoCollection[F, T] instance.
```

--------------------------------

### Obtain a typed MongoCollection

Source: https://kirill5k.github.io/mongo4cats/docs/gettingstarted/collection

Retrieves a collection tied to a specific class using explicit codec registries or implicit providers.

```scala
// needs to have an instance of CodecRegistry built for the provided class  
val collection: IO[MongoCollection[IO, MyClass]] = database.getCollection[MyClass]("mycoll", myClassCodecRegistry)  
  
// needs to have an instance of MongoCodecProvider[MyClass] available in the implicit scope  
val collection: IO[MongoCollection[IO, MyClass]] = database.getCollectionWithCodec[MyClass]("mycoll")  
```

--------------------------------

### Stream MongoDB documents

Source: https://kirill5k.github.io/mongo4cats/docs/operations/find

Retrieve all documents from a collection as an fs2 Stream.

```scala
import mongo4cats.bson.Document  
  
val data: fs2.Stream[IO, Document] = collection.find.stream  
```

--------------------------------

### Update documents using MongoDB Java driver builders

Source: https://kirill5k.github.io/mongo4cats/docs/operations/update

Utilizes the standard MongoDB Java driver's Updates and Filters builders to construct update queries.

```scala
import com.mongodb.client.model.{Filters, Updates}  
  
val update = Updates.combine(Updates.set("field1", "foo"), Updates.currentDate("date"))  
val result: IO[UpdateResult] = collection.updateOne(Filters.empty(), update)  
```

--------------------------------

### Filter MongoDB documents

Source: https://kirill5k.github.io/mongo4cats/docs/operations/find

Apply composable filters to find operations using logical operators.

```scala
import mongo4cats.operations.Filter  
  
val filter1 = Filter.eq("field1", "foo")  
val filter2 = Filter.eq("field2", "bar")  
val filter3 = Filter.exists("field3")  
val data: IO[Option[Document]] = collection.find((filter1 || filter2) && filter2).first  
```

--------------------------------

### Test with Embedded MongoDB

Source: https://kirill5k.github.io/mongo4cats/docs/zio

Extend the EmbeddedMongo trait to run tests against an embedded MongoDB instance.

```scala
import mongo4cats.bson._  
import mongo4cats.bson.syntax._  
import mongo4cats.zio._  
import mongo4cats.zio.embedded.EmbeddedMongo  
import zio._  
import zio.test._  
import zio.test.Assertion._  
  
object ZMongoCollectionSpec extends ZIOSpecDefault with EmbeddedMongo {  
  override def spec = suite("A ZMongoCollection")(  
    test("should store and retrieve documents") {  
      withRunningEmbeddedMongo("localhost", 27017) {  
        ZIO  
          .serviceWithZIO[ZMongoDatabase] { db =>  
            for {  
              coll <- db.getCollection("coll")  
              doc = Document("_id" := ObjectId.gen)  
              insertResult <- coll.insertOne(doc)  
              result <- coll.find.all  
            } yield assert(result)(equalTo(List(doc)))  
          }  
          .provide(  
            ZLayer.scoped(ZMongoClient.fromConnectionString(s"mongodb://localhost:27017")),  
            ZLayer.fromZIO(ZIO.serviceWithZIO[ZMongoClient](_.getDatabase("my-db")))  
          )  
      }  
    }  
  )  
}  
```

--------------------------------

### Sort MongoDB results

Source: https://kirill5k.github.io/mongo4cats/docs/operations/find

Enforce ordering on retrieved data using Sort specifications or sortBy methods.

```scala
import mongo4cats.operations.Sort  
  
// sort in ascending order by field1, then in descending order by field2  
val data = IO[Iterable[Document]] = collection.find.sort(Sort.asc("field1").desc("field2")).all  
  
// same as the above but without Sort specification  
val data = IO[Iterable[Document]] = collection.find.sortBy("field1").sortByDesc("field2").all  
```

--------------------------------

### Retrieve distinct values from a collection

Source: https://kirill5k.github.io/mongo4cats/docs/operations/distinct

Use the distinct method to return unique values for a field as an IO collection or an fs2 stream.

```scala
val distinctValues: IO[Iterable[String]] = collection.distinct[String]("field1").all  
  
// or stream all found values instead  
val distinctValues: fs2.Stream[IO, String] = collection.distinct[String]("field1").stream
```

--------------------------------

### Extend EmbeddedMongo Trait

Source: https://kirill5k.github.io/mongo4cats/docs/embedded

Extend the EmbeddedMongo trait to bring embedded MongoDB into your test class. You can override mongoPort to specify a custom port.

```scala
import cats.effect.IO
import cats.effect.unsafe.implicits.global
import mongo4cats.bson.Document
import mongo4cats.bsom.syntax._
import mongo4cats.client.MongoClient
import mongo4cats.embedded.EmbeddedMongo
import org.scalatest.matchers.must.Matchers
import org.scalatest.wordspec.AsyncWordSpec

class WithEmbeddedMongoSpec extends AsyncWordSpec with Matchers with EmbeddedMongo {
  
  // by default, MongoDB instance will be accessible on 27017 port, which can be overridden:
  override val mongoPort: Int = 12345
  
  "A MongoCollection" should {
    "create and retrieve documents from a db" in withRunningEmbeddedMongo {
      MongoClient.fromConnectionString[IO]("mongodb://localhost:12345").use {
        client =>
          for {
            db <- client.getDatabase("testdb")
            coll <- db.getCollection("docs")
            testDoc = Document("Hello" := "World!")
            _ <- coll.insertOne(testDoc)
            foundDoc <- coll.find.first
          } yield foundDoc mustBe Some(testDoc)
      }
    }.unsafeToFuture()

    // or connection properties can be passed explicitly
    "start instance on different port" in withRunningEmbeddedMongo("localhost", 12355) {
      MongoClient.fromConnectionString[IO]("mongodb://localhost:12355").use {
        client =>
          for {
            db <- client.getDatabase("testdb")
            coll <- db.getCollection("docs")
            testDoc = Document("Hello" := "World!")
            _ <- coll.insertOne(testDoc)
            foundDoc <- coll.find.first
          } yield foundDoc mustBe Some(testDoc)
      }
    }.unsafeToFuture()
  }
}

```
Tokens:
Raw