Ansichten verwenden

Mithilfe von Ansichten können Sie nach Inhalten in einer Datenbank suchen, die bestimmten Kriterien entsprechen. Die Kriterien sind in der Ansichtsdefinition angegeben.

Die Kriterien können auch als Argumente angegeben werden, wenn Sie die Ansicht verwenden.

Ansicht abfragen

Zum Abfragen einer Ansicht übergeben Sie eine Anforderung mit der Methode GET im folgenden Format:

Methode
Setzen Sie eine Partitionsabfrage mit dem folgenden Befehl ab: GET $SERVICE_URL/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_view/$VIEW_NAME. Oder setzen Sie eine globale Abfrage mit dem folgenden Befehl ab: GET $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME.
Anforderung
Keine
Antwort
JSON-Daten mit den Dokumenten, die von der Ansicht zurückgegeben werden.
Zulässige Rollen
_reader

Die Anforderung führt die folgenden Ansichten aus:

  • Die angegebene „ $VIEW_NAME “ aus dem angegebenen „ $DDOC “-Entwurfsdokument innerhalb der Datenbank „ $DATABASE “, die auf Ergebnisse innerhalb des angegebenen Bereichs beschränkt ist $PARTITION_KEY Daten Partition.
  • Die angegebene „ $VIEW_NAME “ aus dem angegebenen „ $DDOC “-Entwurfsdokument in der Datenbank „ $DATABASE “.

Die Beispiele in diesem Dokument variieren zu Veranschaulichungszwecken zwischen Partitionsabfragen und globalen Abfragen. Wenn nicht anders vermerkt, funktioniert das Ändern des Pfads, um den Partitionsnamen einzubetten oder zu entfernen, für jeden Ansichtsabfragetyp.

Argumente für Abfragen und JSON-Hauptteile

In globalen Abfragen können alle Argumente für Abfragen und JSON-Hauptteile verwendet werden. In Partitionsabfragen kann nur die Untergruppe der Argumente verwendet werden, die in der Tabelle angegeben ist.

Für partitionierte Abfragen stehen eine Teilmenge der Abfrage- und JSON-Body-Argumente zur Verfügung
Argument Beschreibung Optionale Typ Standard Unterstützte Werte Partitionsabfrage
conflicts Geben Sie an, ob eine Liste der konfliktbehafteten Revisionen in die _conflicts Eigenschaft des zurückgegebenen Dokuments aufgenommen werden soll. Wird ignoriert, wenn include_docs nicht auf true gesetzt ist. Ja Boolescher Wert Falsch Ja
descending Gibt die Dokumente in absteigender Schlüsselreihenfolge (descending by key) zurück. Ja Boolescher Wert Falsch Ja
end_key Die Rückgabe von Datensätzen stoppen, wenn der angegebene Schlüssel erreicht ist. Ja Zeichenfolge oder JSON-Array Ja
end_key_docid Die Rückgabe von Datensätzen stoppen, wenn die angegebene Dokument-ID erreicht ist. Ja Zeichenfolge Ja
group Geben Sie an, ob die reduzierten Ergebnisse nach Schlüsseln gruppiert werden sollen. Nur gültig, wenn eine Reduzierfunktion in der Ansicht definiert ist. Wenn die Ansicht Schlüssel im JSON-Array-Format ausgibt, ist es möglich, die Gruppen anhand der Anzahl der Array-Elemente mit dem Parameter group_level weiter zu reduzieren. Ja Boolescher Wert Falsch Ja
group_level Geben Sie eine zu verwendende Gruppenebene an. Dies gilt nur, wenn die Ansicht Schlüssel verwendet, bei denen es sich um JSON-Arrays handelt. Bedeutet, dass die Gruppe true ist. Die Gruppenebene gruppiert die reduzierten Ergebnisse nach der angegebenen Anzahl von Feldelementen. Wenn nicht gesetzt, werden die Ergebnisse nach dem gesamten Array-Schlüssel gruppiert und ein reduzierter Wert für jeden vollständigen Schlüssel zurückgegeben. Ja Numerisch Ja
include_docs Schließt den vollständigen Inhalt der Dokumente in die Antwort ein. Ja Boolescher Wert Falsch Ja
inclusive_end Zeilen mit der angegebenen end_key einschließen. Ja Boolescher Wert Ja Ja
key Gibt nur Dokumente zurück, die dem angegebenen Schlüssel entsprechen. Schlüssel sind JSON-Werte und müssen in URL-Codierung angegeben werden. Ja JSON-Array Ja
keys Geben Sie an, dass nur Dokumente zurückgegeben werden sollen, die mit einem der angegebenen Schlüssel übereinstimmen. String-Darstellung eines JSON-Arrays von Schlüsseln, die dem von der View-Funktion ausgegebenen Schlüsseltyp entsprechen. Ja Zeichenfolge oder JSON-Array Ja
limit Begrenzt die Anzahl der zurückgegebenen Dokumente auf die angegebene Zahl. Ja Numerisch Ja
reduce Verwendet die Reduktionsfunktion (reduce). Ja Boolescher Wert Ja Ja
skip Überspringt die angegebene Anzahl von Zeilen vom Anfang. Ja Numerisch 0 Ja
stable Geben Sie an, ob bei jeder Anfrage dieselbe Replik des Index verwendet werden soll. Der Standardwert false kontaktiert alle Replikate und gibt das Ergebnis des ersten, schnellsten Responders zurück. Die Einstellung „ true “ kann in Verbindung mit „ update=false “ die Konsistenz verbessern, allerdings auf Kosten einer höheren Latenz und eines geringeren Durchsatzes, falls die ausgewählte Replik nicht die schnellste der verfügbaren Repliken ist.

