ビューの使用

ビューを使用して、データベース内で特定の基準に一致する内容を検索します。 基準はビュー定義内で指定します。

ビューの使用時に基準を引数として指定することもできます。

ビューの照会

ビューを照会するには、以下の形式で GET 要求を送信します。

メソッド
コマンド GET $SERVICE_URL/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_view/$VIEW_NAME を使用してパーティション照会を発行します。 または、コマンド GET $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME を使用してグローバル照会を発行します。
要求
なし
応答
ビューによって返される文書の JSON。
許可される役割
_reader

要求により、以下のいずれかが実行されます。

  • 指定された「 $DDOC 」設計文書に記載されている「 $VIEW_NAME 」 $DATABASE データベース内において、指定された範囲内の結果に限定されます $PARTITION_KEY データ パーティション。
  • 指定された「 $DDOC 」設計文書に記載されている「 $VIEW_NAME 」 $DATABASE データベース内。

この文書の例は、説明のために、パーティション照会とグローバル照会の間で異なります。 特に明記されていない限り、パーティション名を組み込むか削除するパスの変更は、どのビュー照会タイプでも機能します。

照会および JSON 本文の引数

グローバル照会では、すべての照会および JSON 本文の引数を使用できます。 パーティション照会では、表に示されているサブセットのみを使用できます。

パーティション化されたクエリで利用可能なクエリ引数およびJSONボディ引数のサブセット
引数 説明 オプション タイプ デフォルト サポートされる値 パーティション照会
conflicts 競合するリビジョンのリストを、返されたドキュメントの _conflicts プロパティに含めるかどうかを指定する。 include_docs が true に設定されていない場合は無視される。 ある ブール値 いいえ ある
descending descending by key の順序でドキュメントを返しします。 ある ブール値 いいえ ある
end_key 指定されたキーに達したときに、レコードを返す処理を停止します。 ある ストリングまたは JSON 配列 ある
end_key_docid 指定された文書 ID に達したときに、レコードを返す処理を停止します。 ある ストリング ある
group 縮小された結果をキーごとにグループ化するかどうかを指定する。 ビューにリデュース関数が定義されている場合のみ有効。 ビューがJSON配列形式でキーを出力する場合、group_level パラメータで配列の要素数に基づいてさらにグループを減らすことが可能です。 ある ブール値 いいえ ある
group_level 使用するグループ・レベルを指定する。 このビューがJSON配列のキーを使用している場合にのみ適用されます。 グループが true であることを意味する。 グループ・レベルは、指定された配列要素数で縮小結果をグループ化します。 未設定の場合、結果は配列のキー全体でグループ化され、完全なキーごとに削減された値が返されます。 ある 数値 ある
include_docs 応答に、文書の内容全体を組み込みます。 ある ブール値 いいえ ある
inclusive_end 指定された end_key を持つ行を含めます。 ある ブール値 はい ある
key 指定されたキーに一致する文書のみを返します。 キーは JSON 値であり、URL でエンコードする必要があります。 ある JSON 配列 ある
keys 指定したキーのいずれかにマッチする文書のみを返すように指定する。 ビュー関数が出力するキーの型にマッチするキーの JSON 配列の文字列表現。 ある ストリングまたは JSON 配列 ある
limit 返される文書の数を指定されたカウントに制限します。 ある 数値 ある
reduce reduce 関数を使用します。 ある ブール値 はい ある
skip 先頭からこの行数をスキップします。 ある 数値 0 ある
stable 各リクエストでインデックスの同じレプリカを使用するかどうかを指定します。 デフォルト値は false すべてのレプリカにコンタクトし、最初の最も速いレスポンダからの結果を返します。 true に設定し、 update=false と組み合わせて使用する場合、選択されたレプリカが利用可能なレプリカの中で最速のものでない限り、レイテンシの増加やスループットの低下を代償として、一貫性が向上する可能性があります。

注 ：一般的に、 update=true を使用する場合は、このパラメータを true に設定することは推奨されません。

 ある ブール値 いいえ いいえ
stale

注: stale is deprecated. 代わりに、 stable および update をご利用ください。

