ClickHouse/docs/en/sql-reference/table-functions/cluster.md

59 lines
2.6 KiB
Markdown
Raw Normal View History

---
toc_priority: 50
toc_title: cluster
---
# cluster, clusterAllReplicas {#cluster-clusterallreplicas}
Allows to access all shards in an existing cluster which configured in `remote_servers` section without creating a [Distributed](../../engines/table-engines/special/distributed.md) table. One replica of each shard is queried.
2021-08-16 23:00:38 +00:00
`clusterAllReplicas` function — same as `cluster`, but all replicas are queried. Each replica in a cluster is used as a separate shard/connection.
!!! note "Note"
2021-08-17 01:54:48 +00:00
All available clusters are listed in the [system.clusters](../../operations/system-tables/clusters.md) table.
2021-08-16 23:00:38 +00:00
**Syntax**
``` sql
cluster('cluster_name', db.table[, sharding_key])
cluster('cluster_name', db, table[, sharding_key])
clusterAllReplicas('cluster_name', db.table[, sharding_key])
clusterAllReplicas('cluster_name', db, table[, sharding_key])
```
2021-08-16 23:00:38 +00:00
**Arguments**
- `cluster_name` Name of a cluster that is used to build a set of addresses and connection parameters to remote and local servers.
- `db.table` or `db`, `table` - Name of a database and a table.
2021-08-17 23:03:46 +00:00
- `sharding_key` - A sharding key. Optional. Needs to be specified if the cluster has more than one shard.
2021-08-16 23:00:38 +00:00
**Returned value**
The dataset from clusters.
2021-08-16 23:00:38 +00:00
**Using Macros**
2021-08-17 01:54:48 +00:00
`cluster_name` can contain macros — substitution in curly brackets. The substituted value is taken from the [macros](../../operations/server-configuration-parameters/settings.md#macros) section of the server configuration file.
2021-08-16 23:00:38 +00:00
Example:
```sql
SELECT * FROM cluster('{cluster}', default.example_table);
```
2021-08-16 23:00:38 +00:00
**Usage and Recommendations**
2020-12-20 07:48:55 +00:00
2021-05-27 19:44:11 +00:00
Using the `cluster` and `clusterAllReplicas` table functions are less efficient than creating a `Distributed` table because in this case, the server connection is re-established for every request. When processing a large number of queries, please always create the `Distributed` table ahead of time, and do not use the `cluster` and `clusterAllReplicas` table functions.
The `cluster` and `clusterAllReplicas` table functions can be useful in the following cases:
- Accessing a specific cluster for data comparison, debugging, and testing.
- Queries to various ClickHouse clusters and replicas for research purposes.
- Infrequent distributed requests that are made manually.
Connection settings like `host`, `port`, `user`, `password`, `compression`, `secure` are taken from `<remote_servers>` config section. See details in [Distributed engine](../../engines/table-engines/special/distributed.md).
**See Also**
2020-10-13 17:23:29 +00:00
- [skip_unavailable_shards](../../operations/settings/settings.md#settings-skip_unavailable_shards)
- [load_balancing](../../operations/settings/settings.md#settings-load_balancing)