Hinweis: Generell wird davon abgeraten, diesen Parameter auf „ true “ zu setzen, und dies wird nicht empfohlen, wenn Sie „ update=true “ verwenden.

 Ja Boolescher Wert Falsch Nein
stale Hinweis: stale ist veraltet. Verwenden Sie stattdessen stable und update.

Geben Sie an, ob die Ergebnisse einer veralteten Ansicht verwendet werden sollen, ohne dass eine Neuerstellung aller Ansichten innerhalb des übergeordneten Designdokuments ausgelöst wird.
– ok entspricht stable=true&update=false.
– update_after entspricht stable=true&update=lazy.

 Ja Zeichenfolge Falsch Nein
start_key Datensätze ab dem angegebenen Schlüssel zurückgeben. Ja Zeichenfolge oder JSON-Array Ja
start_key_docid Datensätze ab der angegebenen Dokument-ID zurückgeben. Ja Zeichenfolge Ja
update

Geben Sie an, ob die betreffende Ansicht aktualisiert werden muss, bevor Sie dem Benutzer antworten

  • true- Geben Sie die Ergebnisse zurück, nachdem die Ansicht aktualisiert wurde
  • false- Geben Sie die Ergebnisse zurück, ohne die Ansicht zu aktualisieren
  • lazy- Geben Sie die Ergebnisse der Ansicht zurück, ohne auf eine Aktualisierung zu warten, sondern aktualisieren Sie sie sofort nach der Anfrage.
 Ja Zeichenfolge Ja Ja

Die Angabe von include_docs=true kann Auswirkungen auf die Leistung haben.

Sehen Sie sich das Beispiel zur Verwendung von „ HTTP “ an, um eine Liste der ersten 10 Dokumente abzurufen, die den vollständigen Inhalt der Dokumente aus einer Partition einer Datenbank enthalten, wobei eine benutzerdefinierte Ansicht angewendet wird.

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

Sehen Sie sich das Beispiel zur Verwendung von HTTP an, um eine Liste der ersten 10 Dokumente aus einer Datenbank abzurufen, wobei eine vom Benutzer erstellte Ansicht angewendet wird.

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

Im folgenden Beispiel wird eine Liste der ersten 10 Dokumente einschließlich ihres vollständigen Inhalts aus der Partition „ small-appliances “ einer Datenbank abgerufen, wobei die vom Benutzer erstellte Ansicht „ byApplianceProdId “ verwendet wird.

Client-Bibliotheken verwenden die Methode „ POST “ anstelle von „ GET “, da beide das gleiche Verhalten aufweisen.

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))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Für alle Go-Beispiele muss das Objekt service initialisiert sein. Weitere Informationen finden Sie in den Beispielen im Abschnitt 'Authentifizierung' in der API-Dokumentation.