包含する設計ドキュメント内のすべてのビューの再構築をトリガーせずに、古いビューの結果を使用するかどうかを指定します。

  • ok は、 stable=true&update=false と同等です。
  • update_after は、 stable=true&update=lazy と同等です。
 ある ストリング いいえ いいえ
start_key 指定したキーからレコードを返します。 ある ストリングまたは JSON 配列 ある
start_key_docid 指定した文書 ID からレコードを返します。 ある ストリング ある
update

Specify whether or not the view in question must be updated before you respond to the user.

  • true- Return results after the view is updated.
  • false- Return results without updating the view.
  • lazy- Return the view results without waiting for an update, but update them immediately after the request.
 ある ストリング はい ある

include_docs=true を使用すると、パフォーマンスへの影響が生じる可能性があります。

HTTP を使用して、ユーザー作成のビューを適用し、データベースのパーティションから、ドキュメントの全文を含む最初の 10 件のドキュメントのリストを取得する例をご覧ください。

GET $SERVICE_URL/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_view/$VIEW_NAME?include_docs=true&limit=10 HTTP/1.1

次は、ユーザー作成のビューを適用し、HTTP を使用して、データベースから最初の 10 個の文書のリストを取得する例です。

GET $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME?limit=10 HTTP/1.1

ユーザーが作成した byApplianceProdId ビューを適用し、データベースの small-appliances パーティションから、最初の10件のドキュメントとその全文コンテンツを含むリストを取得する例をご覧ください。

クライアントライブラリでは、 GET の代わりに POST メソッドが使用されます。これは、両者の動作が同じであるためです。

curl -X GET "$SERVICE_URL/products/_partition/small-appliances/_design/appliances/_view/byApplianceProdId?include_docs=true&limit=10"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostPartitionViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostPartitionViewOptions viewOptions =
    new PostPartitionViewOptions.Builder()
        .db("products")
        .ddoc("appliances")
        .includeDocs(true)
        .limit(10)
        .partitionKey("small-appliances")
        .view("byApplianceProdId")
        .build();
