> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> リモート ClickHouse サーバー上のデータベース内のテーブルにリアルタイムでアクセスし、`SELECT` および `INSERT` クエリをそのサーバーに転送します。

# Remote

`Remote` および `RemoteSecure` データベースエンジンは、native TCP プロトコル経由でリモート ClickHouse サーバー上のデータベース内のテーブルにリアルタイムでアクセスできるようにします。これらは、[`MySQL`](/docs/ja/reference/engines/database-engines/mysql) および [`PostgreSQL`](/docs/ja/reference/engines/database-engines/postgresql) データベースエンジンに相当する、ClickHouse 間接続用のエンジンです。

テーブルの一覧とその構造は、必要に応じてリモートサーバーから取得されます (内部的には `SHOW TABLES` と `DESCRIBE TABLE` を使用します) 。そのため、このデータベースは常にリモートサーバーの最新の状態を反映します。各テーブルは、指定されたアドレスから構成されるアドホックなクラスター上の [`Distributed`](/docs/ja/reference/engines/table-engines/special/distributed) ストレージとして公開され、`SELECT` および `INSERT` クエリをリモートサーバーに転送します。

複数の ClickHouse クラスターをフェデレーションしたり、大規模な ClickHouse クラスターを `clickhouse-local` や小規模なクラスターに接続したりする際に便利です。

<div id="creating-a-database">
  ## データベースの作成
</div>

<Tabs>
  <Tab title="Remote" id="remote">
    `Remote` は、ポートを省略した場合、プレーン TCP ポート (`tcp_port`、デフォルトは `9000`) 経由で接続します。

    ```sql theme={null}
    CREATE DATABASE remote_db
    ENGINE = Remote('addresses_expr', 'database'[, 'user'[, 'password']]);
    ```
  </Tab>

  <Tab title="RemoteSecure" id="remote-secure">
    `RemoteSecure` は、ポートを省略した場合、セキュア TCP ポート (`tcp_port_secure`、デフォルトは `9440`) を使用して、セキュアな TLS 接続経由で接続します。

    ```sql theme={null}
    CREATE DATABASE remote_db
    ENGINE = RemoteSecure('addresses_expr', 'database'[, 'user'[, 'password']]);
    ```
  </Tab>
</Tabs>

**エンジンパラメータ**

* `addresses_expr` — リモートサーバーのアドレス、または `host` もしくは `host:port` 形式で複数のアドレスを生成する式です。アドレス式では、[`remote`](/docs/ja/reference/functions/table-functions/remote) テーブル関数と同じグロブパターンを使用できます (たとえば、複数の分片とレプリカに展開される `{a,b,c}`、`{N..M}`、`{a|b}`) 。ポートを省略した場合、`Remote` はプレーン TCP ポート (`tcp_port`、デフォルトは `9000`) を使用し、`RemoteSecure` はセキュア TCP ポート (`tcp_port_secure`、デフォルトは `9440`) を使用します。
* `database` — リモートサーバー上のデータベース名です。
* `user` — リモートユーザー名です。任意。デフォルト: `default`。
* `password` — リモートユーザーのパスワードです。任意。デフォルト: 空。

アドレスと認証情報はデータベース定義に保存されるため、`SHOW CREATE DATABASE` ではパスワードは非表示になります。`remote` テーブル関数と同様に、現在のサーバーを指すアドレスはローカル分片として扱われます。`SELECT` と `INSERT` は現在のユーザーとして直接実行されるため、そのユーザーには基盤となるデータベースとそのテーブルに対する対応する権限が必要です。保存された認証情報は、実際にリモートのサーバーに対してのみ使用されます。分片のローカルレプリカにデータベースまたはテーブルがない場合、ルックアップは [`Distributed`](/docs/ja/reference/engines/table-engines/special/distributed) テーブルと同様に、その分片のリモートレプリカにフォールバックします。その場合、`SHOW CREATE TABLE` は設定済みのアドレスではなく、有効なフォールバック先アドレス (各分片からローカルレプリカを除外したもの) を出力します。これにより、出力された `Remote(...)` テーブル定義は、実際にクエリを処理するオブジェクトを再構築します。

