ZIO DynamoDB

https://github.com/zio/zio-dynamodb
Admin
ZIO DynamoDB is a type-safe, efficient library for accessing AWS DynamoDB with automatic query...
Tokens:48,114
Snippets:299
Trust Score:7.8
License:Apache-2.0
Update:9 months ago
Show doc for...
Tokens:
Raw
### Read and Write Data to DynamoDB (Scala)

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/getting-started.md

This Scala example demonstrates how to read and write data to DynamoDB using ZIO DynamoDB. It defines a case class `Person`, writes an instance to 'personTable', retrieves it using a partition key, and prints the result. It requires ZIO AWS core, ZIO DynamoDB, and ZIO Schema dependencies.

```scala
import zio.aws.core.config
import zio.aws.{ dynamodb, netty }
import zio.dynamodb.DynamoDBQuery.{ get, put }
import zio.dynamodb.{ DynamoDBExecutor }
import zio.schema.{ DeriveSchema, Schema }
import zio.ZIOAppDefault
import zio.dynamodb.ProjectionExpression

object Main extends ZIOAppDefault {

  final case class Person(id: Int, firstName: String)
  object Person {
    implicit lazy val schema: Schema.CaseClass2[Int, String, Person] = DeriveSchema.gen[Person]

    val (id, firstName) = ProjectionExpression.accessors[Person]
  }
  val examplePerson = Person(1, "avi")

  private val program = for {
    _      <- put("personTable", examplePerson).execute
    person <- get("personTable")(Person.id.partitionKey === 1).execute
    _      <- zio.Console.printLine(s"hello $person")
  } yield ()

  override def run = 
    program.provide(
      netty.NettyHttpClient.default,
      config.AwsConfig.default, // uses real AWS dynamodb
      dynamodb.DynamoDb.live,
      DynamoDBExecutor.live
    )
}
```

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

### DynamoDBExecutor Layer Setup (Scala)

Source: https://context7.com/zio/zio-dynamodb/llms.txt

Configures ZIO layers for connecting to AWS DynamoDB or DynamoDB Local. Provides examples for both production AWS and local development environments, including necessary dependencies and client configurations.

```scala
import zio.aws.core.config
import zio.aws.{dynamodb, netty}
import zio.dynamodb.DynamoDBExecutor
import zio.{ZIO, ZIOAppDefault, ZLayer}
import software.amazon.awssdk.auth.credentials.{AwsBasicCredentials, StaticCredentialsProvider}
import software.amazon.awssdk.regions.Region
import java.net.URI

object DynamoDBSetup extends ZIOAppDefault {

  // Production AWS DynamoDB configuration
  val productionLayer = 
    netty.NettyHttpClient.default ++ 
    config.AwsConfig.default ++ 
    dynamodb.DynamoDb.live ++ 
    DynamoDBExecutor.live

  // DynamoDB Local configuration for development/testing
  val awsConfig = ZLayer.succeed(
    config.CommonAwsConfig(
      region = None,
      credentialsProvider = StaticCredentialsProvider.create(
        AwsBasicCredentials.create("dummy", "dummy")
      ),
      endpointOverride = None,
      commonClientConfig = None
    )
  )

  val localLayer: ZLayer[Any, Throwable, DynamoDBExecutor] = 
    (netty.NettyHttpClient.default ++ awsConfig) >>> 
    config.AwsConfig.default >>> 
    dynamodb.DynamoDb.customized { builder => 
      builder.endpointOverride(URI.create("http://localhost:8000")).region(Region.US_EAST_1)
    } ++ 
    DynamoDBExecutor.live

  override def run = ZIO.unit
}
```

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

### Low-Level DynamoDB Operations (Scala)

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/concepts/low-level-api.md

Demonstrates common low-level DynamoDB operations including putting an item, getting an item, updating an item, and deleting an item using the zio-dynamodb library. This example showcases the use of `DynamoDBQuery` methods and expression building.

```scala
import zio.dynamodb.DynamoDBQuery
import zio.dynamodb.AttributeValue._
import zio.dynamodb.PrimaryKey
import zio.dynamodb.Item
import zio.dynamodb.ProjectionExpression

// Example usage:
for {
  _ <- DynamoDBQuery.putItem("person-table", Item("id" -> "1", "name" -> "John", "age" -> 42)).execute
  maybeFound <- DynamoDBQuery.getItem("person-table")(PrimaryKey("id" -> "1")).execute
  _ <- DynamoDBQuery.updateItem("person-table")(PrimaryKey("id" -> "1"))($("name").set("Smith") + $("age").set(21)).execute
  _ <- DynamoDBQuery.deleteItem("person-table")(PrimaryKey("id" -> "1")).execute
} yield ()
```

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

### Configure Get Query Operations in Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/crud-operations/get.md

Provides a template for configuring `get` query operations with consistency modes and conditional expressions. This allows for fine-grained control over data retrieval.

```scala
<GET_QUERY>
  .consistency(<ConsistencyMode>)
  .where(<ConditionExpression>)
```

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

### Execute DynamoDB Operations as Scala Futures

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/future-interop.md

This example demonstrates how to use `DynamoDBExecutorF.make` and the `executeToF` syntax to perform DynamoDB operations like createTable, put, get, and deleteTable, returning results as Scala Futures. It includes setting up a local DynamoDB client and managing resource cleanup.

