{"id":36418565,"url":"https://github.com/tianyirenjian/querybuilder","last_synced_at":"2026-01-11T17:01:29.087Z","repository":{"id":44458193,"uuid":"512697155","full_name":"tianyirenjian/querybuilder","owner":"tianyirenjian","description":"A query builder from laravel.","archived":false,"fork":false,"pushed_at":"2024-02-04T12:56:25.000Z","size":179,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-27T15:45:15.945Z","etag":null,"topics":["database","java","kotlin","querybuilder"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","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/tianyirenjian.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-07-11T09:40:36.000Z","updated_at":"2024-02-10T17:48:34.000Z","dependencies_parsed_at":"2024-02-04T14:07:08.530Z","dependency_job_id":null,"html_url":"https://github.com/tianyirenjian/querybuilder","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/tianyirenjian/querybuilder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tianyirenjian%2Fquerybuilder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tianyirenjian%2Fquerybuilder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tianyirenjian%2Fquerybuilder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tianyirenjian%2Fquerybuilder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tianyirenjian","download_url":"https://codeload.github.com/tianyirenjian/querybuilder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tianyirenjian%2Fquerybuilder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28314259,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T14:58:17.114Z","status":"ssl_error","status_checked_at":"2026-01-11T14:55:53.580Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["database","java","kotlin","querybuilder"],"created_at":"2026-01-11T17:01:26.171Z","updated_at":"2026-01-11T17:01:29.046Z","avatar_url":"https://github.com/tianyirenjian.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QueryBuilder\n\n数据库增删改查构造器，使用 kotlin 编写。kotlin 调用起来非常舒服，java 也可以调用，但是某些复杂参数的函数可能无法简单调用， 需要使用 kotlin 内部的类型，下面有 java 示例。\n\n也可以使用 kotlin 来写 Repository 层调用，然后供其他的 java 代码直接调用方法。\n\nQueryBuilder 是我个人使用的查询库，已用在多个生产项目中，目前运行良好， 平时遇到问题我也会修改和升级程序。\n\n程序在 jdk 1.8 上编译， 在 jdk 1.8 和 jdk 17 均测试正常运行，其他版本我没试过。\n\n### 安装\n\nmaven:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.tianyisoft.database\u003c/groupId\u003e\n  \u003cartifactId\u003equerybuilder\u003c/artifactId\u003e\n  \u003cversion\u003e2.0.4\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n或 gradle\n\n```\nimplementation 'com.tianyisoft.database:querybuilder:2.0.4'\n```\n\n### 使用说明\n\n#### 构造实例\n\nquerybuilder 运行需要 `JdbcTemplate`, 一般 spring boot 程序里面都有，直接注入就行，自己构造也可以。\n\n```kotlin\n\nimport com.tianyisoft.database.Builder\n\nval builder = Builder()\nbuilder.jdbcTemplate = jdbcTemplate\n\n// 定义两个实例，后面示例会用到\nval builder2 = Builder()\nbuilder2.jdbcTemplate = jdbcTemplate\n```\n\n这里是公共方法，如果使用 spring boot 也可以通过后面的 `AbstractRepository` 来避免手动创建实例。\n\n### 获取结果\n\n#### 从表中检索所有行\n\n可以使用 `table` 方法指定数据表， 然后通过 `get` 获取所有行\n\n```kotlin\n\nval users = builder.table(\"users\").get() // List\u003cMap\u003cString, Any?\u003e\u003e\n\nval users = builder.table(\"users\").get(User::class.java) // List\u003cUser\u003e\n```\n\n`get` 可以获取 `List\u003cMap\u003cString, Any?\u003e\u003e` 的结果集，也可以用 `get` 通过 `KClass\u003cT\u003e` 或者 `Class\u003cT\u003e` 获取 `List\u003cT\u003e` 的结果集。\n\n使用 `Class\u003cT\u003e` 获取对象是使用 jackson 来实现，所以如果数据库和字段名称不一致，可以使用 `@JsonProperty` 来标示.\n\n#### 获取单行或单列\n\n可以使用 `first` 方法获取第一条结果\n\n```kotlin\nval user = builder.table(\"users\").first() // Map\u003cString, Any?\u003e\n\nval user = builder.table(\"users\").first(User::class.java) // User\n```\n\n如果不想要整行数据，可以用 `value` 方法取单列的值\n\n```kotlin\nval name = builder.table(\"users\").value(\"name\") // 取第一个用户的 name\n```\n\n如果是使用 `id` 取单行数据，可以使用 `find` 方法\n\n```kotlin\nval user = builder.table(\"users\").find(id)\n```\n\n同样 `find` 方法也有获取对象的重载方法。\n\n可以使用 `sole` 方法来查询数据库中的有且仅有一行的数据，不存在或存在多行都会报错。\n\n```kotlin\nval user = builder.table(\"users\").where(\"role\", \"=\", \"super_admin\").sole()\n```\n\n与之前的 `value` 相对应的也有 `soleValue` 方法，取有且仅有一行的数据的某一列的值。\n\n#### 获取某一列的值\n\n如果要取单列的值的集合，可以使用 `pluck` 方法\n\n```kotlin\nval names = builder.table(\"users\").pluck(\"name\")\n```\n\n也可以向 `pluck` 传入第二个字段，取到一个以第二个字段为键的 Map\n\n```kotlin\nval names = builder.table(\"users\").pluck(\"name\", \"id\") // { \"1\": \"Tom\", \"2\": \"Jerry\" }\n```\n\n#### 分块获取\n\n假如数据库有成千上万条数据，可以通过 `chunk` 方法分块取出, 闭包有两个参数，分别是分组后的数据，和当前页码，也就是第几组\n\n```kotlin\nbuilder.table(\"users\").orderBy(\"id\").chunk(20) { users, page -\u003e\n    for (user in users) {\n        println(user)\n    }\n    true // 必要的， 返回 true 会继续执行，若返回 false 则中断执行\n}\n```\n\n如果在使用 `chunk` 获取数据的同时修改数据，则 `chunk` 获取的数据会有问题，这时可以通过 `chunkById` 来分块获取, 用法和 `chunk` 一致，可以用第三个参数来设置 id 列名。\n\n```kotlin\nbuilder.table(\"users\").chunkById(20, { users, page -\u003e\n    for (user in users) {\n        println(user)\n    }\n    true // 必要的， 返回 true 会继续执行，若返回 false 则中断执行\n}, \"id\")\n```\n\n除了使用 `chunk` 和 `chunkById` 以外，也可以使用 `each` 和 `eachById`, 相比来说，它们更进一步，分组获取后，再循环每一条数据执行操作。\n\n`each` 和 `eachById` 闭包有两个参数，第一个是当前的单条数据，第二个是当前数据的索引，有别于 `chunk` 和 `chunkById` 的页码\n\n```kotlin\nbuilder.table(\"apps\").eachById({row, index -\u003e\n    println(\"index $index:\")\n    println(row)\n    true\n})\n```\n\n\n`chunk` 和 `each` 返回的数据都是 `Map` 类型的，也可以传入 `KClass\u003cT\u003e` 或 `Class\u003cT\u003e` 方法来返回对象。 `chunkById` 和 `eachById` 暂时没有对应的方法。\n\n```kotlin\nbuilder.table(\"apps\").select(\"id\", \"name\").orderBy(\"id\")\n    .each(Apps::class.java, { app, index -\u003e\n        println(app)\n        true\n    })\n```\n\n使用 `chunk` 和 `each` 时，必须指定至少一个排序，`chunkById` 和 `eachById` 则不需要。\n\n#### 聚合函数\n\nBuilder 还提供了多种检索聚合值的方法，例如 `count`, `max`, `min`, `avg`, 和 `sum`\n\n```kotlin\nval count = builder.table(\"users\").count()\nval oldest = builder.table(\"users\").max(\"age\")\n```\n\n可以配合 `where` 使用\n\n```kotlin\nval avg = builder.table(\"users\").where(\"status\", \"=\", 1).avg(\"score\")\n```\n\n#### 判断记录是否存在\n\n除了通过 `count` 方法可以确定查询条件的结果是否存在之外，还可以使用 `exists` 和 `doesntExist` (`notExists`) 方法\n\n```kotlin\nif (builder.table(\"users\").where(\"status\", \"=\", 0).exists()) {\n    // ...\n}\n```\n\n### Select 语句\n\n#### 指定一个 Select 语句\n\n使用 `select` 方法可以指定要查询的列\n\n```kotlin\nval users = builder.table(\"users\").select(\"id\", \"name\", \"email as user_email\").get()\n```\n\n使用 `distinct` 方法可以让查询结果不重复\n\n```kotlin\nval names = builder.table(\"users\").select(\"name\").distinct().get()\n```\n\n### 原生表达式\n\n有时可能需要在查询中插入任意字符串。可以使用原生表达式 `Expression`\n\n```kotlin\nval users = builder.table(\"users\").select(\"id\", Expression(\"upper(name) as upper_name\")).get()\n```\n\n使用 `Expression` 会直接把字符串附加到 sql 语句，因此要注意可能会有 sql 注入风险\n\n下面有几个方法可以代替 `Expression`, 下面所有方法的第二个参数都可以传一个存放绑定值的 list, 也可以使用不定参数的重载方法。使用这几个方法可以避免 sql 注入风险\n\n#### `selectRaw`\n\n```kotlin\nval users = builder.table(\"users\")\n    .selectRaw(\"id, upper(name), score * ? as double_score\", listOf(2))\n    .get()\n```\n\n#### `fromRaw`\n\n```kotlin\n// select * from (select * from users where age \u003c ?) as u\nval youngUser = builder\n    .fromRaw(\"(select * from users where age \u003c ?) as u\", listOf(18))\n    .get()\n```\n\n#### `whereRaw / orWhereRaw`\n\n```kotlin\nval users = builder.table(\"users\")\n    .whereRaw(\"score \u003e ? and status = ?\", listOf(60, 0))\n    .get()\n```\n\n#### `havingRaw / orHavingRaw`\n\n```kotlin\n// select department, SUM(price) as total_sales from `orders` group by `department` having SUM(price) \u003e ?\nbuilder.table(\"orders\")\n    .selectRaw(\"department, SUM(price) as total_sales\")\n    .groupBy(\"department\")\n    .havingRaw(\"SUM(price) \u003e ?\", listOf(2500))\n    .get();\n```\n\n#### `orderByRaw`\n\n```kotlin\nbuilder.table(\"users\")\n    .orderByRaw(\"updated_at - created_at DESC\")\n    .get()\n```\n\n#### `groupByRaw`\n\n```kotlin\nbuilder.table(\"users\")\n    .selectRaw(\"sex, count(*) as sex_count\")\n    .groupByRaw(\"sex\")\n    .get()\n```\n\n### Joins\n\n#### inner join 语句\n\n使用 `join` 方法可以关联其他表，可以关联多个表\n\n```kotlin\n/*\nSELECT `users`.*, `contacts`.`phone`, `orders`.`price`\nFROM `users`\n\tINNER JOIN `contacts` ON `users`.`id` = `contacts`.`user_id`\n\tINNER JOIN `orders` ON `users`.`id` = `orders`.`user_id`\n */\nbuilder.table(\"users\")\n    .join(\"contacts\", \"users.id\", \"=\", \"contacts.user_id\")\n    .join(\"orders\", \"users.id\", \"=\", \"orders.user_id\")\n    .select(\"users.*\", \"contacts.phone\", \"orders.price\")\n    .get()\n```\n\n#### left join 和 right join\n\n使用 `join` 也可以实现 left join 和 right join， 也提供了更方便的 `leftJoin` 和 `rightJoin` 方法\n\n```kotlin\n// select * from `users` as `u` left join `posts` as `p` on `u`.`id` = `p`.`user_id`\nbuilder.table(\"users\", \"u\")\n    .leftJoin(\"posts as p\", \"u.id\", \"=\", \"p.user_id\")\n    .get()\n```\n\n#### cross join\n可以使用 crossJoin 方法执行「交叉连接」。交叉连接在第一个表和被连接的表之间会生成笛卡尔积\n\n```kotlin\nbuilder.table(\"sizes\")\n    .crossJoin(\"colors\")\n    .get()\n```\n\n#### 高级 Join 语句\n\n`join` 方法的第二个参数可以传闭包, 来实现更复杂的逻辑\n\n```kotlin\n/*\nSELECT *\nFROM `users`\n\tINNER JOIN `posts`\n\tON `users`.`id` = `posts`.`created_by`\n\t\tOR `users`.`id` = `posts`.`updated_by`\n */\nbuilder.table(\"users\")\n    .join(\"posts\", {it: JoinClause -\u003e\n        it.on(\"users.id\", \"=\", \"posts.created_by\")\n            .orOn(\"users.id\", \"=\", \"posts.updated_by\")\n    })\n    .get()\n```\n如果你想要在连接上使用 where 风格的语句，你可以在连接上使用 `JoinClause` 实例中的 `where` 和 `orWhere` 方法。这些方法会将列和值进行比较，而不是列和列进行比较：\n\n```kotlin\n/*\nSELECT *\nFROM `users`\n\tINNER JOIN `posts`\n\tON `users`.`id` = `posts`.`created_by`\n\t\tAND `posts`.`status` = ?\n */\n\nbuilder.table(\"users\")\n    .join(\"posts\", {it: JoinClause -\u003e\n        it.on(\"users.id\", \"=\", \"posts.created_by\")\n            .where(\"posts.status\", \"=\", 0)\n    })\n    .get()\n```\n\n#### 子连接查询\n\n可以使用 `joinSub`，`leftJoinSub` 和 `rightJoinSub` 方法关联一个查询作为子查询\n\n```kotlin\n/*\nSELECT *\nFROM `users`\n\tLEFT JOIN (SELECT * FROM `posts` WHERE `status` = ?) `unpublished_posts`\n\tON `users`.`id` = `unpublished_posts`.`user_id`\n */\nbuilder2.table(\"posts\").where(\"status\", \"=\", 0)\nbuilder.table(\"users\")\n    .leftJoinSub(builder2, \"unpublished_posts\", \"users.id\", \"=\", \"unpublished_posts.user_id\")\n    .get()\n```\n\n### Unions\n\n`union`\n\n```kotlin\n// (select `id`,`name` from `users`) union (select `id`,`title` as `name` from `posts`)\nbuilder2.table(\"posts\").select(\"id\", \"title as name\")\nbuilder.table(\"users\").select(\"id\", \"name\").union(builder2).get()\n```\n\n`unionAll` 和 `union` 用法一样，但是 `union` 会删除重复结果\n\n### 基础的 Where 语句\n\n#### where 语句\n\nwhere 语句的第一个参数是列名，第二个参数是操作符，可以使用数据库支持的任意操作符，第三个参数是值, 第四个参数是连接符默认是 and，可以使用 or\n\n例如查询年龄小于18并且积分大于60的用户\n\n```kotlin\nval users = builder.table(\"users\")\n    .where(\"age\", \"\u003c\", 18)\n    .where(\"score\", \"\u003e\", 60)\n    .get()\n```\n\n当操作符是 \"=\" 时，绝大部分情况可以省略操作符, 当**值**是 \"=\", \"!=\" 和 \"\u003c\u003e\" 时，操作符不可以省略, 因为第三个参数默认值是 null，程序会认为是使用以上操作符与 null 比较, 此时可以使用 whereEquals.\n\n省略 \"=\" 操作符时， where 方法的第三个参数不要传，或者传 null\n\n```kotlin\nval users = builder.table(\"users\")\n    .where(\"age\", 18)\n    .where(\"score\", 60)\n    .get()\n```\n\n\n如果有多个条件可以使用一个嵌套 List 直接传递给 `where` 方法\n\n```kotlin\n// select * from `users` where (`age` \u003c ? and `score` \u003e ? and `name` like ?)\nval users = builder.table(\"users\")\n    .where(listOf(listOf(\"age\", \"\u003c\", 18), listOf(\"score\", \"\u003e\", 60), listOf(\"name\", \"like\", \"%Tom%\")))\n    .get()\n```\n\n如果多个条件都是 = 操作符，可以通过一个 Map 直接传给 `where` 方法\n\n```kotlin\n// select * from `users` where (`score` = ? and `age` = ?)\nval users = builder.table(\"users\")\n    .where(hashMapOf(\n        \"age\" to 18,\n        \"score\" to 60\n    ))\n    .get()\n```\n\n#### orWhere 语句\n\n除了给 `where` 方法的最后一个参数传 or 之外，也可以直接使用 `orWhere` 方法。用法同 `where`\n\n```kotlin\n// select * from `users` where `name` = ? or (`age` \u003c ? and `score` \u003e ? and `name` like ?)\nval users = builder.table(\"users\")\n    .where(\"name\", \"=\", \"Tom\")\n    .orWhere(listOf(listOf(\"age\", \"\u003c\", 18), listOf(\"score\", \"\u003e\", 60), listOf(\"name\", \"like\", \"%Tom%\")))\n    .get()\n```\n\n#### 其他 where 语句\n\n##### `whereEquals` / `orWhereEquals`\n\n验证相等，不用每次都传 = 号\n\n```kotlin\n// select * from `users` where `name` = ?\nval users = builder.table(\"users\")\n    .whereEquals(\"name\", \"Tom\")\n    .get()\n```\n\n事实上，`whereEquals` 和 `orWhereEquals` 方法只是 `where` 和 `orWhere` 方法的特殊情况，只是为了更好的语义化\n\n##### `whereBetween` / `orWhereBetween` / `whereNotBetween` / `orWhereNotBetween`\n\n验证 between 关系。意义不同，但用法都一样\n\n```kotlin\n// select * from `users` where `age` between ? and ?\nval users = builder.table(\"users\")\n    .whereBetween(\"age\", listOf(18, 60))\n    .get()\n```\n\n##### `whereIn` / `whereNotIn` / `orWhereIn` / `orWhereNotIn`\n\n验证 in 关系\n\n```kotlin\n// select * from `users` where `name` in (?, ?)\nval users = builder.table(\"users\")\n    .whereIn(\"name\", listOf(\"Tom\", \"Jerry\"))\n    .get()\n```\n\n##### `whereNull` / `whereNotNull` / `orWhereNull` / `orWhereNotNull`\n\n```kotlin\n// select * from `users` where `deleted_at` is null\nval users = builder.table(\"users\")\n    .whereNull(\"deleted_at\")\n    .get()\n```\n\n##### `whereNot` / `orWhereNot`\n\n```kotlin\n// select * from `users` where not `banned` = ?\nval users = builder.table(\"users\")\n  .whereNot(\"banned\", \"=\", 1)\n  .get()\n```\n\n##### `whereDate` / `whereMonth` / `whereDay` / `whereYear` / `whereTime`\n\n用来比较时间\n\n```kotlin\n// select * from `users` where year(`created_at`) = ?\nval users = builder.table(\"users\")\n    .whereYear(\"created_at\", \"=\", 2022)\n    .get()\n```\n\n##### `whereColumn` / `orWhereColumn`\n\n用于比较两个列\n\n```kotlin\n// select * from `users` where `created_at` \u003c `updated_at`\nval users = builder.table(\"users\")\n    .whereColumn(\"created_at\", \"\u003c\", \"updated_at\")\n    .get()\n```\n\n#### 逻辑分组\n\n有时查询条件可能由复杂的 where 条件组合而成，使用 `where` 方法也可以实现。\n\n如果查找 [（age 大于 18 小于 60）或者 （score 小于 90）] 并且 status 等于 0 的用户. (为了演示特意没有使用 whereBetween)\n\n```kotlin\n// sql: select * from `users` where ((`age` \u003e ? and `age` \u003c ?) or `score` \u003c ?) and `status` = ?\n// bindings: [18, 60, 90, 0]\nval users = builder.table(\"users\")\n    .where({query: Builder -\u003e\n        query.where({ q: Builder -\u003e\n            q.where(\"age\", \"\u003e\", \"18\")\n                .where(\"age\", \"\u003c\", 60)\n        }).orWhere(\"score\", \"\u003c\", 90)\n    })\n    .where(\"status\", \"=\", 0)\n    .get()\n```\n\n### 高级 Where 语句\n\n#### Where Exists 语句\n\n`whereExists` 方法允许你使用 where exists SQL 语句\n\n```kotlin\n// select * from `users` where exists (select 1 from `posts` where `id` = `users`.`id`)\nval users = builder.table(\"users\")\n    .whereExists({ query -\u003e\n        query.from(\"posts\")\n            .whereColumn(\"id\", \"=\", \"users.id\").select(Expression(\"1\"))\n    })\n    .get()\n```\n\n#### 子查询 Where 语句\n\n有时候，你可能需要构造一个 where 子查询，将子查询的结果与给定的值进行比较。你可以通过向 `where` 方法传递闭包和值来实现此操作\n\n```kotlin\n// select * from `users` where (select count(*) from `posts` where `id` = `users`.`id`) \u003c ?\nval users = builder.table(\"users\")\n    .where({ query: Builder -\u003e\n        query.from(\"posts\").whereColumn(\"id\", \"=\", \"users.id\").selectRaw(\"count(*)\")\n    }, \"\u003c\", 3)\n    .get()\n```\n\n值也可以是子查询\n\n```kotlin\n// select * from `users` where `limit` \u003e (select count(*) from `posts` where `id` = `users`.`id`)\nval users = builder.table(\"users\")\n    .where(\"limit\", \"\u003e\", { query: Builder -\u003e\n        query.from(\"posts\").whereColumn(\"id\", \"=\", \"users.id\").selectRaw(\"count(*)\")\n    })\n    .get()\n```\n\n#### java 示例\n\n使用 java 写复杂查询时， 可以通过调用 kotlin 的 `Function1` 类来实现\n\n```java\n// select * from `users` where (select count(*) from `posts` where `id` = `users`.`id`) \u003c ?\n\nimport kotlin.jvm.functions.Function1;\n\nbuilder.table(\"users\")\n    .where(new Function1\u003cBuilder, Void\u003e() {\n        @Override\n        public Void invoke(Builder query) {\n            query.from(\"posts\")\n                    .whereColumn(\"id\", \"=\", \"users.id\")\n                    .selectRaw(\"count(*)\");\n            return null;\n        }\n    }, \"\u003c\", 3)\n    .get();\n```\n\n\n### Ordering, Grouping, Limit \u0026 Offset\n\n#### 排序\n\n##### `orderBy` 方法\n\n`orderBy` 方法允许按给定列对查询结果进行排序。`orderBy` 接受的第一个参数应该是排序的列，而第二个参数确定排序的方向，可以是 `asc` 或 `desc`,默认是 `asc`\n\n```kotlin\nval users = builder.table(\"users\")\n    .orderBy(\"name\", \"asc\")\n    .get()\n```\n\n可以多次调用来使用多个字段排序,还有直接使用 `desc` 的 `orderByDesc` 方法\n\n```kotlin\nval users = builder.table(\"users\")\n    .orderBy(\"name\", \"asc\")\n    .orderBy(\"age\", \"desc\")\n    .orderByDesc(\"created_at\")\n    .get()\n```\n\n##### `latest` 和 `oldest` 方法\n\n使用 `latest` 和 `oldest` 方法可以按照日期进行 `desc` / `asc` 排序，默认使用 `created_at` 字段进行排序，也可以自己传递要使用的字段\n\n```kotlin\n// select * from `users` order by `created_at` desc\nval users = builder.table(\"users\")\n    .latest()\n    .get()\n```\n\n##### 随机排序\n\n使用 `inRandomOrder` 方法可以交查询结果随机排序\n\n```kotlin\nval users = builder.table(\"users\")\n    .inRandomOrder()\n    .get()\n```\n\n##### 移除已存在的排序\n\n使用 `reorder` 方法可以移除已存在的排序,也可以传递参数像使用 `orderBy` 一样重新指定排序\n\n```kotlin\nval users = builder.table(\"users\")\n    .orderBy(\"name\", \"asc\")\n    .orderBy(\"age\", \"desc\")\n    .reorder()\n    .get()\n```\n\n#### 分组\n\n##### `groupBy` 和 `having` 方法\n\n`groupBy` 和 `having` 方法可以将查询结果分组。`having` 方法的使用方法类似于 `where` 方法。 `groupBy` 可以接受多个分组参数\n\n```kotlin\nval users = builder.table(\"users\")\n    .selectRaw(\"count(*) as aggregate, age\")\n    .groupBy(\"age\")\n    .having(\"aggregate\", \"\u003e\", 19)\n    .get()\n```\n\n与 `having` 类似的还有 `havingBetween`, `havingNull`, 使用方法类似 `whereBetween` 和 `whereNull`\n\n#### Limit 和 Offset\n\n`limit` 和 `offset` 用来限制查询结果的返回数量或者在查询结果中跳过的数量, 还有两个方法 `take` 和 `skip` 分别是 `limit` 和 `offset` 方法的别名\n\n```kotlin\nval users = builder.table(\"users\")\n    .limit(3)\n    .offset(5)\n    .get()\n```\n\n#### forPage 和 paginate\n\n`forPage` 方法内部使用 `limit` 和 `offset` 来取某一页的数据\n\n```kotlin\nval users = builder.table(\"users\")\n    .forPage(1, 3) // 第 1 页， 取 3 个\n    .get()\n```\n\n`paginate` 方法是自动的分页方法，会执行两条 sql 语句，分别查总数和条目。直接返回分页对象，包括总数量，总页数等。默认当前第 1 页，每页 15条，可以通过传参数修改\n\n```kotlin\nval page = builder.table(\"users\")\n    .paginate()\n```\n\n`paginate` 返回的数据是 `Page` 类型，里面包含的是 `List\u003cMap\u003cString, Any?\u003e\u003e` 类型。也可以传递 `KClass\u003cT\u003e` 或 `Class\u003cT\u003e` 来返回对象类型\n\n### 条件语句\n\n\n有时候查询列表需要根据前台传过来的值来决定要不要使用某列进行筛选，这时可以使用 `ifTrue`, `whenTrue`, `ifFalse`, `whenFalse` 方法来处理，`if` 和 `when` 开头的方法是等价的\n\n```kotlin\nval status = request.getParameter(\"status\")\n\nval users = builder.table(\"users\")\n    .whenTrue(status != null, { query -\u003e\n        query.where(\"status\", \"=\", status)\n    })\n    .get()\n```\n\n这些方法还有第三个参数，当条件不成立的时候，不会执行第二个参数，而是执行第三个。\n\n```kotlin\nval deleted = false // 我这时定义死了\n\nval users = builder.table(\"users\")\n    .whenTrue(deleted, {\n        it.whereNotNull(\"deleted\")\n    }, {\n        it.whereNull(\"deleted\") // 会执行这一条，就像 if/else 一样\n    })\n    .get()\n```\n\n### 插入\n\n虽然是叫 querybuilder, 但是也支持简单的增删改, ^_^。\n\n`insert`, `insertGetId` 和 `insertOrIgnore` 用于给数据库插入记录\n\n`insert` 支持单条插入和多条插入，多条插入还可以设置分批插入,单条插入的参数是 `Map\u003cString, Any?\u003e` 类型，多条插入则是 `List\u003cMap\u003cString, Any?\u003e\u003e`，返回的是插入成功的条数\n\n自 1.0.7 版本开始，支持传入 `com.tianyisoft.database.Table` 子类的实例, `Table` 类通过实现 `fillable` 方法来控制要添加或修改的字段, 具体可见 `Table` 类源码\n\n```kotlin\nval rows = builder.table(\"users\")\n    .insert(hashMapOf(\n        \"name\" to \"tom\",\n        \"age\" to 20,\n        \"created_at\" to Date()\n    ))\n```\n\n`insertGetId` 和单条插入时的 `insert` 方法一致，但是返回的是自增的 id， 如果自增字段不是 id，可以通过第二个参数设置\n\n`insertOrIgnore` 会忽略错误, 用法和 `insert` 一致\n\n### 修改\n\n`update` 用于更新数据,参数是 `Map\u003cString, Any?\u003e` 类型，更新可以使用表达式，比如给某列加 1\n\n```kotlin\nbuilder.table(\"users\")\n    .where(\"id\", \"=\", 3)\n    .update(hashMapOf(\n        \"name\" to \"Jerry\",\n        \"age\" to Expression(\"age + 1\")\n    ))\n```\n\n`increment` 和 `decrement` 用于增加或减少指定字段的值，内部使用的就是 `update` 方法加 `Expression` 表达式\n\n```\nbuilder.table(\"users\")\n    .where(\"id\", \"=\" 3)\n    .increment(\"age\", 2) // 加两岁\n```\n\n### 删除\n\n`delete` 方法可以删除表的记录，可以一次删除一条或多条\n\n```kotlin\nbuilder.table(\"users\")\n    .delete(3)\n```\n\n或\n\n```kotlin\nbuilder.table(\"users\")\n    .where(\"id\", \"\u003e\", 30)\n    .delete()\n```\n\n### 清空表\n\n`truncate` 方法用来清空表，不过不建议使用，清空表这种高风险的操作，还是手动操作比较好\n\n```kotlin\nbuilder.table(\"users\").truncate()\n```\n\n### 调试\n\n可以打印出当前的 sql 语句和绑定的数据，用来判断逻辑是否正确\n\n```kotlin\nbuilder.table(\"users\").where(\"id\", \"=\", 3).dump()\n```\n\n以上程序会打印出\n\n```text\nsql: select * from `users` where `id` = ?\nbindings: [3]\n```\n\n### AbstractRepository\n\n如果你使用的是 spring boot, QueryBuilder 提供了一个 `AbstractRepository` 类\n\n**首先在 spring boot 的 application 类上添加注解 `@EnableRepository`**， 然后就可以继承该类，并添加 `@Component` 就可以注入使用了\n\n继承 `AbstractRepository` 需要提供表名。\n\n```kotlin\nimport com.tianyisoft.database.AbstractRepository\nimport org.springframework.stereotype.Component\nimport com.tianyisoft.database.util.Page\n\n@Component\nopen class UserRepository: AbstractRepository() {\n    override val table: String = \"users\"\n\n    // 获取未删除用户的分页数据\n    fun notDeleted(): Page\u003cMap\u003cString, Any?\u003e\u003e {\n        return query().whereNull(\"deleted_at\").orderBy(\"id\").paginate()\n    }\n}\n```\n\n#### 多数据源\n\nQueryBuilder 本身就可以通过设置不同的 JdbcTemplate 来实现多数据源。使用 `AbstractRepository` 时，可以通过 `@DbTemplate` 来指定使用哪个数据源, 默认使用 spring boot 默认的 JdbcTemplate bean.\n\n#### 基本方法\n\n`AbstractRepository` 也实现了简单的增删改查方法, 同时也可以通过 `query()` 方法使用更多的 querybuilder 提供的方法。\n\n```kotlin\nval id = userRepository.insert(hashMapOf(/*...*/))\nuserRepository.find(id)\nuserRepository.update(id, hashMapOf(/*...*/))\nuserRepository.delete(id)\nuserRepository.query().where(\"id\", \"\u003e\", 3).orWhere(\"age\", \"\u003c\", 10).get()\n```\n\n`AbstractRepository` 还提供了简单的 `beforeInsert`， `afterInsert`, `beforeUpdate`, `afterUpdate`, `beforeDelete` 和 `afterDelete` 方法用于在操作数据前后做一些操作. 可以通过继承方法使用它们。\n\n比如增加数据前要设置 `created_at` 和 `updated_at` 的值。\n\n这个功能只对 `AbstractRepository` 自有的方法有作用，通过 `query()` 调用的操作不起作用\n\n```kotlin\noverride fun beforeInsert(params: MutableMap\u003cString, Any?\u003e): Map\u003cString, Any?\u003e {\n    val now = Date()\n    params[\"created_at\"] = now\n    params[\"updated_at\"] = now\n    return params\n}\n```\n\n上面提到了设置 `created_at` 和 `updated_at` 的值, 还有更直接的办法来完成这个操作，继承 `AbstractRepository` 并重写父类的 `timestamps` 值为 `true` 就可以自动插入这两列的值，还可能通过重写 `createdColumn` 和 `updatedColumn` 来修改字段名。\n\n同样的，这个功能只对 `AbstractRepository` 自有的方法有作用，通过 `query()` 调用的操作不起作用\n\n如果习惯使用 java 写程序，可以使用 kotlin 来实现 Repository, 然后通过 java 代码来调用，这样就只有 Repository 一层是 kotlin 代码。因为使用 kotlin 来调用 querybuilder 实在是太舒服了.\n\n### Snippet 代码片段\n\n有时相同的一些查询条件会多次使用，这时可以写成代码片段，然后在使用时通过 `use` 方法调用\n\n使用代码片段的方法是实现 `Snippet` 接口,比如常用的查询状态的条件可以写一个代码片段\n\n```kotlin\nclass StatusSnippet : Snippet {\n    override fun apply(builder: Builder, vararg params: Any?) {\n        if (params.size == 1) { // 如果有一个参数，直接查询 status\n            builder.where(\"status\", \"=\", params[0])\n        } else if (params.size == 2) { // 如果有两个参数，则第一个是状态的字段名\n            builder.where(params[0] as String, \"=\", params[1])\n        }\n    }\n}\n\n// 或者直接生成一个对象, 是一样的\n\nval statusSnippet = Snippet { builder, params -\u003e\n    if (params.size == 1) {\n        builder.where(\"status\", \"=\", params[0])\n    } else if (params.size == 2) {\n        builder.where(params[0] as String, \"=\", params[1])\n    }\n}\n\n```\n\n这样就创建完一个代码段了，在需要的时候直接使用 `use` 方法，并传入参数即可\n\n```kotlin\nbuilder.table(\"users\").use(StatusSnippet(), 1).get()\n// 或者当参数名不叫 status 时, 比如叫 state\nbuilder.table(\"users\").use(StatusSnippet(), \"state\", 1).get()\n```\n\n实际上 statusSnippet 已经提供了，可以直接使用\n\n### 软删除\n\nQueryBuilder 提供了软删除的功能，可以通过 `enableSoftDelete` 方法来开启，支持定义软删除的字段和类型，目前支持时间和数字两种类型\n\n```kotlin\nbuilder.table(\"users\").enableSoftDelete().get() // 默认是 deleted_at 字段，类型是时间\n\nbuilder.table(\"users\").enableSoftDelete(\"deleted_at\", DeletedDataType.DATETIME).get() // 指定字段名和类型\n\nbuilder.table(\"users\").enableSoftDelete(\"deleted\", DeletedDataType.INTEGER).get() // 指定字段名和类型, 类型为数字型\n```\n\n时间类型会在 sql 中使用 `is null` 来判断是否删除，数字类型会使用 `= 0` 来判断是否删除\n\n软删除会对查询，修改和删除操作起作用， 开启了软删除后，查询和修改会自动加上软删除的条件，删除会自动更新软删除字段的值\n\n### Relation 关联\n\n因为 QueryBuilder 并不是 orm 框架，所以实现关联也没有和类的字段关联起来，而是直接生成一个关联的实例来使用。\n\n目前直接的关联有 `HasOne`(一对一), `BelongsTo`(反向一对一), `HasMany`(一对多) 和 `BelongsToMany`(多对多)。\n\n`HasOne`(一对一), `BelongsTo`(反向一对一), `HasMany`(一对多) 支持递归查询，可能通过设置 relation 的 `recursive` 属性来设置递归的深度，\n比如 `HasOne(\"id_card\", \"user_id\", \"id\").withRecursive()` 表示要使用递归，这在无限级别树等场景下会很有用。\n\n#### HasOne, HasMany 和 BelongsTo\n\n##### HasOne 和 HasMany\n\n首先创建两个表\n\n`user` 表\n\n| id  | name\t | age | habits            |\n|----:|------:|----:|:------------------|\n| 1\t  | 小米\t   | 18\t | [\"sports\"]        |\n| 2\t  | 小明\t   | 22\t | [\"music\"]         |\n| 3\t  | 小红\t   | 21\t | [\"sleep\", \"read\"] |\n\n`id_card` 表\n\n| \tid | \tuser_id\t | number             |\n|----:|----------:|:-------------------|\n| \t1\t |        1\t | ABSBEE2022-02-28   |\n| \t2\t |        2\t | 123456200105021251 |\n\n每个 user 有一个 id_card, 可以表示为 `HasOne(\"id_card\", \"user_id\", \"id\")`, 因为默认参数可以简写为 `HasOne(\"id_card\", \"user_id\")`\n\n查询关联数据使用 `with` 方法, `with` 方法的第一个参数是关联字段的名字，是任意取的，第二个参数是关联对象\n\n```kotlin\nval userWithIdCard = builder.table(\"user\")\n    .with(\"id_card\", HasOne(\"id_card\", \"user_id\"))\n    .get() // List\u003cMap\u003cString, Any?\u003e\u003e\n```\n\n以上程序返回\n\n```json\n[\n    {\n        \"id\":1,\n        \"name\":\"小米\",\n        \"age\":18,\n        \"habits\":\"[\\\"sports\\\"]\",\n        \"id_card\":{\n            \"id\":1,\n            \"user_id\":1,\n            \"number\":\"ABSBEE2022-02-28\"\n        }\n    },\n    {\n        \"id\":2,\n        \"name\":\"小明\",\n        \"age\":22,\n        \"habits\":\"[\\\"music\\\"]\",\n        \"id_card\":{\n            \"id\":2,\n            \"user_id\":2,\n            \"number\":\"123456200105021251\"\n        }\n    },\n    {\n        \"id\":3,\n        \"name\":\"小红\",\n        \"age\":21,\n        \"habits\":\"[\\\"sleep\\\", \\\"read\\\"]\",\n        \"id_card\":null\n    }\n]\n```\n\n这里也可以创建一个 `User` 类和 `IdCard` 类来接收参数\n\n```java\nclass User {\n  private Long id;\n  private String name;\n  private Integer age;\n  private String habits;\n  @JsonProperty(\"id_card\")\n  private Idcard idCard;\n  // getters and setters ...\n}\n\nclass IdCard {\n  private Long id;\n  @JsonProperty(\"user_id\")\n  private Long userId;\n  private String number;\n  // getters and setters ...\n}\n```\n\n取的时候使用 `get` 方法的重载方法就可以了。\n\n```kotlin\nval userWithIdCard = builder.table(\"user\")\n    .with(\"id_card\", HasOne(\"id_card\", \"user_id\"))\n    .get(User::class.java) // List\u003cUser\u003e\n```\n\n以上是 `HasOne` 的用法，`HasOne` 是 `HasMany` 的一种特殊情况，`HasMany` 和 `HasOne` 用法基本一样, 不再赘述。\n\n`HasMany` 返回的是数组，而不像 `HasOne` 是单独的对象，这是唯一的区别。\n\n##### BelongsTo\n\n`BelongsTo` 是和 `HasOne` 和 `HasMany` 相反的关联，还用上面的两个表举例, id_card 是属于 user 的，用 `BelongsTo` 表示就是 `BelongsTo(\"user\", \"user_id\")`\n\n```kotlin\nval idCardWithUser = builder.table(\"id_card\")\n    .with(\"user\", BelongsTo(\"user\", \"user_id\"))\n    .get(IdCard::class.java)\nprintln(idCardWithUser)\n```\n\n输出数据\n\n```text\n[IdCard{id=1, userId=1, number='ABSBEE2022-02-28', user=User{id=1, name='小米', age=18, habits='[\"sports\"]'}}, IdCard{id=2, userId=2, number='123456200105021251', user=User{id=2, name='小明', age=22, habits='[\"music\"]'}}]\n```\n\n`HasOne`, `HasMany` 和 `BelongsTo` 都是继承自 `Builder` 的，可以使用 `Builder` 类的各种方法。\n\n如查询 user, 把 id_card 也带出来，同时限制 id_card 的 id 是大于 1 的。\n\n```kotlin\nbuilder.table(\"user\")\n    .with(\"id_card\", HasOne(\"id_card\", \"user_id\").where(\"id\", \"\u003e\", 1) as HasOne)\n    .get()\n```\n\n#### BelongsToMany\n\n`BelongsToMany` 表示多对多关系，需要中间表的支持。比如用户和权限的关系，一个用户可以有多个权限，一个权限也可以属于多个用户。\n\n下面有3个表，用户表，权限表，用户权限关系表\n\n`user` 表\n\n| id  | name\t |\n|----:|------:|\n| 1\t  | 小米\t   |\n| 2\t  | 小明\t   |\n| 3\t  | 小红\t   |\n\n`permission` 表\n\n|  id | name\t |\n|----:|------:|\n|  1\t |    增\t |\n|  2\t |    删\t |\n|  3\t |    改\t |\n|  4\t |    查\t |\n\n`permission_user` 表\n\n| \tid | \tuser_id | \tpermission_id |\n|----:|---------:|---------------:|\n| \t1\t |       1\t |              1 |\n| \t2\t |       1\t |              2 |\n| \t3\t |       1\t |              3 |\n| \t4\t |       2\t |              4 |\n| \t5\t |       1\t |              4 |\n| \t6\t |       3\t |              4 |\n| \t7\t |       2\t |              1 |\n\nuser 表和 permission 表的关联可以表示为 `BelongsToMany(\"permission\", \"permission_user\", \"user_id\", \"permission_id\", \"id\", \"id\")`, \n第一个参数为关联的表名，第二个参数为中间表名，第三个参数为当前表在中间表里的关联字段，\n第四个参数为关联的表在中间表的关联字段, 第五个参数为当前表的id字段，第六个参数为关联表的id字段。\n当第五个和第六个参数是 id时，可以省略\n\n反向的 permission 表和 user 表的关系可以表示为`BelongsToMany(\"user\", \"permission_user\", \"permission_id\", \"user_id\")`\n\n接下来就可以通过 `with` 方法来取数据了,使用方法和上面的 `HasOne` 没有区别。\n\n`BelongsToMany` 也继承自 `Builder` 类，所以也可以使用 `Builder` 类的各种方法，除此之外，还实现了自己的一些方法用来限制中间表。\n\n这些方法是 `wherePivot`, `wherePivotBetween`, `wherePivotIn`, `wherePivotNull`, `orderByPivot`,这些限制的是中间表的数据, 用法和去掉 Pivot 后的 `Builder` 类同名方法一样，如\n\n```kotlin\nBelongsToMany(\"permission\", \"permission_user\", \"user_id\", \"permission_id\", \"id\", \"id\")\n    .wherePivot(\"id\", \"\u003e\", 3)\n// 要求中间表 permission_user 的数据 id 是大于 3的，不符合条件的数据则不会被关联出来\n```\n\n#### 关联统计\n\n关联可以不直接查出关联数据，而是计算出关联的数据，比如关联的条数，关联内容某列的和等。\n\n关联统计的方法有 `withCount`, `withSum`, `withAvg`, `withMin` 和 `withMax`\n\n还以上面的 `HasOne` 为例, 查询每个 user 的 id_card 数量:\n\n```kotlin\nval user = builder.table(\"user\")\n    .select(\"id\", \"name\") // 这里的 select 是有用的，不然会只返回 id_card_count 一列\n    .withCount(\"id_card_count\", HasOne(\"id_card\", \"user_id\"))\n    .get()\n```\n\n以上代码返回\n\n```json\n[\n    {\n        \"id\":1,\n        \"name\":\"小米\",\n        \"id_card_count\":1\n    },\n    {\n        \"id\":2,\n        \"name\":\"小明\",\n        \"id_card_count\":1\n    },\n    {\n        \"id\":3,\n        \"name\":\"小红\",\n        \"id_card_count\":0\n    }\n]\n```\n\n#### 基于关联存在的查询\n\n可以把关联做为条件来进行查询，比如我要查询有 id_card 的 user, 或者要查询有三个及以上 permission 的 user。\n\n要实现这个的功能可以使用 whereHas\n\n```kotlin\n// 查询有 id_card 的 user\n/*\nSELECT *\nFROM `user`\nWHERE EXISTS (\n\tSELECT 1\n\tFROM `id_card`\n\tWHERE `id_card`.`user_id` = `user`.`id`\n)\n*/\nbuilder.table(\"user\").whereHas(HasOne(\"id_card\", \"user_id\")).get()\n\n\n// 查询有三个及以上 permission 的 user\n/*\nSELECT *\nFROM `user`\nWHERE (\n\tSELECT count(*)\n\tFROM `permission`\n\t\tINNER JOIN `permission_user` ON `permission_user`.`permission_id` = `permission`.`id`\n\tWHERE `permission_user`.`user_id` = `user`.`id`\n) \u003e= ?\n*/\nbuilder.table(\"user\")\n    .whereHas(BelongsToMany(\"permission\", \"permission_user\", \"user_id\", \"permission_id\"), \"\u003e=\", 3)\n    .get()\n```\n\n\n### 结语\n\n上面只是各个方法的简介，更复杂的用法也可能没有提到，可以翻看源码了解。另外，有用的方法会一直增加，文档也会一直完善。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftianyirenjian%2Fquerybuilder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftianyirenjian%2Fquerybuilder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftianyirenjian%2Fquerybuilder/lists"}