アドレス式が複数の分片を指定する場合、各プロキシテーブルはそのすべてから読み取りますが、メタデータ (テーブルの一覧とその構造) は、[`remote`](/docs/ja/reference/functions/table-functions/remote) テーブル関数と同様に任意の分片 (ローカル分片が優先されます) から取得されます。これにより、一覧表示に必要なクエリは分片ごとに 1 件ではなく、1 件だけになります。したがって、クラスターの分片は同じテーブルセットを提供することが想定されます。一部の分片にしか存在しないテーブルはプロキシ経由で提供されますが、そのテーブルを持たない分片ではクエリが失敗します。複数分片データベースのテーブルへの `INSERT` では、各行がランダムな分片に送信されます (プロキシの `Distributed` テーブルには暗黙的な `rand()` シャーディングキーがあります) 。クエリで対象の分片を固定するには、[`insert_shard_id`](/docs/ja/reference/settings/session-settings/insert#insert_shard_id) を設定します。暗黙的なキーは挿入される行を分散するためだけに使用されます。読み取り時、テーブルはシャーディングキーを持たない `Distributed` テーブルのように動作します (特に、[`optimize_skip_unused_shards`](/docs/ja/reference/settings/session-settings/optimize-skip#optimize_skip_unused_shards) と [`force_optimize_skip_unused_shards`](/docs/ja/reference/settings/session-settings/force-optimize#force_optimize_skip_unused_shards) は、これを分片プルーニングキーとして扱いません) 。`SHOW CREATE TABLE` により出力される `Remote(...)` テーブル定義にはこのキーが含まれるため、それを基に再作成したテーブルでも複数分片に対する `INSERT` クエリを受け付けます。

名前付きコレクションもサポートされています。

```sql theme={null}
CREATE DATABASE remote_db
ENGINE = Remote(my_named_collection, database = 'default');
```

<div id="notes">
  ## 注記
</div>

* このエンジンはリモートサーバーに対する読み取り専用ビューです。`Remote` データベースに対する `CREATE TABLE`、`DROP TABLE`、`ALTER` などの DDL ステートメントはサポートされていません。スキーマはリモートサーバー上で直接管理してください。
* 構成されたリモートユーザーにはリモートサーバー上でアクセス権が適用され、ローカルではデータベースおよびそのテーブルに対する通常の権限が適用されます。
* ユーザーに表示が許可されていないローカル分片のテーブルは、アクセス禁止ではなく存在しないものとして報告されます。そのため、`Remote` データベースを使用して、ユーザーに権限のないローカルデータベースのテーブル名を調べることはできません。これは一覧表示 (`SHOW TABLES`、`EXISTS TABLE`) だけでなく、名前解決 (`DESCRIBE TABLE`、`SHOW CREATE TABLE`、`SELECT`) にも適用されます。また、このようなテーブルは分片のリモートレプリカ経由でも提供されません。上記のフォールバックが行われるのは、ローカルレプリカに実際にそのテーブルが存在しない場合のみです。
* 分片のローカルレプリカに存在するデータベースのテーブルを一覧表示すると、その分片のリモートレプリカにのみ存在するテーブルも含まれます。これにより、`SHOW TABLES` と `system.tables` は、これらのレプリカにフォールバックする `EXISTS TABLE`、`DESCRIBE TABLE`、`SELECT` と整合します。リモートレプリカがいずれも応答しない場合は、利用可能なレプリカから得られた結果であるため、ローカルレプリカの一覧がそのまま返されます。
* リモートサーバーが使用不可の場合、そのテーブルを一覧表示する操作 (`SHOW TABLES`、`system.tables`) では、同じデータベースに対する `EXISTS TABLE` や `SELECT` と同様に、空のテーブル一覧ではなく接続エラーが報告されます。このようなデータベースに到達できない間は、すべてのデータベースを対象とする `system.tables` への `SELECT` も失敗することに注意してください。
* `Remote` データベースは、同じサーバー上の別の `Remote` データベースを参照できます。このようなチェーンのテーブルを一覧表示したり記述したりするために、中間データベースに対する権限は必要ありません。中間データベースは独自のデータもメタデータも保持せず、各ホップでプロキシ先のオブジェクトに対する呼び出し元の権限がすでに確認されるためです。一方、データの読み取りと書き込みには、チェーン内のすべてのホップで `SELECT` / `INSERT` が必要です。これは、別の `Distributed` テーブル上に作成された `Distributed` テーブルと同様に、クエリが実際には中間データベースのテーブルに対して実行されるためです。上記の可視性ルールはチェーンでも維持されます。中間データベースが呼び出し元に対して隠すテーブルは、外側のデータベースのリモートレプリカ経由でも提供されません。ローカルレプリカ上の中間データベースが自身のターゲットに到達できない場合、外側の分片のローカルレプリカはまったく応答できません。これはレプリカ自体が停止している場合と同じであり、外側のデータベースは分片のリモートレプリカにフォールバックします。

<div id="example">
  ## 例
</div>

リモートサーバー上の `system` データベースを参照する `Remote` データベースを作成し、そこからデータを読み取ります。

```sql theme={null}
CREATE DATABASE remote_system
ENGINE = Remote('127.0.0.1:9000', 'system', 'default', '');
```

```sql theme={null}
SHOW TABLES FROM remote_system LIKE 'one';
```

```text theme={null}
┌─name─┐
│ one  │
└──────┘
```

```sql theme={null}
SELECT * FROM remote_system.one;
```

```text theme={null}
┌─dummy─┐
│     0 │
└───────┘
```