Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add more explains and examples for SELECT ... INTO OUTFILE statements #15104

Merged
merged 15 commits into from
Nov 28, 2023
Merged
81 changes: 77 additions & 4 deletions sql-statements/sql-statement-select.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,6 @@ The `SELECT` statement is used to read data from TiDB.

![SelectStmt](/media/sqlgram/SelectStmt.png)

> **Note:**
>
> The `SELECT ... INTO OUTFILE` statement is only applicable to TiDB Self-Hosted and not available on [TiDB Cloud](https://docs.pingcap.com/tidbcloud/).

**FromDual:**

![FromDual](/media/sqlgram/FromDual.png)
Expand Down Expand Up @@ -118,6 +114,8 @@ TableSampleOpt ::=

## Examples

### SELECT

```sql
mysql> CREATE TABLE t1 (id INT NOT NULL PRIMARY KEY AUTO_INCREMENT, c1 INT NOT NULL);
Query OK, 0 rows affected (0.11 sec)
Expand Down Expand Up @@ -159,9 +157,84 @@ mysql> SELECT AVG(s_quantity), COUNT(s_quantity) FROM stock;

The above example uses data generated with `tiup bench tpcc prepare`. The first query shows the use of `TABLESAMPLE`.

### SELECT ... INTO OUTFILE

The `SELECT ... INTO OUTFILE` statement is used to write the result of a query to a file.

> **Note:**
>
> - This statement is only applicable to TiDB Self-Hosted and not available on [TiDB Cloud](https://docs.pingcap.com/tidbcloud/).
> - This statement does not support
writing query results to any [external storages](https://docs.pingcap.com/tidb/stable/backup-and-restore-storages) such as Amazon S3 or GCS.
qiancai marked this conversation as resolved.
Show resolved Hide resolved

In the statement, you can specify the format of the output file by using the following clauses:

- `FIELDS TERMINATED BY`: specifies the field delimiter in the file. For example, you can specify it as `','` to output comma-separated values (CSV) or `'\t'` to output tab-separated values (TSV).
- `FIELDS ENCLOSED BY`: specifies the enclosing character that wraps around each field in the file.
- `LINES TERMINATED BY`: specifies the line terminator in the file, if you want to end a line with a certain character.

Assume that there is a table `t` with three columns as follows:

```sql
mysql> CREATE TABLE t (a INT, b VARCHAR(10), c DECIMAL(10,2));
Query OK, 0 rows affected (0.02 sec)

mysql> INSERT INTO t VALUES (1, 'a', 1.1), (2, 'b', 2.2), (3, 'c', 3.3);
Query OK, 3 rows affected (0.01 sec)
```

qiancai marked this conversation as resolved.
Show resolved Hide resolved
The following examples show how to use the `SELECT ... INTO OUTFILE` statement to write the query result to a file.

**Example 1:**

qiancai marked this conversation as resolved.
Show resolved Hide resolved
```sql
mysql> SELECT * FROM t INTO OUTFILE '/tmp/tmp_file1';
Query OK, 3 rows affected (0.00 sec)
```

qw4990 marked this conversation as resolved.
Show resolved Hide resolved
In this example, you can find the query result in `/tmp/tmp_file1` as follows:

```
1 a 1.10
2 b 2.20
3 c 3.30
```
qw4990 marked this conversation as resolved.
Show resolved Hide resolved

qiancai marked this conversation as resolved.
Show resolved Hide resolved
**Example 2:**

```sql
mysql> SELECT * FROM t INTO OUTFILE '/tmp/tmp_file2' FIELDS TERMINATED BY ',' ENCLOSED BY '"';
Query OK, 3 rows affected (0.00 sec)
```

qiancai marked this conversation as resolved.
Show resolved Hide resolved
In this example, you can find the query result in `/tmp/tmp_file2` as follows:

```
"1","a","1.10"
"2","b","2.20"
"3","c","3.30"
```

qiancai marked this conversation as resolved.
Show resolved Hide resolved
**Example 3:**

```sql
mysql> SELECT * FROM t INTO OUTFILE '/tmp/tmp_file3'
-> FIELDS TERMINATED BY ',' ENCLOSED BY '\'' LINES TERMINATED BY '<<<\n';
Query OK, 3 rows affected (0.00 sec)
```

qiancai marked this conversation as resolved.
Show resolved Hide resolved
In this example, you can find the query result in `/tmp/tmp_file3` as follows:

```
'1','a','1.10'<<<
'2','b','2.20'<<<
'3','c','3.30'<<<
```

## MySQL compatibility

- The syntax `SELECT ... INTO @variable` is not supported.
- The syntax `SELECT ... INTO DUMPFILE` is not supported.
- The syntax `SELECT .. GROUP BY expr` does not imply `GROUP BY expr ORDER BY expr` as it does in MySQL 5.7. TiDB instead matches the behavior of MySQL 8.0 and does not imply a default order.
- The syntax `SELECT ... TABLESAMPLE ...` is a TiDB extension and not supported by MySQL.
qw4990 marked this conversation as resolved.
Show resolved Hide resolved

Expand Down
Loading