`Ctrl`+`K`

# 7.15.17. `query`

## 7.15.17.1. 概要

`query` は、select の `--match_columns` と `--query` 引数の機能を関数として提供します。select の `--filter` 引数で複数の `query` 関数を指定することができます。

そのような柔軟性があるので、 複数の `query` 関数を組合せることで全文検索の振舞いを制御することができます。

`query` は select コマンドの `--filter` 内でのみ指定できます。

## 7.15.17.2. 構文

`query` は2つの引数が必要です。 `match_columns` と `query_string` です。

引数の `query_expander` と `options` は省略可能です。

    query(match_columns, query_string)
    query(match_columns, query_string, query_expander)
    query(match_columns, query_string, options)

`options` には以下のキーを指定します。すべてのキー・値のペアは省略可能です。:

    {
      "expander": query_expander,
      "default_mode": default_mode,
      "default_operator": default_operator,
      "flags": flags
    }

## 7.15.17.3. 使い方

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

サンプルスキーマ:

実行例:

    table_create Documents TABLE_NO_KEY
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Documents content COLUMN_SCALAR Text
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    table_create Terms TABLE_PAT_KEY ShortText --default_tokenizer TokenBigram  --normalizer NormalizerAuto
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Terms documents_content_index COLUMN_INDEX|WITH_POSITION Documents content
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    table_create Users TABLE_NO_KEY
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Users name COLUMN_SCALAR ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Users memo COLUMN_SCALAR ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    table_create Lexicon TABLE_HASH_KEY ShortText \
      --default_tokenizer TokenBigramSplitSymbolAlphaDigit \
      --normalizer NormalizerAuto
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Lexicon users_name COLUMN_INDEX|WITH_POSITION Users name
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    column_create Lexicon users_memo COLUMN_INDEX|WITH_POSITION Users memo
    # [[0, 1337566253.89858, 0.000355720520019531], true]

サンプルデータ:

実行例:

    load --table Users
    [
    {"name": "Alice", "memo": "groonga user"},
    {"name": "Alisa", "memo": "mroonga user"},
    {"name": "Bob",   "memo": "rroonga user"},
    {"name": "Tom",   "memo": "nroonga user"},
    {"name": "Tobby", "memo": "groonga and mroonga user. mroonga is ..."},
    ]
    # [[0, 1337566253.89858, 0.000355720520019531], 5]

`--match_columns` と `--query` 引数を使わずに、 `--filter` で `query` 関数を使ってキーワード `alice` を検索する簡単な使用例です。

実行例:

    select Users --output_columns name,_score --filter 'query("name * 10", "alice")'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "name",
    #           "ShortText"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Alice",
    #         10
    #       ]
    #     ]
    #   ]
    # ]

上記のクエリを実行する際、'alice'というキーワードには重みづけとして値 `10` を設定します。

`query` あり/なしで対照的な例がこちらです。

実行例:

    select Users --output_columns name,memo,_score --match_columns "memo * 10" --query "memo:@groonga OR memo:@mroonga OR memo:@user" --sort_keys -_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "name",
    #           "ShortText"
    #         ],
    #         [
    #           "memo",
    #           "ShortText"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Tobby",
    #         "groonga and mroonga user. mroonga is ...",
    #         4
    #       ],
    #       [
    #         "Alice",
    #         "groonga user",
    #         2
    #       ],
    #       [
    #         "Alisa",
    #         "mroonga user",
    #         2
    #       ],
    #       [
    #         "Bob",
    #         "rroonga user",
    #         1
    #       ],
    #       [
    #         "Tom",
    #         "nroonga user",
    #         1
    #       ]
    #     ]
    #   ]
    # ]

この場合、 `groonga` と `mroonga` と `user` というキーワードは同じ重みづけがされています。この方法ではキーワードごとに異なる重みづけを行うことはできません。

実行例:

    select Users --output_columns name,memo,_score --filter 'query("memo * 10", "groonga") || query("memo * 20", "mroonga") || query("memo * 1", "user")' --sort_keys -_score
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         5
    #       ],
    #       [
    #         [
    #           "name",
    #           "ShortText"
    #         ],
    #         [
    #           "memo",
    #           "ShortText"
    #         ],
    #         [
    #           "_score",
    #           "Int32"
    #         ]
    #       ],
    #       [
    #         "Tobby",
    #         "groonga and mroonga user. mroonga is ...",
    #         51
    #       ],
    #       [
    #         "Alisa",
    #         "mroonga user",
    #         21
    #       ],
    #       [
    #         "Alice",
    #         "groonga user",
    #         11
    #       ],
    #       [
    #         "Tom",
    #         "nroonga user",
    #         1
    #       ],
    #       [
    #         "Bob",
    #         "rroonga user",
    #         1
    #       ]
    #     ]
    #   ]
    # ]

