7.3.11. column_create

7.3.11.1. 概要

column_create はテーブルに新しいカラムを作成します。

1つのレコードに複数の値を保存したい場合は1つ以上カラムを作成する必要があります。

Groongaはインデックスをカラムとして提供しています。これは他のシステムと異なります。他のシステムではインデックスはインデックスです。インデックスをカラムとして実装していることで高い柔軟性を実現しています。たとえば、各トークンにメタデータを追加することができます。

カラムの詳細は カラム を見てください。

7.3.11.2. 構文

このコマンドにはたくさんの引数があります。

多くの引数は必須です:

column_create table
              name
              flags
              type
              [source=null]

7.3.11.3. 使い方

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

以下は People テーブルの定義です。例ではこの People テーブルを使います。

実行例:

table_create \
  --name People \
  --flags TABLE_HASH_KEY \
  --key_type ShortText
# [[0, 1337566253.89858, 0.000355720520019531], true]

7.3.11.3.1. スカラーカラムを作成

Groongaは1つの値を保存する用途としてスカラーカラムを提供しています。たとえば、「人」レコードに「年齢」情報を保存するときはスカラーカラムが適切です。なぜなら「人」レコードは「年齢」を1つだけ持つからです。

1つのレコードに複数の値を保存したい場合には、スカラーカラムは適していません。代わりに ベクターカラムを作成 を使ってください。

スカラーカラムを作成するには flags 引数に COLUMN_SCALAR を指定します。

以下は People テーブルに age カラムを作成する例です。 age カラムはスカラーカラムです。このカラムには UInt80-255 )の値を1つ保存できます。

実行例:

column_create \
  --table People \
  --name age \
  --flags COLUMN_SCALAR \
  --type UInt8
# [[0, 1337566253.89858, 0.000355720520019531], true]

以下の load コマンドで1つの値( 7 )を保存できます。

実行例:

load --table People
[
{"_key": "alice", "roles": ["adventurer", "younger-sister"]}
]
# [[0, 1337566253.89858, 0.000355720520019531], 1]

以下の select コマンドで保存された1つの値( 7 )を確認できます。

実行例:

select --table People
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         1
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "age",
#           "UInt8"
#         ]
#       ],
#       [
#         1,
#         "alice",
#         7
#       ]
#     ]
#   ]
# ]

7.3.11.3.2. ベクターカラムを作成

Groongaは複数の値を保存する用途としてベクターカラムを提供しています。たとえば、「人」レコードに複数の「役割」を保存する場合はベクターカラムが適切です。なぜなら「人」レコードは複数の「役割」を持つかもしれないからです。

もし1つのレコードに値を1つだけ保存したい場合はベクターカラムは向いていません。代わりに スカラーカラムを作成 を使ってください。

ベクターカラムを作成するには flags パラメーターに COLUMN_VECTOR を指定します。

以下は People テーブルに roles カラムを作成する例です。 roles カラムはベクターカラムです。カラムの値として0個以上の ShortText の値を保存できます。

実行例:

column_create \
  --table People \
  --name roles \
  --flags COLUMN_VECTOR \
  --type ShortText
# [[0, 1337566253.89858, 0.000355720520019531], true]

以下の load コマンドで複数の値( ["adventurer", "younger-sister"] )を保存できます。

実行例:

load --table People
[
{"_key": "alice", "roles": ["adventurer", "younger-sister"]}
]
# [[0, 1337566253.89858, 0.000355720520019531], 1]

保存した複数の値( ["adventurer", "younger-sister"] )は以下の select コマンドで確認できます。

実行例:

select --table People
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         1
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "age",
#           "UInt8"
#         ],
#         [
#           "roles",
#           "ShortText"
#         ]
#       ],
#       [
#         1,
#         "alice",
#         7,
#         [
#           "adventurer",
#           "younger-sister"
#         ]
#       ]
#     ]
#   ]
# ]