```scala
package zio.dynamodb.examples.dynamodblocal.interop

import zio.dynamodb.DynamoDBQuery.{ get, put }
import zio.dynamodb.examples.dynamodblocal.interop.CeInteropExample.Person
import zio.dynamodb.interop.future.DynamoDBExecutorF
import zio.dynamodb.interop.future.syntax._
import zio.dynamodb.{ AttributeDefinition, BillingMode, DynamoDBQuery, KeySchema }

import scala.concurrent.Await
import scala.concurrent.ExecutionContext.Implicits.global
import scala.concurrent.duration._

object FutureInteropExample extends App {
  implicit val ddbExec: DynamoDBExecutorF = DynamoDBExecutorF.make(
    buildNettyClient = identity,
    buildDynamoDbClient = _.endpointOverride(java.net.URI.create("http://localhost:8000"))
      .region(software.amazon.awssdk.regions.Region.US_EAST_1)
      .credentialsProvider(
        software.amazon.awssdk.auth.credentials.StaticCredentialsProvider.create(
          software.amazon.awssdk.auth.credentials.AwsBasicCredentials.create("dummy", "dummy")
        )
      )
  )

  val program          = for {
    _      <- DynamoDBQuery
                .createTable("Person", KeySchema("id"), BillingMode.PayPerRequest)(
                  AttributeDefinition.attrDefnString("id")
                )
                .executeToF
    _      <- put(tableName = "Person", Person(id = "avi", name = "Avinder")).executeToF
    result <- get(tableName = "Person")(Person.id.partitionKey === "avi").executeToF
    _       = println(s"found=$result")
    _      <- DynamoDBQuery.deleteTable("Person").executeToF

  } yield () // This does not actually return anything, it's () because it's Unit
  val programWithClose = program.andThen { case _ => ddbExec.close() } // Ensure close is called

  Await.result(programWithClose, 30.seconds)
}
```

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

### Put Operation Examples (Scala)

Source: https://context7.com/zio/zio-dynamodb/llms.txt

Illustrates performing 'Put' operations in DynamoDB using ZIO DynamoDB. Shows basic insertion, conditional put to prevent overwrites, and how to retrieve old items upon insertion.

```scala
import zio.dynamodb.DynamoDBQuery.put
import zio.dynamodb.DynamoDBExecutor
import zio.ZIO

val person = Person("1", "John", 30)

// Basic put operation
val simplePut: ZIO[DynamoDBExecutor, Throwable, Unit] = for {
  _ <- put("personTable", person).execute
} yield ()

// Put with condition expression (only insert if item doesn't exist)
val conditionalPut: ZIO[DynamoDBExecutor, Throwable, Unit] = for {
  _ <- put("personTable", person)
         .where(Person.id.notExists)  // Prevents overwriting existing items
         .execute
} yield ()

// Put with return values to get the old item
val putWithReturn: ZIO[DynamoDBExecutor, Throwable, Option[Person]] = 
  put("personTable", person)
    .returns(zio.dynamodb.ReturnValues.AllOld)
    .execute
```

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

### Product Traversal Example (`>>>`)

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/creating-models/field-traversal.md

Demonstrates using the `>>>` combinator to traverse into a nested case class. This example shows how to access the `street` field within the `address` field of a `Person` object.

```scala
  val addressToStreetPE: ProjectionExpression[Person, String]            =
    (Person.address >>> Address.street) 
```

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

### Handle Get Operation Errors with ZIO Absolve in Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/crud-operations/get.md

Shows how to use the `absolve` extension method to convert `ItemError` from the `get` operation's `Either` result into ZIO's error channel. This simplifies error handling by consolidating errors into the standard ZIO error flow.

```scala
import zio.dynamodb.syntax._
for {
  person <- DynamoDBQuery.get("person")(Person.id.primaryKey === "1").execute.absolve
} yield person
```

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

### Run DynamoDBLocal Docker Container

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/index.md

Commands to start and stop a DynamoDB Local Docker container. This is useful for local development and testing without hitting actual AWS DynamoDB.

```bash
docker compose -f docker/docker-compose.yml up -d
```

```bash
docker compose -f docker/docker-compose.yml down
```

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

### Add ZIO DynamoDB Dependency (Scala)

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/getting-started.md

This snippet shows how to add the ZIO DynamoDB library to your Scala project's build.sbt file. Replace `@VERSION@` with the desired version of the library.

```scala
libraryDependencies += "dev.zio" %% "zio-dynamodb" % @VERSION@
```

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

### Cats Effect Interop Example with ZIO DynamoDB

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/ce-interop.md

An example demonstrating how to use ZIO DynamoDB with Cats Effect 3. It shows setting up a `DynamoDBExecutorF` with custom AWS SDK client configuration, performing CRUD operations, and executing a parallel scan with filtering, all within an `IOApp`.

