Skip to content
This repository was archived by the owner on Jul 26, 2023. It is now read-only.

Commit 0a3865a

Browse files
Time-HuTime-Hu
authored
minor fixes & add section about cli connection (#256)
1 parent 227098a commit 0a3865a

File tree

5 files changed

+145
-51
lines changed

5 files changed

+145
-51
lines changed

‎docs/en/guides/stream.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ To get all streams in HStreamDB:
120120
```
121121

122122
:::
123-
s
123+
124124
::: tab Go
125125

126126
```go

‎docs/en/reference/cli.md

+41-11
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,39 @@ Available commands:
4545
subscription Manage Subscriptions in HStreamDB
4646
```
4747

48+
## Connection
49+
50+
### HStream URL
51+
52+
The HStream CLI Client supports connecting to the server cluster with a url in
53+
the following format:
54+
55+
```
56+
<scheme>://<endpoint>:<port>
57+
```
58+
59+
｜Components| Description | Required |
60+
｜-｜-｜-|
61+
| `<scheme>` | The scheme of the connection. Currently, we have `hstream`. To enable security options, `hstreams` is also supported | Yes |
62+
| `<endpoint>` | The endpoint of the server cluster, which can be the hostname or address of the server cluster. | |
63+
| `<port>` | The port of the server cluster. | If not given, the value will be set to the default 6570 |
64+
65+
### Connection Parameters
66+
67+
HStream commands accept connection parameters as separate command-line flags, in addition (or in replacement) to `--service-url`.
68+
69+
::: tip
70+
In the cases where both `--service-url` and the options below are specified, the client will use the value in `--service-url`.
71+
:::
72+
73+
| Option | Description |
74+
|-|-|
75+
| `--host` | The server host and port number to connect to. This can be the address of any node in the cluster. Default: `127.0.0.1` |
76+
| `--port` | The server port to connect to. Default: `6570`|
77+
4878
### Security Settings (optional)
4979

50-
If [security option](../operation/security/overview.md) is enabled, here are
80+
If the [security option](../operation/security/overview.md) is enabled, here are
5181
some options that should also be configured for CLI correspondingly.
5282

5383
#### Encryption
@@ -214,7 +244,7 @@ Available options:
214244
-h,--help Show this help text
215245
```
216246
217-
Example: Create a subscription to stream `demo` with the default settings.
247+
Example: Create a subscription to the stream `demo` with the default settings.
218248
219249
```sh
220250
> hstream subscription create --stream demo sub_demo
@@ -299,7 +329,7 @@ There are two kinds of commands:
299329
300330
### Basic CLI Operations
301331
302-
To quit current cli session:
332+
To quit the current CLI session:
303333
304334
```sh
305335
> :q
@@ -311,7 +341,7 @@ To print out help info overview:
311341
> :h
312342
```
313343
314-
To show specific usage of some SQL statements:
344+
To show the specific usage of some SQL statements:
315345
316346
```sh
317347
> :help CREATE
@@ -339,7 +369,7 @@ CREATE STREAM stream_name;
339369
```
340370
341371
This will create a stream with no particular function. You can `SELECT` data
342-
from the stream and `INSERT` to via corresponding SQL statement.
372+
from the stream and `INSERT` to via the corresponding SQL statement.
343373
344374
2. Create a stream, and this stream will also run a query to select specified
345375
data from some other stream.
@@ -367,8 +397,8 @@ There is no restriction on the number of fields a query can insert. Also, the
367397
type of value is not restricted. However, you need to make sure that the number
368398
of fields and the number of values are aligned.
369399
370-
Deletion command is `DROP STREAM <Stream_name> ;`, which deletes a stream, and
371-
terminate all the [queries](#queries) that depend on the stream.
400+
The deletion command is `DROP STREAM <Stream_name> ;`, which deletes a stream,
401+
and terminates all the [queries](#queries) that depend on the stream.
372402
373403
For example:
374404
@@ -408,7 +438,7 @@ Run a continuous query on the stream to select data from a stream:
408438
409439
After creating a stream, we can select data from the stream in real-time. All
410440
the data inserted after the select query is created will be printed out when the
411-
insert operation happens. Select supports real-time processing on the data
441+
insert operation happens. Select supports real-time processing of the data
412442
inserted into the stream.
413443
414444
For example, we can choose the field and filter the data selected from the
@@ -418,7 +448,7 @@ stream.
418448
SELECT a FROM demo EMIT CHANGES;
419449
```
420450
421-
This will only select field `a` from stream demo.
451+
This will only select field `a` from the stream demo.
422452
423453
How to terminate a query?
424454
@@ -451,7 +481,7 @@ Or under some circumstances, you can choose to `TERMINATE ALL;`.
451481
452482
### View
453483
454-
View is a projection of specified data from streams. For example,
484+
The view is a projection of specified data from streams. For example,
455485
456486
```sql
457487
CREATE VIEW v_demo AS SELECT SUM(a) FROM demo GROUP BY a;
@@ -465,7 +495,7 @@ The operations on view are very similar to those on streams.
465495
466496
Except we can not use `SELECT ... EMIT CHANGES` performed on streams because a
467497
view is static and there are no changes to emit. Instead, for example, we select
468-
from view with:
498+
from the view with:
469499
470500
```sql
471501
SELECT * FROM v_demo WHERE a = 1;

‎docs/en/reference/config.md

+31-14
Original file line numberDiff line numberDiff line change
@@ -9,23 +9,25 @@ or you can [download](https://raw.githubusercontent.com/hstreamdb/hstream/main/c
99

1010
| Name | Default Value | Description |
1111
| ---- | ------------- | ----------- |
12-
| id | | The identifier of a single HServer node, the value must be given and can be overwritten by cli option `--server-id` |
12+
| id | | The identifier of a single HServer node, the value must be given and can be overwritten by cli option `--server-id |
1313
| bind-address | "0.0.0.0" | The IP address or name of the host to which the HServer protocol handler is bound. The value can be overwritten by cli option `--bind-address` |
1414
| advertised-address | "127.0.0.1" | Server listener address value, the value must be given and shouldn't be "0.0.0.0", if you intend to start a cluster or trying to connect to the server from a different network. This value can be overwritten by cli option `--address` |
1515
| gossip-address | | The address used for server internal communication, if not specified, it uses the value of `advertised-address`. The value can be overwritten by cli option "--gossip-address" |
1616
| port | 6570 | Server port value, the value must be given and can be overwritten by cli option `--port`
1717
| internal-port | 6571 | Server port value for internal communications between server nodes, the value must be given and can be overwritten by cli option `--internal-port` |
1818
| metastore-uri | | The server nodes in the same cluster shares an HMeta uniy, this is used for metadata storage and is essential for a server to start. Specify the HMeta protocal such as `zk://` or `rq://`, following with Comma separated host:port pairs, each corresponding to a hmeta server. e.g. zk://127.0.0.1:2181,127.0.0.1:2182,127.0.0.1:2183. The value must be given and can be overwritten by cli option `--metastore-uri` |
19-
log-with-color | true | optional, The options used to control whether print logs with color by the server node, can be overwritten by cli option `--log-with-color` |
20-
log-level | info | optional, the setting control lof print level by the server node the default value can be overwritten by cli option `--log-level` |
19+
| onnector-meta-store | | The metadata store for connectors (hstream io), the value must be given. |
20+
| log-with-color | true | optional, The options used to control whether print logs with color by the server node, can be overwritten by cli option `--log-with-color` |
21+
| log-level | info | optional, the setting control lof print level by the server node the default value can be overwritten by cli option `--log-level` |
2122
| max-record-size | 1024*1024 (1MB) | The largest size of a record batch allowed by HStreamDB|
2223
| enable-tls | false | TLS options: Enable tls, which requires tls-key-path and tls-cert-path options |
2324
| tls-key-path | | TLS options: Key file path for tls, can be generated by openssl |
2425
| tls-cert-path | | The signed certificate by CA for the key(tls-key-path) |
26+
| advertise-listeners | | The advertised listeners for the server, see [advertised_listeners](../operation/advertised_listeners.md) for more details |
2527

2628
### hstore
2729

28-
The configuration for hstore is optional. When the values are not provided, hstreamdb will use the the default values.
30+
The configuration for hstore is optional. When the values are not provided, hstreamdb will use the default values.
2931

3032
| Name | Default Value | Description |
3133
| ---- | ------------- | ----------- |
@@ -41,19 +43,34 @@ Store admin section specifies the client config when connecting to the storage a
4143
| send-timeout | 5000 | optional |
4244
| recv-timeout | 5000 | optional |
4345

44-
### stream
46+
### hstream-io
4547

46-
| Name | Default Value | Description |
47-
| ---- | ------------- | ----------- |
48-
| replication-factor | 1 | optional |
49-
| backlog-retention | 7\*24\*3600 | the retention time in seconds|
48+
| Name | Description |
49+
| ---- | ----------- |
50+
| tasks-path | the io tasks work directory |
51+
| tasks-network | io tasks run as docker containers, so the tasks-network should be the network that can connect to HStreamDB and external systems |
52+
| source-images | key-value map specify the images used by the source connectors |
53+
| sink-images | key-value map specify the images used by the sink connectors |
5054

51-
### subscription
55+
## Resource Attributes
5256

53-
| Name | Default Value | Description |
54-
| ---- | ------------- | ----------- |
55-
| ackTimeoutSeconds | 600 | Maximum time in the server will wait for an acknowledgement |
56-
| maxUnackedRecords | 10000 | The maximum amount of unacknowledged records allowed |
57+
### Stream
58+
59+
| Name | Description |
60+
| ---- | ----------- |
61+
| name | The name of the stream |
62+
| shard count | The number of shards in the stream |
63+
| replication factor | The number of the replicas |
64+
| backlog retention | The retention time of the records in the stream in seconds|
65+
66+
### Subscription
67+
68+
| Name | Description |
69+
| ---- | ----------- |
70+
| id | The id of the subscription |
71+
| stream name | The name of the stream to subscribe |
72+
| ackTimeoutSeconds | Maximum time in the server will wait for an acknowledgement |
73+
| maxUnackedRecords | The maximum amount of unacknowledged records allowed |
5774

5875
## Command-Line Options
5976

‎docs/zh/reference/cli.md

+41-11
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,39 @@ Available commands:
4545
subscription Manage Subscriptions in HStreamDB
4646
```
4747

48+
## Connection
49+
50+
### HStream URL
51+
52+
The HStream CLI Client supports connecting to the server cluster with a url in
53+
the following format:
54+
55+
```
56+
<scheme>://<endpoint>:<port>
57+
```
58+
59+
｜Components| Description | Required |
60+
｜-｜-｜-|
61+
| `<scheme>` | The scheme of the connection. Currently, we have `hstream`. To enable security options, `hstreams` is also supported | Yes |
62+
| `<endpoint>` | The endpoint of the server cluster, which can be the hostname or address of the server cluster. | |
63+
| `<port>` | The port of the server cluster. | If not given, the value will be set to the default 6570 |
64+
65+
### Connection Parameters
66+
67+
HStream commands accept connection parameters as separate command-line flags, in addition (or in replacement) to `--service-url`.
68+
69+
::: tip
70+
In the cases where both `--service-url` and the options below are specified, the client will use the value in `--service-url`.
71+
:::
72+
73+
| Option | Description |
74+
|-|-|
75+
| `--host` | The server host and port number to connect to. This can be the address of any node in the cluster. Default: `127.0.0.1` |
76+
| `--port` | The server port to connect to. Default: `6570`|
77+
4878
### Security Settings (optional)
4979

50-
If [security option](../operation/security/overview.md) is enabled, here are
80+
If the [security option](../operation/security/overview.md) is enabled, here are
5181
some options that should also be configured for CLI correspondingly.
5282

5383
#### Encryption
@@ -214,7 +244,7 @@ Available options:
214244
-h,--help Show this help text
215245
```
216246
217-
Example: Create a subscription to stream `demo` with the default settings.
247+
Example: Create a subscription to the stream `demo` with the default settings.
218248
219249
```sh
220250
> hstream subscription create --stream demo sub_demo
@@ -299,7 +329,7 @@ There are two kinds of commands:
299329
300330
### Basic CLI Operations
301331
302-
To quit current cli session:
332+
To quit the current CLI session:
303333
304334
```sh
305335
> :q
@@ -311,7 +341,7 @@ To print out help info overview:
311341
> :h
312342
```
313343
314-
To show specific usage of some SQL statements:
344+
To show the specific usage of some SQL statements:
315345
316346
```sh
317347
> :help CREATE
@@ -339,7 +369,7 @@ CREATE STREAM stream_name;
339369
```
340370
341371
This will create a stream with no particular function. You can `SELECT` data
342-
from the stream and `INSERT` to via corresponding SQL statement.
372+
from the stream and `INSERT` to via the corresponding SQL statement.
343373
344374
2. Create a stream, and this stream will also run a query to select specified
345375
data from some other stream.
@@ -367,8 +397,8 @@ There is no restriction on the number of fields a query can insert. Also, the
367397
type of value is not restricted. However, you need to make sure that the number
368398
of fields and the number of values are aligned.
369399
370-
Deletion command is `DROP STREAM <Stream_name> ;`, which deletes a stream, and
371-
terminate all the [queries](#queries) that depend on the stream.
400+
The deletion command is `DROP STREAM <Stream_name> ;`, which deletes a stream,
401+
and terminates all the [queries](#queries) that depend on the stream.
372402
373403
For example:
374404
@@ -408,7 +438,7 @@ Run a continuous query on the stream to select data from a stream:
408438
409439
After creating a stream, we can select data from the stream in real-time. All
410440
the data inserted after the select query is created will be printed out when the
411-
insert operation happens. Select supports real-time processing on the data
441+
insert operation happens. Select supports real-time processing of the data
412442
inserted into the stream.
413443
414444
For example, we can choose the field and filter the data selected from the
@@ -418,7 +448,7 @@ stream.
418448
SELECT a FROM demo EMIT CHANGES;
419449
```
420450
421-
This will only select field `a` from stream demo.
451+
This will only select field `a` from the stream demo.
422452
423453
How to terminate a query?
424454
@@ -451,7 +481,7 @@ Or under some circumstances, you can choose to `TERMINATE ALL;`.
451481
452482
### View
453483
454-
View is a projection of specified data from streams. For example,
484+
The view is a projection of specified data from streams. For example,
455485
456486
```sql
457487
CREATE VIEW v_demo AS SELECT SUM(a) FROM demo GROUP BY a;
@@ -465,7 +495,7 @@ The operations on view are very similar to those on streams.
465495
466496
Except we can not use `SELECT ... EMIT CHANGES` performed on streams because a
467497
view is static and there are no changes to emit. Instead, for example, we select
468-
from view with:
498+
from the view with:
469499
470500
```sql
471501
SELECT * FROM v_demo WHERE a = 1;

0 commit comments

Comments
 (0)