# Mapping Tables

EMQX Mapping Tablesプラグインは、Rule SQL用の名前付きマッピングテーブルを提供します。ルールで安定した識別子、コード、またはバイナリフィールドIDを長い`CASE WHEN`式をSQL文に保持せずに構造化された値にマッピングする必要がある場合に、このプラグインを使用してください。

このプラグインはEMQX 6.3.0以降で利用可能です。Rule SQLで`maptab_lookup`を使用する前に、プラグインをインストールして起動してください。

マッピングテーブルは`emqx ctl maptabs` CLIを通じてJSONファイルからロードされ、EMQXのレプリケートされたデータベースに格納されます。ルールは`maptab_lookup` SQL関数でテーブルをクエリします。関数のシグネチャやSQLの例については、[組み込みSQL関数](../../../data-integration/rule-sql-builtin-functions.md)を参照してください。

## テーブルファイル

マッピングテーブルはJSONファイルです。ファイル名の`.json`拡張子を除いた部分がテーブル名として使用されます。テーブル名には英数字、アンダースコア、ハイフンのみ使用できます。

JSONファイルは行オブジェクトの配列を含む必要があります。各行は`key`フィールドを含まなければなりません。行内のその他すべてのフィールドはその行の値マップを形成します。

例：

```json
[
  {
    "key": 1,
    "signal_name": "temperature_c",
    "start_bit": 17,
    "length": 8,
    "type": "integer",
    "signedness": "signed",
    "endian": "big"
  },
  {
    "key": 2,
    "signal_name": "pressure_kpa",
    "start_bit": 17,
    "length": 32,
    "type": "float",
    "signedness": "unsigned",
    "endian": "big"
  }
]
```

`key`はJSONの整数または文字列でなければなりません。ネイティブJSON型は保持されるため、整数の`50`と文字列の`"50"`は異なるキーとして扱われます。

ロードはフェイルクローズ方式です。ファイルに以下の問題がある場合、EMQXはファイル全体を拒否し、以前のテーブルバージョンを保持します。

- 無効なJSON
- 配列でないトップレベルの値
- オブジェクトでない行
- `key`を含まない行
- 重複したキー
- 浮動小数点数、ブール値、null、配列、オブジェクト型のキー

## CLIコマンド

`emqx ctl maptabs` CLIを使用してマッピングテーブルを管理します。

| コマンド | 説明 |
| --- | --- |
| `emqx ctl maptabs list` | ローカルノードにキャッシュされているテーブルの一覧を表示。行数とバージョンも含む。 |
| `emqx ctl maptabs status` | 全稼働ノードのテーブル一覧を表示。キャッシュのずれ検出に使用。 |
| `emqx ctl maptabs load <file>` | テーブルJSONファイルを検証し、全ノードにレプリケート。 |
| `emqx ctl maptabs reload` | 全稼働ノードでストレージからキャッシュを再構築。キャッシュ同期が必要な場合に使用。 |
| `emqx ctl maptabs get <name>` | 保存されているテーブルのJSON内容を表示。 |
| `emqx ctl maptabs delete <name>` | 全ノードからテーブルを削除。 |

すべてのコマンド出力はJSON形式ですが、`emqx ctl maptabs get <name>`はテーブルが存在する場合、保存されたテーブルJSON内容を直接出力します。

## 設定

プラグインは標準のプラグイン設定API `PUT /api/v5/plugins/<name-vsn>/config` またはプラグイン設定ファイルで設定します。

| 設定項目 | デフォルト | 説明 |
| --- | --- | --- |
| `max_tables` | `100` | マッピングテーブルの最大数。この制限を超える新規テーブルのロードは拒否されます。既存テーブルの置換は可能です。 |
| `max_rows_per_table` | `10000` | 1テーブルあたりの最大行数。これを超えるファイルは拒否されます。 |
| `max_table_file_bytes` | `10000000` | テーブルJSONファイルの最大サイズ（バイト）。これを超えるファイルはメモリに読み込まれる前に拒否されます。 |

制限はテーブルロード時にチェックされます。制限変更は既にロード済みのテーブルを削除または切り詰めしません。

## クラスター動作

プラグインはテーブル内容をEMQXの組み込みレプリケートデータベースに保存します。テーブルのロードや削除はクラスター内のすべてのノードにレプリケートされ、各ノードは保存されたテーブル内容からインメモリキャッシュを再構築します。

クラスター内のすべてのノードにプラグインをインストールして起動してください。テーブルロードや削除時にダウンしていたノードは、再起動時にストレージからキャッシュを再構築して追いつきます。

キャッシュの更新はリーダーに対して原子操作です。ルールのルックアップは古いテーブルバージョンか新しいテーブルバージョンのいずれかを参照し、部分的な更新は見ません。

## アクセスと共有

マッピングテーブルは管理者のみがCLIを通じて管理します。テーブルはテナントのネームスペースを越えて共有されます。ルックアップはクライアントがマルチテナンシーネームスペースに属しているかどうかに関わらず、すべてのクライアントに同じ行を返します。

テナントごとに行を分ける必要がある場合は、テーブルデータにテナントをエンコードしてください。例えば、ルックアップキーにテナントを含めます。

```sql
maptab_lookup('signals', concat(client_attrs.tns, ':', item_id))
```

または、テナントごとに1つのテーブルを使用し、ルール内でテーブル名を構成する方法もあります。テーブル内のすべてのキーとルックアップ箇所に同じ規約を適用してください。

<!-- PLUGIN-DOWNLOADS:BEGIN (auto-generated, do not edit) -->

## ダウンロード

各EMQXリリース用のtarball：

| EMQXバージョン | プラグインバージョン | パッケージ |
|---|---|---|
| 6.3.0 | 0.1.2 | [emqx_maptabs-0.1.2.tar.gz](https://www.emqx.com/downloads/emqx-plugins/6.3.0/emqx_maptabs-0.1.2.tar.gz) ([sha256](https://www.emqx.com/downloads/emqx-plugins/6.3.0/emqx_maptabs-0.1.2.sha256)) |

<!-- PLUGIN-DOWNLOADS:END -->