{"id":29137514,"url":"https://github.com/shiny/clickhousesqlbuilder","last_synced_at":"2025-08-23T01:36:48.351Z","repository":{"id":300268551,"uuid":"1003508022","full_name":"shiny/ClickHouseSqlBuilder","owner":"shiny","description":"A minimal SQL builder for ClickHouse in the JavaScript ecosystem.","archived":false,"fork":false,"pushed_at":"2025-06-17T09:52:41.000Z","size":6,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-28T17:07:59.974Z","etag":null,"topics":["clickhouse","sqlbuilder"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shiny.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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-17T08:54:18.000Z","updated_at":"2025-06-17T09:58:37.000Z","dependencies_parsed_at":"2025-06-20T19:35:12.819Z","dependency_job_id":null,"html_url":"https://github.com/shiny/ClickHouseSqlBuilder","commit_stats":null,"previous_names":["shiny/clickhousesqlbuilder"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shiny/ClickHouseSqlBuilder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiny%2FClickHouseSqlBuilder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiny%2FClickHouseSqlBuilder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiny%2FClickHouseSqlBuilder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiny%2FClickHouseSqlBuilder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shiny","download_url":"https://codeload.github.com/shiny/ClickHouseSqlBuilder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shiny%2FClickHouseSqlBuilder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262775558,"owners_count":23362536,"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":["clickhouse","sqlbuilder"],"created_at":"2025-06-30T12:38:20.251Z","updated_at":"2025-06-30T12:38:37.259Z","avatar_url":"https://github.com/shiny.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ClickHouse Query Builder\n\n## Quick Start\n\n```bash\nbun i clickhouse-sql-builder\n```\n## Notes\n- This is an early-stage concept—integrate with caution.\n- It's already powering the analytics behind the short URL feature on u301.com.\n- Released as an open-source internal utility by the U301 URL Shortener team.\n\n## Problems with Using the ClickHouse JS SDK\n\n- In the JavaScript ecosystem, ORM support for ClickHouse is minimal, and trying to force it into an ORM doesn’t make much sense, especially given how rigid schemas and complex queries are in ClickHouse.\n- The native ClickHouse JS SDK is hard to use. you often end up manually concatenating SQL strings.\n- This becomes especially painful when dealing with optional filters, where query readability quickly degrades.\n\nTo address this, I created a minimal ClickHouse Query Builder with a few guiding principles:\n\n- It should focus purely on SQL string composition—no custom syntax or third-party dependencies. You can pass in raw SQL strings as needed.\n- It should add lightweight support for parameter binding in the ClickHouse JS SDK to help prevent SQL injection.\n- It should be designed to feel intuitive.\n- It should leverage TypeScript's type system to simplify building SQL queries.\n\n## Example\n\n```typescript\nimport { createClient } from '@clickhouse/client'\nimport { ClickHouseSqlBuilder } from 'clickhouse-query-builder'\nconst builder = ClickHouseSqlBuilder\n    .select([\n        'count(*) AS click',\n        'toDate(access_date, :timezone) date'\n    ])\n    .from('analyze_short_url_visit')\n    .where('workspace_id=:workspaceId')\n    .whereBetween('access_date', ':startDatetime', ':endDatetime')\n    .groupBy('date')\n    .orderBy('date', 'ASC')\n    .withFill({\n        from: 'toDate(:startDatetime, :timezone)',\n        to: 'toDate(:endDatetime, :timezone) + INTERVAL 1 DAY',\n        step: `INTERVAL 1 DAY`\n    })\n\n// Add optional conditions\nconst shortLink = 'u301.co/try'\nif(shortLink) {\n    builder.and(shortLink)\n}\n\n// Bind Params\nbuilder.addParam('String', {\n    workspaceId: '1',\n    timezone: 'Europe/London',\n    shortLink\n})\nbuilder.addParam('DateTime64', {\n    startDatetime: new Date('2025-06-17 00:00:00'),\n    endDatetime: new Date('2025-07-17 23:59:59')\n})\n\nconst client = createClient({\n    url: 'http://localhost:8123/default',\n    compression: {\n        response: true,\n        request: true\n    },\n})\n\nconst result = await client.query({\n    query: builder.toSql(),\n    query_params: builder.queryParams(),\n    format: 'JSONEachRow',\n})\n\n```\n\nThe resulting SQL query looks like this:\n\n```sql\nSELECT count(*) AS click, toDate(access_date, :timezone) date \n\tFROM analyze_short_url_visit \n\tWHERE workspace_id=:workspaceId AND access_date BETWEEN :startDatetime AND :endDatetime \n\tGROUP BY date \n\tORDER BY date ASC \n\tWITH FILL FROM toDate(:startDatetime, :timezone) TO toDate(:endDatetime, :timezone) + INTERVAL 1 DAY STEP INTERVAL 1 DAY\n```\n\n## License\nThe MIT License","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshiny%2Fclickhousesqlbuilder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshiny%2Fclickhousesqlbuilder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshiny%2Fclickhousesqlbuilder/lists"}