# Mapping Tables

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

このプラグインはEMQX 6.1.5以降で利用可能です。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))
```

またはテナントごとにテーブルを分け、ルール内でテーブル名を構成することも可能です。テーブル内のすべてのキーと照会箇所に同じ規約を適用してください。

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

## ダウンロード

各EMQXリリースのtarball：

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

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