```scala
package zio.dynamodb.examples.dynamodblocal.interop

import software.amazon.awssdk.auth.credentials.AwsBasicCredentials
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider
import software.amazon.awssdk.regions.Region
import zio.dynamodb.DynamoDBQuery.{ createTable, deleteTable, get, put }

import cats.effect.std.Console
import cats.effect.IO
import cats.effect.IOApp
import cats.syntax.all._

import java.net.URI

import zio.dynamodb.interop.ce.syntax._
import zio.dynamodb.ProjectionExpression
import zio.schema.DeriveSchema
import zio.schema.Schema
import zio.dynamodb.KeySchema
import zio.dynamodb.BillingMode
import zio.dynamodb.AttributeDefinition
import zio.dynamodb.DynamoDBQuery
import cats.effect.kernel.Async

/**
 * example cats effect interop application
 *
 * to run in the sbt console:
 * {{{ 
 * zio-dynamodb-examples/runMain zio.dynamodb.examples.dynamodblocal.interop.CeInteropExample
 * }}}
 */
object CeInteropExample extends IOApp.Simple {

  final case class Person(id: String, name: String)
  object Person {
    implicit val schema: Schema.CaseClass2[String, String, Person] = DeriveSchema.gen[Person]
    val (id, name)                                                 = ProjectionExpression.accessors[Person]
  }

  def program[F[_]](implicit F: Async[F]) = {
    val console = Console.make[F]

    for {
      _ <- DynamoDBExceutorF
             .ofCustomised[F] { builder => // note only AWS SDK model is exposed here, not zio.aws
               builder
                 .endpointOverride(URI.create("http://localhost:8000"))
                 .region(Region.US_EAST_1)
                 .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create("dummy", "dummy")))
             }
             .use { implicit dynamoDBExecutorF => // To use extension method "executeToF" we need implicit here
               for {
                 _         <- createTable("Person", KeySchema("id"), BillingMode.PayPerRequest)(
                                AttributeDefinition.attrDefnString("id")
                              ).executeToF
                 _         <- put(tableName = "Person", Person(id = "avi", name = "Avinder")).executeToF
                 result    <- get(tableName = "Person")(Person.id.partitionKey === "avi").executeToF
                 _         <- console.println(s"found=$result")
                 fs2Stream <- DynamoDBQuery
                                .scanAll[Person](tableName = "Person")
                                .parallel(50) // server side parallel scan
                                .filter(Person.name.beginsWith("Avi") && Person.name.contains("de"))
                                .executeToF
                 _         <- fs2Stream.evalTap(person => console.println(s"person=$person")).compile.drain
                 _         <- deleteTable("Person").executeToF
               } yield () 
             }
    } yield () 
  }

  val run = program[IO]
}

```

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

### Integrate ZIO DynamoDB with Cats Effect 3 Applications

Source: https://context7.com/zio/zio-dynamodb/llms.txt

Demonstrates how to use ZIO DynamoDB within a Cats Effect 3 application. It shows how to configure the DynamoDB client and execute common operations like put, get, and scan using `executeToF`.

```scala
import cats.effect.{IO, IOApp}
import zio.dynamodb.DynamoDBQuery.{get, put, scanAll}
import zio.dynamodb.interop.ce.syntax._
import zio.dynamodb.interop.ce.DynamoDBExecutorF
import software.amazon.awssdk.regions.Region
import java.net.URI

object CatsEffectExample extends IOApp.Simple {

  val run = DynamoDBExecutorF.ofCustomised[IO] { builder =>
    builder
      .endpointOverride(URI.create("http://localhost:8000"))
      .region(Region.US_EAST_1)
  }.use { implicit executor =>
    for {
      _         <- put("personTable", Person("1", "John", 30)).executeToF
      result    <- get("personTable")(Person.id.partitionKey === "1").executeToF
      _         <- IO.println(s"Found: $result")
      fs2Stream <- scanAll[Person]("personTable")
                     .filter(Person.age > 18)
                     .executeToF  // Returns fs2.Stream
      _         <- fs2Stream.evalTap(p => IO.println(s"Scanned: $p")).compile.drain
    } yield ()
  }
}
```

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

### Execute Get Operation in Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/crud-operations/get.md

Demonstrates executing a `get` operation to retrieve a 'person' item by its ID. The result is an `Either` type, indicating either a successful retrieval or an `ItemError`.

```scala
for {
  errorOrPerson <- DynamoDBQuery.get("person")(Person.id.primaryKey === "1").execute
} yield errorOrPerson
```

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

### ZIO DynamoDB Primary Key Expression Examples

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/projection-expression.md

Demonstrates how to define partition and sort keys using the ZIO DynamoDB library for high-level API interactions. These expressions are used to uniquely identify items.

```scala
Person.id.partitionKey === "1"
Person.id.partitionKey === "1" && Person.group.sortKey === "2"
```

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

### Handle Get Operation with Option for Not Found in Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/crud-operations/get.md

Illustrates using the `maybeFound` extension method to treat 'item not found' cases as successful `Option` types. `DecodingError`s are pushed to the ZIO error channel, while `ValueNotFound` errors are mapped to `None`.

```scala
import zio.dynamodb.syntax._
for {
  maybePerson <- DynamoDBQuery.get("person")(Person.id.primaryKey === "1").execute.maybeFound
} yield maybePerson
```

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

### Manage DynamoDB Tables Programmatically with zio-dynamodb

Source: https://context7.com/zio/zio-dynamodb/llms.txt

This snippet demonstrates how to programmatically create and delete DynamoDB tables using zio-dynamodb. It shows examples for creating tables with a partition key only, and with a composite key (partition and sort key), along with specifying attribute definitions and billing mode. Requires 'zio-dynamodb' and 'zio'.

```scala
import zio.dynamodb.DynamoDBQuery.{createTable, deleteTable}
import zio.dynamodb.{KeySchema, BillingMode, AttributeDefinition}
import zio.ZIO

// Assuming DynamoDBExecutor trait is defined elsewhere

// Create table with partition key only
val createSimpleTable: ZIO[DynamoDBExecutor, Throwable, Unit] = for {
  _ <- createTable(
         tableName = "personTable",
         keySchema = KeySchema("id"),
         billingMode = BillingMode.PayPerRequest
       )(
         AttributeDefinition.attrDefnString("id")
       ).execute
} yield ()

// Create table with composite key (partition + sort)
val createCompositeTable: ZIO[DynamoDBExecutor, Throwable, Unit] = for {
  _ <- createTable(
         tableName = "equipmentTable",
         keySchema = KeySchema("id", "year"),  // id=partition, year=sort
         billingMode = BillingMode.PayPerRequest
       )(
         AttributeDefinition.attrDefnString("id"),
         AttributeDefinition.attrDefnNumber("year")
       ).execute
} yield ()

// Delete table
val dropTable: ZIO[DynamoDBExecutor, Throwable, Unit] = for {
  _ <- deleteTable("personTable").execute
} yield ()

```

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