Sehen Sie sich das Beispiel an, um eine Liste der ersten 10 Dokumente aus einer Datenbank abzurufen, wobei die vom Benutzer erstellte getVerifiedEmails-Ansicht angewendet wird.

Client-Bibliotheken verwenden die Methode „ POST “ anstelle von „ GET “, da beide das gleiche Verhalten aufweisen.

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))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Für alle Go-Beispiele muss das Objekt service initialisiert sein. Weitere Informationen finden Sie in den Beispielen im Abschnitt 'Authentifizierung' in der API-Dokumentation.

Beispielantwort für die Anforderung:

{
  "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
}

Indizes

Wenn eine Ansicht in einem Entwurfsdokument definiert wird, wird auch der entsprechende Index auf Basis der in der Ansicht definierten Informationen erstellt. Verwenden Sie Indizes, um Dokumente nach anderen Kriterien als das Feld _id zu suchen. Beispiel: Sie können Dokumente nach einem Feld oder einer Kombination von Feldern auswählen, oder nach einem Wert auswählen, der unter Verwendung des Dokumentinhalts berechnet wird. Der Index wird mit Daten gefüllt, sobald das Entwurfsdokument erstellt wurde. Bei sehr großen Datenbanken kann dieser Prozess einige Zeit dauern.

Wenn eines der folgenden Ereignisse eintritt, wird der Indexinhalt automatisch inkrementell aktualisiert:

  • Der Datenbank wird ein neues Dokument hinzugefügt.
  • Ein vorhandenes Dokument wird aus der Datenbank gelöscht.
  • Ein vorhandenes Dokument in der Datenbank wird aktualisiert.

Ansichtsindizes werden insgesamt neu erstellt, wenn die Ansichtsdefinition geändert wird oder wenn eine andere Ansichtsdefinition in demselben Entwurfsdokument geändert wird. Die Neuerstellung stellt sicher, dass Änderungen an den Ansichtsdefinitionen in den Ansichtsindizes abgebildet werden. Um sicherzustellen, dass die Neuerstellung erfolgt, wird bei jeder Aktualisierung des Dokuments ein Fingerabdruck der Ansichtsdefinition erstellt. Wenn sich der Fingerabdruck ändert, werden die Ansichtsindizes neu erstellt.

Neuerstellungen von Ansichtsindizes finden statt, wenn Sie irgendeine der Ansichten ändern, die in dem betreffenden Entwurfsdokument definiert sind. Wenn Sie zum Beispiel ein Entwurfsdokument mit drei Ansichten haben und das Entwurfsdokument aktualisieren, werden alle drei Ansichtsindizes in dem Entwurfsdokument neu erstellt. Wenn Sie ein Entwurfsdokument für eine größere Datenbank ändern möchten, finden Sie entsprechende Informationen unter Entwurfsdokumentmanagement.

Wenn die Datenbank kürzlich aktualisiert wurde, kann sich die Rückgabe der Ergebnisse verzögern, wenn auf die Ansicht zugegriffen wird. Die Verzögerung wird durch die Anzahl der Änderungen an der Datenbank sowie durch die Bedingung beeinflusst, ob der Ansichtsindex noch nicht aktuell ist, weil der Datenbankinhalt geändert wurde.

Diese Verzögerungen lassen sich nicht vermeiden. Für neu erstellte Datenbanken können Sie die Verzögerungen möglicherweise verringern, indem Sie die Ansichtsdefinition im Entwurfsdokument in Ihrer Datenbank erstellen, bevor Sie Dokumente einfügen oder aktualisieren. Das Erstellen der Sichtdefinition im Entwurfsdokument führt zu inkrementellen Aktualisierungen des Index, wenn die Dokumente eingefügt werden.

Wenn die Antwortgeschwindigkeit einen wichtigeren Aspekt als die Aktualität der Daten darstellt, besteht eine Alternative darin, Benutzern den Zugriff auf eine alte Version des Ansichtsindex zu ermöglichen. Um den Zugriff auf eine alte Version des Ansichtsindex zuzulassen, verwenden Sie den Parameter update in der Abfragezeichenfolge, wenn Sie eine Ansichtsabfrage durchführen.