ViewResult response =
    service.postPartitionView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postPartitionView({
  db: 'products',
  ddoc: 'appliances',
  includeDocs: true,
  limit: 10,
  partitionKey: 'small-appliances',
  view: 'byApplianceProdId'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_partition_view(
  db='products',
  ddoc='appliances',
  include_docs=True,
  limit=10,
  partition_key='small-appliances',
  view='byApplianceProdId'
).get_result()
print(response)

postPartitionViewOptions := service.NewPostPartitionViewOptions(
  "products",
  "small-appliances",
  "appliances",
  "byApplianceProdId",
)
postPartitionViewOptions.SetIncludeDocs(true)
postPartitionViewOptions.SetLimit(10)
viewResult, response, err := service.PostPartitionView(postPartitionViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

前の Go の例では、以下のインポート・ブロックが必要です。

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

すべての Go の例では、serviceオブジェクトを初期化する必要があります。 詳しくは、API 資料の認証セクションで例を参照してください。

次は、ユーザー作成の getVerifiedEmails ビューを適用して、データベースから最初の 10 個の文書のリストを取得する例です。

クライアントライブラリでは、 GET の代わりに POST メソッドが使用されます。これは、両者の動作が同じであるためです。

curl -X GET "$SERVICE_URL/users/_design/allusers/_view/getVerifiedEmails?limit=10"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .limit(10)
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  limit: 10
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  limit=10
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
postViewOptions.SetLimit(10)
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

前の Go の例では、以下のインポート・ブロックが必要です。

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

すべての Go の例では、serviceオブジェクトを初期化する必要があります。 詳しくは、API 資料の認証セクションで例を参照してください。

要求に対する応答の例を以下に示します。

{
  "offset": 0,
  "rows": [
    {
      "id": "abc125",
      "key": "amelie.smith@aol.com",
      "value": [
        "Amelie Smith",
        true,
        "2020-04-24T10:42:59.000Z"
      ]
    },
    {
      "id": "abc123",
      "key": "bob.smith@aol.com",
      "value": [
        "Bob Smith",
        true,
        "2019-01-24T10:42:59.000Z"
      ]
    }
  ],
  "total_rows": 2
}

索引

ビューが設計文書で定義されると、ビュー内に定義されている情報に基づいて、対応する索引も作成されます。 索引を使用して、 _id フィールド以外の基準で文書を検索します。 例えば、フィールド、フィールドの組み合わせ、または文書の内容を使用して計算された値によって選択できます。 索引には、設計文書が作成されるとすぐにデータが取り込まれます。 大規模なデータベースでは、このプロセスに時間がかかることがあります。

以下のイベントのいずれかが発生した場合、インデックスの内容はインクリメンタルに自動的に更新されます：

  • 新しい文書がデータベースに追加されます。
  • 既存の文書がデータベースから削除されます。
  • データベース内の既存の文書が更新されます。

ビュー定義が変更されるか、同じ設計文書内の別のビュー定義が変更されると、ビュー索引は完全に再作成されます。 再作成により、ビュー定義に対する変更がビュー索引に反映されます。 再作成が確実に行われるようにするために、設計文書が更新されるたびにビュー定義の「指紋」が作成されます。 指紋が変更されると、ビュー索引が再作成されます。

ビュー索引は、設計文書に定義されているすべてのビューのうちいずれかのビューを変更すると、再作成されます。 例えば、3 つのビューを含む設計文書がある場合に設計文書を更新すると、設計文書内の 3 つすべてのビュー索引が再作成されます。 より大規模なデータベースの設計文書を変更する場合は、設計文書の管理ガイドを参照してください。

データベースが最近更新された場合、ビューにアクセスすると結果が遅延する可能性があります。 遅延は、データベースに対する変更の数、およびデータベースの内容が変更されたためにビュー索引が最新でないかどうかによって影響を受けます。

これらの遅延をなくすことはできません。 新しく作成されたデータベースの場合、文書を挿入または更新する前に、データベース内の設計文書にビュー定義を作成することにより、遅延を削減することができます。 設計文書にビュー定義を作成すると、文書の挿入時に、索引に対して増分更新が実行されます。

応答速度のほうがデータを最新に保つことよりも重要な場合は、代わりに、ユーザーが古いバージョンのビュー索引にアクセスできるようにすることもできます。 古いバージョンのビュー索引にアクセスできるようにするには、ビュー照会を行うときに update 照会ストリング・パラメーターを使用します。

索引付けプロセッサーを使用せずに古い索引バージョンを保存する場合は、"autoupdate": {"indexes": false} を設定して、すべての索引が作成されないようにすることができます。 または、以下のいずれかのオプションを設計文書に追加して、ビューが自動更新されないようにすることもできます。 "autoupdate": false を設定すると、すべての索引タイプが索引付けされないようにすることができます。

以下の例を参照してください。

{
  "_id": "_design/lookup",
  "autoupdate": false,
  "views": {
    "view": {
      "map": "function(doc)..."
    }
  }
}

{
  "_id": "_design/lookup",
  "autoupdate": {"views": false},
  "views": {
    "view": {
      "map": "function(doc)..."
    }
  }
}

ビューの最新性

デフォルトでは、すべての索引結果にデータベースの現在の状態が反映されます。 IBM Cloudant は、バックグラウンドで索引を自動的かつ非同期的に作成します。 この手法により、 通常、クエリを実行した時点でインデックスは完全に最新の状態になっています。 もし デフォルトでは、IBM Cloudantはクエリ時に残りの更新を適用します。 を適用します。

IBM Cloudantにはいくつかのパラメータがあります、 この動作を変更するために、次に説明するいくつかのパラメータを提供します。 を使用しないことを推奨する。 通常、副作用がその利点を上回るからである。

パラメーター

update オプションは、ビューの更新を待機せずにビュー結果を受け入れる準備ができているかどうかを示します。 デフォルト値は true で、結果を返す前にビューが更新されることを意味します。 lazy 値は、ビューの更新前に結果を返すが、その後、いずれにしてもビューを更新する必要があることを意味します。

IBM Cloudant はバックグラウンドで インデックスを最新の状態に保つよう努めていますが、 update=false や update=lazy を使用してクエリを実行した際、ビューがどの程度 古くなっているかについては保証されません。

stable オプションは、単一の整合したシャードのセットから結果を取得するかどうかを示します。 false という値は、 利用可能なすべてのシャードレプリカに対してクエリが実行され、 IBM Cloudantは最速のレスポンスを使用します。 レスポンスを使用します。 対照的に stable=true インデックスのレプリカを1つだけ使用します。 インデックスの

stable=true 使用するとレイテンシーが大きくなることがある。 を使用すると、たとえ他のコピーの方が速く応答できるとしても、 インデックスのコピーの1つだけを参照するため、待ち時間が長くなります。 を使用すると、たとえ他のコピーの方が速く応答したとしても、 インデックスのコピーの1つだけを参照するため、待ち時間が長くなります。

パラメーターの結合

stable=false と update=false を指定した場合、同じクエリであっても、結果間の不一致が大きくなる。 を指定した場合、同じクエリでデータベースを変更しない場合でも、結果の不一致が大きくなります。 データベースを変更しなくても システムがこの動作に耐えられると確信できる場合以外は、この組み合わせは避けることをお勧めします。 システムがこの動作に耐えられると確信していない限り、この組み合わせは避けることをお勧めします。

返された行のソート

ビュー照会によって返されるデータは、配列の形式です。 配列内の各要素は、標準的な UTF-8 ソートアルゴリズムを用いてソートされます。 ソートは、ビュー関数で定義されたキーに適用されます。

以下の表に、出力の基本的な順序を示します。

返された行の順序
値 順序
null 1 番目
false
true
数値
テキスト (小文字)
テキスト (大文字)
配列 (この表に示されている順序を使用した、各要素の値による)
オブジェクト (この表に示されている順序を使用した、キー順序におけるキーの値による) 最後

返されるビュー情報の順序を逆にするには、descending 照会値を true に設定します。

keys パラメーターを指定するビュー要求を実行する場合、結果は、指定された keys 配列と同じ順序で返されます。

次は、HTTP を使用して、逆のソート順でレコードを要求する例です。

GET $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME?descending=true HTTP/1.1
Accept: application/json

次は、逆のソート順でレコードを要求する例です。

クライアント・ライブラリーは、GET の代わりに POST メソッドを使用します。これは、これらのメソッドが同様の動作をするためです。

curl -X GET "$SERVICE_URL/users/_design/allusers/_view/getVerifiedEmails?descending=true"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .descending(true)
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  descending: true
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  descending=True
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
postViewOptions.SetDescending(true)
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

前の Go の例では、以下のインポート・ブロックが必要です。

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

すべての Go の例では、serviceオブジェクトを初期化する必要があります。 詳しくは、API 資料の認証セクションで例を参照してください。

次は、レコードを逆のソート順で要求する場合の応答の例です。

{
  "total_rows": 2,
  "offset": 0,
  "rows": [
    {
      "id": "abc123",
      "key": "bob.smith@aol.com",
      "value": [
        "Bob Smith",
        true,
        "2019-01-24T10:42:59.000Z"
      ]
    },
    {
      "id": "abc125",
      "key": "amelie.smith@aol.com",
      "value": [
        "Amelie Smith",
        true,
        "2020-04-24T10:42:59.000Z"
      ]
    }
  ]
}

開始キーと終了キーの指定

start_key および end_key の各照会引数を使用して、ビューの照会時に返される値の範囲を指定できます。

ソート方向は、常に最初に適用されます。 次に、 start_key および end_key の各照会引数を使用して、フィルタリングが適用されます。 ソートプランとフィルタープランの組み合わせが意味をなさない場合、キーレンジに一致する行がない可能性があります。

次は、HTTP を使用して、start_key および end_key の各照会引数を含むグローバル照会を行う例です。

GET $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME?start_key="alpha"&end_key="beta" HTTP/1.1

次は、start_key および end_key の各照会引数を含むグローバル照会の例です。

クライアントライブラリでは、 GET の代わりに POST メソッドが使用されます。これは、両者の動作が同じであるためです。

curl -X GET "$SERVICE_URL/users/_design/allusers/_view/getVerifiedEmails?start_key=\"alpha\"&end_key=\"beta\""

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .startKey("alpha")
    .endKey("beta")
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  startKey: 'alpha',
  endKey: 'beta'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  start_key='alpha',
  end_key='beta'  
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
postViewOptions.StartKey = "alpha"
postViewOptions.EndKey = "beta"
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

前の Go の例では、以下のインポート・ブロックが必要です。

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

すべての Go の例では、serviceオブジェクトを初期化する必要があります。 詳しくは、API 資料の認証セクションで例を参照してください。

たとえば、 start_key を使用して alpha、end_key に beta を使用すると 1 件の結果を返すデータベースがある場合、逆の順序では 400 (誤った要求) エラーが発生します。 これは、キー・フィルターが適用される前に、ビュー内の項目が反転されるためです。

次は、HTTP を使用して、start_key および end_key クエリの解析エラーが発生する可能性があります： 

GET $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME?descending=true&start_key="alpha"&end_key="beta" HTTP/1.1

次は、start_key と end_key の順序を逆にすると 400 エラーが発生する可能性がある理由を示す例です。

クライアントライブラリでは、 GET の代わりに POST メソッドが使用されます。これは、両者の動作が同じであるためです。

curl -X GET "$SERVICE_URL/users/_design/allusers/_view/getVerifiedEmails?descending=true&start_key=\"alpha\"&end_key=\"beta\""

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .descending(true)
    .startKey("alpha")
    .endKey("beta")
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  descending: true,
  startKey: 'alpha',
  endKey: 'beta'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  descending=True,  
  start_key='alpha',
  end_key='beta'  
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
postViewOptions.SetDescending(true)
postViewOptions.StartKey = "alpha"
postViewOptions.EndKey = "beta"
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

前の Go の例では、以下のインポート・ブロックが必要です。

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

すべての Go の例では、serviceオブジェクトを初期化する必要があります。 詳しくは、API 資料の認証セクションで例を参照してください。

beta の end_key が、alpha の start_key の前に表示され、照会構文解析エラーが発生します。

解決策は、ソート順だけでなく、start_key パラメーター値と end_key パラメーター値も反転することです。

次の例では、descending 照会引数を使用して、start_key および end_key の各照会引数を反転することにより、出力の順序を適切にフィルタリングおよび反転します。

HTTP を使用して、適切なフィルタリングおよびソートをグローバル照会に適用する例を以下に示します。

GET $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME?descending=true&start_key="beta"&end_key="alpha" HTTP/1.1

次は、適切なフィルタリングおよびソートをグローバル照会に適用する例です。

クライアントライブラリでは、 GET の代わりに POST メソッドが使用されます。これは、両者の動作が同じであるためです。

curl -X GET "$SERVER_URL/users/_design/allusers/_view/getVerifiedEmails?descending=true&start_key=\"beta\"&end_key=\"alpha\""

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .descending(true)
    .startKey("beta")
    .endKey("alpha")
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  descending: true,
  startKey: 'beta',
  endKey: 'alpha'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  descending=True,  
  start_key='beta',
  end_key='alpha'  
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
postViewOptions.SetDescending(true)
postViewOptions.StartKey = "beta"
postViewOptions.EndKey = "alpha"
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

前の Go の例では、以下のインポート・ブロックが必要です。

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

すべての Go の例では、serviceオブジェクトを初期化する必要があります。 詳しくは、API 資料の認証セクションで例を参照してください。

キーのリストを使用したビューの照会

使用するキーのリストを指定して、照会を実行することもできます。

この方法でデータベースからの情報を要求する場合、指定された $DDOC 設計文書からの指定された $VIEW_NAME が使用されます。 GET メソッドの keys パラメーターと同様に、POST メソッドを使用して、ビュー結果の取得に使用するキーを指定できます。 その他すべての側面において、 POST メソッドは、GET API 要求と同じです。 特に、照会ストリングまたは JSON 本文のいずれかで、その照会パラメーターのいずれかを使用できます。

次は、すべてのユーザーを返す HTTP 要求 (ビューのキーが amelie.smith@aol.com または bob.smith@aol.com のいずれかに一致する) の例です。

POST $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME HTTP/1.1
Content-Type: application/json
{
  "keys": [
    "amelie.smith@aol.com",
    "bob.smith@aol.com"
  ]
}

すべてのユーザーを返すグローバルクエリの例をご覧ください（ビューのキーが amelie.smith@aol.com または bob.smith@aol.com のいずれかと一致する場合）：

curl -X POST "$SERVICE_URL/users/_design/allusers/_view/getVerifiedEmails" -H "Content-Type: application/json" --data '{
  "keys": [
    "amelie.smith@aol.com",
    "bob.smith@aol.com"
  ]
}'

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
import java.util.Arrays;
Cloudant service = Cloudant.newInstance();
PostViewOptions viewOptions = new PostViewOptions.Builder()
    .db("users")
    .ddoc("allusers")
    .view("getVerifiedEmails")
    .keys(Arrays.asList("amelie.smith@aol.com", "bob.smith@aol.com"))
    .build();
ViewResult response =
    service.postView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postView({
  db: 'users',
  ddoc: 'allusers',
  view: 'getVerifiedEmails',
  keys: ['amelie.smith@aol.com', 'bob.smith@aol.com']
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_view(
  db='users',
  ddoc='allusers',
  view='getVerifiedEmails',
  keys=['amelie.smith@aol.com', 'bob.smith@aol.com']
).get_result()
print(response)

postViewOptions := service.NewPostViewOptions(
  "users",
  "allusers",
  "getVerifiedEmails",
)
keys := []interface{}{"amelie.smith@aol.com", "bob.smith@aol.com"}
postViewOptions.SetKeys(keys)
viewResult, response, err := service.PostView(postViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

前の Go の例では、以下のインポート・ブロックが必要です。

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

すべての Go の例では、serviceオブジェクトを初期化する必要があります。 詳しくは、API 資料の認証セクションで例を参照してください。

応答には、標準のビュー情報が含まれますが、キーが一致する文書に限定されます。

キーのリストを使用して照会を実行した後の応答の例を以下に示します。

{
  "total_rows": 2,
  "offset": 0,
  "rows": [
    {
      "id": "abc125",
      "key": "amelie.smith@aol.com",
      "value": [
        "Amelie Smith",
        true,
        "2020-04-24T10:42:59.000Z"
      ]
    },
    {
      "id": "abc123",
      "key": "bob.smith@aol.com",
      "value": [
        "Bob Smith",
        true,
        "2019-01-24T10:42:59.000Z"
      ]
    }
  ]
}

ページネーション

ビューに キーベースのページネーションを 使用します。 具体的な詳細と例については、APIドキュメントのトピック「 Paging on view queries 」を参照してください。

複数文書の取り出し

次のセクションでは、データベース内の多数のドキュメントに対して POST リクエストを行う方法について説明します。

クライアント・アプリケーションの場合、この手法は、複数の GET API 要求を使用するのよりも効果的です。

ただし、include_docs=true では、それ自体のビューにアクセスする場合と比較して、追加の処理時間が必要になることがあります。

これは、ビュー照会で include_docs=true を使用することにより、クライアント・アプリケーションの応答を構成するために、すべての結果文書の取得が必要になるためです。 実際に、一連の文書すべての GET 要求が実行され、各要求は、他のアプリケーション要求とリソースを求めて競合します。

この影響を軽減する 1 つの方法は、ビュー索引ファイルから直接結果を取得することです。 include_docs=true を省略して、ビュー索引ファイルから直接結果を取得します。 代わりに、設計文書のマップ関数で、ビュー索引の値として必要なフィールドを出力します。

例えば、マップ関数で、以下の設計仕様を使用できます。

function(user) {
  if(user.email_verified === true) {
    emit(user.email, {name: user.name, email_verified: user.email_verified, joined: user.joined});
  }
}

次は、HTTP を使用して、パーティション内のリストされたキーと一致する文書の全コンテンツを取得する要求の例です。

POST $SERVICE_URL/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_view/$VIEW_NAME HTTP/1.1
Content-Type: application/json
{
  "include_docs": true,
  "keys" : [
    "1000043",
    "1000044"
  ]
}

次は、products パーティション内のリストされたキーと一致する文書の全コンテンツを取得する要求の例です。

curl -X POST "$SERVICE_URL/products/_partition/small-appliances/_design/appliances/_view
/byApplianceProdId" -H "Content-Type: application/json" --data '{
  "include_docs": true,
  "keys" : [
    "1000043",
    "1000044"
  ]
}'

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.PostPartitionViewOptions;
import com.ibm.cloud.cloudant.v1.model.ViewResult;
import java.util.Arrays;
Cloudant service = Cloudant.newInstance();
PostPartitionViewOptions viewOptions =
    new PostPartitionViewOptions.Builder()
        .db("products")
        .ddoc("appliances")
        .keys(Arrays.asList("1000043", "1000044"))
        .includeDocs(true)
        .partitionKey("small-appliances")
        .view("byApplianceProdId")
        .build();
ViewResult response =
    service.postPartitionView(viewOptions).execute()
        .getResult();
System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');
const service = CloudantV1.newInstance({});
service.postPartitionView({
  db: 'products',
  ddoc: 'appliances',
  keys: ['1000043', '1000044'],
  includeDocs: true,
  partitionKey: 'small-appliances',
  view: 'byApplianceProdId'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_partition_view(
  db='products',
  ddoc='appliances',
  keys=['1000043', '1000044'],
  include_docs=True,  
  partition_key='small-appliances',
  view='byApplianceProdId'
).get_result()
print(response)

postPartitionViewOptions := service.NewPostPartitionViewOptions(
  "products",
  "small-appliances",
  "appliances",
  "byApplianceProdId",
)
keys := []interface{}{"1000043", "1000044"}
postPartitionViewOptions.SetKeys(keys)
postPartitionViewOptions.SetIncludeDocs(true)
viewResult, response, err := service.PostPartitionView(postPartitionViewOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(viewResult, "", "  ")
fmt.Println(string(b))

前の Go の例では、以下のインポート・ブロックが必要です。

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

すべての Go の例では、serviceオブジェクトを初期化する必要があります。 詳しくは、API 資料の認証セクションで例を参照してください。

次は、指定されたキーと一致する各アプライアンスの文書全体を返す (省略された) 応答の例です。

{
  "total_rows": 4,
  "offset": 1,
  "rows": [
    {
      "id": "small-appliances:1000043",
      "key": "1000043",
      "value": [
        "Bar",
        "Pro",
        "A professional, high powered innovative tool with a sleek design and outstanding performance"
      ],
      "doc": {
        "_id": "small-appliances:1000043",
        "_rev": "2-b595c929aabc3ab13415cd0cc03e665d",
        "type": "product",
        "taxonomy": [
          "Home",
          "Kitchen",
          "Small Appliances"
        ],
        "keywords": [
          "Bar",
          "Blender",
          "Kitchen"
        ],
        "productId": "1000043",
        "brand": "Bar",
        "name": "Pro",
        "description": "A professional, high powered innovative tool with a sleek design and outstanding performance",
        "colours": [
          "black"
        ],
        "price": 99.99,
        "image": "assets/img/barpro.jpg"
      }
    },
    {
      "id": "small-appliances:1000044",
      "key": "1000044",
      "value": [
        "Baz",
        "Omelet Maker",
        "Easily make delicious and fluffy omelets without flipping - Innovative design - Cooking and cleaning is easy"
      ],
      "doc": {
        "_id": "small-appliances:1000044",
        "_rev": "2-d54d022a9407ab9f06b1889cb2ab8a6e",
        "type": "product",
        "taxonomy": [
          "Home",
          "Kitchen",
          "Small Appliances"
        ],
        "keywords": [
          "Baz",
          "Maker",
          "Kitchen"
        ],
        "productId": "1000044",
        "brand": "Baz",
        "name": "Omelet Maker",
        "description": "Easily make delicious and fluffy omelets without flipping - Innovative design - Cooking and cleaning is easy",
        "colours": [
          "black"
        ],
        "price": 29.99,
        "image": "assets/img/bazomeletmaker.jpg"
      }
    }
  ]
}