### Perform Batch Get Item from DynamoDB using ZIO DynamoDB Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/cheat-sheet.md

Demonstrates how to retrieve multiple items from a DynamoDB table in a single request using ZIO DynamoDB's batch get operation. It takes a list of keys and a function to construct individual 'get' requests.

```scala
import zio.dynamodb.{DynamoDBQuery, ProjectionExpression}

// Assuming Person model and its partition key accessor (id) are defined
val listOfIds = List("1", "2", "3")

val batchGet = for {
  people <- DynamoDBQuery.batch(listOfIds)(id => 
              DynamoDBQuery.get[Person]("personTable")(
                Person.id.partitionKey === id
              )
            ).execute
} yield people
```

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

### Using AttrMap for Nested Field Access

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/low-level-api/attribute-value.md

Provides an example of using the `getOptionalItem` method on an AttrMap to access and parse nested data structures, demonstrating chained calls to `get` and `getOptional` within a for-comprehension.

```scala
val attrMap                                = AttrMap("f1" -> AttrMap("f2" -> "a", "f3" -> "b"))
val either: Either[ItemError, Option[Foo]] = for {
  maybeFoo <- attrMap.getOptionalItem("f1") { m =>
           for {
             s <- m.get[String]("f2")
             o <- m.getOptional[String]("f3")
           } yield Foo(s, o)
         }
  } yield maybeFoo
```

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

### Integrate ZIO DynamoDB with Scala Futures

Source: https://context7.com/zio/zio-dynamodb/llms.txt

Shows how to use ZIO DynamoDB with Scala Futures for applications not using ZIO or other effect types. It covers setting up the `DynamoDBExecutorF` for Futures and executing operations like put and get.

```scala
import zio.dynamodb.DynamoDBQuery.{get, put}
import zio.dynamodb.interop.future.DynamoDBExecutorF
import zio.dynamodb.interop.future.syntax._
import scala.concurrent.{Await, Future}
import scala.concurrent.ExecutionContext.Implicits.global
import scala.concurrent.duration._

object FutureExample extends App {

  implicit val executor: DynamoDBExecutorF = DynamoDBExecutorF.make(
    buildNettyClient = identity,
    buildDynamoDbClient = _.endpointOverride(java.net.URI.create("http://localhost:8000"))
      .region(software.amazon.awssdk.regions.Region.US_EAST_1)
  )

  val program: Future[Unit] = for {
    _      <- put("personTable", Person("1", "John", 30)).executeToF
    result <- get("personTable")(Person.id.partitionKey === "1").executeToF
    _       = println(s"Found: $result")
  } yield ()

  Await.result(program.andThen { case _ => executor.close() }, 30.seconds)
}
```

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

### Query DynamoDB Table using ZIO DynamoDB Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/cheat-sheet.md

Shows how to query items from a DynamoDB table based on a key condition using ZIO DynamoDB. This example retrieves all items matching the specified partition key.

```scala
import zio.stream.ZStream
import zio.dynamodb.{DynamoDBQuery, ProjectionExpression}

// Assuming Person model and its partition key accessor (id) are defined
val queryAllItems = for {
  stream <- DynamoDBQuery.queryAll[Person]("personTable")
              .whereKey(Person.id.partitionKey === "someId")
              .execute
} yield stream
```

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

### Get DynamoDB Item using ZIO DynamoDB Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/cheat-sheet.md

Demonstrates how to retrieve a single item from a DynamoDB table using the 'get' operation in ZIO DynamoDB. It specifies the table name and the partition key for the item to be fetched.

```scala
import zio.dynamodb.{DynamoDBQuery, ProjectionExpression}

// Assuming Person model and its accessors (id, name, year) are defined
val getItem = for {
  person <- DynamoDBQuery.get("personTable")(
              Person.id.partitionKey === "1"
            ).execute
} yield person
```

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

### scanSome Combinators for Advanced Querying

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/scan-and-query-operations/scan-some.md

Illustrates the use of combinators with the scanSome operation to refine queries. This includes setting consistency, specifying a starting key for pagination, applying server-side filters, and utilizing secondary indexes.

```scala
<SCAN_SOME_QUERY>
  .consistency(<ConsistencyMode>)
  .startKey(<LastEvaluatedKey>)
  .filter(<ConditionExpression>) // eg Equipment.price > 1.0 - filtering is done server side AFTER the scan 
  .indexName(<IndexName>)        // use a secondary index
```

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

### Scan DynamoDB Table with Paging using ZIO DynamoDB Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/cheat-sheet.md

Demonstrates how to perform a paginated scan of a DynamoDB table using ZIO DynamoDB. This is useful for retrieving large datasets in manageable chunks, specifying a limit and starting from a previous evaluated key.

```scala
import zio.dynamodb.{DynamoDBQuery, LastEvaluatedKey}
import zio.schema.Schema

// Assuming Person case class and its schema are defined
val oldLastEvaluatedKey: Option[LastEvaluatedKey] = None // Replace with actual previous key if applicable

val paginatedScan = for {
  (people, newLastEvaluatedKey) <- DynamoDBQuery.scanSome[Person]("personTable", limit = 5)
                                      .startKey(oldLastEvaluatedKey)
                                      .execute
} yield (people, newLastEvaluatedKey)
```

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

### Query DynamoDB Table with Paging using ZIO DynamoDB Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/cheat-sheet.md

Illustrates how to perform a paginated query on a DynamoDB table using ZIO DynamoDB. This allows retrieving query results in batches, specifying a limit and starting from a previous evaluated key.

