照会パラメーター

クエリパラメータは、 IBM Cloudant クエリリクエストの出力を変更し、ソート順、返されるフィールド、またはレスポンスのページ分割を変更します。パラメータは selector。

パラメータの概要

このJSONドキュメントは、利用可能なすべてのクエリ・パラメータを使用する：

{
  // Query selector
	"selector": {
		"year": {
			"$gt": 2010
		}
	},
	// Specify fields to return
	"fields": ["_id", "_rev", "year", "title"],
	// Specify sort order
	"sort": [{"year": "asc"}],
	// Return a maximum number of results
	"limit": 10,
	// Start returning results from a previous bookmark (pagination)
	"bookmark":"g1AAAAA-eJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJB"
	// Hint to use a specific index for a query
	"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8",
	// Disallow using a different index than the specified index
  "allow_fallback": false
	}

返すフィールドの指定

データベースからドキュメントを選択する際に、どのフィールドを返すかを指定することができます。これにはメリットがある：

結果は、アプリケーションに必要な文書の部分のみに制限されます。
応答のサイズが縮小されます。

返すフィールドは、クエリの fields 配列で指定します。指定されたフィールド名は、ドット表記を使用してサブフィールドにアクセスできます。

このクエリーは、結果文書から指定された4つのフィールドだけを返します：

{
	"selector": {
		"Actor_name": "Robert De Niro"
	},
	"fields": [
		"Actor_name",
		"Movie_year",
		"_id",
		"_rev"
	]
}

指定されたフィルター・フィールドのみが応答に含まれます。_idやその他のメタデータ・フィールドは自動的には組み込まれません。

結果の並べ替え

クエリの sort フィールドを使用して、返される結果の順序を指定します。 sort フィールドは、フィールド名と方向のペアのリストを含む、配列として表現される。最初のフィールド名と方向のペアは、ソートの最上位のレベルです。さらにペアがあれば、次のソートレベルを指定する。

ソート・フィールドは任意のフィールドにすることができます。必要な場合は、サブフィールドにドット表記を使用します。

方向値は、上昇の場合は asc 、下降の場合は desc ：

"sort": [{ "fieldName1": "desc" }, { "fieldName2": "desc" }]

方向の値を指定しない場合は、デフォルトの asc が使用されます。昇順ソートには、以下の省略形が使える：

"sort": [ "fieldName1", "fieldName2" ]

標準的な要件は、セレクターを使用してコンテンツを検索し、指定されたフィールドに従って結果を設定した方向でソートすることです。

ソートを使用するには、ソートフィールドを含むインデックスを定義しなければならない。 json インデックスを使用する場合、フィールドはソートと同じ順序で指定しなければならない。

現在、IBM Cloudant 照会では、ソート順序が異なる複数のフィールドはサポートされていません。そのため、方向はすべて昇順またはすべて降順のどちらかにする必要があります。

方向が昇順の場合は、オブジェクトの代わりにストリングを使用してソート・フィールドを指定できます。

テキストインデックスを使ったソート

text インデックスに対するソート・クエリで、ソートされるフィールドのタイプを決定できないフィールド名の場合、フィールドの型を指定する必要があるかもしれません。以下に例を示します。

"sort": [ { "<fieldname>:string": "asc" } ]

フィールド・タイプを指定すべき状況
照会で使用されるのはどの索引ですか?	フィールド・タイプ要件
JSON 索引	なし
すべての文書のすべてのフィールドのテキスト索引	ソート・フィールドに 1 つのタイプがある文書がデータベースに含まれている場合は、照会でソート・フィールドを指定します。ソート・フィールドに異なるタイプがある文書が含まれている場合も、照会でソート・フィールドを指定します。
他の任意のテキスト索引	照会のすべてのソート・フィールドのタイプを指定します。

次の構文を使用すると、すべての文書のすべてのフィールドのテキスト索引が作成されます。 "index": {}.

フィールドに異なるデータ・タイプが含まれている場合、ソート順は未定義です。この特性は、テキスト索引とビュー索引の重要な相違点です。データ・タイプが異なるフィールドのソート動作は、将来のバージョンで変更される可能性があります。

ページネーション

IBM Cloudant 照会では、ブックマーク・フィールドによるページネーションをサポートしています。すべての _find 応答には、ブックマークが含まれています。ブックマークは、後で照会が行われたときに再開する場所を決定するために IBM Cloudant が使用するトークンです。照会結果の次のセットを取得するには、前の応答で受け取ったブックマークを次の要求に追加します。セレクターは変更しないでください。そうしないと、予期しない結果になります。後方にページ番号付けするには、前のブックマークを使用して前の結果セットを返すことができます。

ブックマークが存在しても、より多くの結果が保証されるわけではありません。返された結果の数と要求されたページ・サイズを比較することにより、結果セットの終わりかどうかをテストできます。返された結果が制限より小さい場合、それ以上の結果は結果セットに返されていません。

特定のインデックスの使用を示唆

特定の索引を使用するように照会に指示するには、照会に use_index パラメーターを追加します。これはヒントであり、そのインデックスがクエリに使用できない場合は、代替のインデックスが使用されます。

use_index パラメーターの値は、以下のいずれかのフォーマットです。

"use_index": "$DDOC"
"use_index": ["$DDOC","$INDEX_NAME"]

このクエリ例では、 use_index を使用して特定のインデックスをヒンティングしています：

{
	"selector": {
		"$text": "Pacino",
		"year": 2010
	},
	"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8"
}

特定のインデックスの使用を強制する

allow_fallback パラメータを use_index と組み合わせると、特定のインデックスの使用を強制することができる。インデックスがクエリに使用できない場合、クエリはエラー応答を返します。

use_index を指定せずに "allow_fallback": false を使用すると、 _all_docs 組み込みインデックスが使用できなくなる。

このクエリ例は、 use_index で allow_fallback を使用して特定のインデックスを強制していることを示しています：

{
	"selector": {
		"$text": "Pacino",
		"year": 2010
	},
	"use_index": "_design/32372935e14bed00cc6db4fc9efca0f1537d34a8",
  "allow_fallback": false
}