7.3.12. column_copy — Groonga v16.0.2ドキュメント

本文へスキップ
`Ctrl`+`K`

# 7.3.12. `column_copy`

## 7.3.12.1. 概要

Added in version 5.0.7.

`column_copy` はカラムのすべての値を他のカラムにコピーします。

このコマンドを使うと、次のような機能を実装できます。

> - カラムの設定を変更

> - テーブルの設定を変更

次のステップでカラムの設定を変更できます。

> 1. 新しい設定で新しいカラムを作る

> 2. 現在のカラムから新しいカラムへすべての値をコピーする

> 3. 現在のカラムを削除する

> 4. 新しいカラムを現在のカラムにリネームする

次のステップでテーブルの設定を変更できます。

> 1. 新しい設定で新しいテーブルを作る

> 2. すべてのカラムを同じ設定で新しいテーブルに作る

> 3. 現在のテーブルから新しいテーブルへすべてのカラムの値をコピーする

> 4. 現在のテーブルを削除する

> 5. 新しいテーブルを現在のテーブルにリネームする

具体例は後で示します。

`TABLE_NO_KEY` テーブルから他のテーブルにカラムの値をコピーすることはできません。また、他のテーブルから `TABLE_NO_KEY` テーブルにカラムの値をコピーすることもできません。これは、レコードのキーがないとどのレコードとどのレコードを対応させればよいか決められないからです。

`TABLE_NO_KEY` テーブルから同じ `TABLE_NO_KEY` テーブルにカラムの値をコピーすることはできます。

`TABLE_HASH_KEY` / `TABLE_PAT_KEY` / `TABLE_DAT_KEY` テーブルから他の `TABLE_HASH_KEY` / `TABLE_PAT_KEY` / `TABLE_DAT_KEY` テーブルにカラムの値をコピーすることができます。同じテーブルに対してもできます。

## 7.3.12.2. 構文

このコマンドには4つの引数があります。

すべての引数は必須です:

    column_copy from_table
                from_name
                to_table
                to_name

## 7.3.12.3. 使い方

このコマンドのユースケースは次の通りです。

> - カラムの設定を変更

> - テーブルの設定を変更

### 7.3.12.3.1. カラムの設定の変更方法

カラムの値の型を変えることができます。たとえば、カラムの型を `UInt32` から `ShortText` に変えることができます。

カラムの種類を変えることができます。たとえば、 `COLUMN_SCALAR` カラムを `COLUMN_VECTOR` カラムに変えることができます。

カラムを他のテーブルに移動することができます。たとえば、 `high_score` カラムを `Players` テーブルから `Users` テーブルに移動できます。

カラムの設定を変更する基本的なステップは次の通りです。

> 1. 新しい設定で新しいカラムを作る

> 2. 現在のカラムから新しいカラムへすべての値をコピーする

> 3. 現在のカラムを削除する

> 4. 新しいカラムを現在のカラムにリネームする

カラムの値の型を `ShortText` から `Int32` に変更する例です。

スキーマ定義とサンプルデータは以下の通りです。

実行例:

    table_create Logs TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Logs serial COLUMN_SCALAR Int32
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Logs
    [
    {"_key": "log1", "serial": 1}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]

次のコマンドは `Logs.serial` カラムの値の型を `Int32` から `ShortText` に変えています。

実行例:

    column_create Logs new_serial COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_copy Logs serial Logs new_serial
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_remove Logs serial
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_rename Logs new_serial serial
    # [[0,1337566253.89858,0.000355720520019531],true]
    select Logs
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "serial",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "log1",
    #         "1"
    #       ]
    #     ]
    #   ]
    # ]

`select` のレスポンスを見ると `Logs.serial` が `ShortText` の値を保存していることがわかります。

カラムの種類を `COLUMN_SCALAR` から `COLUMN_VECTOR` に変更する例です。

スキーマ定義とサンプルデータは以下の通りです。

実行例:

    table_create Entries TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Entries tag COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Entries
    [
    {"_key": "entry1", "tag": "Groonga"}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]

次のコマンドは `Entries.tag` を `COLUMN_SCALAR` から `COLUMN_VECTOR` へ変更します。