```scala
import zio.dynamodb.{DynamoDBQuery, LastEvaluatedKey}
import zio.schema.Schema

// Assuming Person case class and its schema are defined
val oldLastEvaluatedKey: Option[LastEvaluatedKey] = None // Replace with actual previous key if applicable

val paginatedQuery = for {
  (people, newLastEvaluatedKey) <- DynamoDBQuery.querySome[Person]("personTable", limit = 5)
                                      .whereKey(Person.id.partitionKey === "1")
                                      .startKey(oldLastEvaluatedKey)
                                      .execute
} yield (people, newLastEvaluatedKey)
```

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

### Define DynamoDB Primary Keys Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/cheat-sheet.md

Provides examples of how to define primary keys (partition and sort keys) for DynamoDB operations using ZIO DynamoDB's type-safe API. This is crucial for targeting specific items or ranges of items.

```scala
import zio.dynamodb.ProjectionExpression

// For a table with only a partition key
val partitionKeyQuery = Person.id.partitionKey === "1"

// For a table with both partition and sort keys
val compositeKeyQuery = Person.id.partitionKey === "1" && Person.year.sortKey === 2020
```

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

### Execute Update Operation in Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/crud-operations/update.md

Provides an example of executing the 'update' operation in Scala. It demonstrates how to specify the table name, primary key, and combine multiple update actions using the '+' operator.

```scala
for {
  _ <- DynamoDBQuery.update("person")(Person.id.primaryKey === "1")(
    Person.name.set(42) + Person.age.set(42)
  ).execute
} yield maybePerson
```

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

### DynamoDB Field Traversal Examples with ProjectionExpressions

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/creating-models/field-traversal.md

Illustrates various field traversal operations using `ProjectionExpression` combinators: `>>>` for case classes, `valueAt` for maps, and `elementAt` for lists. These are used within ZIO DynamoDB update operations.

```scala
  val person                                                             =
    Person("john@gmail.com", Map("sports" -> List("cricket", "football")), Address("1", "Main St"))

  // ProjectionExpressions extracted deliberately to illustrate the types
  val addressToStreetPE: ProjectionExpression[Person, String]            =
    (Person.address >>> Address.street) 
  val valueAtHobbiesPE: ProjectionExpression[Person, List[String]]       =
    Person.hobbies.valueAt("sports")
  val valueAtAndElementAtHobbiesPE: ProjectionExpression[Person, String] =
    Person.hobbies.valueAt("sports").elementAt(0)

  for {
    _ <- DynamoDBQuery.put("people", person).execute

    _ <- DynamoDBQuery
           .update("people")(Person.email.partitionKey === "john@gmail.com")(
             addressToStreetPE.set("2nd St")
           )
           .execute

    _ <- DynamoDBQuery
           .update("people")(Person.email.partitionKey === "john@gmail.com")(
             valueAtHobbiesPE.set(List("tennis", "rugby"))
           )
           .execute

    _ <- DynamoDBQuery
           .update("people")(Person.email.partitionKey === "john@gmail.com")(
             valueAtAndElementAtHobbiesPE.set("cricket")
           )
           .execute

  } yield ()
```

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

### Manual Batching with Parallelization

Source: https://context7.com/zio/zio-dynamodb/llms.txt

Demonstrates manual batching of multiple DynamoDB operations using the `zip` operator for parallel execution. This can be useful for combining different types of operations. Dependencies include zio-dynamodb and zio.

```scala
import zio.dynamodb.DynamoDBQuery
import zio.dynamodb.DynamoDBQuery.{get, put}
import zio.ZIO

val people = List(
  Person("1", "John", 30),
  Person("2", "Jane", 25),
  Person("3", "Bob", 35)
)
val ids = List("1", "2", "3")

// Manual zip for auto-batching with parallelization
val manualBatch: ZIO[DynamoDBExecutor, Throwable, Unit] = for {
  _ <- (put("personTable", Person("1", "John", 30)) zip
        put("personTable", Person("2", "Jane", 25)) zip
        put("personTable", Person("3", "Bob", 35))).execute
} yield ()
```

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

### Visualizing DynamoDB Encodings with zio-dynamodb-json

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/creating-models/index.md

Illustrates how to use the `zio-dynamodb-json` module to view the DynamoDB types generated by ZIO DynamoDB codecs. This is helpful during model development for understanding data representation in AWS JSON format.

```scala
import zio.dynamodb.json._
val person = Person("email", Map("sports" -> List("cricket", "football")), Instant.now)
println(person.toJsonStringPretty[Person])
```

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

### Define Get Operation in Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/crud-operations/get.md

Defines the `get` operation for retrieving an item from a DynamoDB table. It takes a table name and a primary key expression, returning a `DynamoDBQuery` that results in either an `ItemError` or the retrieved item.

```scala
def get[From: Schema](tableName: String)(
    primaryKeyExpr: KeyConditionExpr.PrimaryKeyExpr[From]
  ): DynamoDBQuery[From, Either[ItemError, From]] = ???
```

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

### GET /items

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/crud-operations/get.md

Retrieves a single item from a DynamoDB table based on its primary key. The operation returns either the item or an error if the item is not found or cannot be decoded.

```APIDOC
## GET /items

### Description
Retrieves a single item from a DynamoDB table based on its primary key. The operation returns either the item or an error if the item is not found or cannot be decoded.

### Method
GET

### Endpoint
`/items`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
**tableName** (String) - Required - The name of the DynamoDB table.
**primaryKeyExpr** (KeyConditionExpr.PrimaryKeyExpr) - Required - An expression defining the primary key of the item to retrieve.

### Request Example
```scala
// Assuming Person case class with schema and Person.id defined
import zio.dynamodb.DynamoDBQuery

