{"id":19502328,"url":"https://github.com/zio/zio-query","last_synced_at":"2026-01-11T17:36:37.229Z","repository":{"id":38848540,"uuid":"262891583","full_name":"zio/zio-query","owner":"zio","description":"Add efficient pipelining, batching, and caching to any data source","archived":false,"fork":false,"pushed_at":"2025-03-20T07:24:45.000Z","size":937,"stargazers_count":152,"open_issues_count":4,"forks_count":22,"subscribers_count":15,"default_branch":"series/2.x","last_synced_at":"2025-04-04T02:44:05.034Z","etag":null,"topics":["functional-programming","query-optimization","scala","zio"],"latest_commit_sha":null,"homepage":"https://zio.dev/zio-query","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-10T23:06:58.000Z","updated_at":"2025-04-02T11:56:30.000Z","dependencies_parsed_at":"2023-02-18T01:16:16.477Z","dependency_job_id":"fe7b24f0-430b-4719-bbd1-d8af90844f27","html_url":"https://github.com/zio/zio-query","commit_stats":{"total_commits":360,"total_committers":23,"mean_commits":"15.652173913043478","dds":0.6777777777777778,"last_synced_commit":"0ea6d62fc482f0f03ee5419af2899f6d1531836d"},"previous_names":["zio/zquery"],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-query","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-query/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-query/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-query/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zio","download_url":"https://codeload.github.com/zio/zio-query/tar.gz/refs/heads/series/2.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248646823,"owners_count":21139078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["functional-programming","query-optimization","scala","zio"],"created_at":"2024-11-10T22:16:05.497Z","updated_at":"2026-01-11T17:36:37.199Z","avatar_url":"https://github.com/zio.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"[//]: # (This file was autogenerated using `zio-sbt-website` plugin via `sbt generateReadme` command.)\n[//]: # (So please do not edit it manually. Instead, change \"docs/index.md\" file or sbt setting keys)\n[//]: # (e.g. \"readmeDocumentation\" and \"readmeSupport\".)\n\n# ZIO Query\n\n[ZIO Query](https://github.com/zio/zio-query) is a library for writing optimized queries to data sources in a high-level compositional style. It can add efficient pipelining, batching, and caching to any data source. ZIO Query helps us dramatically reduce load on data sources and improve performance.\n\n[![Production Ready](https://img.shields.io/badge/Project%20Stage-Production%20Ready-brightgreen.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-query/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-query_2.13.svg?label=Sonatype%20Release)](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-query_2.13/) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-query_2.13.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-query_2.13/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-query-docs_2.13/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-query-docs_2.13) [![ZIO Query](https://img.shields.io/github/stars/zio/zio-query?style=social)](https://github.com/zio/zio-query)\n\n## Introduction\n\nSome key features of ZIO Query:\n\n- **Batching** — ZIO Query detects parts of composite queries that can be executed in parallel without changing the semantics of the query.\n- **Pipelining** — ZIO Query detects parts of composite queries that can be combined together for fewer individual requests to the data source.\n- **Caching** — ZIO Query can transparently cache read queries to minimize the cost of fetching the same item repeatedly in the scope of a query.\n\nCompared with Fetch, ZIO Query supports response types that depend on request types, does not require higher-kinded types and implicits, supports ZIO environment and statically typed errors, and has no dependencies except for ZIO.\n\nA `ZQuery[R, E, A]` is a purely functional description of an effectual query that may contain requests from one or more data sources, requires an environment `R`, and may fail with an `E` or succeed with an `A`.\n\nRequests that can be performed in parallel, as expressed by `zipWithPar` and combinators derived from it, will automatically be batched. Requests that must be performed sequentially, as expressed by `zipWith` and combinators derived from it, will automatically be pipelined. This allows for aggressive data source specific optimizations. Requests can also be deduplicated and cached.\n\n\nThis allows for writing queries in a high level, compositional style, with confidence that they will automatically be optimized. For example, consider the following query from a user service.\n\nAssume we have the following database access layer APIs:\n\n```scala\ndef getAllUserIds: ZIO[Any, Nothing, List[Int]] = {\n  // Get all user IDs e.g. SELECT id FROM users\n  ZIO.succeed(???)\n}\n\ndef getUserNameById(id: Int): ZIO[Any, Nothing, String] = {\n  // Get user by ID e.g. SELECT name FROM users WHERE id = $id\n  ZIO.succeed(???)\n}\n```\n\nWe can get their corresponding usernames from the database by the following code snippet:\n\n```scala\nval userNames = for {\n  ids   \u003c- getAllUserIds\n  names \u003c- ZIO.foreachPar(ids)(getUserNameById)\n} yield names\n```\n\nIt works, but this is not performant. It is going to query the underlying database _N + 1_ times, one for `getAllUserIds` and one for each call to `getUserNameById`.\n\nIn contrast, `ZQuery` will automatically optimize this to two queries, one for `userIds` and one for `userNames`:\n\n```scala\nlazy val getAllUserIds: ZQuery[Any, Nothing, List[Int]]    = ???\ndef getUserNameById(id: Int): ZQuery[Any, Nothing, String] = ???\n\nlazy val userQuery: ZQuery[Any, Nothing, List[String]] = for {\n  userIds   \u003c- getAllUserIds\n  userNames \u003c- ZQuery.foreachPar(userIds)(getUserNameById)\n} yield userNames\n```\n\n## Installation\n\nIn order to use this library, we need to add the following line in our `build.sbt` file:\n\n```scala\nlibraryDependencies += \"dev.zio\" %% \"zio-query\" % \"0.7.6\"\n```\n\n## Example\n\nHere is an example of using ZIO Query, which optimizes multiple database queries by batching all of them in one query:\n\n```scala\nimport zio._\nimport zio.query._\n\nobject ZQueryExample extends ZIOAppDefault {\n  case class GetUserName(id: Int) extends Request[Throwable, String]\n\n  lazy val UserDataSource: DataSource.Batched[Any, GetUserName] =\n    new DataSource.Batched[Any, GetUserName] {\n      val identifier: String = \"UserDataSource\"\n\n      def run(requests: Chunk[GetUserName])(implicit trace: Trace): ZIO[Any, Nothing, CompletedRequestMap] =\n        requests.toList match {\n          case request :: Nil =\u003e\n            val result: Task[String] = {\n              // get user by ID e.g. SELECT name FROM users WHERE id = $id\n              ZIO.succeed(???)\n            }\n\n            result.exit.map(CompletedRequestMap.single(request, _))\n\n          case batch: Seq[GetUserName] =\u003e\n            val result: Task[List[(Int, String)]] = {\n              // get multiple users at once e.g. SELECT id, name FROM users WHERE id IN ($ids)\n              ZIO.succeed(???)\n            }\n\n            result.foldCause(\n              CompletedRequestMap.failCause(requests, _),\n              CompletedRequestMap.fromIterableWith(_)(kv =\u003e GetUserName(kv._1), kv =\u003e Exit.succeed(kv._2))\n            )\n        }\n    }\n\n  def getUserNameById(id: Int): ZQuery[Any, Throwable, String] =\n    ZQuery.fromRequest(GetUserName(id))(UserDataSource)\n\n  val query: ZQuery[Any, Throwable, List[String]] =\n    for {\n      ids \u003c- ZQuery.succeed(1 to 10)\n      names \u003c- ZQuery.foreachPar(ids)(id =\u003e getUserNameById(id)).map(_.toList)\n    } yield (names)\n\n  def run = query.run.tap(usernames =\u003e Console.printLine(s\"Usernames: $usernames\"))\n}\n```\n\n## Resources\n\n- [Wicked Fast API Calls with ZIO Query](https://www.youtube.com/watch?v=rUUxDXJMzJo) by Adam Fraser (July 2020) (https://www.youtube.com/watch?v=rUUxDXJMzJo)\n\n## Documentation\n\nLearn more on the [ZIO Query homepage](https://zio.dev/zio-query)!\n\n## Contributing\n\nFor the general guidelines, see ZIO [contributor's guide](https://zio.dev/contributor-guidelines).\n\n## Code of Conduct\n\nSee the [Code of Conduct](https://zio.dev/code-of-conduct)\n\n## Support\n\nCome chat with us on [![Badge-Discord]][Link-Discord].\n\n[Badge-Discord]: https://img.shields.io/discord/629491597070827530?logo=discord \"chat on discord\"\n[Link-Discord]: https://discord.gg/2ccFBr4 \"Discord\"\n\n## License\n\n[License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzio%2Fzio-query","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzio%2Fzio-query","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzio%2Fzio-query/lists"}