Fivetranの命名規則セットガイド：スキーマ・テーブル・カラムの名称変換（Naming conventions）の詳細

## 概要

Fivetran では、コネクタの種類（データベース系と非データベース系）や設定（Fivetran naming と Source naming）によって、ソースから転送するスキーマ名・テーブル名・カラム名が変換されることがあります。本ドキュメントでは、その主な仕様を整理しています。

本記事は下記記事の一部です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/d5372a04-4384-4eb1-8120-075f8cbbb7e6.png)

出所：[フルマネージドなデータ連携：データ統合の自動化を実現する Fivetran の全貌 #fivetran - Qiita](https://qiita.com/manabian/items/2a760238d3fc1021aae7)


## Fivetran における名称変換（Naming conventions）

Fivetran は、異なるソースがそれぞれ持つ命名スタイルを統一し、ターゲットシステムの規約や仕様に合わせるためにスキーマやカラムに対して名称変換（Naming conventions）を行います。詳しくは、公式ドキュメントに記載されています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/076051d0-a2bf-4c78-8119-301dd33e3e67.png)

出所：[How to build a data stack \| Fivetran connector strategy](https://fivetran.com/docs/core-concepts#namingconventions)

Fivetran には 2 種類のネーミング方式があり、接続作成時に選択できます。Fivetran naming ではスキーマ用とテーブル／カラム用のルールが別々に存在し、さらにデータベースコネクタか非データベースコネクタかによって変換ルールが異なります。

- Fivetran naming： ソースの名称を可能な限り保持しつつ、非 ASCII 文字などを宛先上の一貫した命名規則に合わせる方法
- Source naming： ソースの元の名称（UTF-8）をそのまま利用する方法

ただし、Source naming がサポートされているコネクターは多くありません（2025年4月14日時点）。以下が対応する主なコネクターです。

> **Supported connectors**
>
> Fivetran supports Source naming for the following connectors:
>
> - [MySQL](https://fivetran.com/docs/connectors/databases/mysql)
> - [PostgreSQL](https://fivetran.com/docs/connectors/databases/postgresql)
> - [SQL Server](https://fivetran.com/docs/connectors/databases/sql-server)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/ed7a653c-f8ee-4162-88ae-d75d49598ea1.png)

出所：[How to sync databases with your destination using Fivetran](https://fivetran.com/docs/connectors/databases#sourcenaming)

Source naming はテーブル名が UTF-8 に対応しているか、また宛先側の制約を満たせるかなどが前提条件となっており、要件を満たさない場合は同期できません。特に SQL Server では文字のバイト数を最適化するため Shift-JIS（正確には CP932）の照合順序を使用していることがあるため、そのような設定の場合には動作検証が必須です。

> When enabled, Fivetran preserves the original or source names of the schemas, tables, and columns with UTF-8 values without any modifications and replicates them to your destination.
> 
> Some destinations may have reserved keywords or restrictions that prevent certain names from being used. We display a warning message in such instances and exclude the schemas, tables, or columns from the sync.

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/e5d077ba-e567-4e8f-9cb7-955d14480d1b.png)

出所：[How to build a data stack | Fivetran connector strategy](https://fivetran.com/docs/core-concepts#sourcenaming)

> 有効にすると、Fivetranは、UTF-8値を持つスキーマ、テーブル、および列の元の名前またはソース名を変更せずに保持し、それらを宛先にレプリケートします。
> 
> 一部の目的地では、特定の名前が予約済みキーワードとなっていたり制限に抵触する場合があります。そのような場合は警告メッセージが表示され、該当するスキーマやテーブル、カラムは同期から除外されます。

上記の翻訳

## データベースのコネクターにおける名称

### データベースコネクターのスキーマ

#### スキーマに関する命名規則

データベースコネクターでは、スキーマにプレフィックスを設定できます。ソースのデータベース内に複数スキーマがあることが考慮されており、Destination には `{schema_prefix}_{source_schema_name}` という形式のスキーマが作成されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/01a1c936-8992-4336-b42c-13bb7411ce8a.png)

スキーマに関する命名規則は、次のようにドキュメントで説明されています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/3c09e252-06b5-4b40-b7e2-7288b627911d.png)

出所：[How to build a data stack \| Fivetran connector strategy](https://fivetran.com/docs/core-concepts#schemanamingruleset)

#### スキーマに関する命名規則に関する検証

`テスト__検証` というスキーマを作成・同期したところ、スキーマプレフィックスである `dbx_01_` に `tesuto__jian_zheng` が追加された名称となりました。ひらがなはアルファベットに変換され、漢字は中国語の発音記号（ピンイン）に変換されるようです。

```sql
%sql
CREATE SCHEMA IF NOT EXISTS `テスト__検証`;
CREATE TABLE IF NOT EXISTS `テスト__検証`.table_01
(
  col_1 string
);
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/142e6dd5-3874-45cf-b94b-10b77551a58b.png)


### データベースコネクターのテーブルおよびカラム

#### テーブルおよびカラムに関する命名規則

Source naming が選択できるコネクターの場合、ソースに合わせた元のテーブル／カラム名（UTF-8）をそのまま利用できます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/b3c43ab2-528a-4c24-a700-f34804788f3a.png)

Fivetran naming を選択した場合、以下のルールに従って自動的にテーブル名とカラム名が変換されます。テーブル名を手動で指定する方法は確認できませんでした。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/a8f0a68d-a692-4416-9114-925e7c323b35.png)

出所：[How to build a data stack \| Fivetran connector strategy](https://fivetran.com/docs/core-concepts#tableandcolumnnamingrulesetfordatabaseconnectors)

#### テーブルおよびカラムに関する命名規則に関する検証

Fivetran naming を設定し、`!fivetran_naming_表` というテーブルを同期したところ、Destination では `__fivetran_naming_biao` というテーブル名になりました。以下はソース側と Destination 側の DDL です。

```sql
%sql
CREATE TABLE bap_databricks_template_databricks_sa.fivetran_source.`!fivetran_naming_表` (
  My_Name_001 STRING,
  `my name_002` STRING,
  MyName_003 STRING,
  Myname123_004 STRING,
  My123name123_005 STRING,
  `My_Name!` STRING,
  My_Name____c STRING,
  `1MyName_008` STRING,
  `!MyName_009` STRING,
  `カタカナ` STRING,
  `漢字` STRING,
  `発注明細番号` STRING,
  `mynamé_with_accents` STRING,
  UPERCASE STRING,
  A123456789_B123456789_C1234567890_D123456789_E123456789_F123456789_G123456789_H123456789_I123456789_J123456789_K123456789_L123456789_M123456789_N123456789 STRING
)
USING delta
TBLPROPERTIES (
  'delta.columnMapping.mode' = 'name'
);
```

```sql
%sql
CREATE TABLE dbx_01_fivetran_source.__fivetran_naming_biao (
  fa_zhu_ming_xi_fan_hao STRING,
  my_name_001 STRING,
  my_name_002 STRING,
  myname_003 STRING,
  myname123_004 STRING,
  my123name123_005 STRING,
  my_name____c STRING,
  my_name_ STRING,
  `1myname_008` STRING,
  __myname_009 STRING,
  katakana STRING,
  han_zi STRING,
  myname_with_accents STRING,
  upercase STRING,
  a123456789_b123456789_c1234567890_d123456789_e123456789_f123456789_g123456789_h123456789_i123456789_j123456789_k123456789_l123456789_m123456789_n123456789 STRING,
  _fivetran_id STRING,
  _fivetran_deleted BOOLEAN,
  _fivetran_synced TIMESTAMP
)
USING delta
TBLPROPERTIES (
  'delta.checkpoint.writeStatsAsJson' = 'false',
  'delta.checkpoint.writeStatsAsStruct' = 'true',
  'delta.enableDeletionVectors' = 'true',
  'delta.feature.deletionVectors' = 'supported',
  'delta.minReaderVersion' = '3',
  'delta.minWriterVersion' = '7'
);
```

カラムは以下の通り変換されています。

| #  | ソースカラム                | Destination カラム         | 備考・変換例                                                                 |
|----|----------------------------|----------------------------|------------------------------------------------------------------------------|
| 1  | My_Name_001               | my_name_001               | 大文字 → 小文字への単純変換                                                 |
| 2  | `my name_002`             | my_name_002               | スペースをアンダースコアに変換＋小文字化                                     |
| 3  | MyName_003                | myname_003                | キャメルケースを小文字に                                                    |
| 4  | Myname123_004             | myname123_004             | 数字を含む箇所も含めて小文字に                                              |
| 5  | My123name123_005          | my123name123_005          | 全体を小文字に変換                                                          |
| 6  | `My_Name!`                | my_name_                  | 「!」を削除し、末尾に「_」が付加                                             |
| 7  | My_Name____c              | my_name____c              | 大文字を小文字に変換                                                        |
| 8  | `1MyName_008`             | 1myname_008               | 先頭が数字でもそのまま、小文字化のみ                                         |
| 9  | `!MyName_009`             | __myname_009              | 先頭の「!」をアンダースコアに。元の「MyName」も小文字へ                       |
| 10 | `カタカナ`                | katakana                  | カタカナをローマ字に変換                                                    |
| 11 | `漢字`                    | han_zi                    | 漢字をピンイン表記に変換し、単語の境界でアンダースコアを挿入                 |
| 12 | `発注明細番号`            | fa_zhu_ming_xi_fan_hao    | 漢字をピンイン表記に変換し、単語の境界でアンダースコアを挿入                 |
| 13 | `mynamé_with_accents`     | myname_with_accents       | アクセント記号を取り除いて小文字（é → e）化                                      |
| 14 | UPERCASE                  | upercase                  | 大文字を小文字化                                                            |
| 15 | A123456789_B123456789_C…  | a123456789_b123456789_c…  | 長い英数字列も同様に小文字化                                                |

## 非データベースにおける名称変換

### 非データベースコネクターのスキーマ

#### スキーマに関する命名規則

非データベースコネクターを作成する際は、スキーマ名を手動で指定します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/59b1dfb4-18ec-4a0c-b21e-7b13caf26c63.png)

スキーマに関しては、以下のような制限があります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/3c09e252-06b5-4b40-b7e2-7288b627911d.png)

出所：[How to build a data stack \| Fivetran connector strategy](https://fivetran.com/docs/core-concepts#schemanamingruleset)

#### スキーマに関する命名規則に関する検証

スキーマ名を手動で設定するため、すべてが自動変換されるわけではありません。大文字は小文字に変換されますが、日本語などの非アスキー文字を含むとエラーになりました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/ce09d612-65e3-4048-8ec5-f2be76336b6b.png)

> Invalid schema name. Schema name shouldn't be empty, should contain only letters, numbers, or underscores, and cannot begin with a number.

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/fce7d794-a121-4587-99b1-7e9fe34596cf.png)


### 非データベースコネクターのテーブルおよびカラム

#### テーブルおよびカラムに関する命名規則

Files コネクターなど一部のコネクターでは、テーブル名を手動で指定できます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/b24bac3a-d46d-4690-b030-b9de548e8a27.png)

一方、テーブル名を指定できないコネクターの場合は、次のルールに基づいて自動的にテーブル名やカラム名が決定されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/e51901b2-a309-4441-a69d-0d1f0d8cb05e.png)

出所：[How to build a data stack \| Fivetran connector strategy](https://fivetran.com/docs/core-concepts#tableandcolumnnamingrulesetfornondatabaseconnectors)

#### テーブルおよびカラムに関する命名規則に関する検証

以下の CSV を同期したところ、下記のテーブルが作成されました。

```csv
"My_Name_001","My Name_002","MyName","mYName","MyName123","My123name","My_Name!","My_Name____c","1MyName","!MyName","résumé","カタカナ","漢字","UPERCASE"
"sample1","sample2","sample3","sample4","sample5","sample6","sample7","sample8","sample9","sample10","sample12","sample13","sample14","sample15
```

```sql
%sql
CREATE TABLE azure_blob_storage.test_data (
  my_name_001 STRING,
  my_name_002 STRING,
  my_name STRING,
  m_yname STRING,
  my_name_123 STRING,
  my_123_name STRING,
  my_name_ STRING,
  my_name_c STRING,
  _1_my_name STRING,
  _my_name STRING,
  resume STRING,
  katakana STRING,
  han_zi STRING,
  upercase STRING,
  _file STRING,
  _line BIGINT,
  _modified TIMESTAMP,
  _fivetran_synced TIMESTAMP
);
```

カラム名は以下のように変換されました。

| #  | ソースカラム           | Destination カラム | 備考・変換例                                                                              |
|----|-----------------------|--------------------|-------------------------------------------------------------------------------------------|
| 1  | My_Name_001          | my_name_001        | 大文字を小文字に変換。アンダースコアはそのまま維持                                         |
| 2  | My Name_002          | my_name_002        | スペースをアンダースコアに変換し、小文字に                                                |
| 3  | MyName               | my_name            | キャメルケースをスネークケースへ変換                                                      |
| 4  | mYName               | m_yname            | 途中の大文字前にアンダースコアを付加し、小文字化                                          |
| 5  | MyName123            | my_name_123        | 英文字と数字の境界でアンダースコアを付加し、小文字化                                      |
| 6  | My123name            | my_123_name        | 数字部分を分割しアンダースコアを付加、小文字化                                            |
| 7  | My_Name!             | my_name_           | 特殊文字「!」を除去                                                                       |
| 8  | My_Name____c         | my_name_c          | 連続するアンダースコアをまとめ、小文字化                                                 |
| 9  | 1MyName              | _1_my_name         | 先頭が数字の場合、さらに先頭にアンダースコアを追加。キャメルケースはスネークケースへ       |
| 10 | !MyName              | _my_name           | 先頭の「!」をアンダースコアに置換し、キャメルケースをスネークケース化                     |
| 11 | résumé               | resume             | アクセント記号（é）を除去し、小文字化                                                    |
| 12 | カタカナ             | katakana           | カタカナをローマ字に変換                                                                 |
| 13 | 漢字                 | han_zi             | 漢字をピンイン表記へ変換し、単語の境界にアンダースコア                                    |
| 14 | UPERCASE             | upercase           | 大文字を小文字に変換                                                                     |

## ソースのカラム名称に変更する方法

### ビューによる名称変更

ソースのテーブル名やカラム名をどうしてもソースと同じにしたい場合には、ビューで名称を再定義する方法があります。下記例では、Fivetran で同期したテーブルをベースに、ソースカラム名へ変換するビューを作成しています。

```sql
%sql
CREATE OR REPLACE VIEW `!fivetran_naming_表`
AS
SELECT 
  my_name_001 AS `My_Name_001`,
  my_name_002 AS `my name_002`,
  myname_003 AS `MyName_003`,
  myname123_004 AS `Myname123_004`,
  my123name123_005 AS `My123name123_005`,
  my_name_ AS `My_Name!`,
  my_name____c AS `My_Name____c`,
  `1myname_008` AS `1MyName_008`,
  __myname_009 AS `!MyName_009`,
  katakana AS `カタカナ`,
  han_zi AS `漢字`,
  fa_zhu_ming_xi_fan_hao AS `発注明細番号`,
  myname_with_accents AS `mynamé_with_accents`,
  upercase AS `UPERCASE`,
  a123456789_b123456789_c1234567890_d123456789_e123456789_f123456789_g123456789_h123456789_i123456789_j123456789_k123456789_l123456789_m123456789_n123456789 
       AS `A123456789_B123456789_C1234567890_D123456789_E123456789_F123456789_G123456789_H123456789_I123456789_J123456789_K123456789_L123456789_M123456789_N123456789`
FROM dbx_01_fivetran_source.__fivetran_naming_biao;
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/d7f815ec-e084-4d1c-a7c2-1808295be05e.png)

Fivetran Platform Connector で同期されたメタデータを利用すれば、下記のようにマッピング情報（ソースカラムと宛先カラムの対応）を取得できます。

```sql
%sql
SELECT
  cn.connection_name AS connector_name,
  st.name AS source_table,
  s.name AS source_column,
  dt.name AS destination_table,
  d.name AS destination_column
FROM
  fivetran_metadata.COLUMN_LINEAGE cl
    JOIN fivetran_metadata.SOURCE_COLUMN_METADATA s
      ON cl.source_column_id = s.id
    JOIN fivetran_metadata.DESTINATION_COLUMN_METADATA d
      ON cl.destination_column_id = d.id
    JOIN fivetran_metadata.SOURCE_TABLE_METADATA st
      ON s.table_id = st.id
    JOIN fivetran_metadata.DESTINATION_TABLE_METADATA dt
      ON d.table_id = dt.id
    JOIN fivetran_metadata.connection cn
      on s.connection_id = cn.connection_id
WHERE
  cn.connection_name = 'dbx_01'
  AND st.name = '!fivetran_naming_表';
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/93878e8a-2934-4f40-8da6-69c22947257d.png)

Fivetran Platform Connector の詳細は下記を参照してください。Fivetran のコネクターが生成する MAR（Monthly Active Rows）は無償であることや、ER 図なども記述されています。

- [Fivetran Platform Connector](https://fivetran.com/docs/logs/fivetran-platform)

> IMPORTANT: The MAR that Fivetran Platform connections generate is free, though you may incur costs in your destination. Learn more in our pricing documentation.

出所：[Fivetran Platform Connector](https://fivetran.com/docs/logs/fivetran-platform)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/24031/596b428d-d96e-47e8-a9e5-665d514112ea.png)

出所：[Fivetran Platform Connector](https://fivetran.com/docs/logs/fivetran-platform)