一方、複数の `query` を指定することで、 `groonga` と `mroonga` と `user` それぞれのキーワードに対し異なる重みづけを行えます。

結果として、意図した様に異なる重みづけを行いつつ全文検索の振舞いを制御することができます。

## 7.15.17.4. 引数

### 7.15.17.4.1. 必須引数

必須引数は二つあります。 `match_columns` と `query_string` です。

#### 7.15.17.4.1.1. `match_columns`

`query_string` パラメーターの値で全文検索するときのデフォルトの検索対象カラムを指定します。このパラメーターは `select` の match_columns パラメーターと同じ役割です。

#### 7.15.17.4.1.2. `query_string`

クエリー構文 で検索条件を指定します。このパラメーターは `select` コマンドの `query` パラメーターと同じ役割です。

`select` コマンドの `query` については match_columns を参照してください。

### 7.15.17.4.2. 省略可能引数

いくつか省略可能な引数があります。

#### 7.15.17.4.2.1. `query_expander`

クエリー展開に使うクエリー展開オブジェクトの名前または置換カラム名を指定します。

利用可能なクエリー展開オブジェクトは クエリー展開オブジェクト一覧 を参照してください。

置換カラム名は `テーブル名.カラム名` という書式を使います。

詳細は query_expander を見てください。

#### 7.15.17.4.2.2. `default_mode`

デフォルトの検索モードを指定します。検索モードは `column:@keyword` というような構文でカスタマイズできます。デフォルトの検索モードは `column:@keyword` ではなく単に `keyword` と指定したときに使われます。構文の詳細は クエリー構文 を見てください。

以下は利用可能なモードです。デフォルトは `"MATCH"` モードです。このモードでは全文検索をします。

モード | 別名 | 説明
--- | --- | ---
`"EQUAL"` | `"=="` | デフォルトのモードとして 等価条件 を使います。
`"NOT_EQUAL"` | `"!="` | デフォルトのモードとして 不等価条件 を使います。
`"LESS"` | `"<"` | デフォルトのモードとして 小なり条件 を使います。
`"GREATER"` | `">"` | デフォルトのモードとして 大なり条件 を使います。
`"LESS_EQUAL"` | `"<="` | デフォルトのモードとして 以下条件 を使います。
`"GREATER_EQUAL"` | `">="` | デフォルトのモードとして 以上条件 を使います。
`"MATCH"` | `"@"` | デフォルトのモードとして 全文検索条件 を使います。 これがデフォルトです。
`"NEAR"` | `"*N"` | デフォルトのモードとして 近傍検索条件 を使います。
`"SIMILAR"` | `"*S"` | デフォルトのモードとして 類似文書検索条件 を使います。
`"PREFIX"` | `"^"`, `"@^"` | デフォルトのモードとして 前方一致検索条件 を使います。
`"SUFFIX"` | `"$"`, `"@$"` | デフォルトのモードとして 後方一致検索条件 を使います。
`"REGEXP"` | `"~"`, `"@~"` | デフォルトのモードとして 正規表現条件 を使います。

#### 7.15.17.4.2.3. `default_operator`

デフォルトの論理演算子を指定します。これは `キーワード1 キーワード2` というように条件式の間に `OR` や `-` といった論理演算子が指定されない場合に使われます。デフォルトの論理演算子は `キーワード1` の結果セットと `キーワード2` の結果セットを組み合わせるときに使われます。デフォルトの論理演算子は `AND` です。つまり、 `キーワード1 キーワード2` の結果セットは `キーワード1` の結果セットと `キーワード2` の結果セットの両方に含まれるレコードだけが含まれます。

以下は利用可能な論理演算子ですデフォルトは `"AND"` です。

論理演算子 | 別名 | 説明
--- | --- | ---
`"AND"` | `"&&"`, `"+"` | デフォルトの論理演算子として 論理積 を使います。
`"OR"` | `"||"` | デフォルトの論理演算子として 論理和 を使います。
`"AND_NOT"` | `"&!"`, `"-"` | デフォルトの論理演算子として 論理差 を使います。

#### 7.15.17.4.2.4. `flags`

クエリーのパース方法をカスタマイズするフラグを指定します。

1つ以上のフラグを指定できます。複数のフラグを指定する場合は `|` で区切ります。以下が複数のフラグを指定する例です。:

    query("title * 10 || content",
          "keyword",
          {"flags": "ALLOW_COLUMN|ALLOW_LEADING_NOT"})

詳細は query_flags を見てください。

## 7.15.17.5. 戻り値

この関数は対象レコードがマッチしたかどうかを真偽値で返します。

この関数はセレクターとしても動きます。つまり、効率的に実行できるということです。

## 7.15.17.6. 参考

- select

- query_parallel_or