7.3.11.3.3. 重み付きベクターカラムの作成

TODO: See also 重み付きベクターカラム and adjuster.

7.3.11.3.4. テーブルのレコードを参照するカラムを作成

スカラーカラムもベクターカラムも既存のテーブルのレコードへの参照を保存することができます。これはレコード間の参照関係を保存する場合に便利です。

たとえば、「本」レコードで登場人物を保存する場合は、「人」レコードを参照するカラムを使うとよいです。なぜなら、同じ「人」が複数の本に登場するかもしれないからです。

テーブルのレコードを参照するカラムを作成するには type パラメーターに参照するテーブルの名前を指定します。

以下は Books テーブルに character カラムを作成する例です。 character カラムは People テーブルを参照しています。 character カラムには People テーブルのレコードを1つ保存できます。

以下が Books テーブルの定義です。

実行例:

table_create \
  --name Books \
  --flags TABLE_HASH_KEY \
  --key_type ShortText
# [[0, 1337566253.89858, 0.000355720520019531], true]

以下は Books テーブルにある character カラムの定義です。 --type People がポイントです。

実行例:

column_create \
  --table Books \
  --name character \
  --flags COLUMN_SCALAR \
  --type People
# [[0, 1337566253.89858, 0.000355720520019531], true]

以下の load コマンドで1つの参照( "alice" )を保存できます。レコードを参照するにはキーの値( People._key の値)を使います。

実行例:

load --table Books
[
{"_key": "Alice's Adventure in Wonderland", "character": "alice"}
]
# [[0, 1337566253.89858, 0.000355720520019531], 1]

保存した参照( "alice" レコード)は以下の select コマンドで確認できます。以下の例では age カラムの値と roles カラムの値を取得しています。

実行例:

select \
 --table Books \
 --output_columns _key,character._key,character.age,character.roles
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         1
#       ],
#       [
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "character._key",
#           "ShortText"
#         ],
#         [
#           "character.age",
#           "UInt8"
#         ],
#         [
#           "character.roles",
#           "ShortText"
#         ]
#       ],
#       [
#         "Alice's Adventure in Wonderland",
#         "alice",
#         7,
#         [
#           "adventurer",
#           "younger-sister"
#         ]
#       ]
#     ]
#   ]
# ]

7.3.11.3.5. インデックスカラムを作成

Groongaは高速に検索する用途としてインデックスカラムを提供しています。インデックスカラムはあなたのデータを保存しません。インデックスカラムは高速な検索に必要なデータを保存します。

インデックスカラムは自分で更新する必要はありません。インデックス対象のデータカラム(スカラーカラムまたはベクターカラム)にデータを入れると、インデックスカラムは自動で更新されます。1つのインデックスカラムに複数のインデックス対象のカラムを指定することもできます。

もし、 People テーブルの age カラム用のインデックスカラムがあると、 age カラムの値に対する完全一致検索・比較検索・範囲検索を高速に処理することができます。

