7.15.20. query#
7.15.20.1. Summary#
query provides --match_columns and --query parameters of
select feature as function. You can specify
multiple query functions in --filter parameter in
select.
Because of such flexibility, you can control full text search behavior
by combination of multiple query functions.
query can be used in only --filter in
select.
7.15.20.2. Syntax#
query requires two parameters - match_columns and
query_string.
The parameter query_expander and options are optional:
query(match_columns, query_string)
query(match_columns, query_string, query_expander)
query(match_columns, query_string, options)
options uses the following format. All of key-value pairs are
optional:
{
"expander": query_expander,
"default_mode": default_mode,
"default_operator": default_operator,
"flags": flags
}
7.15.20.3. Usage#
Here are a schema definition and sample data to show usage.
Sample schema:
Execution example:
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]
Sample data:
Execution example:
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]
Here is the simple usage of query function which executes full
text search by keyword alice without using --match_columns and
--query arguments in --filter.
Execution example:
select Users --output_columns name,_score --filter 'query("name * 10", "alice")'
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 1
# ],
# [
# [
# "name",
# "ShortText"
# ],
# [
# "_score",
# "Int32"
# ]
# ],
# [
# "Alice",
# 10
# ]
# ]
# ]
# ]
When executing above query, the keyword alice is weighted to the
value 10.
Here are the contrasting examples with/without query.
Execution example:
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
# ]
# ]
# ]
# ]
In this case, the all keywords groonga, mroonga and user
use the default weight. You can’t pass different weight value to each
keyword in this way.
Execution example:
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
# ]
# ]
# ]
# ]
On the other hand, by specifying multiple query, the keywords
groonga, mroonga and user use different weight.
As a result, you can control full text search result score by specifying different weight to the keywords on your purpose.
7.15.20.4. Parameters#
7.15.20.4.1. Required parameters#
There are two required parameters, match_columns and query_string.
7.15.20.4.1.1. match_columns#
Specifies the default target columns for full text search by
query_string parameter value. It is the same role as
match_columns parameter in select.
7.15.20.4.1.2. query_string#
Specifies the search condition in
Query syntax. It is the same role as
query parameter in select.
See match_columns about query parameter in
select.
7.15.20.4.2. Optional parameters#
There are some optional parameters.
7.15.20.4.2.1. query_expander#
Specifies the query expander name or substitution column name for query expansion.
See Query expanders for available query expanders.
Substitution column name uses ${TABLE}.${COLUMN} format.
See query_expander for details.
7.15.20.4.2.2. default_mode#
Specifies the default search mode. You can change search mode by
column:@keyword like syntax. The default search mode is used when
you just specify keyword instead of column:@keyword. See
Query syntax for more syntax details.
Here are available modes. The default is "MATCH" mode. It does
full text search.
Mode |
Aliases |
Description |
|---|---|---|
|
|
It uses Equal condition as the default mode. |
|
|
It uses Not equal condition as the default mode. |
|
|
It uses Less than condition as the default mode. |
|
|
It uses Greater than condition as the default mode. |
|
|
It uses Less than or equal to condition as the default mode. |
|
|
It uses Greater than or equal to condition as the default mode. |
|
|
It uses Full text search condition as the default mode. It’s the default. |
|
|
It uses Near search condition as the default mode. |
|
|
It uses Similar search condition as the default mode. |
|
|
It uses Prefix search condition as the default mode. |
|
|
It uses Suffix search condition as the default mode. |
|
|
It uses Regular expression condition as the default mode. |
7.15.20.4.2.3. default_operator#
Specifies the default logical operator. It’s used when no logical
operator such as OR and - are specified between conditional
expressions like keyword1 keyword2. The default logical operator
is used to combine keyword1 result set and keyword2 result
set. The default logical operator is AND. So keyword1 keyword2
result set includes only records that they are included in both
keyword1 result set and keyword2 result set.
Here are available logical operators. The default is "AND".
Logical operator |
Aliases |
Description |
|---|---|---|
|
|
It uses Logical AND as the default logical operator. |
|
|
It uses Logical OR as the default logical operator. |
|
|
It uses Logical AND NOT as the default logical operator. |
7.15.20.4.2.4. flags#
Specifies the flags that customizes how to parse query.
You can specify multiple flags by separating each flags by |. Here
is the example to specify multiple flags:
query("title * 10 || content",
"keyword",
{"flags": "ALLOW_COLUMN|ALLOW_LEADING_NOT"})
See query_flags for available flags.
7.15.20.5. Return value#
This function returns whether a record is matched or not as boolean.
This function is also worked as a selector. It means that this function can be executable effectively.