val getItem = for {
  errorOrPerson <- DynamoDBQuery.get("person")(Person.id.primaryKey === "1").execute
} yield errorOrPerson
```

### Response
#### Success Response (200)
**Item** (Object) - The retrieved item, or a JSON representation of it.
**Either[ItemError, From]** - A Scala Either type where 'From' is the model class representing the item, and 'ItemError' is a sealed trait with 'ValueNotFound' and 'DecodingError' instances.

#### Response Example
```json
{
  "person": {
    "id": "1",
    "name": "John Doe"
  }
}
```

### Working with `get` return values

#### Using `absolve` to handle errors
This approach pushes all `ItemError` instances into the ZIO error channel.

```scala
import zio.dynamodb.syntax._

val getAbsolved = for {
  person <- DynamoDBQuery.get("person")(Person.id.primaryKey === "1").execute.absolve
} yield person
```

#### Using `maybeFound` to handle `NotFound` as Option
This approach treats `NotFound` as a success case by returning an `Option` type, pushing `DecodingError` into the ZIO error channel.

```scala
import zio.dynamodb.syntax._

val getMaybeFound = for {
  maybePerson <- DynamoDBQuery.get("person")(Person.id.primaryKey === "1").execute.maybeFound
} yield maybePerson
```

### `get` query operations

It is possible to chain additional query modifiers to the `get` operation:

```scala
<GET_QUERY>
  .consistency(<ConsistencyMode>)
  .where(<ConditionExpression>)
```
```

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

### Interact with DynamoDB using Low-Level API in zio-dynamodb

Source: https://context7.com/zio/zio-dynamodb/llms.txt

This snippet illustrates direct DynamoDB interactions using the low-level API provided by zio-dynamodb, bypassing type safety for more granular control. It covers 'putItem', 'getItem', 'updateItem' with attribute modification using the '$' function, 'deleteItem', 'scanAllItem', and 'queryAllItem'. Dependencies include 'zio-dynamodb' and 'zio'.

```scala
import zio.dynamodb.DynamoDBQuery._
import zio.dynamodb.ProjectionExpression.$ 
import zio.dynamodb.{Item, PrimaryKey}
import zio.ZIO

// Assuming DynamoDBExecutor trait is defined elsewhere

// Low-level put
val lowLevelPut: ZIO[DynamoDBExecutor, Throwable, Unit] = for {
  _ <- putItem("personTable", Item("id" -> "1", "name" -> "John", "age" -> 30)).execute
} yield ()

// Low-level get
val lowLevelGet: ZIO[DynamoDBExecutor, Throwable, Option[Item]] =
  getItem("personTable")(PrimaryKey("id" -> "1")).execute

// Low-level update using $ function
val lowLevelUpdate: ZIO[DynamoDBExecutor, Throwable, Unit] = for {
  _ <- updateItem("personTable")(PrimaryKey("id" -> "1"))(
         $("name").set("Jane") + $("age").set(31)
       ).execute
} yield ()

// Low-level delete
val lowLevelDelete: ZIO[DynamoDBExecutor, Throwable, Unit] = for {
  _ <- deleteItem("personTable")(PrimaryKey("id" -> "1")).execute
} yield ()

// Low-level scan and query
val lowLevelScan = scanAllItem("personTable", $("id"), $("name"), $("age")).execute
val lowLevelQuery = queryAllItem("personTable", $("id"), $("name"))
  .whereKey($("id").partitionKey === "1")
  .execute

```

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

### GET Operation

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/crud-operations/index.md

Retrieves an item from a DynamoDB table based on its primary key.

```APIDOC
## GET /items/{primaryKey}

### Description
Retrieves an item from a DynamoDB table using its primary key, ensuring type safety.

### Method
GET

### Endpoint
`/items/{primaryKey}`

### Parameters
#### Query Parameters
- **tableName** (string) - Required - The name of the DynamoDB table.

#### Path Parameters
- **primaryKey** (object) - Required - An expression representing the primary key of the item to retrieve.

### Request Example
```json
{
  "tableName": "my-table",
  "primaryKey": {
    "id": "123"
  }
}
```

### Response
#### Success Response (200)
- **item** (object) - The retrieved item.
- **error** (object) - An error object if the item was not found or an error occurred.

#### Response Example
```json
{
  "item": {
    "id": "123",
    "name": "John Doe",
    "age": 30
  }
}
```
```json
{
  "error": {
    "type": "ItemNotFound"
  }
}
```
```

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

### Add ZIO DynamoDB to Project (build.sbt)

Source: https://context7.com/zio/zio-dynamodb/llms.txt

Instructions to add ZIO DynamoDB and its optional interop modules to a Scala project using sbt. Specifies the library version for core functionality and for Cats Effect 3, Scala Future, and JSON debugging.

```scala
// build.sbt
libraryDependencies ++= Seq(
  "dev.zio" %% "zio-dynamodb" % "1.0.0-RC24"
)

// Optional: Cats Effect 3 interop
libraryDependencies ++= Seq(
  "dev.zio" %% "zio-dynamodb-ce" % "1.0.0-RC24"
)

// Optional: Scala Future interop
libraryDependencies ++= Seq(
  "dev.zio" %% "zio-dynamodb-future" % "1.0.0-RC24"
)

// Optional: DynamoDB JSON debugging module
libraryDependencies ++= Seq(
  "dev.zio" %% "zio-dynamodb-json" % "1.0.0-RC24"
)
```

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

### ZIO DynamoDB Condition Expression Operators

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/projection-expression.md