Wenn Sie alte Indexversionen speichern wollen, ohne dass dazu eine Prozessorbelastung durch Indexierung anfällt, können Sie die Erstellung aller Indizes stoppen, indem Sie "autoupdate": {"indexes": false} angeben. Alternativ können Sie die automatische Aktualisierung von Ansichten stoppen, indem Sie eine der folgenden Optionen in einem Entwurfsdokument hinzufügen. Sie können die Indexierung aller Indextypen stoppen, wenn Sie "autoupdate": false festlegen.

Beispiele:

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

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

Aktualität von Ansichten

Alle Indexergebnisse geben standardmäßig den aktuellen Status der Datenbank wieder. IBM Cloudant erstellt die Indizes automatisch und asynchron im Hintergrund. Diese Vorgehensweise bedeutet in der Regel, dass der Index zum Zeitpunkt der Abfrage vollständig auf dem neuesten Stand ist. Wenn nicht, wendet IBM Cloudant standardmäßig die verbleibenden Aktualisierungen zur Abfragezeit.

IBM Cloudant bietet ein paar Parameter, die im Folgenden beschrieben werden, um dieses Verhalten zu ändern. Wir raten von der Verwendung da die Nebenwirkungen in der Regel ihren Nutzen überwiegen.

Parameter

Die Option update gibt an, ob Sie bereit sind, Ansichtsergebnisse zu akzeptieren, ohne auf die Aktualisierung der Ansicht zu warten. Der Standardwert ist true, was bedeutet, dass die Ansicht aktualisiert wird, bevor Ergebnisse zurückgegeben werden. Der Wert lazy bedeutet, dass die Ergebnisse zurückgegeben werden, bevor die Ansicht aktualisiert wird, dass die Ansicht anschließend jedoch auf jeden Fall aktualisiert werden muss.

IBM Cloudant bemüht sich zwar, die Indizes im Hintergrund auf dem neuesten Stand zu halten, es gibt jedoch keine Garantie dafür, wie veraltet die Ansicht ist, wenn sie mit update=false oder update=lazy abgefragt wird.

Die Option stable gibt an, ob Sie es bevorzugen, Ergebnisse aus einem einzigen konsistenten Satz von Shards abzurufen. Der Wert „ false “ bedeutet, dass alle verfügbaren Shard-Replikate abgefragt werden und IBM Cloudant verwendet die schnellste antwort. Im Gegensatz dazu ist die Einstellung stable=true zwingt die Datenbank, nur eine Replik des index zu verwenden.

Die Verwendung von stable=true kann eine hohe Latenz verursachen, da sie nur eine der Kopien des Indexes abfragt, auch wenn die anderen Kopien schneller reagieren.

Parameter kombinieren

Wenn Sie stable=false und update=false angeben, sehen Sie größere inkonsistenz zwischen den Ergebnissen, selbst bei derselben Abfrage und ohne änderungen an der Datenbank vorzunehmen. Wir raten von dieser Kombination ab, es sei denn sie nicht sicher sind, dass Ihr System dieses Verhalten tolerieren kann.

Zurückgegebene Zeilen sortieren

Die Daten, die von einer Ansichtsabfrage zurückgegeben werden, haben die Form eines Arrays. Jedes Element im Array wird mithilfe einer Standard- UTF-8 Sortierverfahren sortiert. Die Sortierung wird auf den Schlüssel angewendet, der in der Ansichtsfunktion ('view') definiert ist.

Die grundlegende Reihenfolge der Ausgabe wird in der folgenden Tabelle gezeigt:

Reihenfolge der zurückgegebenen Zeilen
Wert Reihenfolge
null Erste
false
true
Zahlen
Text (Kleinbuchstaben)
Text (Großbuchstaben)
Arrays (nach den Werten in jedem Element in der in dieser Tabelle gezeigten Reihenfolge)
Objekte (nach den Werten von Schlüsseln in Schlüsselreihenfolge in der Reihenfolge dieser Tabelle) Letzte

Sie können die Reihenfolge der zurückgegebenen Ansichtsinformationen umkehren, indem Sie den Abfrageparameter descending auf den Wert true setzen.

Wenn Sie eine Ansichtsanforderung absetzen, die den Parameter keys angibt, werden die Ergebnisse in derselben Reihenfolge wie das angegebene Array keys zurückgegeben.

