@hypequery/clickhouse 1.0.5 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/core/connection.d.ts +53 -77
- package/dist/core/connection.d.ts.map +1 -1
- package/dist/core/connection.js +93 -28
- package/dist/core/features/analytics.d.ts +1 -1
- package/dist/core/features/analytics.d.ts.map +1 -1
- package/dist/core/query-builder.d.ts +33 -19
- package/dist/core/query-builder.d.ts.map +1 -1
- package/dist/core/query-builder.js +12 -0
- package/dist/core/tests/integration/setup.d.ts +1 -1
- package/dist/core/tests/integration/setup.d.ts.map +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/package.json +16 -2
- package/README.md +0 -279
|
@@ -1,84 +1,34 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import type {
|
|
1
|
+
import type { ClickHouseSettings } from '@clickhouse/client-common';
|
|
2
|
+
import type { ClickHouseClient as NodeClickHouseClient } from '@clickhouse/client';
|
|
3
|
+
import type { ClickHouseClient as WebClickHouseClient } from '@clickhouse/client-web';
|
|
4
|
+
import type { ClickHouseConfig } from './query-builder';
|
|
5
|
+
type ClickHouseClient = NodeClickHouseClient | WebClickHouseClient;
|
|
3
6
|
/**
|
|
4
|
-
*
|
|
7
|
+
* The main entry point for connecting to a ClickHouse database.
|
|
8
|
+
* Provides static methods to initialize the connection and retrieve the client.
|
|
9
|
+
*
|
|
10
|
+
* Supports two modes of operation:
|
|
11
|
+
* 1. **Manual injection**: Provide a client instance via `config.client` (required for browser environments)
|
|
12
|
+
* 2. **Auto-detection**: Automatically uses @clickhouse/client for Node.js environments
|
|
5
13
|
*
|
|
6
14
|
* @category Core
|
|
7
15
|
* @example
|
|
8
16
|
* ```typescript
|
|
9
|
-
*
|
|
17
|
+
* // Method 1: Manual injection (required for browser environments)
|
|
18
|
+
* import { createClient } from '@clickhouse/client-web';
|
|
19
|
+
* const client = createClient({
|
|
10
20
|
* host: 'http://localhost:8123',
|
|
11
21
|
* username: 'default',
|
|
12
|
-
* password: 'password'
|
|
13
|
-
*
|
|
14
|
-
* };
|
|
15
|
-
* ```
|
|
16
|
-
*/
|
|
17
|
-
export interface ClickHouseConnectionOptions {
|
|
18
|
-
/**
|
|
19
|
-
* The URL of the ClickHouse server, including protocol and port.
|
|
20
|
-
* Example: 'http://localhost:8123' or 'https://your-instance.clickhouse.cloud:8443'
|
|
21
|
-
*/
|
|
22
|
-
host: string;
|
|
23
|
-
/**
|
|
24
|
-
* Username for authentication. Defaults to 'default' if not provided.
|
|
25
|
-
*/
|
|
26
|
-
username?: string;
|
|
27
|
-
/**
|
|
28
|
-
* Password for authentication.
|
|
29
|
-
*/
|
|
30
|
-
password?: string;
|
|
31
|
-
/**
|
|
32
|
-
* The database to connect to. Defaults to 'default' if not provided.
|
|
33
|
-
*/
|
|
34
|
-
database?: string;
|
|
35
|
-
/**
|
|
36
|
-
* Enable secure connection (TLS/SSL).
|
|
37
|
-
* This is automatically set to true if the host URL starts with https://
|
|
38
|
-
*/
|
|
39
|
-
secure?: boolean;
|
|
40
|
-
/**
|
|
41
|
-
* Custom HTTP headers to include with each request.
|
|
42
|
-
*/
|
|
43
|
-
http_headers?: Record<string, string>;
|
|
44
|
-
/**
|
|
45
|
-
* Request timeout in milliseconds.
|
|
46
|
-
*/
|
|
47
|
-
request_timeout?: number;
|
|
48
|
-
/**
|
|
49
|
-
* Compression options for the connection.
|
|
50
|
-
*/
|
|
51
|
-
compression?: {
|
|
52
|
-
response?: boolean;
|
|
53
|
-
request?: boolean;
|
|
54
|
-
};
|
|
55
|
-
/**
|
|
56
|
-
* Application name to identify in ClickHouse server logs.
|
|
57
|
-
*/
|
|
58
|
-
application?: string;
|
|
59
|
-
/**
|
|
60
|
-
* Keep-alive connection settings.
|
|
61
|
-
*/
|
|
62
|
-
keep_alive?: {
|
|
63
|
-
enabled: boolean;
|
|
64
|
-
};
|
|
65
|
-
/**
|
|
66
|
-
* Logger configuration.
|
|
67
|
-
*/
|
|
68
|
-
log?: any;
|
|
69
|
-
/**
|
|
70
|
-
* Additional ClickHouse-specific settings.
|
|
71
|
-
*/
|
|
72
|
-
clickhouse_settings?: ClickHouseSettings;
|
|
73
|
-
}
|
|
74
|
-
/**
|
|
75
|
-
* The main entry point for connecting to a ClickHouse database.
|
|
76
|
-
* Provides static methods to initialize the connection and retrieve the client.
|
|
22
|
+
* password: 'password'
|
|
23
|
+
* });
|
|
77
24
|
*
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
* //
|
|
25
|
+
* ClickHouseConnection.initialize({
|
|
26
|
+
* host: 'http://localhost:8123',
|
|
27
|
+
* database: 'my_database',
|
|
28
|
+
* client // Explicitly provide the client
|
|
29
|
+
* });
|
|
30
|
+
*
|
|
31
|
+
* // Method 2: Auto-detection (Node.js environments only)
|
|
82
32
|
* ClickHouseConnection.initialize({
|
|
83
33
|
* host: 'http://localhost:8123',
|
|
84
34
|
* username: 'default',
|
|
@@ -93,20 +43,38 @@ export interface ClickHouseConnectionOptions {
|
|
|
93
43
|
* format: 'JSONEachRow'
|
|
94
44
|
* });
|
|
95
45
|
* ```
|
|
46
|
+
*
|
|
47
|
+
* @note This library requires one of the following peer dependencies:
|
|
48
|
+
* - @clickhouse/client (for Node.js environments)
|
|
49
|
+
* - @clickhouse/client-web (for browser environments)
|
|
50
|
+
*
|
|
51
|
+
* **Important**: Browser environments require manual injection because `require()` calls don't work in browsers.
|
|
96
52
|
*/
|
|
97
53
|
export declare class ClickHouseConnection {
|
|
98
54
|
private static instance;
|
|
55
|
+
private static clientModule;
|
|
99
56
|
/**
|
|
100
57
|
* Initializes the ClickHouse connection with the provided configuration.
|
|
101
58
|
* This method must be called before any queries can be executed.
|
|
102
59
|
*
|
|
60
|
+
* **Priority order:**
|
|
61
|
+
* 1. If `config.client` is provided, use it directly (manual injection)
|
|
62
|
+
* 2. Otherwise, auto-detect @clickhouse/client for Node.js environments
|
|
63
|
+
*
|
|
64
|
+
* **Note**: Browser environments require manual injection because `require()` calls don't work in browsers.
|
|
65
|
+
*
|
|
103
66
|
* @param config - The connection configuration options
|
|
104
67
|
* @returns The ClickHouseConnection class for method chaining
|
|
105
|
-
* @throws Will throw an error if
|
|
68
|
+
* @throws Will throw an error if no ClickHouse client is available
|
|
106
69
|
*
|
|
107
70
|
* @example
|
|
108
71
|
* ```typescript
|
|
109
|
-
* //
|
|
72
|
+
* // Manual injection (required for browser environments)
|
|
73
|
+
* import { createClient } from '@clickhouse/client-web';
|
|
74
|
+
* const client = createClient({ host: 'http://localhost:8123' });
|
|
75
|
+
* ClickHouseConnection.initialize({ host: 'http://localhost:8123', client });
|
|
76
|
+
*
|
|
77
|
+
* // Auto-detection (Node.js environments only)
|
|
110
78
|
* ClickHouseConnection.initialize({
|
|
111
79
|
* host: 'http://localhost:8123',
|
|
112
80
|
* username: 'default',
|
|
@@ -115,7 +83,7 @@ export declare class ClickHouseConnection {
|
|
|
115
83
|
* });
|
|
116
84
|
* ```
|
|
117
85
|
*/
|
|
118
|
-
static initialize(config:
|
|
86
|
+
static initialize(config: ClickHouseConfig): typeof ClickHouseConnection;
|
|
119
87
|
/**
|
|
120
88
|
* Retrieves the ClickHouse client instance for direct query execution.
|
|
121
89
|
*
|
|
@@ -131,6 +99,14 @@ export declare class ClickHouseConnection {
|
|
|
131
99
|
* });
|
|
132
100
|
* ```
|
|
133
101
|
*/
|
|
134
|
-
static getClient():
|
|
102
|
+
static getClient(): ClickHouseClient;
|
|
103
|
+
/**
|
|
104
|
+
* Gets the ClickHouseSettings type from the loaded client module.
|
|
105
|
+
* Only available when using auto-detection (not manual injection).
|
|
106
|
+
*
|
|
107
|
+
* @returns The ClickHouseSettings type or an empty object if not available
|
|
108
|
+
*/
|
|
109
|
+
static getClickHouseSettings(): ClickHouseSettings;
|
|
135
110
|
}
|
|
111
|
+
export {};
|
|
136
112
|
//# sourceMappingURL=connection.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/core/connection.ts"],"names":[],"mappings":"AAAA,OAAO,
|
|
1
|
+
{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/core/connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,IAAI,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,KAAK,EAAE,gBAAgB,IAAI,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAwB,MAAM,iBAAiB,CAAC;AAI9E,KAAK,gBAAgB,GAAG,oBAAoB,GAAG,mBAAmB,CAAC;AA+CnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiC;IACxD,OAAO,CAAC,MAAM,CAAC,YAAY,CAAuC;IAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,oBAAoB;IAaxE;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,SAAS,IAAI,gBAAgB;IAOpC;;;;;OAKG;IACH,MAAM,CAAC,qBAAqB,IAAI,kBAAkB;CAGnD"}
|
package/dist/core/connection.js
CHANGED
|
@@ -1,12 +1,64 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { isClientConfig } from './query-builder';
|
|
2
|
+
// Function to synchronously get the appropriate client
|
|
3
|
+
function getClickHouseClientSync() {
|
|
4
|
+
const isDev = process.env.NODE_ENV === 'development';
|
|
5
|
+
const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
|
|
6
|
+
// In Node.js environment, use Node.js client only
|
|
7
|
+
if (isNode) {
|
|
8
|
+
try {
|
|
9
|
+
// eslint-disable-next-line @typescript-eslint/no-var-requires
|
|
10
|
+
const clientNode = require('@clickhouse/client');
|
|
11
|
+
if (isDev) {
|
|
12
|
+
console.log('hypequery: Using @clickhouse/client for Node.js environment');
|
|
13
|
+
}
|
|
14
|
+
return {
|
|
15
|
+
createClient: clientNode.createClient,
|
|
16
|
+
ClickHouseSettings: clientNode.ClickHouseSettings || {}
|
|
17
|
+
};
|
|
18
|
+
}
|
|
19
|
+
catch (error) {
|
|
20
|
+
throw new Error('@clickhouse/client is required for Node.js environments.\n\n' +
|
|
21
|
+
'Install with: npm install @clickhouse/client\n\n' +
|
|
22
|
+
'Alternatively, you can provide a client instance directly in the config.client option.');
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
// For browser environments, require() doesn't work, so we can't auto-detect
|
|
26
|
+
// Users must use manual injection in browser environments
|
|
27
|
+
throw new Error('Unable to auto-detect ClickHouse client in browser environment. ' +
|
|
28
|
+
'Please use manual injection by providing a client instance:\n\n' +
|
|
29
|
+
'```typescript\n' +
|
|
30
|
+
'import { createClient } from \'@clickhouse/client-web\';\n' +
|
|
31
|
+
'const client = createClient({ host: \'http://localhost:8123\' });\n' +
|
|
32
|
+
'ClickHouseConnection.initialize({ host: \'http://localhost:8123\', client });\n' +
|
|
33
|
+
'```\n\n' +
|
|
34
|
+
'This is required because browser environments cannot use require() to load modules.');
|
|
35
|
+
}
|
|
2
36
|
/**
|
|
3
37
|
* The main entry point for connecting to a ClickHouse database.
|
|
4
38
|
* Provides static methods to initialize the connection and retrieve the client.
|
|
5
39
|
*
|
|
40
|
+
* Supports two modes of operation:
|
|
41
|
+
* 1. **Manual injection**: Provide a client instance via `config.client` (required for browser environments)
|
|
42
|
+
* 2. **Auto-detection**: Automatically uses @clickhouse/client for Node.js environments
|
|
43
|
+
*
|
|
6
44
|
* @category Core
|
|
7
45
|
* @example
|
|
8
46
|
* ```typescript
|
|
9
|
-
* //
|
|
47
|
+
* // Method 1: Manual injection (required for browser environments)
|
|
48
|
+
* import { createClient } from '@clickhouse/client-web';
|
|
49
|
+
* const client = createClient({
|
|
50
|
+
* host: 'http://localhost:8123',
|
|
51
|
+
* username: 'default',
|
|
52
|
+
* password: 'password'
|
|
53
|
+
* });
|
|
54
|
+
*
|
|
55
|
+
* ClickHouseConnection.initialize({
|
|
56
|
+
* host: 'http://localhost:8123',
|
|
57
|
+
* database: 'my_database',
|
|
58
|
+
* client // Explicitly provide the client
|
|
59
|
+
* });
|
|
60
|
+
*
|
|
61
|
+
* // Method 2: Auto-detection (Node.js environments only)
|
|
10
62
|
* ClickHouseConnection.initialize({
|
|
11
63
|
* host: 'http://localhost:8123',
|
|
12
64
|
* username: 'default',
|
|
@@ -21,19 +73,36 @@ import { createClient } from '@clickhouse/client-web';
|
|
|
21
73
|
* format: 'JSONEachRow'
|
|
22
74
|
* });
|
|
23
75
|
* ```
|
|
76
|
+
*
|
|
77
|
+
* @note This library requires one of the following peer dependencies:
|
|
78
|
+
* - @clickhouse/client (for Node.js environments)
|
|
79
|
+
* - @clickhouse/client-web (for browser environments)
|
|
80
|
+
*
|
|
81
|
+
* **Important**: Browser environments require manual injection because `require()` calls don't work in browsers.
|
|
24
82
|
*/
|
|
25
83
|
export class ClickHouseConnection {
|
|
26
84
|
/**
|
|
27
85
|
* Initializes the ClickHouse connection with the provided configuration.
|
|
28
86
|
* This method must be called before any queries can be executed.
|
|
29
87
|
*
|
|
88
|
+
* **Priority order:**
|
|
89
|
+
* 1. If `config.client` is provided, use it directly (manual injection)
|
|
90
|
+
* 2. Otherwise, auto-detect @clickhouse/client for Node.js environments
|
|
91
|
+
*
|
|
92
|
+
* **Note**: Browser environments require manual injection because `require()` calls don't work in browsers.
|
|
93
|
+
*
|
|
30
94
|
* @param config - The connection configuration options
|
|
31
95
|
* @returns The ClickHouseConnection class for method chaining
|
|
32
|
-
* @throws Will throw an error if
|
|
96
|
+
* @throws Will throw an error if no ClickHouse client is available
|
|
33
97
|
*
|
|
34
98
|
* @example
|
|
35
99
|
* ```typescript
|
|
36
|
-
* //
|
|
100
|
+
* // Manual injection (required for browser environments)
|
|
101
|
+
* import { createClient } from '@clickhouse/client-web';
|
|
102
|
+
* const client = createClient({ host: 'http://localhost:8123' });
|
|
103
|
+
* ClickHouseConnection.initialize({ host: 'http://localhost:8123', client });
|
|
104
|
+
*
|
|
105
|
+
* // Auto-detection (Node.js environments only)
|
|
37
106
|
* ClickHouseConnection.initialize({
|
|
38
107
|
* host: 'http://localhost:8123',
|
|
39
108
|
* username: 'default',
|
|
@@ -43,29 +112,14 @@ export class ClickHouseConnection {
|
|
|
43
112
|
* ```
|
|
44
113
|
*/
|
|
45
114
|
static initialize(config) {
|
|
46
|
-
//
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
if (config.http_headers)
|
|
55
|
-
clientConfig.http_headers = config.http_headers;
|
|
56
|
-
if (config.request_timeout)
|
|
57
|
-
clientConfig.request_timeout = config.request_timeout;
|
|
58
|
-
if (config.compression)
|
|
59
|
-
clientConfig.compression = config.compression;
|
|
60
|
-
if (config.application)
|
|
61
|
-
clientConfig.application = config.application;
|
|
62
|
-
if (config.keep_alive)
|
|
63
|
-
clientConfig.keep_alive = config.keep_alive;
|
|
64
|
-
if (config.log)
|
|
65
|
-
clientConfig.log = config.log;
|
|
66
|
-
if (config.clickhouse_settings)
|
|
67
|
-
clientConfig.clickhouse_settings = config.clickhouse_settings;
|
|
68
|
-
this.instance = createClient(clientConfig);
|
|
115
|
+
// If a client is explicitly provided, use it directly
|
|
116
|
+
if (isClientConfig(config)) {
|
|
117
|
+
this.instance = config.client;
|
|
118
|
+
return ClickHouseConnection;
|
|
119
|
+
}
|
|
120
|
+
// Otherwise, auto-detect the client (we know we have a host-based config)
|
|
121
|
+
this.clientModule = getClickHouseClientSync();
|
|
122
|
+
this.instance = this.clientModule.createClient(config);
|
|
69
123
|
return ClickHouseConnection;
|
|
70
124
|
}
|
|
71
125
|
/**
|
|
@@ -85,8 +139,19 @@ export class ClickHouseConnection {
|
|
|
85
139
|
*/
|
|
86
140
|
static getClient() {
|
|
87
141
|
if (!this.instance) {
|
|
88
|
-
throw new Error('ClickHouse connection not initialized');
|
|
142
|
+
throw new Error('ClickHouse connection not initialized. Call ClickHouseConnection.initialize() first.');
|
|
89
143
|
}
|
|
90
144
|
return this.instance;
|
|
91
145
|
}
|
|
146
|
+
/**
|
|
147
|
+
* Gets the ClickHouseSettings type from the loaded client module.
|
|
148
|
+
* Only available when using auto-detection (not manual injection).
|
|
149
|
+
*
|
|
150
|
+
* @returns The ClickHouseSettings type or an empty object if not available
|
|
151
|
+
*/
|
|
152
|
+
static getClickHouseSettings() {
|
|
153
|
+
return this.clientModule?.ClickHouseSettings || {};
|
|
154
|
+
}
|
|
92
155
|
}
|
|
156
|
+
ClickHouseConnection.instance = null;
|
|
157
|
+
ClickHouseConnection.clientModule = null;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { QueryBuilder } from '../query-builder';
|
|
2
2
|
import { ColumnType, TableColumn } from '../../types';
|
|
3
|
-
import { ClickHouseSettings } from '@clickhouse/client-
|
|
3
|
+
import { ClickHouseSettings } from '@clickhouse/client-common';
|
|
4
4
|
export declare class AnalyticsFeature<Schema extends {
|
|
5
5
|
[tableName: string]: {
|
|
6
6
|
[columnName: string]: ColumnType;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../../src/core/features/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,
|
|
1
|
+
{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../../src/core/features/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAE9D,qBAAa,gBAAgB,CAC3B,MAAM,SAAS;IAAE,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAA;CAAE,EAC5E,CAAC,EACD,SAAS,SAAS,OAAO,GAAG,KAAK,EACjC,YAAY,GAAG,EAAE,EACjB,SAAS,GAAG,CAAC;IAED,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC;IAExF,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM;;;;;;;;;;;;;;;;;;IAS/D,eAAe,CACb,MAAM,EAAE,MAAM,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,EACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,eAAe;;;;;;;;;;;;;;;;;;IAiBhK,WAAW,CAAC,IAAI,EAAE,kBAAkB;;;;;;;;;;;;;;;;;;CAQrC"}
|
|
@@ -1,9 +1,39 @@
|
|
|
1
1
|
import { CrossFilter } from './cross-filter';
|
|
2
2
|
import { ColumnType, FilterOperator, OrderDirection, TableColumn, AggregationType, QueryConfig, OperatorValueMap, InferColumnType, PaginationOptions, PaginatedResult } from '../types';
|
|
3
|
-
import { ClickHouseSettings } from '@clickhouse/client-web';
|
|
4
3
|
import { SQLFormatter } from './formatters/sql-formatter';
|
|
5
4
|
import { JoinRelationships, JoinPathOptions } from './join-relationships';
|
|
6
5
|
import { SqlExpression } from './utils/sql-expressions';
|
|
6
|
+
import type { ClickHouseSettings, BaseClickHouseClientConfigOptions } from '@clickhouse/client-common';
|
|
7
|
+
import type { ClickHouseClient as NodeClickHouseClient } from '@clickhouse/client';
|
|
8
|
+
import type { ClickHouseClient as WebClickHouseClient } from '@clickhouse/client-web';
|
|
9
|
+
type ClickHouseClient = NodeClickHouseClient | WebClickHouseClient;
|
|
10
|
+
/**
|
|
11
|
+
* Configuration for host-based connections.
|
|
12
|
+
*/
|
|
13
|
+
export interface ClickHouseHostConfig extends BaseClickHouseClientConfigOptions {
|
|
14
|
+
/** The ClickHouse server host URL. */
|
|
15
|
+
host: string;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Configuration for client-based connections.
|
|
19
|
+
*/
|
|
20
|
+
export interface ClickHouseClientConfig extends BaseClickHouseClientConfigOptions {
|
|
21
|
+
/** Pre-configured ClickHouse client instance. */
|
|
22
|
+
client: ClickHouseClient;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Configuration options for ClickHouse connections.
|
|
26
|
+
* Either provide a client instance OR connection details, but not both.
|
|
27
|
+
*/
|
|
28
|
+
export type ClickHouseConfig = ClickHouseHostConfig | ClickHouseClientConfig;
|
|
29
|
+
/**
|
|
30
|
+
* Type guard to check if a config is a host-based configuration.
|
|
31
|
+
*/
|
|
32
|
+
export declare function isHostConfig(config: ClickHouseConfig): config is ClickHouseHostConfig;
|
|
33
|
+
/**
|
|
34
|
+
* Type guard to check if a config is a client-based configuration.
|
|
35
|
+
*/
|
|
36
|
+
export declare function isClientConfig(config: ClickHouseConfig): config is ClickHouseClientConfig;
|
|
7
37
|
/**
|
|
8
38
|
* A type-safe query builder for ClickHouse databases.
|
|
9
39
|
* @template Schema - The full database schema
|
|
@@ -199,24 +229,8 @@ export declare function createQueryBuilder<Schema extends {
|
|
|
199
229
|
[K in keyof Schema]: {
|
|
200
230
|
[columnName: string]: ColumnType;
|
|
201
231
|
};
|
|
202
|
-
}>(config: {
|
|
203
|
-
host: string;
|
|
204
|
-
username?: string;
|
|
205
|
-
password?: string;
|
|
206
|
-
database?: string;
|
|
207
|
-
http_headers?: Record<string, string>;
|
|
208
|
-
request_timeout?: number;
|
|
209
|
-
compression?: {
|
|
210
|
-
response?: boolean;
|
|
211
|
-
request?: boolean;
|
|
212
|
-
};
|
|
213
|
-
application?: string;
|
|
214
|
-
keep_alive?: {
|
|
215
|
-
enabled: boolean;
|
|
216
|
-
};
|
|
217
|
-
log?: any;
|
|
218
|
-
clickhouse_settings?: ClickHouseSettings;
|
|
219
|
-
}): {
|
|
232
|
+
}>(config: ClickHouseConfig): {
|
|
220
233
|
table<TableName extends keyof Schema>(tableName: TableName): QueryBuilder<Schema, Schema[TableName], false, {}>;
|
|
221
234
|
};
|
|
235
|
+
export {};
|
|
222
236
|
//# sourceMappingURL=query-builder.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../../src/core/query-builder.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EACL,UAAU,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,eAAe,EAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,kBAAkB,EAAE,MAAM,
|
|
1
|
+
{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../../src/core/query-builder.ts"],"names":[],"mappings":"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"}
|
|
@@ -9,6 +9,18 @@ import { QueryModifiersFeature } from './features/query-modifiers';
|
|
|
9
9
|
import { FilterValidator } from './validators/filter-validator';
|
|
10
10
|
import { PaginationFeature } from './features/pagination';
|
|
11
11
|
import { CrossFilteringFeature } from './features/cross-filtering';
|
|
12
|
+
/**
|
|
13
|
+
* Type guard to check if a config is a host-based configuration.
|
|
14
|
+
*/
|
|
15
|
+
export function isHostConfig(config) {
|
|
16
|
+
return 'host' in config && !('client' in config);
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Type guard to check if a config is a client-based configuration.
|
|
20
|
+
*/
|
|
21
|
+
export function isClientConfig(config) {
|
|
22
|
+
return 'client' in config && !('host' in config);
|
|
23
|
+
}
|
|
12
24
|
/**
|
|
13
25
|
* A type-safe query builder for ClickHouse databases.
|
|
14
26
|
* @template Schema - The full database schema
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
export declare const initializeTestConnection: () => Promise<{
|
|
2
2
|
table<TableName extends never>(tableName: TableName): import("../../query-builder").QueryBuilder<{}, {}[TableName], false, {}, {}[TableName]>;
|
|
3
3
|
}>;
|
|
4
|
-
export declare const ensureConnectionInitialized: () => import("@clickhouse/client-web
|
|
4
|
+
export declare const ensureConnectionInitialized: () => import("@clickhouse/client").ClickHouseClient | import("@clickhouse/client-web").ClickHouseClient;
|
|
5
5
|
export declare const isDockerAvailable: () => Promise<boolean>;
|
|
6
6
|
export declare const isDockerComposeAvailable: () => Promise<boolean>;
|
|
7
7
|
export declare const isContainerRunning: (containerName: string) => Promise<boolean>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/core/tests/integration/setup.ts"],"names":[],"mappings":"AA6CA,eAAO,MAAM,wBAAwB;;EAyBpC,CAAC;AAGF,eAAO,MAAM,2BAA2B,
|
|
1
|
+
{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/core/tests/integration/setup.ts"],"names":[],"mappings":"AA6CA,eAAO,MAAM,wBAAwB;;EAyBpC,CAAC;AAGF,eAAO,MAAM,2BAA2B,yGAevC,CAAC;AAGF,eAAO,MAAM,iBAAiB,QAAa,OAAO,CAAC,OAAO,CAOzD,CAAC;AAGF,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,OAAO,CAahE,CAAC;AAGF,eAAO,MAAM,kBAAkB,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,OAAO,CAO/E,CAAC;AAGF,eAAO,MAAM,iBAAiB,QAAa,OAAO,CAAC,OAAO,CAQzD,CAAC;AAGF,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,IAAI,CAwC7D,CAAC;AAGF,eAAO,MAAM,iBAAiB,GAC5B,oBAAgB,EAChB,sBAAoB,KACnB,OAAO,CAAC,IAAI,CAad,CAAC;AAGF,eAAO,MAAM,uBAAuB,QAAa,OAAO,CAAC,IAAI,CA0B5D,CAAC;AAGF,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,KAAK,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,MAAM,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ;AAGD,eAAO,MAAM,SAAS,EAAE,cAoBvB,CAAC;AAGF,eAAO,MAAM,iBAAiB,QAAa,OAAO,CAAC,IAAI,CAuFtD,CAAC"}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
export { createQueryBuilder } from './core/query-builder.js';
|
|
2
2
|
export { ClickHouseConnection } from './core/connection.js';
|
|
3
3
|
export { JoinRelationships } from './core/join-relationships.js';
|
|
4
|
+
export type { ClickHouseConfig, ClickHouseHostConfig, ClickHouseClientConfig } from './core/query-builder.js';
|
|
5
|
+
export { isHostConfig, isClientConfig } from './core/query-builder.js';
|
|
4
6
|
export type { TableSchema, QueryConfig, ColumnType, WhereExpression, GroupByExpression, TableRecord, DatabaseSchema, PaginatedResult, PageInfo, PaginationOptions } from './types/base';
|
|
5
7
|
export type { JoinPath, JoinPathOptions } from './core/join-relationships.js';
|
|
6
8
|
export { CrossFilter } from './core/cross-filter.js';
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,YAAY,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,eAAe,EACf,QAAQ,EACR,iBAAiB,EAClB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EACL,GAAG,EACH,KAAK,EACL,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,qBAAqB,EACtB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,aAAa,EACb,iBAAiB,EAClB,MAAM,iCAAiC,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACvE,YAAY,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,eAAe,EACf,QAAQ,EACR,iBAAiB,EAClB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EACL,GAAG,EACH,KAAK,EACL,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,qBAAqB,EACtB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,aAAa,EACb,iBAAiB,EAClB,MAAM,iCAAiC,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hypequery/clickhouse",
|
|
3
|
-
"version": "1.0
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "ClickHouse typescript query builder",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"types": "dist/index.d.ts",
|
|
@@ -35,11 +35,25 @@
|
|
|
35
35
|
"README-CLI.md"
|
|
36
36
|
],
|
|
37
37
|
"dependencies": {
|
|
38
|
-
"@clickhouse/client-web": "^0.2.0",
|
|
39
38
|
"dotenv": "^16.0.0"
|
|
40
39
|
},
|
|
40
|
+
"peerDependencies": {
|
|
41
|
+
"@clickhouse/client": "^0.2.0 || ^1.0.0",
|
|
42
|
+
"@clickhouse/client-web": "^0.2.0 || ^1.0.0"
|
|
43
|
+
},
|
|
44
|
+
"peerDependenciesMeta": {
|
|
45
|
+
"@clickhouse/client": {
|
|
46
|
+
"optional": true
|
|
47
|
+
},
|
|
48
|
+
"@clickhouse/client-web": {
|
|
49
|
+
"optional": true
|
|
50
|
+
}
|
|
51
|
+
},
|
|
41
52
|
"devDependencies": {
|
|
42
53
|
"@babel/plugin-transform-modules-commonjs": "^7.26.3",
|
|
54
|
+
"@clickhouse/client": "^1.11.2",
|
|
55
|
+
"@clickhouse/client-common": "^1.11.2",
|
|
56
|
+
"@clickhouse/client-web": "^1.11.2",
|
|
43
57
|
"@semantic-release/changelog": "^6.0.3",
|
|
44
58
|
"@semantic-release/commit-analyzer": "^11.1.0",
|
|
45
59
|
"@semantic-release/git": "^10.0.1",
|
package/README.md
DELETED
|
@@ -1,279 +0,0 @@
|
|
|
1
|
-
# hypequery
|
|
2
|
-
|
|
3
|
-
<div align="center">
|
|
4
|
-
<img src="https://hypequery.dev/img/logo.svg" alt="hypequery Logo" width="200"/>
|
|
5
|
-
<h1>@hypequery/clickhouse</h1>
|
|
6
|
-
<p>A typescript-first library for building type-safe dashboards with ClickHouse</p>
|
|
7
|
-
|
|
8
|
-
[](https://github.com/lukejreilly/hypequery/blob/main/LICENSE)
|
|
9
|
-
[](https://badge.fury.io/js/@hypequery%2Fcore)
|
|
10
|
-
[](https://github.com/lukejreilly/hypequery/stargazers)
|
|
11
|
-
</div>
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
## Overview
|
|
15
|
-
|
|
16
|
-
hypequery is a typescript-first query builder for ClickHouse designed specifically for building real-time, type-safe analytics dashboards. Unlike generic SQL query builders, hypequery understands your ClickHouse schema and provides full type checking throughout your codebase, making it ideal for data-intensive applications.
|
|
17
|
-
|
|
18
|
-
## Features
|
|
19
|
-
|
|
20
|
-
- 🎯 **Type-Safe**: Full TypeScript support with inferred types from your ClickHouse schema
|
|
21
|
-
- 🚀 **Performant**: Built for real-time analytics with optimized query generation
|
|
22
|
-
- 🔍 **Cross Filtering**: Powerful cross-filtering capabilities for interactive dashboards
|
|
23
|
-
- 📊 **Dashboard Ready**: Built-in support for pagination, sorting, and filtering
|
|
24
|
-
- 🛠️ **Developer Friendly**: Fluent API design for an intuitive development experience
|
|
25
|
-
- 📱 **Platform Agnostic**: Works in both Node.js and browser environments
|
|
26
|
-
- 🔄 **Schema Generation**: CLI tool to generate TypeScript types from your ClickHouse schema
|
|
27
|
-
|
|
28
|
-
## Installation
|
|
29
|
-
|
|
30
|
-
### npm
|
|
31
|
-
```bash
|
|
32
|
-
npm install @hypequery/clickhouse
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
### yarn
|
|
36
|
-
```bash
|
|
37
|
-
yarn add @hypequery/clickhouse
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
### pnpm
|
|
41
|
-
```bash
|
|
42
|
-
pnpm add @hypequery/clickhouse
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
## Quick Start
|
|
46
|
-
|
|
47
|
-
```typescript
|
|
48
|
-
import { createQueryBuilder } from '@hypequery/clickhouse';
|
|
49
|
-
import type { Schema } from './generated-schema';
|
|
50
|
-
|
|
51
|
-
// Initialize the query builder
|
|
52
|
-
const db = createQueryBuilder<Schema>({
|
|
53
|
-
host: 'your-clickhouse-host',
|
|
54
|
-
username: 'default',
|
|
55
|
-
password: '',
|
|
56
|
-
database: 'default'
|
|
57
|
-
});
|
|
58
|
-
|
|
59
|
-
// Build and execute a query
|
|
60
|
-
const results = await db
|
|
61
|
-
.table('trips')
|
|
62
|
-
.select(['pickup_datetime', 'dropoff_datetime', 'total_amount'])
|
|
63
|
-
.where('total_amount', '>', 50)
|
|
64
|
-
.orderBy('pickup_datetime', 'DESC')
|
|
65
|
-
.limit(10)
|
|
66
|
-
.execute();
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
## Schema Generation
|
|
70
|
-
|
|
71
|
-
hypequery provides a CLI tool to generate TypeScript types from your ClickHouse schema:
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
# Install globally (optional)
|
|
75
|
-
npm install -g @hypequery/clickhouse
|
|
76
|
-
|
|
77
|
-
# Generate schema types
|
|
78
|
-
npx hypequery-generate --host your-clickhouse-host --database your-database
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
This creates a `generated-schema.ts` file that you can import in your application:
|
|
82
|
-
|
|
83
|
-
```typescript
|
|
84
|
-
import { createQueryBuilder } from '@hypequery/clickhouse';
|
|
85
|
-
import type { IntrospectedSchema } from './generated-schema';
|
|
86
|
-
|
|
87
|
-
const db = createQueryBuilder<IntrospectedSchema>({
|
|
88
|
-
// connection details
|
|
89
|
-
});
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
## Core Features
|
|
93
|
-
|
|
94
|
-
### Type-Safe Queries
|
|
95
|
-
|
|
96
|
-
hypequery provides full TypeScript support, ensuring your queries are type-safe:
|
|
97
|
-
|
|
98
|
-
```typescript
|
|
99
|
-
// Column names are type-checked
|
|
100
|
-
const query = db.table('trips')
|
|
101
|
-
.select(['pickup_datetime', 'total_amount'])
|
|
102
|
-
.where('total_amount', '>', 50)
|
|
103
|
-
.execute();
|
|
104
|
-
|
|
105
|
-
// Type error if column doesn't exist
|
|
106
|
-
db.table('trips').select(['non_existent_column']); // TypeScript error
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
### Cross Filtering
|
|
110
|
-
|
|
111
|
-
Implement interactive dashboards with cross-filtering support:
|
|
112
|
-
|
|
113
|
-
```typescript
|
|
114
|
-
import { CrossFilter } from '@hypequery/clickhouse';
|
|
115
|
-
|
|
116
|
-
// Create a filter
|
|
117
|
-
const filter = new CrossFilter()
|
|
118
|
-
.add({
|
|
119
|
-
column: 'pickup_datetime',
|
|
120
|
-
operator: 'gte',
|
|
121
|
-
value: '2024-01-01'
|
|
122
|
-
})
|
|
123
|
-
.add({
|
|
124
|
-
column: 'total_amount',
|
|
125
|
-
operator: 'gt',
|
|
126
|
-
value: 20
|
|
127
|
-
});
|
|
128
|
-
|
|
129
|
-
// Apply to multiple queries
|
|
130
|
-
const query1 = db.table('trips')
|
|
131
|
-
.applyCrossFilters(filter)
|
|
132
|
-
.execute();
|
|
133
|
-
|
|
134
|
-
const query2 = db.table('drivers')
|
|
135
|
-
.applyCrossFilters(filter)
|
|
136
|
-
.execute();
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
### Pagination
|
|
140
|
-
|
|
141
|
-
Built-in cursor-based pagination for efficient data loading:
|
|
142
|
-
|
|
143
|
-
```typescript
|
|
144
|
-
// First page
|
|
145
|
-
const firstPage = await db.table('trips')
|
|
146
|
-
.select(['pickup_datetime', 'total_amount'])
|
|
147
|
-
.orderBy('pickup_datetime', 'DESC')
|
|
148
|
-
.paginate({
|
|
149
|
-
pageSize: 10
|
|
150
|
-
});
|
|
151
|
-
|
|
152
|
-
// Next page
|
|
153
|
-
const nextPage = await db.table('trips')
|
|
154
|
-
.select(['pickup_datetime', 'total_amount'])
|
|
155
|
-
.orderBy('pickup_datetime', 'DESC')
|
|
156
|
-
.paginate({
|
|
157
|
-
pageSize: 10,
|
|
158
|
-
after: firstPage.pageInfo.endCursor
|
|
159
|
-
});
|
|
160
|
-
|
|
161
|
-
// Previous page
|
|
162
|
-
const prevPage = await db.table('trips')
|
|
163
|
-
.select(['pickup_datetime', 'total_amount'])
|
|
164
|
-
.orderBy('pickup_datetime', 'DESC')
|
|
165
|
-
.paginate({
|
|
166
|
-
pageSize: 10,
|
|
167
|
-
before: nextPage.pageInfo.startCursor
|
|
168
|
-
});
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
### Advanced Queries
|
|
172
|
-
|
|
173
|
-
hypequery supports complex queries including joins, aggregations, and subqueries:
|
|
174
|
-
|
|
175
|
-
```typescript
|
|
176
|
-
// Aggregations
|
|
177
|
-
const stats = await db.table('trips')
|
|
178
|
-
.avg('total_amount')
|
|
179
|
-
.max('trip_distance')
|
|
180
|
-
.count('trip_id')
|
|
181
|
-
.where('pickup_datetime', '>=', '2024-01-01')
|
|
182
|
-
.execute();
|
|
183
|
-
|
|
184
|
-
// Joins
|
|
185
|
-
const tripsWithDrivers = await db.table('trips')
|
|
186
|
-
.select(['trips.trip_id', 'trips.total_amount', 'drivers.name'])
|
|
187
|
-
.join('drivers', 'trips.driver_id', '=', 'drivers.id')
|
|
188
|
-
.execute();
|
|
189
|
-
|
|
190
|
-
// Raw SQL when needed
|
|
191
|
-
const customQuery = await db.table('trips')
|
|
192
|
-
.select([
|
|
193
|
-
db.raw('toStartOfDay(pickup_datetime) as day'),
|
|
194
|
-
'count() as trip_count'
|
|
195
|
-
])
|
|
196
|
-
.groupBy(db.raw('toStartOfDay(pickup_datetime)'))
|
|
197
|
-
.execute();
|
|
198
|
-
```
|
|
199
|
-
|
|
200
|
-
## Environment Support
|
|
201
|
-
|
|
202
|
-
### Browser Environment
|
|
203
|
-
|
|
204
|
-
For browser usage, you'll typically need to set up a proxy server to avoid CORS issues:
|
|
205
|
-
|
|
206
|
-
```typescript
|
|
207
|
-
const db = createQueryBuilder<Schema>({
|
|
208
|
-
host: '/api/clickhouse', // Proxy through your API route
|
|
209
|
-
username: 'default',
|
|
210
|
-
password: '',
|
|
211
|
-
database: 'default'
|
|
212
|
-
});
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
### Node.js Environment
|
|
216
|
-
|
|
217
|
-
For server-side applications, you can connect directly to ClickHouse:
|
|
218
|
-
|
|
219
|
-
```typescript
|
|
220
|
-
const db = createQueryBuilder<Schema>({
|
|
221
|
-
host: 'http://your-clickhouse-server:8123',
|
|
222
|
-
username: 'default',
|
|
223
|
-
password: 'your-password',
|
|
224
|
-
database: 'default'
|
|
225
|
-
});
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
## Versioning and Release Channels
|
|
229
|
-
|
|
230
|
-
hypequery follows semantic versioning and provides multiple release channels:
|
|
231
|
-
|
|
232
|
-
- **Latest**: Stable releases (`npm install @hypequery/clickhouse`)
|
|
233
|
-
- **Beta**: Pre-release versions (`npm install @hypequery/clickhouse@beta`)
|
|
234
|
-
|
|
235
|
-
## Documentation
|
|
236
|
-
|
|
237
|
-
For detailed documentation and examples, visit our [documentation site](https://hypequery.dev/docs).
|
|
238
|
-
|
|
239
|
-
- [Getting Started](https://hypequery.dev/docs/installation)
|
|
240
|
-
- [Query Building](https://hypequery.dev/docs/guides/query-building)
|
|
241
|
-
- [Filtering](https://hypequery.dev/docs/guides/filtering)
|
|
242
|
-
- [Pagination](https://hypequery.dev/docs/features/pagination)
|
|
243
|
-
- [API Reference](https://hypequery.dev/docs/reference/api)
|
|
244
|
-
|
|
245
|
-
## Examples
|
|
246
|
-
|
|
247
|
-
Check out our example implementations:
|
|
248
|
-
|
|
249
|
-
- [Example Dashboard](https://github.com/lukejreilly/hypequery/tree/main/examples/example-dashboard): A complete Next.js dashboard with hypequery
|
|
250
|
-
- [React Query Integration](https://hypequery.dev/docs/guides/integrations/react-query): Using hypequery with React Query
|
|
251
|
-
- [Time Series Analysis](https://hypequery.dev/docs/guides/timeseries): Building time series analytics
|
|
252
|
-
|
|
253
|
-
## Troubleshooting
|
|
254
|
-
|
|
255
|
-
### Common Issues
|
|
256
|
-
|
|
257
|
-
- **Connection Errors**: Ensure your ClickHouse server is running and accessible
|
|
258
|
-
- **CORS Issues**: Use a proxy server for browser environments
|
|
259
|
-
- **Type Errors**: Make sure to regenerate your schema types after schema changes
|
|
260
|
-
|
|
261
|
-
## Contributing
|
|
262
|
-
|
|
263
|
-
We welcome contributions! Please see our [contributing guide](CONTRIBUTING.md) for details.
|
|
264
|
-
|
|
265
|
-
## License
|
|
266
|
-
|
|
267
|
-
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
268
|
-
|
|
269
|
-
## Support
|
|
270
|
-
|
|
271
|
-
- 📚 [Documentation](https://hypequery.dev/docs)
|
|
272
|
-
- 🐛 [Issue Tracker](https://github.com/lukejreilly/hypequery/issues)
|
|
273
|
-
- 💬 [Discussions](https://github.com/lukejreilly/hypequery/discussions)
|
|
274
|
-
|
|
275
|
-
---
|
|
276
|
-
|
|
277
|
-
<div align="center">
|
|
278
|
-
<sub>Built with ❤️ by the hypequery team</sub>
|
|
279
|
-
</div>
|