Provides examples of common operators used with ZIO DynamoDB ConditionExpressions or FilterExpressions. These operators allow for flexible data filtering based on attribute values and types.

```scala
// Equality
Person.age === 30
// Inequality
Person.age <> 30
// Greater than
Person.age > 30
// Greater than or equal
Person.age >= 30
// Less than
Person.age < 30
// Less than or equal
Person.age <= 30
// Exists
Person.name.exists
// Not Exists
Person.name.notExists
// Size (for String, List, Set)
Person.name.size > 10
// Type check
Person.age.isNumber
Person.name.isString
Person.data.isBinary
// Between
Person.age.between(18, 65)
// BeginsWith (for String)
Person.name.beginsWith("J")
// In Set
Person.id.inSet(Set("1", "2", "3"))
// In (multiple values)
Person.status.in("active", "pending")
// Contains (for String, Set, List)
Person.tags.contains("scala")
Person.list.contains("item1")
// ContainsSet (for String, Set, List)
Person.tags.containsSet(Set("scala", "zio"))
```

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

### Unit Testing DynamoDB with TestDynamoDBExecutor in Scala

Source: https://context7.com/zio/zio-dynamodb/llms.txt

Demonstrates using TestDynamoDBExecutor for in-memory unit testing of DynamoDB operations without requiring a live AWS connection. It shows how to add tables, put items, and retrieve items, asserting the expected results. This approach is ideal for fast and reliable testing.

```scala
import zio.dynamodb.{DynamoDBExecutor, TestDynamoDBExecutor}
import zio.dynamodb.DynamoDBQuery.{get, put}
import zio.test._

object PersonRepositorySpec extends ZIOSpecDefault {

  def spec = suite("PersonRepository")(
    test("should store and retrieve a person") {
      for {
        _      <- TestDynamoDBExecutor.addTable("personTable", "id")
        _      <- put("personTable", Person("1", "John", 30)).execute
        result <- get("personTable")(Person.id.partitionKey === "1").execute
      } yield assertTrue(result == Right(Person("1", "John", 30)))
    }.provide(DynamoDBExecutor.test),

    test("should return NotFound for missing items") {
      for {
        _      <- TestDynamoDBExecutor.addTable("personTable", "id")
        result <- get("personTable")(Person.id.partitionKey === "999").execute
      } yield assertTrue(result.isLeft)
    }.provide(DynamoDBExecutor.test)
  )
}
```

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

### Compose Batched DynamoDB Queries with Zip and Batch

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/auto-batching-and-parallelisation.md

Demonstrates composing DynamoDB queries using `zip` for potential parallelisation and `batch` for guaranteed auto-batching. The `execute` method triggers the batching mechanism for eligible operations.

```scala
val batchedWrite1 = DynamoDBQuery.put("person", Person("1", "John", 21))
        .zip(DynamoDBQuery.put("person", Person("2", "Jane", 22)))

val batchedWrite2 = DynamoDBQuery.batch(people)(person => put("person", person))

for {
  _ <- batchedWrite1.execute // PutItem operations will be batched
  _ <- batchedWrite2.execute // PutItem operations will be batched
} yield ()
```

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

### Transactional Get Items from Multiple DynamoDB Tables with ZIO

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/cheat-sheet.md

Executes a transactional read operation across multiple DynamoDB tables using ZIO. This allows fetching data from different tables atomically.

```scala
tuple <- (get("personTable")(Person.id.partitionKey === "1") zip get("employeeTable")(Employee.id.partitionKey === "2")).transaction.execute
```

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

### Define Models with ZIO Schema (Scala)

Source: https://context7.com/zio/zio-dynamodb/llms.txt

Demonstrates defining Scala case classes for DynamoDB items and deriving their schemas using ZIO Schema. Includes generation of type-safe projection expressions for field access.

```scala
import zio.schema.{DeriveSchema, Schema}
import zio.dynamodb.ProjectionExpression

final case class Person(id: String, name: String, age: Int)
object Person {
  // Automatic schema derivation for codec generation
  implicit val schema: Schema.CaseClass3[String, String, Int, Person] = DeriveSchema.gen[Person]

  // Generate type-safe projection expressions for each field
  val (id, name, age) = ProjectionExpression.accessors[Person]
}

final case class Equipment(id: String, year: Int, model: String, price: Double)
object Equipment {
  implicit val schema: Schema.CaseClass4[String, Int, String, Double, Equipment] = DeriveSchema.gen[Equipment]
  val (id, year, model, price) = ProjectionExpression.accessors[Equipment]
}
```

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

### Perform DynamoDB Update Expression Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/cheat-sheet.md

Shows how to construct and execute an update expression for a DynamoDB item using ZIO DynamoDB. This example updates the 'name' and increments the 'year' attribute for a specified item.

```scala
import zio.dynamodb.{DynamoDBQuery, ProjectionExpression}

// Assuming Person model and its accessors (id, name, year) are defined
val updateWithExpression = for {
  _ <- DynamoDBQuery.update("personTable")(
         Person.id.partitionKey === "1"
       )(
         Person.name.set("John") + Person.year.add(1)
       ).execute
} yield ()

```

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

### Query with Paging

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/cheat-sheet.md

Performs a paginated query of a DynamoDB table, returning a subset of items and a token for the next page.

```APIDOC
## GET /query/{tableName}/paginated

### Description
Performs a paginated query of a DynamoDB table.

### Method
GET

### Endpoint
`/query/{tableName}/paginated`

### Parameters
#### Path Parameters
- **tableName** (string) - Required - The name of the table to query.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of items to return per page.
- **primaryKeyCondition** (string) - Required - The condition for the primary key.

### Request Example
```scala
import zio.dynamodb.DynamoDBQuery.querySome