実行例:

    column_create Entries new_tag COLUMN_VECTOR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_copy Entries tag Entries new_tag
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_remove Entries tag
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_rename Entries new_tag tag
    # [[0,1337566253.89858,0.000355720520019531],true]
    select Entries
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "tag",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         1,
    #         "entry1",
    #         [
    #           "Groonga"
    #         ]
    #       ]
    #     ]
    #   ]
    # ]

`select` のレスポンスを見ると、 `Entries.tag` が `COLUMN_VECTOR` の値を保存していることがわかります。

`high_score` カラムを `Players` テーブルから `Users` テーブルに移動する例です。

スキーマ定義とサンプルデータは以下の通りです。

実行例:

    table_create Players TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Players high_score COLUMN_SCALAR Int32
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Players
    [
    {"_key": "player1", "high_score": 100}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]

次のコマンドは `high_score` カラムを `Players` テーブルから `Users` テーブルに移動します。

実行例:

    table_create Users TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Users high_score COLUMN_SCALAR Int32
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_copy Players high_score Users high_score
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_remove Players high_score
    # [[0,1337566253.89858,0.000355720520019531],true]
    select Users
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "high_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         1,
    #         "player1",
    #         100
    #       ]
    #     ]
    #   ]
    # ]

`select` の結果を見ると、 `Players.high_score` を `Users.high_score` に移動できていることがわかります。

### 7.3.12.3.2. テーブルの設定の変更方法

テーブルのキーの型を変更できます。たとえば、キーの型を `Int32` から `ShortText` に変更できます。

テーブルの種類を変更できます。たとえば、 `TABLE_HASH_KEY` テーブルを `TABLE_PAT_KEY` テーブルに変更できます。

デフォルトトークナイザーやノーマライザーなど他のオプションも変更できます。たとえば、デフォルトトークナイザーを `TokenBigrm` から `TokenBigramSplitSymbolAlphaDigit` に変更できます。

注釈

`TABLE_NO_KEY` テーブルは変更できません。なぜなら、 `TABLE_NO_KEY` レコードのキーがないからです。レコードのキーがないとコピー先のレコードを特定することができません。

テーブルの設定を変更する基本的なステップは次の通りです。

> 1. 新しい設定で新しいテーブルを作る

> 2. すべてのカラムを同じ設定で新しいテーブルに作る

> 3. 現在のテーブルから新しいテーブルへすべてのカラムの値をコピーする

> 4. 現在のテーブルを削除する

> 5. 新しいテーブルを現在のテーブルにリネームする

テーブルのキーの型を `Int32` から `ShortText` に変更する例です。

スキーマ定義とサンプルデータは以下の通りです。

実行例:

    table_create IDs TABLE_HASH_KEY Int32
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create IDs label COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create IDs used COLUMN_SCALAR Bool
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table IDs
    [
    {"_key": 100, "label": "ID 100", used: true}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]

次のコマンドは `IDs` テーブルのキーの型を `Int32` から `ShortText` に変更します。

実行例:

    table_create NewIDs TABLE_HASH_KEY Int32
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create NewIDs label COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create NewIDs used COLUMN_SCALAR Bool
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_copy IDs label NewIDs label
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_copy IDs used  NewIDs used
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_remove IDs
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_rename NewIDs IDs
    # [[0,1337566253.89858,0.000355720520019531],true]
    select IDs
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "Int32"
    #         ],
    #         [
    #           "label",
    #           "ShortText"
    #         ],
    #         [
    #           "used",
    #           "Bool"
    #         ]
    #       ],
    #       [
    #         1,
    #         100,
    #         "ID 100",
    #         true
    #       ]
    #     ]
    #   ]
    # ]

`select` のレスポンスを見ると、 `IDs` は `ShortText` のキーを保存していることがわかります。

テーブルの種類を `TABLE_HASH_KEY` から `TABLE_PAT_KEY` に変更する例です。

スキーマ定義とサンプルデータは以下の通りです。

実行例:

    table_create Names TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Names used COLUMN_SCALAR Bool
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Names
    [
    {"_key": "alice", "used": false}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]

