Skip to content

Commit a04468a

Browse files
mshustovmshustov
authored
Merge pull request #2765 from ClickHouse/1.8.0-js-update
Update the JS docs for 1.8.0
2 parents e1b60ad + 4cca713 commit a04468a

File tree

1 file changed

+46
-34
lines changed
  • docs/en/integrations/language-clients

1 file changed

+46
-34
lines changed

‎docs/en/integrations/language-clients/js.md

+46-34
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ npm i @clickhouse/client-web
6060

6161
| Client version | ClickHouse |
6262
|----------------|------------|
63-
| 1.5.0 | 23.3+ |
63+
| 1.8.0 | 23.3+ |
6464

6565
Likely, the client will work with the older versions, too; however, this is best-effort support and is not guaranteed. If you have ClickHouse version older than 23.3, please refer to [ClickHouse security policy](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md) and consider upgrading.
6666

@@ -117,6 +117,7 @@ When creating a client instance, the following connection settings can be adjust
117117
- **session_id?: string** - optional ClickHouse Session ID to send with every request.
118118
- **keep_alive?: { enabled?: boolean }** - enabled by default in both Node.js and Web versions.
119119
- **http_headers?: Record<string, string>** - additional HTTP headers for outgoing ClickHouse requests. See also: [Reverse proxy with authentication docs](./js.md#reverse-proxy-with-authentication)
120+
- **roles?: string | string[]** - ClickHouse role name(s) to attach to the outgoing requests. See also: [Using roles with the HTTP interface](https://clickhouse.com/docs/en/interfaces/http#setting-role-with-query-parameters)
120121

121122
#### Node.js-specific configuration parameters
122123

@@ -135,7 +136,7 @@ URL configuration will _always_ overwrite the hardcoded values and a warning wil
135136
It is possible to configure most of the client instance parameters with a URL. The URL format is `http[s]://[username:password@]hostname:port[/database][?param1=value1&param2=value2]`. In almost every case, the name of a particular parameter reflects its path in the config options interface, with a few exceptions. The following parameters are supported:
136137

137138
| Parameter | Type |
138-
| ------------------------------------------- | ----------------------------------------------------------------- |
139+
|---------------------------------------------|-------------------------------------------------------------------|
139140
| `pathname` | an arbitrary string. |
140141
| `application_id` | an arbitrary string. |
141142
| `session_id` | an arbitrary string. |
@@ -184,7 +185,7 @@ createClient({
184185

185186
The client implements a connection via HTTP(s) protocol. RowBinary support is on track, see the [related issue](https://github.com/ClickHouse/clickhouse-js/issues/216).
186187

187-
The following example demonstrates how to set up a connection against ClickHouse Cloud. It assumes `host` (including
188+
The following example demonstrates how to set up a connection against ClickHouse Cloud. It assumes `url` (including
188189
protocol and port) and `password` values are specified via environment variables, and `default` user is used.
189190

190191
**Example:** Creating a Node.js Client instance using environment variables for configuration.
@@ -193,7 +194,7 @@ protocol and port) and `password` values are specified via environment variables
193194
import { createClient } from '@clickhouse/client'
194195

195196
const client = createClient({
196-
host: process.env.CLICKHOUSE_HOST ?? 'http://localhost:8123',
197+
url: process.env.CLICKHOUSE_HOST ?? 'http://localhost:8123',
197198
username: process.env.CLICKHOUSE_USER ?? 'default',
198199
password: process.env.CLICKHOUSE_PASSWORD ?? '',
199200
})
@@ -236,6 +237,8 @@ interface BaseQueryParams {
236237
session_id?: string
237238
// credentials override; if not specified, the client's credentials will be used.
238239
auth?: { username: string, password: string }
240+
// A specific list of roles to use for this query. Overrides the roles set in the client configuration.
241+
role?: string | Array<string>
239242
}
240243
```
241244

@@ -752,6 +755,7 @@ It's only that formats like [ClickHouse JSON](https://clickhouse.com/docs/en/sql
752755
| JSONStrings | ❌ | ❌️ | ❌ | ✔️ | ✔️ |
753756
| JSONCompactStrings | ❌ | ❌ | ❌ | ✔️ | ✔️ |
754757
| JSONEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
758+
| JSONEachRowWithProgress | ❌️ | ❌ | ✔️ ❗- see below | ✔️ | ✔️ |
755759
| JSONStringsEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
756760
| JSONCompactEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
757761
| JSONCompactStringsEachRow | ✔️ | ❌ | ✔️ | ✔️ | ✔️ |
@@ -773,39 +777,47 @@ It's only that formats like [ClickHouse JSON](https://clickhouse.com/docs/en/sql
773777

774778
For Parquet, the main use case for selects likely will be writing the resulting stream into a file. See [the example](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/select_parquet_as_file.ts) in the client repository.
775779

780+
`JSONEachRowWithProgress` is an output-only format that supports progress reporting in the stream. See [this example](https://github.com/ClickHouse/clickhouse-js/blob/main/examples/node/select_json_each_row_with_progress.ts) for more details.
781+
776782
The entire list of ClickHouse input and output formats is available
777783
[here](https://clickhouse.com/docs/en/interfaces/formats).
778784

779785
## Supported ClickHouse data types
780786

781-
| Type | Status | JS type |
782-
|----------------|----------------|-----------------------|
783-
| UInt8/16/32 | ✔️ | number |
784-
| UInt64/128/256 | ✔️❗- see below | string |
785-
| Int8/16/32 | ✔️ | number |
786-
| Int64/128/256 | ✔️❗- see below | string |
787-
| Float32/64 | ✔️ | number |
788-
| Decimal | ✔️❗- see below | number |
789-
| Boolean | ✔️ | boolean |
790-
| String | ✔️ | string |
791-
| FixedString | ✔️ | string |
792-
| UUID | ✔️ | string |
793-
| Date32/64 | ✔️ | string |
794-
| DateTime32/64 | ✔️❗- see below | string |
795-
| Enum | ✔️ | string |
796-
| LowCardinality | ✔️ | string |
797-
| Array(T) | ✔️ | T[] |
798-
| JSON | ✔️ | object |
799-
| Nested | ✔️ | T[] |
800-
| Tuple | ✔️ | Tuple |
801-
| Nullable(T) | ✔️ | JS type for T or null |
802-
| IPv4 | ✔️ | string |
803-
| IPv6 | ✔️ | string |
804-
| Point | ✔️ | [ number, number ] |
805-
| Ring | ✔️ | Array<Point\> |
806-
| Polygon | ✔️ | Array<Ring\> |
807-
| MultiPolygon | ✔️ | Array<Polygon\> |
808-
| Map(K, V) | ✔️ | Record<K, V\> |
787+
:::note
788+
The related JS type is relevant for any `JSON*` formats except the ones that represent everything as a string (e.g. `JSONStringEachRow`)
789+
:::
790+
791+
| Type | Status | JS type |
792+
|--------------------|-----------------|----------------------------|
793+
| UInt8/16/32 | ✔️ | number |
794+
| UInt64/128/256 | ✔️ ❗- see below | string |
795+
| Int8/16/32 | ✔️ | number |
796+
| Int64/128/256 | ✔️ ❗- see below | string |
797+
| Float32/64 | ✔️ | number |
798+
| Decimal | ✔️ ❗- see below | number |
799+
| Boolean | ✔️ | boolean |
800+
| String | ✔️ | string |
801+
| FixedString | ✔️ | string |
802+
| UUID | ✔️ | string |
803+
| Date32/64 | ✔️ | string |
804+
| DateTime32/64 | ✔️ ❗- see below | string |
805+
| Enum | ✔️ | string |
806+
| LowCardinality | ✔️ | string |
807+
| Array(T) | ✔️ | T[] |
808+
| (new) JSON | ✔️ | object |
809+
| Variant(T1, T2...) | ✔️ | T (depends on the variant) |
810+
| Dynamic | ✔️ | T (depends on the variant) |
811+
| Nested | ✔️ | T[] |
812+
| Tuple | ✔️ | Tuple |
813+
| Nullable(T) | ✔️ | JS type for T or null |
814+
| IPv4 | ✔️ | string |
815+
| IPv6 | ✔️ | string |
816+
| Point | ✔️ | [ number, number ] |
817+
| Ring | ✔️ | Array<Point\> |
818+
| Polygon | ✔️ | Array<Ring\> |
819+
| MultiPolygon | ✔️ | Array<Polygon\> |
820+
| Map(K, V) | ✔️ | Record<K, V\> |
809821

810822
The entire list of supported ClickHouse formats is available
811823
[here](https://clickhouse.com/docs/en/sql-reference/data-types/).
@@ -1060,7 +1072,7 @@ and CA file name is `CA.pem`:
10601072

10611073
```ts
10621074
const client = createClient({
1063-
host: 'https://<hostname>:<port>',
1075+
url: 'https://<hostname>:<port>',
10641076
username: '<username>',
10651077
password: '<password>', // if required
10661078
tls: {
@@ -1073,7 +1085,7 @@ Mutual TLS configuration example using client certificates:
10731085

10741086
```ts
10751087
const client = createClient({
1076-
host: 'https://<hostname>:<port>',
1088+
url: 'https://<hostname>:<port>',
10771089
username: '<username>',
10781090
tls: {
10791091
ca_cert: fs.readFileSync('certs/CA.pem'),

0 commit comments

Comments
 (0)