val (people, lastEvaluatedKey) = querySome[Person]("personTable", limit = 5).whereKey(Person.id.partitionKey === "1").execute
```

### Response
#### Success Response (200)
- **people** (List[Person]) - A list of items returned in the current page.
- **lastEvaluatedKey** (string) - The key to use for the next paginated query, or null if this is the last page.

#### Response Example
```json
{
  "people": [
    {
      "id": "1",
      "name": "Alice",
      "year": 1995
    }
  ],
  "lastEvaluatedKey": "someToken"
}
```
```

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

### Update DynamoDB Item using ZIO DynamoDB Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/cheat-sheet.md

Illustrates how to update an existing item in a DynamoDB table using ZIO DynamoDB. This example updates the 'name' attribute for a specific item identified by its partition key.

```scala
import zio.dynamodb.{DynamoDBQuery, ProjectionExpression}

// Assuming Person model and its accessors (id, name) are defined
val updateItem = for {
  _ <- DynamoDBQuery.update("personTable")(
         Person.id.partitionKey === "1"
       )(
         Person.name.set("Foo")
       ).execute
} yield ()

```

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

### Add ZIO DynamoDB Future Interop to build.sbt

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/README.md

This code snippet shows how to include the Future interop module for ZIO DynamoDB in your build.sbt file. This is useful for projects that do not use effect libraries and need to work with Scala's standard Future type. It allows seamless integration with existing Play applications or other Future-based code.

```scala
libraryDependencies ++= Seq(
  "dev.zio" %% "zio-dynamodb-future" % "1.0.0-RC24"
)
```

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

### Custom Encoding for Scala Either Type

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/hi-level-api/creating-models/index.md

Demonstrates how to customize the encoding for Scala's `Either` type in ZIO DynamoDB. By default, it uses a map structure. This example shows how to create a 'union' type encoding using `Schema.Fallback` and a transformation.

```scala
implicit def fallbackEither[A, B](implicit schemaA: Schema[A], schemaB: Schema[B]): Schema[Either[A, B]] = 
      Schema.Fallback(schemaA, schemaB).transform(_.toEither, Fallback.fromEither)
```

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

### Add zio-dynamodb-future Dependency

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/future-interop.md

This snippet shows how to add the `zio-dynamodb-future` library to your `build.sbt` file, enabling interop with Scala Futures.

```scala
libraryDependencies ++= Seq(
  "dev.zio" %% "zio-dynamodb-future" % "@VERSION@"
)
```

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

### Get Item from DynamoDB Table

Source: https://context7.com/zio/zio-dynamodb/llms.txt

Retrieves an item from a DynamoDB table based on its primary key. Supports various return types including Either[ItemError, T], Option[T], and direct results. It leverages ZIO's effect system for type-safe error handling.

```scala
import zio.dynamodb.DynamoDBQuery.get
import zio.dynamodb.DynamoDBError.ItemError
import zio.dynamodb.syntax._
import zio.ZIO

// Basic get - returns Either[ItemError, Person]
val basicGet: ZIO[DynamoDBExecutor, Throwable, Either[ItemError, Person]] = 
  get("personTable")(Person.id.partitionKey === "1").execute

// Get with absolve - pushes errors into ZIO error channel
val getWithAbsolve: ZIO[DynamoDBExecutor, Throwable, Person] = 
  get("personTable")(Person.id.partitionKey === "1").execute.absolve

// Get with maybeFound - returns Option[Person], treating NotFound as success
val getWithMaybe: ZIO[DynamoDBExecutor, Throwable, Option[Person]] = 
  get("personTable")(Person.id.partitionKey === "1").execute.maybeFound

// Get with composite primary key (partition key + sort key)
val getWithSortKey: ZIO[DynamoDBExecutor, Throwable, Either[ItemError, Equipment]] = 
  get("equipmentTable)(
    Equipment.id.partitionKey === "equip1" && Equipment.year.sortKey === 2023
  ).execute
```

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

### Import zio-dynamodb-json utilities

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/reference/zio-dynamodb-json.md

Import the necessary extension methods and functions from the `zio.dynamodb.json` package to utilize the JSON conversion capabilities.

```scala
import zio.dynamodb.json._
```

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

### Perform DynamoDB Read Transactions in Scala

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/guides/transactions.md

Illustrates how to execute multiple read operations (get items) as a single atomic transaction in DynamoDB using zio-dynamodb. This allows fetching data from different tables or items atomically. Requires defining case classes for data models and their ZIO Schemas.

```scala
val getStudent = get("student")(Student.id.partitionKey === "1")
val getBill = get("billing")(Bill.id.partitionKey === "1")

val getStudentAndBillTransaction = (getStudent zip getBill).transaction

for {
  studentAndBill <- getStudentAndBillTransaction.execute
} yield studentAndBill
```

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

### Add ZIO DynamoDB Cats Effect Interop to build.sbt

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/README.md

This code snippet demonstrates how to add the Cats Effect 3 interop module for ZIO DynamoDB to your build.sbt file. This module enables integration with projects using Cats Effect. Ensure you have the core ZIO DynamoDB dependency as well.

```scala
libraryDependencies ++= Seq(
  "dev.zio" %% "zio-dynamodb-ce" % "1.0.0-RC24"
)
```

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

### Add ZIO DynamoDB to build.sbt

Source: https://github.com/zio/zio-dynamodb/blob/series/2.x/docs/index.md

Specifies the dependency required to include the core ZIO DynamoDB library in your Scala project. This is added to your build.sbt file.

```scala
libraryDependencies ++= Seq(
  "dev.zio" %% "zio-dynamodb" % "@VERSION@"
)
```
Tokens:
Raw