インデックスカラムを作成するには次のパラメーターを指定します。

  • flags パラメーター: COLUMN_INDEX

  • type パラメーター: インデックス対象カラムのテーブル名(たとえば People

  • source パラメーター:インデックス対象カラム名(たとえば age

完全一致検索・比較検索・範囲検索用のインデックスカラムには flags パラメーターに追加のフラグは必要ありません。全文検索用のインデックスカラム、マルチカラムインデックスカラムには追加のフラグが必要になります。詳細は 全文検索用のインデックスカラムを作成マルチカラムインデックスカラムを作成 を見てください。

以下は People テーブルの age カラム用のインデックスカラムを作成する例です。

はじめに範囲インデックスカラム用のテーブルを作成します。詳細は 範囲検索用のインデックステーブルの作成 を見てください。この例では TABLE_PAT_KEY として Ages テーブルを作成します。

実行例:

table_create \
  --name Ages \
  --flags TABLE_PAT_KEY \
  --key_type UInt8
# [[0, 1337566253.89858, 0.000355720520019531], true]

これで People テーブルの age カラム用のインデックスカラムを作れるようになりました。 flags パラメーターの COLUMN_INDEXtype パラメーターの Peoplesource パラメーターの age がポイントです。

実行例:

column_create \
  --table Ages \
  --name people_age_index \
  --flags COLUMN_INDEX \
  --type People \
  --source age
# [[0, 1337566253.89858, 0.000355720520019531], true]

ログを確認すると、新しく作成した Ages.people_age_index インデックスカラムを使って age > 5 を評価していることがわかります。Groongaは使用したインデックスカラムを info ログレベルでログに出力します。ログレベルは log_level コマンドを使うと動的に変更できます。

実行例:

log_level --level info
# [[0, 1337566253.89858, 0.000355720520019531], true]
select \
  --table People \
  --filter 'age > 5'
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         1
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "age",
#           "UInt8"
#         ],
#         [
#           "roles",
#           "ShortText"
#         ]
#       ],
#       [
#         1,
#         "alice",
#         7,
#         [
#           "adventurer",
#           "younger-sister"
#         ]
#       ]
#     ]
#   ]
# ]
# log: 2016-10-13 19:10:02.292711|i| [table][select][index][range] <Ages.people_age_index>
log_level --level notice
# [[0, 1337566253.89858, 0.000355720520019531], true]

以下のログから Ages.people_age_index が使われたことを確認できます。

[table][select][index][range] <Ages.people_age_index>

このログは範囲検索に Ages.people_age_index インデックスカラムを使ったことを示しています。

7.3.11.3.7. マルチカラムインデックスカラムを作成

複数のカラム用のインデックスカラムを作成できます。これは1つのインデックスカラムで複数のカラムに対して高速に検索できるということです。インデックス対象の複数のカラムが多くの同じトークンを共有しているときは、マルチカラムインデックスカラムはシングルカラムインデックスカラムよりも空間効率がよくなります。一方、検索速度はシングルカラムインデックスカラムの方が速くなることが多いです。理由はマルチカラムインデックスカラムは大きくなりがちだからです。

1つのマルチカラムインデックスカラムで、異なるテーブルの複数のカラムをインデックス対象にすることはできません。1つのマルチカラムインデックスカラムでは同じテーブルの複数のカラムをインデックス対象に指定してください。たとえば、 People._keyBooks._key をインデックス対象としたマルチカラムインデックスカラムは作成できません。なぜなら、違うテーブルのカラムだからです。 People._keyPeople.roles をインデックス対象としたマルチカラムインデックスカラムは作成できます。なぜなら同じテーブルのカラムだからです。

シングルカラムインデックスカラムとマルチカラムインデックスカラムでは違いがあります。マルチカラムインデックスカラムのときは flags パラメーターに WITH_SECTION を追加しなければいけません。つまり、 flags パラメーターに COLUMN_INDEX|WITH_SECTION と指定するということです。これが違いです。

全文検索用のマルチカラムインデックスカラムを作成する場合は flags パラメーターに COLUMN_INDEX|WITH_POSITION|WITH_SECTION と指定します。全文検索インデックスカラムの詳細は 全文検索用のインデックスカラムを作成 を見てください。

以下は People テーブルのキーと roles カラム用のマルチカラム全文検索インデックスカラムを作成する例です。

インデックス用のテーブルは、シングルカラムインデックスとマルチカラムインデックスカラムで違いはありません。この例では 全文検索用のインデックスカラムを作成 で使った Terms テーブルを使います。

People テーブルのキーと roles カラム用のマルチカラム全文検索インデックスカラムを作成します。 flags パラメーターの COLUMN_INDEX|WITH_POSITION|WITH_SECTIONtype パラメーターの Peoplesource パラメーターの _key,roles がポイントです。

実行例:

column_create \
  --table Terms \
  --name people_key_roles_index \
  --flags COLUMN_INDEX|WITH_POSITION|WITH_SECTION \
  --type People \
  --source _key,roles
# [[0, 1337566253.89858, 0.000355720520019531], true]

ログを確認すると、新しく作成した Terms.people_key_roles_index マルチカラム全文検索インデックスカラムを使って --match_columns _key--query Alice を評価していることがわかります。Groongaは使用したインデックスカラムを info ログレベルでログに出力します。ログレベルは log_level コマンドを使うと動的に変更できます。

実行例:

log_level --level info
# [[0, 1337566253.89858, 0.000355720520019531], true]
select \
  --table People \
  --match_columns _key,roles \
  --query Alice
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         1
#       ],
#       [
#         [
#           "_id",
#           "UInt32"
#         ],
#         [
#           "_key",
#           "ShortText"
#         ],
#         [
#           "age",
#           "UInt8"
#         ],
#         [
#           "roles",
#           "ShortText"
#         ]
#       ],
#       [
#         1,
#         "alice",
#         7,
#         [
#           "adventurer",
#           "younger-sister"
#         ]
#       ]
#     ]
#   ]
# ]
# log: 2016-10-13 19:10:03.513171|i| [object][search][index][key][exact] <Terms.people_key_roles_index>
# log: 2016-10-13 19:10:03.513194|i| grn_ii_sel > (Alice)
# log: 2016-10-13 19:10:03.513219|i| n=1 (Alice)
# log: 2016-10-13 19:10:03.513247|i| exact: 1
# log: 2016-10-13 19:10:03.513251|i| hits=1
log_level --level notice
# [[0, 1337566253.89858, 0.000355720520019531], true]

以下のログから Terms.people_roles_index を使ったことを確認できます。

[object][search][index][key][exact] <Terms.people_key_roles_index>

このログは全文検索に Terms.people_roles_index インデックスカラムを使ったことを示しています。(正確に言うと転置索引を使った完全一致検索にこのインデックスカラムを使っています。)

7.3.11.3.8. 小さなインデックスカラムを作成

もし、インデックス対象のデータが小さいことがわかっているならインデックスカラムが使用するメモリー量を減らせます。デフォルトのインデックスカラムと比べて 1/256 のメモリー使用量になります。

ではどのくらいのデータなら小さいのでしょうか。それはデータによります。小さなインデックスカラムは少なくとも10億レコードを扱えません。もし、インデックス対象がテキスト系の型(ShortTextTextLongText のどれか)ではないスカラーカラムだけの場合、扱える最大レコード数はインデックス対象のデータの種類に依存します。もし、インデックス対象のカラムに 1123 というデータが入っていたとすると、種類数は 3123 )になります。以下の表はインデックス対象データの種類数と扱える最大レコード数の関係を示しています。

インデックス対象データの種類数と小さなインデックスカラムで扱えるレコード数

インデックス対象のデータの種類数

処理できるレコード数

1 16779234
2 4648070
4 7238996
8 8308622
16 11068624
32 12670817
64 18524211
128 38095511
256 51265384

小さなインデックスカラムを作成するには COLUMN_INDEX|INDEX_SMALL というように flags パラメーターに INDEX_SMALL を追加します。

People テーブルが100万レコードしかないなら、 age カラム用に小さなインデックスカラムを使うことができます。

実行例:

column_create \
  --table Ages \
  --name people_age_small_index \
  --flags COLUMN_INDEX|INDEX_SMALL \
  --type People \
  --source age
# [[0, 1337566253.89858, 0.000355720520019531], true]

7.3.11.3.9. 中サイズのインデックスカラムを作成

インデックス対象のデータが中サイズならインデックスカラムが使うメモリー使用量を減らすことができます。デフォルトのインデックスカラムよりも 5/24 のメモリー使用量になります。

どのくらいのデータが中サイズのデータでしょうか。それはデータによります。

もし、インデックス対象がスカラーカラム1つだけであれば、中サイズのインデックスカラムはすべてのレコードを処理できます。

以下のケースでは中サイズのインデックスカラムはすべてのレコードを処理できないかもしれません。

  • インデックス対象がテキスト系の型( ShortTextTextLongText のどれか)のスカラーカラム1つ

  • インデックス対象がベクターカラム1つ

  • インデックス対象が複数のカラム

  • インデックステーブルにトークナイザーが付いている

中サイズのインデックスカラムを作成するには COLUMN_INDEX|INDEX_MEDIUM というように flags パラメーターに INDEX_MEDIUM を追加します。

People テーブルの age カラム用のインデックスカラムであれば中サイズのインデックスカラムでも安全です。なぜなら、 UInt8 型のスカラーカラム1つだからです。

以下は中サイズのインデックスカラムを作る例です。

実行例:

column_create \
  --table Ages \
  --name people_age_medium_index \
  --flags COLUMN_INDEX|INDEX_MEDIUM \
  --type People \
  --source age
# [[0, 1337566253.89858, 0.000355720520019531], true]

7.3.11.4. 引数

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

7.3.11.4.1. 必須引数

いくつか必須の引数があります。

7.3.11.4.1.1. table

新しいカラムを追加する対象となる既存のテーブル名を指定します。

7.3.11.4.1.2. name

作成するカラム名を指定します。

カラム名は同じテーブル内で一意でなければいけません。

利用可能な文字は以下の通りです。

  • 0 .. 9 (数字)

  • a .. z (アルファベット。小文字)

  • A .. Z (アルファベット。大文字)

  • # (シャープ)

  • @ (アットマーク)

  • - (ハイフン)

  • _ (アンダースコア)(注: 最初の文字としてアンダースコアを使うことはできません。)

上記の文字を1つ以上使って名前を決めます。 _name というように、最初の文字に _ を使えないことに注意してください。

7.3.11.4.1.3. flags

カラムの種類とカラムをカスタマイズするオプションを指定します。

指定可能なフラグは以下の通りです。

フラグ

説明

COLUMN_SCALAR

スカラーカラム。値を1つ保存できます。 スカラーカラム あるいは スカラーカラムを作成 も見てください。

COLUMN_VECTOR

ベクターカラム。複数の値を保存できます。 ベクターカラム あるいは ベクターカラムを作成 も見てください。

COLUMN_INDEX

インデックスカラム。高速に検索するためのデータを保存します。 インデックスカラム あるいは インデックスカラムを作成 も見てください。

COMPRESS_ZLIB

zlibを使ったカラム値圧縮機能を有効にします。zlibサポート付きのGroongaが必要です。

zlibを使った圧縮はLZ4を使った圧縮よりも空間効率がよいです。しかし、zlibを使った圧縮はLZ4を使った圧縮よりも遅いです。

このフラグは COLUMN_SCALARCOLUMN_VECTOR でだけ使えます。

COMPRESS_LZ4

LZ4を使ったカラム値圧縮機能を有効にします。LZ4サポート付きのGroongaが必要です。

LZ4を使った圧縮はzlibを使った圧縮よりも速いです。しかし、LZ4を使った圧縮はzlibを使った圧縮よりも空間効率が低いです。

このフラグは COLUMN_SCALARCOLUMN_VECTOR でだけ使えます。

WITH_SECTION

インデックスカラムのセクションサポートを有効にします。

セクションサポートが有効になると、同じインデックスカラムで複数の文書をサポートできます。

マルチカラムインデックスカラムを作成するときはこのフラグを指定しなければいけません。詳細は マルチカラムインデックスカラムを作成 を見てください。

セクションサポートを有効にするとインデックスカラムが使う領域が増えます。セクションサポートが必要ない場合は有効にしないでください。

このフラグは COLUMN_INDEX でだけ有効です。

WITH_WEIGHT

ベクターカラム・インデックスカラムの重みサポートを有効にします。

ベクターカラムの重みサポートを有効にすると各要素に重みを追加できます。インデックスカラムの重みサポートを有効にすると各ポスティングに重みを追加できます。これらは検索スコアの調整に役立ちます。

adjuster を使う場合はこのフラグを指定します。詳細は 重み付きベクターカラムの作成 を見てください。

重みをサポートすると使用する領域が増えます。重みが必要ない場合は有効にしないでください。

COLUMN_VECTORCOLUMN_INDEX でだけこのフラグは有効です。

WITH_POSITION

インデックスカラムの位置情報サポートを有効にします。これはインデックスカラムを完全転置インデックスにするということです。(インデックスカラムは転置インデックスとして実装されています。)

位置情報サポートが有効だと各ポスティングにドキュメントでの出現位置を追加できます。この情報はフレーズ検索をするときに必要になります。全文検索用のインデックスは位置情報サポートを有効にしなければいけません。なぜなら、全文検索はフレーズ検索を使うからです。

全文検索インデックスカラムを作成するときはこのフラグを指定してください。詳細は 全文検索用のインデックスカラムを作成 を見てください。

位置情報をサポートすると使用する領域が増えます。位置情報サポートが必要ない場合は有効にしないでください。

このフラグは COLUMN_INDEX でだけ有効です。

INDEX_SMALL

バージョン 6.0.8 で追加.

小さなインデックスを作成するときに指定します。

インデックス対象のデータが小さいときは小さなインデックスカラムで十分です。小さなインデックスカラムは通常のインデックスカラム・中サイズのインデックスカラムよりも使用メモリーが少ないです。「小さいデータ」とはなにか、このフラグをどうやって使えばよいかは 小さなインデックスカラムを作成 を見てください。

このフラグは COLUMN_INDEX でだけ有効です。

INDEX_MEDIUM

バージョン 6.0.8 で追加.

中サイズのインデックスカラムを作成するときに指定します。

インデックス対象のデータが中サイズなら中サイズのインデックスカラムで十分です。中サイズのインデックスカラムは通常のインデックスカラムよりも使用メモリー量が少ないです。「中サイズのデータ」とはなにか、このフラグをどうやって使えばよいかは 中サイズのインデックスカラムを作成 を見てください。

このフラグは COLUMN_INDEX でだけ有効です。

COLUMN_${TYPE} フラグのどれかを必ず指定します。2つ以上の COLUMN_${TYPE} フラグを指定してはいけません。たとえば、 COLUMN_SCALAR|COLUMN_VECTOR は不正な指定です。

WITH_SECTION|WITH_POSITION というように、 | (縦棒)で複数のフラグを組み合わせることができます。

7.3.11.4.1.4. type

カラムの値の型を指定します。

カラムがスカラーカラムかベクターカラムなら利用可能な型は次の通りです。

  • データ型 で説明している組み込みの型

  • ユーザーが定義したテーブル

カラムがインデックスカラムのときの利用可能な型は次の通りです。

  • ユーザーが定義したテーブル

以下も見てください。

7.3.11.4.2. 省略可能引数

省略可能な引数があります。

7.3.11.4.2.1. source

インデックス対象のカラムを指定します。 source パラメーターには1つ以上のカラムを指定できます。

このパラメーターはインデックスカラムでだけ利用可能です。

type で指定したテーブルのカラムだけ指定できます。テーブルのキーをインデックス対象にしたい場合は _key 疑似カラムを指定します。

source パラメーターに複数のカラムを指定するときは _key,roles というように , (コンマ)で区切ります。

7.3.11.5. 戻り値

column_create が成功したときは以下のようにボディは true になります:

[HEADER, true]

column_create が失敗したときはボディは false になります:

[HEADER, false]

HEADER にエラーの詳細が含まれます。

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