Sehen Sie sich das Beispiel zur Verwendung von HTTP zum Anfordern der Datensätze in umgekehrter Sortierreihenfolge an:

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

Sehen Sie sich das Beispiel zum Anfordern der Datensätze in umgekehrter Sortierreihenfolge an.

Clientbibliotheken verwenden die Methode POST anstelle von GET, da sie ein ähnliches Verhalten aufweisen.

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))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Für alle Go-Beispiele muss das Objekt service initialisiert sein. Weitere Informationen finden Sie in den Beispielen im Abschnitt 'Authentifizierung' in der API-Dokumentation.

Sehen Sie sich die Beispielantwort zum Anfordern der Datensätze in umgekehrter Sortierreihenfolge an:

{
  "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- und Endschlüssel angeben

Mit den Abfrageargumenten start_key und end_key kann der Wertebereich angegeben werden, der beim Abfragen der Ansicht zurückgegeben wird.

Die Sortierrichtung wird immer zuerst angewendet. Als Nächstes wird die Filterung mithilfe der Abfrageargumente start_key und end_key angewendet. Es ist möglich, dass keine Zeilen mit Ihrem Schlüsselbereich übereinstimmen, wenn Sortier- und Filterpläne in Kombination keinen Sinn ergeben.

Sehen Sie sich das Beispiel für die Verwendung von HTTP zum Erstellen einer globalen Abfrage an, die start_key enthält, und end_key-Abfrageargumente:

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

Sehen Sie sich das Beispiel für eine globale Abfrage an, die Abfrageargumente start_key und end_key enthält.

Client-Bibliotheken verwenden die Methode „ POST “ anstelle von „ GET “, da beide das gleiche Verhalten aufweisen.

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))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Für alle Go-Beispiele muss das Objekt service initialisiert sein. Weitere Informationen finden Sie in den Beispielen im Abschnitt 'Authentifizierung' in der API-Dokumentation.

Wenn Sie beispielsweise eine Datenbank haben, die ein Ergebnis zurückgibt, wenn Sie die Abfrage „ start_key “ mit folgendem Inhalt ausführen: alpha und end_key von beta verwenden, erhalten Sie einen Fehler 400 (Fehlerhafte Anforderung) mit einer umgekehrten Reihenfolge. Dies liegt daran, dass die Einträge in der Ansicht umgekehrt werden, bevor der Schlüsselfilter angewendet wird.

Sehen Sie sich das Beispiel an, in dem HTTP verwendet wird, um zu veranschaulichen, warum die Umkehrung der Reihenfolge von start_key und end_key könnte einen Fehler beim Parsen der Abfrage zurückgeben:

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

Sehen Sie sich das Beispiel an, das veranschaulicht, warum die Umkehrung der Reihenfolge von start_key und end_key einen Fehler 400 verursachen kann.

Client-Bibliotheken verwenden die Methode „ POST “ anstelle von „ GET “, da beide das gleiche Verhalten aufweisen.

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))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Für alle Go-Beispiele muss das Objekt service initialisiert sein. Weitere Informationen finden Sie in den Beispielen im Abschnitt 'Authentifizierung' in der API-Dokumentation.

Die end_key von beta wird vor der start_key von alpha angezeigt, was zu einem Abfrage-Parsing-Fehler führt.

Die Lösung besteht darin, nicht nur die Sortierreihenfolge, sondern auch die Werte der Parameter start_key und end_key umzukehren.

Das folgende Beispiel zeigt die korrekte Filterung und Umkehrung der Reihenfolge der Ausgabe mithilfe des Abfragearguments descending und der Abfrageargumente start_key und end_key.

Beispiel für die Verwendung von HTTP mit korrekter Anwendung der Filterung und Sortierung auf eine globale Abfrage:

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

Sehen Sie sich das Beispiel zum Anwenden der korrekten Filterung und Sortierung auf eine globale Abfrage an.

Client-Bibliotheken verwenden die Methode „ POST “ anstelle von „ GET “, da beide das gleiche Verhalten aufweisen.

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))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Für alle Go-Beispiele muss das Objekt service initialisiert sein. Weitere Informationen finden Sie in den Beispielen im Abschnitt 'Authentifizierung' in der API-Dokumentation.

Ansicht mit einer Liste von Schlüsseln abfragen

