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

# 7.15.38. `vector_find`

## 7.15.38.1. 概要

Added in version 8.0.4.

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

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

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

    plugin_register functions/vector

## 7.15.38.2. 構文

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

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

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

## 7.15.38.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.38.4. 引数

必須の引数は2つです。

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

### 7.15.38.4.1. 必須引数

`vector` と `value` は必須です。

#### 7.15.38.4.1.1. `vector`

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

#### 7.15.38.4.1.2. `value`

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

### 7.15.38.4.2. 省略可能引数

`mode` は省略可能です。

#### 7.15.38.4.2.1. `mode`

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

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

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

## 7.15.38.5. 戻り値

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