IBM Cloudant 検索の使用
検索インデックスは、Lucene クエリパーサ構文を使用してデータベースに問い合わせる方法を提供します。 検索索引は、文書の 1 つ以上のフィールドを使用します。
検索索引を使用して照会を実行したり、文書を含まれる内容に基づいて検索したり、グループ、ファセットまたは地理的検索を処理したりすることができます。
検索索引を作成するには、JavaScript 関数をデータベース内の設計文書に追加します。 索引は、1 つの検索要求が処理された後、またはサーバーで文書の更新が検出された後に作成されます。 index
関数では、以下のパラメーターを使用します。
- フィールド名 - 索引を照会する際に使用するフィールドの名前。 このパラメーターを
default
に設定すると、照会構文にフィールドが指定されていない場合に、このフィールドが照会されます。 - 索引付けするデータ (
doc.address.country
など)。 - (オプション) 3 番目のパラメーターには、
boost
、facet
、index
およびstore
の各フィールドが含まれます。 これらのフィールドについては、後で詳しく説明します。
デフォルトでは、検索索引応答により、25 行が返されます。 返される行数は、limit
パラメーターを使用することで変更できます。 ただし、検索からの結果セットは 200 行に制限されます。 各応答には bookmark
フィールドが含まれます。 後の照会で bookmark
フィールドの値を組み込み、応答を調べることができます。
API を照会するには、URI、IBM Cloudant ダッシュボード、curl または ブラウザー・プラグイン (Postman や RESTClient など) の方法のいずれかを使用できます。
検索索引を定義する設計文書の例を以下に示します。
{
"_id": "_design/search_example",
"indexes": {
"animals": {
"index": "function(doc){ ... }"
}
}
}
検索索引パーティショニング・タイプ
検索索引は、以下のものからパーティション・タイプを継承します。 options.partitioned
それを含む設計文書のフィールド。
index 関数
存在しないデータ・フィールドを使用して索引付けしようとすると、失敗します。 この問題を回避するには、適切なガード節を使用します。
索引付け関数は、環境で使用されるメモリーの一部に文書自体が含まれる、メモリーが制約された環境で作動します。 コードのスタックおよび文書は、このメモリー内に収まる必要があります。 文書の最大サイズは 64 MB に制限されています。
検索索引内では、同じフィールド名を複数のデータ・タイプに索引付けしないでください。 同じフィールド名が同じ検索索引関数内の異なるデータ・タイプに索引付けされている場合、エラーを受け取ることがあります。 このエラーは、 was indexed without position data
というフィールドを検索インデックスに問い合わせた際に発生します。 例えば、これら両方の行を同じ検索索引関数に含めないでください。 これらの行は、myfield
フィールドを、ストリング "this is a string"
と数値 123
の 2 つの異なるデータ・タイプとして索引付けします。
index("myfield", "this is a string");
index("myfield", 123);
索引フィールドに含まれる関数は、データベース内の文書ごとに呼び出される JavaScript 関数です。 この関数は、文書をパラメーターとして使用し、そこから一部のデータを抽出してから、
index
フィールドに定義された関数を呼び出してそのデータを索引付けします。
index
関数では、3 つのパラメーターを使用します。このうち、3 番目のパラメーターはオプションです。
最初のパラメータは、インデックスにクエリを実行する際に使用するフィールドの名前です。 これは、後続のクエリのLucene構文部分で指定されます。 照会の例を以下に示します。
query=color:red
Lucene フィールド名 color
は、index
関数の最初のパラメーターです。
query
パラメーターは q
に省略できるため、次の例に、照会を記述する別の方法を示します。
q=color:red
名前を定義する際に特殊値 "default"
を使用する場合は、照会時にフィールド名を指定する必要はありません。 その結果、照会を単純化できます。
query=red
2 番目のパラメーターは、索引付けするデータです。 データを索引付けする場合は、以下の情報に注意してください。
- このデータに指定できるのは、ストリング、数値またはブール値のみです。 その他のタイプは、index 関数呼び出しでエラーが返されます。
- この理由または他の理由で、関数の実行時にエラーが返された場合、文書はその検索索引に追加されません。
3 番目のパラメーター (オプション) は、以下のフィールドを含む JavaScript オブジェクトです。
オプション | 説明 | 値 | デフォルト |
---|---|---|---|
boost |
検索結果で関連性を指定する数値。 1 より大きいランキング調整値が索引付けされた内容は、ランキング調整値が索引付けされていない内容より関連性が高くなります。 ランキング調整値が 1 より小さい内容は、関連性があまりありません。 | 正の浮動小数点数 | 1 (ランキング調整なし) |
facet |
ファセット索引を作成します。 詳しくは、ファセットを参照してください。 | true |
false |
index |
データが索引付けされているかどうか、および索引付けされている場合にはその方法。 false に設定されている場合、データを検索に使用することはできませんが、store が true に設定されている場合は、引き続き索引から取得できます。 詳しくは、アナライザーを参照してください。 |
true , false |
true |
store |
true の場合、値は検索結果で返されます。それ以外の場合、値は返されません。 |
true , false |
false |
store
パラメーターを設定しない場合、文書の索引データ結果は、照会に対する応答で返されません。
検索索引関数の例を以下に示します。
function(doc) {
index("default", doc._id);
if (doc.min_length) {
index("min_length", doc.min_length, {"store": true});
}
if (doc.diet) {
index("diet", doc.diet, {"store": true});
}
if (doc.latin_name) {
index("latin_name", doc.latin_name, {"store": true});
}
if (doc.class) {
index("class", doc.class, {"store": true});
}
}
保存 vs include_docs=true
IBM Cloudant が検索からデータを返す場合、store: true
オプションまたは include_docs=true
オプションのいずれかを選択できます。 以下の説明を参照してください。
- 索引付け時に、
{store: true}
オプションを選択します。 このオプションは、当該フィールドが索引に格納される必要があることを示します。 フィールドが索引付け自体に使用されない場合でも、フィールドを格納することができます。 例えば、検索アルゴリズムが電話番号での検索を含んでいなくても、電話番号を格納する場合があります。 - 照会時に、
?include_docs=true
を渡して、一致する各文書の本文全体が返されるようにしたいことを IBM Cloud に示します。
最初のオプションは、索引が大きくなることを意味しますが、データを取得する最も速い方法です。 2 番目のオプションでは、索引は小さく保たれますが、検索結果セットが計算された後で文書本文を取り出す必要があるため、IBM Cloud にとっては余分な照会時作業が追加されます。 この処理は、より実行に時間がかかることがあります。また、IBM Cloud クラスターにさらなる負担がかかります。
可能であれば、以下のガイドラインに従って最初のオプションを選択してください
- 検索可能にしたいフィールドのみを索引付けする。
- 照会時に取得する必要のあるフィールドのみを格納する。
索引ガード節
index
関数には、2 番目のパラメーターとして、索引付けするデータ・フィールドの名前が必要です。 ただし、そのデータ・フィールドが文書に存在しない場合は、エラーが発生します。 解決策は、フィールドが存在するかどうかを確認する適切な「ガード句」を使用することです。 この節には、対応する索引を作成しようとする前に予期されるデータ・タイプが含まれています。
索引データ・フィールドのタイプについて検証が行われない定義の例を以下に示します。
if (doc.min_length) {
index("min_length", doc.min_length, {"store": true});
}
JavaScript typeof
演算子を使用して、ガード節テストを実装できます。 フィールドが存在し、予期されるタイプである場合は、適切なタイプ名が返されます。 ガード節テストが成功した場合、index 関数を安全に使用できます フィールドが存在しない場合、フィールドの予期されるタイプは返されません。このため、フィールドの索引付けは試行しません。
以下のいずれかの値がテストされると、JavaScript では、結果が false と見なされます。
- 'undefined'
- ヌル
- 数値 +0
- 数値 -0
- NaN (数でない)
- "" (空の文字列)
ガード節を使用して必要なデータ・フィールドが存在するかどうかを検査し、索引付けが試行される前に数値を保持する例を以下に示します。
if (typeof doc.min_length === 'number') {
index("min_length", doc.min_length, {"store": true});
}
一般的なガード節テストを使用して、候補データ・フィールドのタイプが定義されていることを確認します。
「一般的な」ガード節の例を以下に示します。
if (typeof doc.min_length) !== 'undefined') {
// The field exists, and does have a type, so we can proceed to index using it.
...
}
アナライザー
アナライザーは、テキスト内の用語を認識する方法を定義する設定です。 詳細は 検索アナライザー を参照。
アナライザーは、複数の言語を索引付けする必要がある場合に役立ちます。
以下の表は、IBM Cloudant検索でサポートされている汎用アナライザの一覧です:
アナライザー | 説明 |
---|---|
classic |
標準 Lucene アナライザー (およそバージョン 3.1)。 |
email |
standard アナライザーと同様ですが、完全なトークンとして E メール・アドレスを一致させようとします。 |
keyword |
入力は一切トークン化されません。 |
simple |
文字以外の部分でテキストを分割する。 |
simple_asciifolding |
文字以外の部分でテキストを分割する。 文字を最も近いASCII文字に変換する |
standard |
デフォルト・アナライザー。 Unicode™テキストセグメンテーションアルゴリズムの単語区切りルールを実装しています。 |
whitespace |
テキストをホワイトスペースの境界で分割する。 |
アナライザー文書の例を以下に示します。
{
"_id": "_design/analyzer_example",
"indexes": {
"INDEX_NAME": {
"index": "function (doc) { ... }",
"analyzer": "$ANALYZER_NAME"
}
}
}
言語固有のアナライザー
これらのアナライザーは特定の言語における一般的な単語を省略し、 また、多くの場合、 接頭辞や接尾辞も削除します。 言語の名前は、アナライザーの名前でもあります。
arabic
armenian
basque
bulgarian
brazilian
catalan
cjk
(中国語、日本語、韓国語)chinese
(smartcn
)czech
danish
dutch
english
finnish
french
german
greek
galician
hindi
hungarian
indonesian
irish
italian
japanese
(kuromoji
)latvian
norwegian
persian
polish
(stempel
)portuguese
romanian
russian
spanish
swedish
thai
turkish
言語固有のアナライザーは、指定された言語用に最適化されています。 汎用アナライザーを言語固有のアナライザーと組み合わせることはできません。 代わりに、perfield
アナライザーを使用して、文書内のフィールドごとに異なるアナライザーを選択できます。
フィールドごとのアナライザー
perfield
アナライザーにより、さまざまなフィールドに対して多くのアナライザーを構成します。
フィールドごとに異なるアナライザーを定義する例を以下に示します。
{
"_id": "_design/analyzer_example",
"indexes": {
"INDEX_NAME": {
"analyzer": {
"name": "perfield",
"default": "english",
"fields": {
"spanish": "spanish",
"german": "german"
}
},
"index": "function (doc) { ... }"
}
}
}
ストップワード
ストップワードは、索引付けされない単語です。 これらを設計文書内で定義するには、アナライザー・ストリングをオブジェクトに変換します。
keyword
、simple
および whitespace
の各アナライザーでは、ストップワードはサポートされていません。
standard
アナライザーのデフォルト・ストップワードのリストを以下に示します。
"a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if",
"in", "into", "is", "it", "no", "not", "of", "on", "or", "such",
"that", "the", "their", "then", "there", "these", "they", "this",
"to", "was", "will", "with"
非インデックス化語(「stop」)を定義する次の例をご覧ください
{
"_id": "_design/stop_words_example",
"indexes": {
"INDEX_NAME": {
"analyzer": {
"name": "portuguese",
"stopwords": [
"foo",
"bar",
"baz"
]
},
"index": "function (doc) { ... }"
}
}
}
アナライザーのトークン化のテスト
アナライザーのトークン化の結果をテストするには、サンプル・データを _search_analyze
エンドポイントに POST します。
HTTP を使用して keyword
アナライザーをテストする例を以下に示します。
Host: $ACCOUNT.cloudant.com
POST /_search_analyze HTTP/1.1
Content-Type: application/json
{"analyzer":"keyword", "text":"ablanks@renovations.com"}
コマンド・ラインを使用して keyword
アナライザーをテストする例を以下に示します。
curl "https://$ACCOUNT.cloudant.com/_search_analyze" \
-H "Content-Type: application/json" \
-d '{"analyzer":"keyword", "text":"ablanks@renovations.com"}'
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostSearchAnalyzeOptions;
import com.ibm.cloud.cloudant.v1.model.SearchAnalyzeResult;
Cloudant service = Cloudant.newInstance();
PostSearchAnalyzeOptions searchAnalyzerOptions =
new PostSearchAnalyzeOptions.Builder()
.analyzer("keyword")
.text("ablanks@renovations.com")
.build();
SearchAnalyzeResult response =
service.postSearchAnalyze(searchAnalyzerOptions).execute()
.getResult();
System.out.println(response);
import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postSearchAnalyze({
analyzer: 'keyword',
text: 'ablanks@renovations.com',
}).then(response => {
console.log(response.result);
});
from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_search_analyze(
analyzer='keyword',
text='ablanks@renovations.com'
).get_result()
print(response)
postSearchAnalyzeOptions := service.NewPostSearchAnalyzeOptions(
"keyword",
"ablanks@renovations.com",
)
searchAnalyzeResult, _, err := service.PostSearchAnalyze(postSearchAnalyzeOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(searchAnalyzeResult, "", " ")
fmt.Println(string(b))
前の Go の例では、以下のインポート・ブロックが必要です。
import (
"encoding/json"
"fmt"
"github.com/IBM/cloudant-go-sdk/cloudantv1"
)
keyword
アナライザーをテストする結果を以下に示します。
{
"tokens": [
"ablanks@renovations.com"
]
}
HTTP を使用して standard
アナライザーをテストする例を以下に示します。
Host: $ACCOUNT.cloudant.com
POST /_search_analyze HTTP/1.1
Content-Type: application/json
{"analyzer":"standard", "text":"ablanks@renovations.com"}
コマンド・ラインを使用して standard
アナライザーをテストする例を以下に示します。
curl "https://$ACCOUNT.cloudant.com/_search_analyze" -H "Content-Type: application/json"
-d '{"analyzer":"standard", "text":"ablanks@renovations.com"}'
standard
アナライザーをテストする結果を以下に示します。
{
"tokens": [
"ablanks",
"renovations.com"
]
}
照会
検索索引は、作成後に照会できます。
-
以下の要求を使用して、パーティション照会を実行します。
GET /$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_search/$INDEX_NAME
-
以下の要求を使用して、グローバル照会を実行します。
GET /$DATABASE/_design/$DDOC/_search/$INDEX_NAME
query
パラメーターを使用して、検索を指定します。
HTTP を使用してパーティション化された索引を照会する例を以下に示します。
GET /$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query="*:*"&limit=1 HTTP/1.1
Content-Type: application/json
Host: $ACCOUNT.cloudant.com
コマンド・ラインを使用してパーティション化された索引を照会する例を以下に示します。
curl "https://$ACCOUNT.cloudant.com/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query=\"*:*\"&limit=1"
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostPartitionSearchOptions;
import com.ibm.cloud.cloudant.v1.model.SearchResult;
Cloudant service = Cloudant.newInstance();
PostPartitionSearchOptions searchOptions =
new PostPartitionSearchOptions.Builder()
.db("<db-name>")
.partitionKey("<partition-key>")
.ddoc("<ddoc>")
.index("<index-name>")
.query("*:*")
.includeDocs(true)
.limit(1)
.build();
SearchResult response =
service.postPartitionSearch(searchOptions).execute()
.getResult();
System.out.println(response);
import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postSearch({
db: '<db-name>',
partitionKey: '<partition-key>',
ddoc: '<ddoc>',
index: '<index-name>',
query: '*:*',
includeDocs: true,
limit: 1
}).then(response => {
console.log(response.result);
});
from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_search(
db='<db-name>',
partition_key='<partition-key>',
ddoc='<ddoc>',
index='<index-name>',
query='*:*',
include_docs=True,
limit=1
).get_result()
print(response)
postPartitionSearchOptions := service.NewPostPartitionSearchOptions(
"<db-name>",
"<partition-key>",
"<ddoc>",
"<index-name>",
"*:*",
)
postPartitionSearchOptions.SetIncludeDocs(true)
postPartitionSearchOptions.SetLimit(1)
searchResult, _, err := service.PostPartitionSearch(postPartitionSearchOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(searchResult, "", " ")
fmt.Println(string(b))
前の Go の例では、以下のインポート・ブロックが必要です。
import (
"encoding/json"
"fmt"
"github.com/IBM/cloudant-go-sdk/cloudantv1"
)
HTTP を使用してグローバル索引を照会する例を以下に示します。
GET /$DATABASE/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query="*:*"&limit=1 HTTP/1.1
Content-Type: application/json
Host: $ACCOUNT.cloudant.com
コマンド・ラインを使用してグローバル索引を照会する例を以下に示します。
curl "https://$ACCOUNT.cloudant.com/$DATABASE/_design/$DDOC/_search/$INDEX_NAME?include_docs=true&query=\"*:*\"&limit=1"
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostSearchOptions;
import com.ibm.cloud.cloudant.v1.model.SearchResult;
Cloudant service = Cloudant.newInstance();
PostSearchOptions searchOptions = new PostSearchOptions.Builder()
.db("<db-name>")
.ddoc("<ddoc>")
.index("<index-name>")
.query("*:*")
.includeDocs(true)
.limit(1)
.build();
SearchResult response =
service.postSearch(searchOptions).execute()
.getResult();
System.out.println(response);
import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postSearch({
db: '<db-name>',
ddoc: '<ddoc>',
index: '<index-name>',
query: '*:*',
includeDocs: true,
limit: 1
}).then(response => {
console.log(response.result);
});
from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_search(
db='<db-name>',
ddoc='<ddoc>',
index='<index-name>',
query='*:*',
include_docs=True,
limit=1
).get_result()
print(response)
postSearchOptions := service.NewPostSearchOptions(
"<db-name>",
"<ddoc>",
"<index-name>",
"*:*",
)
postSearchOptions.SetIncludeDocs(true)
postSearchOptions.SetLimit(1)
searchResult, _, err := service.PostSearch(postSearchOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(searchResult, "", " ")
fmt.Println(string(b))
前の Go の例では、以下のインポート・ブロックが必要です。
import (
"encoding/json"
"fmt"
"github.com/IBM/cloudant-go-sdk/cloudantv1"
)
照会パラメーター
パラメーター および を使用するには、counts
ファセットdrilldown
を有効にする必要があります。
引数 | 説明 | オプション | タイプ | サポートされる値 | パーティション照会 |
---|---|---|---|---|---|
bookmark |
前の検索から受け取ったブックマーク。 このパラメーターにより、結果のページングが可能になります。 ブックマークの後に結果が存在しない場合、結果リストの最後を確認する、行配列が空で同じブックマークを含む応答を受け取ります。 | yes |
ストリング | ある | |
counts |
このフィールドは、カウントが要求されるストリング・フィールドの名前の配列を定義します。 応答には、検索照会と一致する、文書間でのこのフィールド名の固有値ごとのカウントが含まれます。 このパラメーターが機能するには、ファセットを有効にする必要があります。 | ある | JSON | フィールド名の JSON 配列。 | いいえ |
drilldown |
このフィールドは複数回使用できます。 使用するたびに、フィールドの名前と値のペアを定義します。 検索では、指定されたフィールドに示された値を含む文書のみを突き合わせます。 これは、"fieldname:value" パラメーターで q を使用するのとは、その値が分析されないという点でのみ異なります。 このパラメーターが機能するには、ファセットを有効にする必要があります。 |
いいえ | JSON | フィールド名と値の 2 つの要素を含む JSON 配列。 | ある |
group_field |
検索で一致したものをグループ化するときに基準となるフィールド。 | ある | ストリング | ストリング・フィールドの名前を含むストリング。 数値、オブジェクト、配列などの他のデータを含むフィールドは使用できません。 | いいえ |
group_limit |
最大グループ数。 このフィールドは、group_field が指定されている場合にのみ使用できます。 |
ある | 数値 | いいえ | |
group_sort |
このフィールドは、group_field が使用される検索において、グループの順序を定義します。 デフォルトのソート順は関連性によって決まります。 |
ある | JSON | このフィールドには、ソート・フィールドと同じ値を指定できるため、単一のフィールドおよびフィールドの配列がサポートされます。 | いいえ |
highlight_fields |
強調表示するフィールドを指定します。 指定する場合、結果オブジェクトには、指定した各フィールドの項目を持つ highlights フィールドが含まれます。 |
ある | 文字列のアレイ | ある | |
highlight_pre_tag |
highlights 出力で強調表示された単語の前に挿入されるストリング。 | はい。デフォルトは <em> です。 |
ストリング | ある | |
highlight_post_tag |
highlights 出力で強調表示された単語の後に挿入されるストリング。 | はい。デフォルトは </em> です。 |
ストリング | ある | |
highlight_number |
highlights で返されるフラグメントの数。 検索語がフラグメント・サイズを超える場合、検索語全体が返されます。 | はい。デフォルトは 1 です。 | 数値 | ある | |
highlight_size |
フィールドの内容を文字数 (いわゆるフラグメント) に分割し、指定されたフラグメント内の一致のみを強調表示します。 | はい。デフォルトは 100 文字です。 | 数値 | ある | |
include_docs |
応答に、文書の内容全体を組み込みます。 | ある | ブール値 | ある | |
include_fields |
検索結果に含めるフィールド名の JSON 配列。 含めるフィールドにはすべて、store:true オプションで索引付けする必要があります。 |
はい。デフォルトはすべてのフィールドです。 | 文字列のアレイ | ある | |
limit |
返される文書の数を指定された数に制限します。 グループ化検索の場合、このパラメーターは、グループごとの文書の数を制限します。 | ある | 数値 | しきい値には、200 以下の任意の正整数を指定できます。 | ある |
q |
query の省略形。 Lucene 照会を実行します。 |
いいえ | ストリングまたは数値 | ある | |
query |
Lucene 照会を実行します。 | いいえ | ストリングまたは数値 | ある | |
ranges |
このフィールドは、ファセットされた数値検索フィールドの範囲を定義します。 値は JSON オブジェクトであり、ここで、フィールド名はファセットされた数値検索フィールド、フィールドの値は JSON オブジェクトです。 JSON オブジェクトのフィールド名は、範囲の名前です。 値は、範囲を説明するストリングです ("[0 TO 10]" など)。 |
ある | JSON | 値は、フィールドの値としてオブジェクトを含むオブジェクトである必要があります。 これらのオブジェクトには、フィールド値として範囲を含むストリングが必要です。 | いいえ |
sort |
結果のソート順を指定します。 グループ化検索では (group_field が使用されている場合)、このパラメーターは、グループ内のソート順を指定します。 デフォルトのソート順は関連性によって決まります。 |
ある | JSON | 降順の場合は "fieldname<type>" または -fieldname<type> の形式の JSON ストリング。 fieldname はストリング・フィールドまたは数値フィールドの名前であり、type は数値、ストリングまたはストリングの JSON 配列のいずれかです。 type 部分はオプションであり、デフォルトは number です。 例としては、 "foo" 、 "-foo" 、 "bar<string>" 、 "-foo<number>" 、および ["-foo<number>","bar<string>"] があります。
ソートに使用されるストリング・フィールドを分析フィールドにすることはできません。 ソートに使用されるフィールドは、検索照会に使用されるものと同じ索引作成機能によって索引付けされている必要があります。 |
ある |
stale |
索引の作成が終了するのを待機せずに結果を返します。 | ある | ストリング | OK | ある |
bookmark
オプションと stale
オプションを組み合わせないでください。 これらのオプションにより、応答に使用するシャード・レプリカの選択が制約されます。 これらのオプションを一緒に使用すると、低速または使用不可のレプリカに接続を試みたときに問題が発生する可能性があります。
include_docs=true
を使用すると、パフォーマンスへの影響が生じる可能性があります。
関連性
複数の結果が返される場合は、それらの結果をソートできます。 デフォルトでは、ソート順は「関連性」によって決まります。
関連性は、 Apache Lucene Scoring に従って測定されます 例えば、単純なデータベースで単語 example
を検索する場合、2 つの文書にその単語が含まれることがあります。 1 つの文書で単語 example
に
10 回言及しているが、2 番目の文書では 2 回しか言及していない場合、最初の文書がより「関連性」が高いと見なされます。
sort
パラメーターを指定しない場合、関連性がデフォルトで使用されます。 最もスコアリングが高い一致が、最初に返されます。
sort
パラメーターを指定する場合、一致は、関連性を無視して指定された値の順序で返されます。
sort
パラメーターを使用し、関連性による順序付けも検索結果に含める場合は、 sort
パラメーター内で特殊フィールド -<score>
または <score>
を使用します。
検索照会の POST
GET
HTTP メソッドを使用する代わりに、POST
メソッドを使用することもできます。
POST
照会の主な利点は、要求本文を含めることができることで、要求を JSON オブジェクトとして指定できる点です。 上記の表の各パラメーターは、要求本文内の JSON オブジェクト内のフィールドに対応しています。
HTTP を使用して検索要求を POST
する例を以下に示します。
POST /db/_design/ddoc/_search/searchname HTTP/1.1
Content-Type: application/json
Host: $ACCOUNT.cloudant.com
コマンド・ラインを使用して検索要求を POST
する例を以下に示します。
curl "https://$ACCOUNT.cloudant.com/$DATABASE/_design/$DDOC/_search/$INDEX_NAME" -X POST -H "Content-Type: application/json" -d @search.json
検索要求を含む JSON 文書の例を以下に示します。
{
"q": "index:my query",
"sort": "foo",
"limit": 3
}
照会構文
IBM Cloudant の検索クエリの構文は、 Luceneの構文に基づいています。 検索照会は、名前を省略しない限り、
name:value
の形式になります。名前を省略する場合は、次の例に示すようにデフォルト・フィールドが使用されます。
検索照会式の例を以下に示します。
// Birds
class:bird
// Animals that begin with the letter "l"
l*
// Carnivorous birds
class:bird AND diet:carnivore
// Herbivores that start with letter "l"
l* AND diet:herbivore
// Medium-sized herbivores
min_length:[1 TO 3] AND diet:herbivore
// Herbivores that are 2m long or less
diet:herbivore AND min_length:[-Infinity TO 2]
// Mammals that are at least 1.5m long
class:mammal AND min_length:[1.5 TO Infinity]
// Find "Meles meles"
latin_name:"Meles meles"
// Mammals who are herbivore or carnivore
diet:(herbivore OR omnivore) AND class:mammal
// Return all results
*:*
複数のフィールドに対するクエリーは論理的に結合でき、グループとフィールドはさらにグループ化できます。 利用可能な論理演算子は大文字と小文字を区別し、 AND
です
+
,
OR
,
NOT
, and -
. 範囲照会は、ストリングまたは数値に対して実行できます。
ファジー検索が必要な場合は、~
を指定して照会を実行し、検索語に似た用語を検索できます。 例えば、こうだ、
look~
book
と という用語を見つけます。 took
範囲照会の上限が両方とも数字のみを含むストリングである場合、境界はストリングではなく数値として処理されます。 例えば、照会 mod_date:["20170101" TO "20171231"]
を使用して検索する場合、結果には、mod_date
がストリング "20170101" と "20171231" の間ではなく、数値 20170101 と
20171231 の間にある文書が含まれます。
検索語の重要度を変更するには、^
と正数を追加します。 この変更により、ランキング調整値の指数に比例して、より関連性の高いまたは低い用語を含む一致が作成されます。 デフォルト値は 1 です。これは、一致の強度において増減がないことを意味します。 10 進値 0 から 1 を指定すると、重要度が低下し、一致の強度は弱くなります。 1 より大きい値を指定すると、重要度が増加し、一致の強度は強くなります。
ワイルドカード検索は、単一 (?
) と複数 (*
) の両方の文字検索でサポートされます。 以下に例を示します。
dat?
would match date
and data
, and dat*
would match date
,
data
,
database
, and dates
. ワイルドカードは検索語の後に指定する必要があります。
すべての結果を返すには、*:*
を使用します。
検索からの結果セットは 200 行に制限されており、デフォルトでは 25 行が返されます。 返される行の数は、 limit
パラメーターを使用して変更できます。
検索照会で "group_field"
引数を指定しない場合、応答にはブックマークが含まれます。 このブックマークを後で URL パラメーターとして指定すると、応答では、結果の次のセットを素早く簡単に取得できるように、既に検出された行がスキップされます。
検索照会に "group_field"
パラメーターが含まれている場合、応答にはブックマークが含まれません。
group_field
、group_limit
および group_sort
の各オプションは、グローバル照会を行う場合にのみ使用できます。
以下の文字を検索する場合は、エスケープする必要があります。
+ - && || ! ( ) { } [ ] ^ " ~ * ? : \ /
これらの文字のいずれかをエスケープするには、前に円記号(\
)を使用します。
検索照会に対する応答には、各結果の order
フィールドが含まれます。
order
フィールドは、最初の要素として sort
パラメーターで指定された 1 つ以上のフィールドを含む配列です。 クエリに sort
パラメータ が含まれていない場合、 order
フィールドには Luceneの関連スコアが含まれます
sort by distance
地理的検索で説明されているように 機能を使用する場合、最初の要素はポイントからの距離です。 距離は、キロメートルまたはマイルのいずれかを使用して測定されます。
順序配列の 2 番目の要素は無視できます。 これは、トラブルシューティングの目的にのみ使用されます。
ファセット
IBM Cloudant 検索では、ファセット検索もサポートされており、一致に関する集約情報を素早く簡単に検出できます。 特殊な ?q=*:*
照会構文を使用してすべての文書を突き合わせ、返されたファセットを使用して照会を絞り込むことができます。 ファセット照会でフィールドに索引付けする必要があることを示すには、そのオプションで {"facet": true}
を設定します。
ファセット検索を有効にすることを指定した検索照会の例を以下に示します。
function(doc) {
index("type", doc.type, {"facet": true});
index("price", doc.price, {"facet": true});
}
ファセットを使用するには、索引内のすべての文書に、ファセットが有効になっているすべてのフィールドが含まれている必要があります。 文書にすべてのフィールドが含まれていない場合は、「
bad_request
が存在しない」という理由で、field_name
エラーを受け取ります。 各文書にファセットのすべてのフィールドが含まれていない場合は、フィールドごとに個別の索引を作成します。 フィールドごとに個別の索引を作成しない場合は、すべてのフィールドを含む文書のみを含める必要があります。 単一の if
ステートメントを使用して、各文書にフィールドが存在することを確認します。
各文書に必要なフィールドが存在することを確認する if
ステートメントの例を以下に示します。
if (typeof doc.town == "string" && typeof doc.name == "string") {
index("town", doc.town, {facet: true});
index("name", doc.name, {facet: true});
}
カウント
counts
オプションは、グローバル照会を行う場合にのみ使用できます。
counts
ファセット構文では、フィールドのリストを使用して、指定された各フィールドの固有値ごとに照会結果の数を返します。
count
演算は、索引値がストリングの場合にのみ機能します。 索引値を混合タイプにすることはできません。 例えば、100 個のストリングが索引付けされ、1 つの数値が索引付けされている場合、この索引を count
演算に使用することはできません。
typeof
演算子を使用してタイプを確認し、 parseInt
を使用して変換することができます
parseFloat
, or .toString()
functions.
counts
ファセット構文を使用する照会の例を以下に示します。
?q=*:*&counts=["type"]
counts
ファセット構文を使用した後の応答の例を以下に示します。
{
"total_rows":100000,
"bookmark":"g...",
"rows":[...],
"counts":{
"type":{
"sofa": 10,
"chair": 100,
"lamp": 97
}
}
}
drilldown
drilldown
オプションは、グローバル照会を行う場合にのみ使用できます。
指定されたラベルとディメンションが等しい文書に、結果を制限できます。 結果を制限するには、
drilldown=["dimension","label"]
を検索照会に追加します。 複数の drilldown
パラメーターを含めると、複数のディメンションに従って結果を制限できます。
drilldown
パラメーターの使用は、key:value
パラメーターで q
を使用するのと似ていますが、drilldown
パラメーターは、アナライザーでスキップされる可能性のある値を返します。
例えば、アナライザーで "a"
などのストップワードが索引付けされなかった場合、drilldown
を指定すると、drilldown=["key","a"]
パラメーターは、そのストップワードを返します。
範囲
ranges
オプションは、グローバル照会を行う場合にのみ使用できます。
range
ファセット構文では、指定された各カテゴリーに適合する結果の数返すために、範囲に標準 Lucene 構文を再使用します。 包括的範囲照会は、大括弧 ([
, ]
) で示されます。 排他的範囲照会は、中括弧 ({
, }
) で示されます。
索引値を混合タイプにすることはできません。 例えば、100 個のストリングが索引付けされ、1 つの数値が索引付けされている場合、この索引を range
演算に使用することはできません。
typeof
演算子を使用してタイプを確認し、 parseInt
を使用して変換することができます
parseFloat
, or .toString()
functions.
ranges
を突き合わせるためにファセット検索を使用する要求の例を以下に示します。
?q=*:*&ranges={"price":{"cheap":"[0 TO 100]","expensive":"{100 TO Infinity}"}}
ファセット検索で ranges
を検査した後の結果の例を以下に示します。
{
"total_rows":100000,
"bookmark":"g...",
"rows":[...],
"ranges": {
"price": {
"expensive": 278682,
"cheap": 257023
}
}
}
地理的検索
テキスト・フィールドの内容による検索に加えて、地理的座標からの距離で結果をソートすることもできます。
この方法で結果をソートするには、経度と緯度を表す 2 つの数値フィールドに索引付けする必要があります。
その後、特別な <distance...>
ソート・フィールドを使用して照会を行うことができます。このソート・フィールドには、以下の 5 つのパラメーターがあります。
- 経度フィールド名 - 経度フィールドの名前 (例では
mylon
)。 - 緯度フィールド名 - 緯度フィールドの名前 (例では
mylat
)。 - 起点の経度 - 距離でソートする起点となる場所の経度。
- 起点の緯度 - 距離でソートする起点となる場所の緯度。
- 単位 - 使用する単位には、キロメートルの場合は
km
、またはマイルの場合はmi
が含まれます。 距離は、順序フィールドで返されます。
距離によるソートは、緯度と経度による範囲検索や、 地理的情報以外の情報を含む検索など、 他の検索クエリと組み合わせることができます。
このようにして、境界ボックス内を検索し、追加の基準を使用して検索を絞り込むことができます。
地理的データの例を以下に示します。
{
"name":"Aberdeen, Scotland",
"lat":57.15,
"lon":-2.15,
"type":"city"
}
地理的データの検索索引を含む設計文書の例を以下に示します。
function(doc) {
if (doc.type && doc.type == 'city') {
index('city', doc.name, {'store': true});
index('lat', doc.lat, {'store': true});
index('lon', doc.lon, {'store': true});
}
}
ニューヨークへの距離によって北半球の都市をソートする照会に HTTP を使用する例を以下に示します。
GET /examples/_design/cities-designdoc/_search/cities?q=lat:[0+TO+90]&sort="<distance,lon,lat,-74.0059,40.7127,km>" HTTP/1.1
Host: $ACCOUNT.cloudant.com
ニューヨークへの距離によって北半球の都市をソートする照会にコマンド・ラインを使用する例を以下に示します。
curl "https://$ACCOUNT.cloudant.com/examples/_design/cities-designdoc/_search/cities?q=lat:\[0+TO+90\]&sort=\"<distance,lon,lat,-74.0059,40.7127,km>\""
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostSearchOptions;
import com.ibm.cloud.cloudant.v1.model.SearchResult;
import java.util.Arrays;
Cloudant service = Cloudant.newInstance();
PostSearchOptions searchOptions = new PostSearchOptions.Builder()
.db("examples")
.ddoc("cities-designdoc")
.index("cities")
.query("lat:\\[0+TO+90\\]")
.sort(Arrays.asList("<distance,lon,lat,-74.0059,40.7127,km>"))
.build();
SearchResult response =
service.postSearch(searchOptions).execute()
.getResult();
System.out.println(response);
import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postSearch({
db: 'examples',
ddoc: 'cities-designdoc',
index: 'cities',
query: 'lat:\\[0+TO+90\\]',
sort: ['<distance,lon,lat,-74.0059,40.7127,km>']
}).then(response => {
console.log(response.result);
});
from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_search(
db='examples',
ddoc='cities-designdoc',
index='cities',
query='lat:\\[0+TO+90\\]',
sort=['<distance,lon,lat,-74.0059,40.7127,km>']
).get_result()
print(response)
postSearchOptions := service.NewPostSearchOptions(
"examples",
"cities-designdoc",
"cities",
"lat:\\[0+TO+90\\]",
)
postSearchOptions.SetSort([]string{"<distance,lon,lat,-74.0059,40.7127,km>"})
searchResult, _, err := service.PostSearch(postSearchOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(searchResult, "", " ")
fmt.Println(string(b))
前の Go の例では、以下のインポート・ブロックが必要です。
import (
"encoding/json"
"fmt"
"github.com/IBM/cloudant-go-sdk/cloudantv1"
)
ニューヨークへの距離によってソートされた北半球の都市のリストを含む (省略された) 応答の例を以下に示します。
{
"total_rows": 205,
"bookmark": "g1A...XIU",
"rows": [
{
"id": "city180",
"order": [
8.530665755719783,
18
],
"fields": {
"city": "New York, N.Y.",
"lat": 40.78333333333333,
"lon": -73.96666666666667
}
},
{
"id": "city177",
"order": [
13.756343205985946,
17
],
"fields": {
"city": "Newark, N.J.",
"lat": 40.733333333333334,
"lon": -74.16666666666667
}
},
{
"id": "city178",
"order": [
113.53603438866077,
26
],
"fields": {
"city": "New Haven, Conn.",
"lat": 41.31666666666667,
"lon": -72.91666666666667
}
}
]
}
検索語の強調表示
検索語が言及されたコンテキストを取得して、結果をより強調してユーザーに表示できるようにすると、役立つ場合があります。
結果をより強調するには、検索照会に highlight_fields
パラメーターを追加します。 抜粋するフィールド名を指定して、検索語が強調教示された状態で返されるようにします。
デフォルトでは、検索語は強調表示するために <em>
タグ内に配置されますが、強調表示は highlights_pre_tag
パラメーターと highlights_post_tag
パラメーターを使用してオーバーライドできます。
フラグメントの長さは、デフォルトで 100 文字です。
highlights_size
パラメーターを使用して、異なる長さを要求できます。
highlights_number
は返されるフラグメントの数を制御するパラメーターで、デフォルトは 1 です。
応答では、フィールド名ごとに 1 つのサブフィールドを含む、highlights
フィールドが追加されます。
フィールドごとに、検索語が強調表示されたフラグメントの配列を受け取ります。
強調表示が機能するには、store: true
オプションを使用して、フィールドを索引内に保管します。
HTTP を使用して強調表示が有効な検索を行う例を以下に示します。
GET /movies/_design/searches/_search/movies?q=movie_name:Azazel&highlight_fields=["movie_name"]&highlight_pre_tag=" "&highlight_post_tag=" "&highlights_size=30&highlights_number=2 HTTP/1.1
HOST: $ACCOUNT.cloudant.com
Authorization: ...
ハイライト表示を有効にして検索するためのコマンドラインの例を以下に示します
curl "https://$ACCOUNT.cloudant.com/movies/_design/searches/_search/movies?q=\"movie_name:Azazel\"&highlight_fields=\[\"movie_name\"\]&highlight_pre_tag=\" \"&highlight_post_tag=\" \"&highlights_size=30&highlights_number=2" \
-X GET
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostSearchOptions;
import com.ibm.cloud.cloudant.v1.model.SearchResult;
import java.util.Arrays;
Cloudant service = Cloudant.newInstance();
PostSearchOptions searchOptions = new PostSearchOptions.Builder()
.db("movies")
.ddoc("searches")
.index("movies")
.query("movie_name:Azazel")
.highlightFields(Arrays.asList("[\"movie_name\"]"))
.highlightPreTag("\" \"")
.highlightPostTag("\" \"")
.highlightSize(30)
.highlightNumber(2)
.build();
SearchResult response =
service.postSearch(searchOptions).execute()
.getResult();
System.out.println(response);
import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postSearch({
db: 'movies',
ddoc: 'searches',
index: 'movies',
query: 'movie_name:Azazel',
highlightFields: ['["movie_name"]'],
highlightPreTag: '" "',
highlightPostTag: '" "',
highlightSize: 30,
highlightNumber: 2
}).then(response => {
console.log(response.result);
});
from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_search(
db='movies',
ddoc='searches',
index='movies',
query='movie_name:Azazel',
highlight_fields=['["movie_name"]'],
highlight_pre_tag='" "',
highlight_post_tag='" "',
highlight_size=30,
highlight_number=2
).get_result()
print(response)
postSearchOptions := service.NewPostSearchOptions(
"movies",
"searches",
"movies",
"movie_name:Azazel",
)
postSearchOptions.SetHighlightFields([]string{"[\"movie_name\"]"})
postSearchOptions.SetHighlightPreTag("\" \"")
postSearchOptions.SetHighlightPostTag("\" \"")
postSearchOptions.SetHighlightSize(30)
postSearchOptions.SetHighlightNumber(2)
searchResult, _, err := service.PostSearch(postSearchOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(searchResult, "", " ")
fmt.Println(string(b))
前の Go の例では、以下のインポート・ブロックが必要です。
import (
"encoding/json"
"fmt"
"github.com/IBM/cloudant-go-sdk/cloudantv1"
)
強調表示された検索結果の例を以下に示します。
{
"highlights": {
"movie_name": [
" on the Azazel Orient Express",
" Azazel manuals, you"
]
}
}
検索索引メタデータ
検索索引に関する情報を取得するには、以下の例に示すように、GET
要求を _search_info
エンドポイントに送信します。
DDOC
は、索引を含む設計文書を参照し、INDEX_NAME
は索引の名前です。
HTTP を使用して検索索引メタデータを要求する例を以下に示します。
GET /$DATABASE/_design/$DDOC/_search_info/$INDEX_NAME HTTP/1.1
コマンド・ラインを使用して検索索引メタデータを要求する例を以下に示します。
curl "https://$ACCOUNT.cloudant.com/$DATABASE/_design/$DDOC/_search_info/$INDEX_NAME" \
-X GET
import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.GetSearchInfoOptions;
import com.ibm.cloud.cloudant.v1.model.SearchInfoResult;
Cloudant service = Cloudant.newInstance();
GetSearchInfoOptions infoOptions =
new GetSearchInfoOptions.Builder()
.db("<db-name>")
.ddoc("<ddoc>")
.index("<index-name>")
.build();
SearchInfoResult response =
service.getSearchInfo(infoOptions).execute()
.getResult();
System.out.println(response);
import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.getSearchInfo({
db: '<db-name>',
ddoc: '<ddoc>',
index: '<index-name>'
}).then(response => {
console.log(response.result);
});
from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.get_search_info(
db='<db-name>',
ddoc='<ddoc>',
index='<index-name>'
).get_result()
print(response)
getSearchInfoOptions := service.NewGetSearchInfoOptions(
"<db-name>",
"<ddoc>",
"<index-name>",
)
searchInfoResult, _, err := service.GetSearchInfo(getSearchInfoOptions)
if err != nil {
panic(err)
}
b, _ := json.MarshalIndent(searchInfoResult, "", " ")
fmt.Println(string(b))
前の Go の例では、以下のインポート・ブロックが必要です。
import (
"encoding/json"
"fmt"
"github.com/IBM/cloudant-go-sdk/cloudantv1"
)
応答には、索引内の文書数やディスク上の索引のサイズなど、索引に関する情報が含まれます。
検索索引メタデータを要求した後の応答の例を以下に示します。
{
"name": "_design/DDOC/INDEX",
"search_index": {
"pending_seq": 7125496,
"doc_del_count": 129180,
"doc_count": 1066173,
"disk_size": 728305827,
"committed_seq": 7125496
}
}