ClickHouse/docs/en/query_language/misc.md

215 lines
8.2 KiB
Markdown
Raw Normal View History

# Miscellaneous Queries
## ATTACH
This query is exactly the same as `CREATE`, but
- instead of the word `CREATE` it uses the word `ATTACH`.
- The query doesn't create data on the disk, but assumes that data is already in the appropriate places, and just adds information about the table to the server.
After executing an ATTACH query, the server will know about the existence of the table.
If the table was previously detached (``DETACH``), meaning that its structure is known, you can use shorthand without defining the structure.
```sql
ATTACH TABLE [IF NOT EXISTS] [db.]name [ON CLUSTER cluster]
```
This query is used when starting the server. The server stores table metadata as files with `ATTACH` queries, which it simply runs at launch (with the exception of system tables, which are explicitly created on the server).
## DROP
This query has two types: `DROP DATABASE` and `DROP TABLE`.
```sql
DROP DATABASE [IF EXISTS] db [ON CLUSTER cluster]
```
Deletes all tables inside the 'db' database, then deletes the 'db' database itself.
If `IF EXISTS` is specified, it doesn't return an error if the database doesn't exist.
```sql
DROP [TEMPORARY] TABLE [IF EXISTS] [db.]name [ON CLUSTER cluster]
```
Deletes the table.
If `IF EXISTS` is specified, it doesn't return an error if the table doesn't exist or the database doesn't exist.
## DETACH
Deletes information about the 'name' table from the server. The server stops knowing about the table's existence.
```sql
DETACH TABLE [IF EXISTS] [db.]name [ON CLUSTER cluster]
```
This does not delete the table's data or metadata. On the next server launch, the server will read the metadata and find out about the table again.
Similarly, a "detached" table can be re-attached using the `ATTACH` query (with the exception of system tables, which do not have metadata stored for them).
There is no `DETACH DATABASE` query.
## RENAME
Renames one or more tables.
```sql
RENAME TABLE [db11.]name11 TO [db12.]name12, [db21.]name21 TO [db22.]name22, ... [ON CLUSTER cluster]
```
All tables are renamed under global locking. Renaming tables is a light operation. If you indicated another database after TO, the table will be moved to this database. However, the directories with databases must reside in the same file system (otherwise, an error is returned).
## SHOW DATABASES
```sql
SHOW DATABASES [INTO OUTFILE filename] [FORMAT format]
```
Prints a list of all databases.
This query is identical to `SELECT name FROM system.databases [INTO OUTFILE filename] [FORMAT format]`.
See also the section "Formats".
## SHOW TABLES
```sql
SHOW [TEMPORARY] TABLES [FROM db] [LIKE 'pattern'] [INTO OUTFILE filename] [FORMAT format]
```
Displays a list of tables
- tables from the current database, or from the 'db' database if "FROM db" is specified.
- all tables, or tables whose name matches the pattern, if "LIKE 'pattern'" is specified.
This query is identical to: `SELECT name FROM system.tables WHERE database = 'db' [AND name LIKE 'pattern'] [INTO OUTFILE filename] [FORMAT format]`.
See also the section "LIKE operator".
## SHOW PROCESSLIST
```sql
SHOW PROCESSLIST [INTO OUTFILE filename] [FORMAT format]
```
Outputs a list of queries currently being processed, other than `SHOW PROCESSLIST` queries.
Prints a table containing the columns:
**user** The user who made the query. Keep in mind that for distributed processing, queries are sent to remote servers under the 'default' user. SHOW PROCESSLIST shows the username for a specific query, not for a query that this query initiated.
**address** The name of the host that the query was sent from. For distributed processing, on remote servers, this is the name of the query requestor host. To track where a distributed query was originally made from, look at SHOW PROCESSLIST on the query requestor server.
**elapsed** The execution time, in seconds. Queries are output in order of decreasing execution time.
**rows_read**, **bytes_read** How many rows and bytes of uncompressed data were read when processing the query. For distributed processing, data is totaled from all the remote servers. This is the data used for restrictions and quotas.
**memory_usage** Current RAM usage in bytes. See the setting 'max_memory_usage'.
**query** The query itself. In INSERT queries, the data for insertion is not output.
**query_id** The query identifier. Non-empty only if it was explicitly defined by the user. For distributed processing, the query ID is not passed to remote servers.
This query is identical to: `SELECT * FROM system.processes [INTO OUTFILE filename] [FORMAT format]`.
Tip (execute in the console):
```bash
watch -n1 "clickhouse-client --query='SHOW PROCESSLIST'"
```
## SHOW CREATE TABLE
```sql
SHOW CREATE [TEMPORARY] TABLE [db.]table [INTO OUTFILE filename] [FORMAT format]
```
Returns a single `String`-type 'statement' column, which contains a single value the `CREATE` query used for creating the specified table.
## DESCRIBE TABLE
```sql
DESC|DESCRIBE TABLE [db.]table [INTO OUTFILE filename] [FORMAT format]
```
Returns two `String`-type columns: `name` and `type`, which indicate the names and types of columns in the specified table.
Nested data structures are output in "expanded" format. Each column is shown separately, with the name after a dot.
## EXISTS
```sql
EXISTS [TEMPORARY] TABLE [db.]name [INTO OUTFILE filename] [FORMAT format]
```
Returns a single `UInt8`-type column, which contains the single value `0` if the table or database doesn't exist, or `1` if the table exists in the specified database.
## USE
```sql
USE db
```
Lets you set the current database for the session.
The current database is used for searching for tables if the database is not explicitly defined in the query with a dot before the table name.
This query can't be made when using the HTTP protocol, since there is no concept of a session.
## SET
```sql
SET param = value
```
Allows you to set `param` to `value`. You can also make all the settings from the specified settings profile in a single query. To do this, specify 'profile' as the setting name. For more information, see the section "Settings".
The setting is made for the session, or for the server (globally) if `GLOBAL` is specified.
When making a global setting, the setting is not applied to sessions already running, including the current session. It will only be used for new sessions.
When the server is restarted, global settings made using `SET` are lost.
To make settings that persist after a server restart, you can only use the server's config file.
## OPTIMIZE
```sql
OPTIMIZE TABLE [db.]name [ON CLUSTER cluster] [PARTITION partition] [FINAL]
```
Asks the table engine to do something for optimization.
Supported only by `*MergeTree` engines, in which this query initializes a non-scheduled merge of data parts.
If you specify a `PARTITION`, only the specified partition will be optimized.
If you specify `FINAL`, optimization will be performed even when all the data is already in one part.
WIP on documentation (#2692) * Additional .gitignore entries * Merge a bunch of small articles about system tables into single one * Merge a bunch of small articles about formats into single one * Adapt table with formats to English docs too * Add SPb meetup link to main page * Move Utilities out of top level of docs (the location is probably not yet final) + translate couple articles * Merge MacOS.md into build_osx.md * Move Data types higher in ToC * Publish changelog on website alongside documentation * Few fixes for en/table_engines/file.md * Use smaller header sizes in changelogs * Group up table engines inside ToC * Move table engines out of top level too * Specificy in ToC that query language is SQL based. Thats a bit excessive, but catches eye. * Move stuff that is part of query language into respective folder * Move table functions lower in ToC * Lost redirects.txt update * Do not rely on comments in yaml + fix few ru titles * Extract major parts of queries.md into separate articles * queries.md has been supposed to be removed * Fix weird translation * Fix a bunch of links * There is only table of contents left * "Query language" is actually part of SQL abbreviation * Change filename in README.md too * fix mistype * s/formats\/interfaces/interfaces\/formats/g * Remove extra clarification from header as it was too verbose, probably making it a bit more confusing * Empty article was supposed to be hidden * At least change incorrect title * Move special links to the bottom of nav and slightly highlight them * Skip hidden pages in bottom navigation too * Make front page of documentation to be part of Introduction * Make tables in introduction somewhat readable + move abbreviation definitions earlier * Some introduction text refactoring * Some docs introduction refactoring * Use admonitions instead of divs * Additional .gitignore * Treat .gif as images too * Clarify ToC item
2018-07-20 17:35:34 +00:00
!!! warning
OPTIMIZE can't fix the "Too many parts" error.
## KILL QUERY
```sql
KILL QUERY [ON CLUSTER cluster]
WHERE <where expression to SELECT FROM system.processes query>
[SYNC|ASYNC|TEST]
[FORMAT format]
```
Attempts to forcibly terminate the currently running queries.
The queries to terminate are selected from the system.processes table using the criteria defined in the `WHERE` clause of the `KILL` query.
Examples:
```sql
-- Forcibly terminates all queries with the specified query_id:
KILL QUERY WHERE query_id='2-857d-4a57-9ee0-327da5d60a90'
-- Synchronously terminates all queries run by 'username':
KILL QUERY WHERE user='username' SYNC
```
Read-only users can only stop their own queries.
By default, the asynchronous version of queries is used (`ASYNC`), which doesn't wait for confirmation that queries have stopped.
The synchronous version (`SYNC`) waits for all queries to stop and displays information about each process as it stops.
The response contains the `kill_status` column, which can take the following values:
1. 'finished' The query was terminated successfully.
2. 'waiting' Waiting for the query to end after sending it a signal to terminate.
3. The other values explain why the query can't be stopped.
A test query (`TEST`) only checks the user's rights and displays a list of queries to stop.