Skip to content

Commit

Permalink
Merge pull request ClickHouse#232 from yamasite/refine-quickstart
Browse files Browse the repository at this point in the history 
Introduce the clients earlier for the quickstart guide
  • Loading branch information
@DanRoscigno
DanRoscigno authored Aug 4, 2022
2 parents c5b7400 + 742e0b9 commit 62904cc
Showing 1 changed file with 109 additions and 78 deletions.
187 changes: 109 additions & 78 deletions docs/en/quick-start.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,10 @@ If your OS is not supported or for other install options, view the [installation

## 2. Connect to ClickHouse

You can connect to ClickHouse by using the built-in UI or the ClickHouse client.

### Use the Built-in UI

1. The ClickHouse server listens for HTTP clients on port 8123 by default. There is a built-in UI for running SQL queries at <a href="http://127.0.0.1:8123/play" target="_blank">http://127.0.0.1:8123/play</a> (change the hostname accordingly).

<img src={require('./images/quickstart_01.png').default} class="image" alt="The Play UI" />
Expand All @@ -97,6 +101,83 @@ If your OS is not supported or for other install options, view the [installation

<img src={require('./images/quickstart_02.png').default} class="image" alt="View the results" />


### Use the ClickHouse Client

<Tabs groupId="os">
<TabItem value="linux" label="Linux" default>

You can also connect to your ClickHouse server using a command-line tool named **clickhouse-client**:
```bash
clickhouse-client
```

</TabItem>
<TabItem value="mac" label="macOS">

You can also connect to your ClickHouse server using a command-line tool named **clickhouse-client**. Open a new terminal and change directories to where you downloaded the `clickhouse` binary in step 1 above, then run the following command:
```bash
./clickhouse client
```

</TabItem>
</Tabs>

If you get the smiley face prompt, you are ready to run queries!
```response
:)
```

1. Give it a try by running the following query:
```sql
SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp
```

Notice the response comes back in a nice table format:
```response
SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp ASC
Query id: f7a33012-bc8c-4f0f-9641-260ee1ffe4b8
┌─user_id─┬─message────────────────────────────────────────────┬───────────timestamp─┬──metric─┐
│ 102 │ Insert a lot of rows per batch │ 2022-03-21 00:00:00 │ 1.41421 │
│ 102 │ Sort your data based on your commonly-used queries │ 2022-03-22 00:00:00 │ 2.718 │
│ 101 │ Hello, ClickHouse! │ 2022-03-22 14:04:09 │ -1 │
│ 101 │ Granules are the smallest chunks of data read │ 2022-03-22 14:04:14 │ 3.14159 │
└─────────┴────────────────────────────────────────────────────┴─────────────────────┴─────────┘
4 rows in set. Elapsed: 0.008 sec.
```

2. Add a `FORMAT` clause to specify one of the [many supported output formats of ClickHouse](/en/interfaces/formats/):
```sql
SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp
FORMAT TabSeparated
```
In the above query, the output is returned as tab-separated:
```response
Query id: 3604df1c-acfd-4117-9c56-f86c69721121
102 Insert a lot of rows per batch 2022-03-21 00:00:00 1.41421
102 Sort your data based on your commonly-used queries 2022-03-22 00:00:00 2.718
101 Hello, ClickHouse! 2022-03-22 14:04:09 -1
101 Granules are the smallest chunks of data read 2022-03-22 14:04:14 3.14159
4 rows in set. Elapsed: 0.005 sec.
```

3. To exit the `clickhouse-client`, enter the **exit** command:
```bash
:) exit
Bye.
```

## 3. Create a Table

1. As in most databases management systems, ClickHouse logically groups tables into **databases**. Use the `CREATE DATABASE` command to create a new database in ClickHouse:
Expand Down Expand Up @@ -177,83 +258,9 @@ rows at once. (Don't worry - ClickHouse can easily handle that type of volume!)
<img src={require('./images/quickstart_03.png').default} class="image" alt="New rows inserted" />


## 5. The ClickHouse Client

<Tabs groupId="os">
<TabItem value="linux" label="Linux" default>

1. You can also connect to your ClickHouse server using a command-line tool named **clickhouse-client**:
```bash
clickhouse-client
```

</TabItem>
<TabItem value="mac" label="macOS">

1. You can also connect to your ClickHouse server using a command-line tool named **clickhouse-client**. Open a new terminal and change directories to where you downloaded the `clickhouse` binary in step 1 above, then run the following command:
```bash
./clickhouse client
```

</TabItem>
</Tabs>

2. If you get the smiley face prompt, you are ready to run queries!
```response
:)
```

Give it a try by running the following query:
```sql
SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp
```

Notice the response comes back in a nice table format:
```response
SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp ASC
Query id: f7a33012-bc8c-4f0f-9641-260ee1ffe4b8
┌─user_id─┬─message────────────────────────────────────────────┬───────────timestamp─┬──metric─┐
│ 102 │ Insert a lot of rows per batch │ 2022-03-21 00:00:00 │ 1.41421 │
│ 102 │ Sort your data based on your commonly-used queries │ 2022-03-22 00:00:00 │ 2.718 │
│ 101 │ Hello, ClickHouse! │ 2022-03-22 14:04:09 │ -1 │
│ 101 │ Granules are the smallest chunks of data read │ 2022-03-22 14:04:14 │ 3.14159 │
└─────────┴────────────────────────────────────────────────────┴─────────────────────┴─────────┘
4 rows in set. Elapsed: 0.008 sec.
```

3. Add a `FORMAT` clause to specify one of the [many supported output formats of ClickHouse](/en/interfaces/formats/):
```sql
SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp
FORMAT TabSeparated
```
In the above query, the output is returned as tab-separated:
```response
Query id: 3604df1c-acfd-4117-9c56-f86c69721121
102 Insert a lot of rows per batch 2022-03-21 00:00:00 1.41421
102 Sort your data based on your commonly-used queries 2022-03-22 00:00:00 2.718
101 Hello, ClickHouse! 2022-03-22 14:04:09 -1
101 Granules are the smallest chunks of data read 2022-03-22 14:04:14 3.14159
4 rows in set. Elapsed: 0.005 sec.
```

4. To exit the `clickhouse-client`, enter the **exit** command:
```bash
:) exit
Bye.
```

## 6. Insert a CSV file
## 5. Insert a CSV file

A common task when getting started with a database is to insert some data that you already have in files. We have some
sample data online that you can insert that represents clickstream data - it includes a user ID, a URL that was visited, and
Expand All @@ -268,11 +275,35 @@ the timestamp of the event.

2. The following command inserts the data into `my_first_table`:
``` bash
clickhouse-client --query='INSERT INTO helloworld.my_first_table FORMAT CSV' < data.csv
clickhouse-client \
--query='INSERT INTO helloworld.my_first_table FORMAT CSV' < data.csv
```

3. Notice the new rows appear in the table now:
<img src={require('./images/quickstart_04.png').default} class="image" alt="New rows from CSV file" />
3. Run the following query to validate the insertion:

```sql
SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp ASC
```

```
SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp ASC
Query id: d7216864-2b85-4ad2-9073-6c0bef7ed0c6
┌─user_id─┬─message────────────────────────────────────────────┬───────────timestamp─┬──metric─┐
│ 103 │ Use FORMAT to specify the format │ 2022-02-21 10:43:30 │ 678.9 │
│ 102 │ This is data in a file │ 2022-02-22 10:43:28 │ 123.45 │
│ 101 │ It is comma-separated │ 2022-02-23 00:00:00 │ 456.78 │
│ 102 │ Insert a lot of rows per batch │ 2022-07-15 00:00:00 │ 1.41421 │
│ 102 │ Sort your data based on your commonly-used queries │ 2022-07-16 00:00:00 │ 2.718 │
│ 101 │ Hello, ClickHouse! │ 2022-07-16 00:19:30 │ -1 │
│ 101 │ Granules are the smallest chunks of data read │ 2022-07-16 00:19:35 │ 3.14159 │
└─────────┴────────────────────────────────────────────────────┴─────────────────────┴─────────┘
```

## What's Next?

Expand Down

0 comments on commit 62904cc

Please sign in to comment.