Sie können eine Abfrage auch unter Angabe einer Liste der zu verwendenden Schlüssel ausführen.

Wenn Informationen aus einer Datenbank auf diese Weise angefordert werden, wird die angegebene $VIEW_NAME aus dem angegebenen $DDOC-Entwurfsdokument verwendet. Ebenso wie beim Parameter keys für die Methode GET können Sie die Methode POST verwenden, um die Schlüssel anzugeben, die zum Abrufen der Ansichtsergebnisse verwendet werden sollen. In allen anderen Aspekten stimmt die Methode POST mit der API-Anforderung GET überein. Insbesondere können Sie jeden der Abfrageparameter entweder in der Abfragezeichenfolge oder im JSON-Hauptteil verwenden.

Sehen Sie sich die HTTP-Beispielanforderung an, die alle Benutzer zurückgibt, wobei der Schlüssel für die Ansicht entweder amelie.smith@aol.com oder bob.smith@aol.com entspricht:

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"
  ]
}

Hier ein Beispiel für eine globale Abfrage, die alle Benutzer zurückgibt (wobei der Schlüssel für die Ansicht entweder amelie.smith@aol.com oder bob.smith@aol.com lautet):

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))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Für alle Go-Beispiele muss das Objekt service initialisiert sein. Weitere Informationen finden Sie in den Beispielen im Abschnitt 'Authentifizierung' in der API-Dokumentation.

Die Antwort enthält die Standardinformationen für Ansichten, jedoch nur die Dokumente, bei denen die Schlüssel übereinstimmen.

Beispiel für eine Antwort nach Ausführung einer Abfrage unter Verwendung einer Liste von Schlüsseln:

{
  "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"
      ]
    }
  ]
}

Seitenaufteilung

Verwenden Sie eine schlüsselbasierte Paginierung für Ansichten. Spezifische Details und Beispiele finden Sie in der API-Dokumentation unter Paging bei View-Abfragen.

Abrufen mehrerer Dokumente

Der folgende Abschnitt befasst sich mit einer „ POST “-Abfrage, die auf zahlreiche Dokumente aus einer Datenbank abzielt.

Für eine Clientanwendung ist dieses Verfahren effizienter als die Verwendung mehrerer API-Anforderungen mit der Methode GET.

Allerdings kann die Einstellung include_docs=true im Vergleich zu dem Zugriff auf die Ansicht allein zusätzliche Verarbeitungszeit erfordern.

Dies hat den Grund, dass bei Verwendung der Einstellung include_docs=true in einer Ansichtsabfrage alle Ergebnisdokumente abgerufen werden müssen, um die Antwort für die Clientanwendung zusammenzustellen. Tatsächlich wird eine ganze Reihe von GET-Anforderungen für Dokumente ausgeführt, die jeweils mit den anderen Anwendungsanforderungen um Ressourcen konkurrieren.

Eine Möglichkeit, diesen Effekt zu mindern, besteht darin, Ergebnisse direkt aus der Ansichtsindexdatei abzurufen. Lassen Sie die Angabe include_docs=true weg, um Ergebnisse direkt aus der Ansichtsindexdatei abzurufen. Geben Sie stattdessen die Felder, die als Wert für den Ansichtsindex erforderlich sind, in der Zuordnungsfunktion in einem Entwurfsdokument aus ('emit').

In Ihrer Zuordnungsfunktion könnten Sie zum Beispiel die folgende Entwurfsspezifikation verwenden:

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

Sehen Sie sich die Beispielanforderung an, die HTTP zum Abrufen des vollständigen Inhalts von Dokumenten verwendet, die den aufgelisteten Schlüsseln in einer Partition entsprechen:

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"
  ]
}

Sehen Sie sich die Beispielanforderung zum Abrufen des vollständigen Inhalts von Dokumenten an, die den aufgelisteten Schlüsseln in der products-Partition entsprechen:

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))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Für alle Go-Beispiele muss das Objekt service initialisiert sein. Weitere Informationen finden Sie in den Beispielen im Abschnitt 'Authentifizierung' in der API-Dokumentation.

Sehen Sie sich die Beispielantwort (abgekürzt) an, die das vollständige Dokument für jede Appliance zurückgibt, die einem bereitgestellten Schlüssel entspricht:

{
  "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"
      }
    }
  ]
}