次のコマンドは `Names` テーブルを `TABLE_HASH_KEY` から `TABLE_PAT_KEY` に変更します。

実行例:

    table_create NewNames TABLE_PAT_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create NewNames used COLUMN_SCALAR Bool
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_copy Names used NewNames used
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_remove Names
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_rename NewNames Names
    # [[0,1337566253.89858,0.000355720520019531],true]
    select Names --filter '_key @^ "ali"'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "used",
    #           "Bool"
    #         ]
    #       ],
    #       [
    #         1,
    #         "alice",
    #         false
    #       ]
    #     ]
    #   ]
    # ]

`select` で 前方一致検索演算子 を使えているので、 `Names` が `TABLE_PAT_KEY` に変わったことがわかります。`TABLE_HASH_KEY` では 前方一致検索演算子 を使えません。

## 7.3.12.4. 引数

このセクションでは引数について説明します。

### 7.3.12.4.1. 必須引数

すべての引数は必須です。

#### 7.3.12.4.1.1. `from_table`

ソースカラムのテーブル名を指定します。

`TABLE_NO_KEY` テーブルを含むすべてのテーブルを指定できます。

`TABLE_NO_KEY` テーブルを指定するときは、 to_table には同じテーブルを指定しなければいけません。

`from_table` の使用例です。

スキーマ定義とサンプルデータは以下の通りです。

実行例:

    table_create FromTable TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create FromTable from_column COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create FromTable to_column   COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table FromTable
    [
    {"_key": "key1", "from_column": "value1"}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]
    select FromTable --output_columns _key,from_column,to_column
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "from_column",
    #           "ShortText"
    #         ],
    #         [
    #           "to_column",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "key1",
    #         "value1",
    #         ""
    #       ]
    #     ]
    #   ]
    # ]

すべての値を `from_column` から `to_column` にコピーできます。

実行例:

    column_copy FromTable from_column FromTable to_column
    # [[0,1337566253.89858,0.000355720520019531],true]
    select FromTable --output_columns _key,from_column,to_column
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "from_column",
    #           "ShortText"
    #         ],
    #         [
    #           "to_column",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "key1",
    #         "value1",
    #         "value1"
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.12.4.1.2. `from_name`

値をコピーするカラムの名前を指定します。

具体例は from_table を見てください。

#### 7.3.12.4.1.3. `to_table`

コピー先のカラムのテーブル名を指定します。

同じテーブル内でカラムの値をコピーしたいときは、 from_table に指定した名前と同じ名前を指定します。

`to_table` に `TABLE_NO_KEY` テーブルを指定することはできません。なぜなら、レコードのキーがないとGroongaはコピー先のレコードを特定できないからです。

例外が1つあります。 `from_table` と `to_table` に同じテーブル名を指定した場合は、 `to_table` に `TABLE_NO_KEY` テーブルを指定できます。なぜなら、コピー元テーブルとコピー先テーブルが同じテーブルならGroongaはコピー先のレコードを特定できるからです。

`to_table` を使った例です。

スキーマ定義とサンプルデータは以下の通りです。

実行例:

    table_create Table TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Table column COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_create ToTable TABLE_HASH_KEY ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create ToTable to_column COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Table
    [
    {"_key": "key1", "column": "value1"}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]

`Table.column` から `ToTable.to_column` にすべての値をコピーできます。

実行例:

    column_copy Table column ToTable to_column
    # [[0,1337566253.89858,0.000355720520019531],true]
    select ToTable --output_columns _key,to_column
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "to_column",
    #           "ShortText"
    #         ]
    #       ],
    #       [
    #         "key1",
    #         "value1"
    #       ]
    #     ]
    #   ]
    # ]

#### 7.3.12.4.1.4. `to_name`

コピー先のカラム名を指定します。

具体例は to_table を見てください。

### 7.3.12.4.2. 省略可能引数

省略可能な引数はありません。

## 7.3.12.5. 戻り値

このコマンドが成功したときは以下のようにボディは `true` になります:

    [HEADER, true]

このコマンドが失敗すると、 `HEADER` にエラーの詳細が含まれます。

`HEADER` については 出力形式 を参照してください。