7.15.31. vector_find

7.15.31.1. 概要

バージョン 8.0.4 で追加.

指定したベクターから指定した条件にマッチする最初の要素を返します。どの要素もマッチしない場合は null を返します。

等価条件だけでなく以下条件や前方一致条件なども使えます。

この関数を有効にするには、以下のコマンドで functions/vector プラグインを登録します。:

plugin_register functions/vector

7.15.31.2. 構文

vector_find のパラメーター数は2つまたは3つです。:

vector_find(vector, value)
vector_find(vector, value, mode)

3番目の引数を省略すると、 vector 内の各要素と value の比較には等価条件を使います。

7.15.31.3. 使い方

まず functions/vector プラグインを登録します。

実行例:

plugin_register functions/vector
# [[0, 1337566253.89858, 0.000355720520019531], true]

使い方を示すために使うスキーマ定義とサンプルデータは以下の通りです。

サンプルスキーマ:

実行例:

table_create  Memos TABLE_HASH_KEY ShortText
# [[0, 1337566253.89858, 0.000355720520019531], true]
column_create Memos tags COLUMN_VECTOR ShortText
# [[0, 1337566253.89858, 0.000355720520019531], true]

サンプルデータ:

実行例:

load --table Memos
[
{"_key": "Groonga is fast",          "tags": ["groonga"]},
{"_key": "Mroonga is fast",          "tags": ["mroonga", "groonga"]},
{"_key": "Groonga is very good!",    "tags": ["groonga"]},
{"_key": "Droonga is fast",          "tags": ["droonga", "groonga"]},
{"_key": "Groonga is a HTTP server", "tags": ["groonga", "http"]}
]
# [[0, 1337566253.89858, 0.000355720520019531], 5]

以下は vector_find の簡単な使い方です。この使い方では tags カラム内の要素を検索して最初に見つかった要素を返します。

実行例:

select \
  --table Memos \
  --output_columns 'tags, vector_find(tags, "mroonga")'
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         5
#       ],
#       [
#         [
#           "tags",
#           "ShortText"
#         ],
#         [
#           "vector_find",
#           null
#         ]
#       ],
#       [
#         [
#           "groonga"
#         ],
#         null
#       ],
#       [
#         [
#           "mroonga",
#           "groonga"
#         ],
#         "mroonga"
#       ],
#       [
#         [
#           "groonga"
#         ],
#         null
#       ],
#       [
#         [
#           "droonga",
#           "groonga"
#         ],
#         null
#       ],
#       [
#         [
#           "groonga",
#           "http"
#         ],
#         null
#       ]
#     ]
#   ]
# ]

この例では tags カラムの中に "mroonga" がある場合は "mroonga" を返し、そうでない場合は null を返しています。

3番目の引数でそれぞれの値をどうやって比較するかをカスタマイズできます。以下は要素の検索に全文検索を使う例です。

実行例:

select \
  --table Memos \
  --output_columns 'tags, vector_find(tags, "roonga", "@")'
# [
#   [
#     0,
#     1337566253.89858,
#     0.000355720520019531
#   ],
#   [
#     [
#       [
#         5
#       ],
#       [
#         [
#           "tags",
#           "ShortText"
#         ],
#         [
#           "vector_find",
#           null
#         ]
#       ],
#       [
#         [
#           "groonga"
#         ],
#         "groonga"
#       ],
#       [
#         [
#           "mroonga",
#           "groonga"
#         ],
#         "mroonga"
#       ],
#       [
#         [
#           "groonga"
#         ],
#         "groonga"
#       ],
#       [
#         [
#           "droonga",
#           "groonga"
#         ],
#         "droonga"
#       ],
#       [
#         [
#           "groonga",
#           "http"
#         ],
#         "groonga"
#       ]
#     ]
#   ]
# ]

この例では tags カラム内に "groonga""mroonga""droonga" のどれかが含まれていれば、最初に見つかったその値を返します。たとえば、 ["droonga", "groonga"] の場合は "droonga" を返します。 "groonga" は返しません。なぜなら、2つ目の要素である "groonga" を検索する前に最初の要素である "droonga" がマッチするからです。

この例では tags カラム内に "groonga""mroonga""droonga" のどの値も含まれていない場合は null を返します。

7.15.31.4. 引数

必須の引数は2つです。

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

7.15.31.4.1. 必須引数

vectorvalue は必須です。

7.15.31.4.1.1. vector

検索対象のベクターを指定します。

7.15.31.4.1.2. value

比較対象の値を指定します。

7.15.31.4.2. 省略可能引数

mode は省略可能です。

7.15.31.4.2.1. mode

value と各要素を比較する方法(モード)を指定します。

利用可能なモード名は default_mode を見てください。 "NEAR""SIMILAR""SUFFIX" 以外のすべてのモード名をサポートしています。

デフォルトのモードは "EQUAL" です。 default_mode ではデフォルトのモードは "MATCH" ですが、 vector_find のデフォルトのモードは "EQUAL" です。

7.15.31.5. 戻り値

マッチした場合はマッチした要素。マッチしない場合は null