Funktionsweise von Entwurfsdokumenten

IBM® Cloudant® for IBM Cloud® behandelt bestimmte Felder und Werte in Entwurfsdokumenten als Funktionen. Mithilfe von Entwurfsdokumenten werden Indizes erstellt und Aktualisierungen validiert.

Jedes Entwurfsdokument definiert entweder partitionierte oder globale Indizes, die durch das Feld options.partitioned gesteuert werden. Ein partitionierter Index lässt nur Abfragen für eine einzelne Datenpartition in einer partitionierten Datenbank zu. Ein globaler Index ermöglicht Abfragen für alle Daten innerhalb einer Datenbank. Dies verursacht jedoch einen höheren Aufwand in den Bereichen Latenz und Durchsatz der Abfragen als bei einem partitionierten Index.

Entwurfsdokument erstellen oder aktualisieren

Methode: PUT /$DATABASE/_design/$DDOC
Anforderung: JSON der Informationen des Entwurfsdokuments.
Antwort: JSON-Status.
Zulässige Rollen: _admin

Wenn Sie ein Entwurfsdokument erstellen möchten, laden Sie es in die angegebene Datenbank hoch.

In diesen Beispielen $VARIABLES kann auf Standard-oder Entwurfsdokumente verweisen. Um zwischen ihnen zu unterscheiden, haben Standarddokumente ein _id, das mit $DOCUMENT_ID gekennzeichnet ist, während Entwurfsdokumente ein _id haben, das mit $DDOC gekennzeichnet ist.

Die Dokument-ID eines Entwurfsdokuments enthält in keinem Fall einen Partitionsschlüssel, unabhängig vom Partitionierungstyp der Datenbank. Auf den Partitionsschlüssel kann verzichtet werden, da die in einem Entwurfsdokument enthaltenen Indizes für alle Partitionen einer partitionierten Datenbank gelten.

Wenn ein Entwurfsdokument aktualisiert wird, löscht IBM Cloudant die Indizes der vorherigen Version und erstellt den Index völlig neu. Wenn Sie ein Entwurfsdokument für eine umfangreiche Datenbank ändern müssen, beachten Sie die Hinweise im Leitfaden zur Verwaltung von Entwurfsdokumenten.

Die Struktur eines Entwurfsdokuments umfasst die folgenden Elemente:

_id

ID des Entwurfsdokuments. Dieser ID wird immer das Präfix _design vorangestellt und sie enthält niemals einen Partitionsschlüssel, unabhängig vom Partitionierungstyp der Datenbank.

_rev

Revision des Entwurfsdokuments.

Optionen

Enthält Optionen für dieses Entwurfsdokument.

Partitioniert (optional, boolesch): Legt fest, ob dieses Entwurfsdokument partitionierte oder globale Indizes beschreibt. Weitere Informationen finden Sie unter Das Feld options.partitioned.

Ansichten (optional)

Ein Objekt, das MapReduce-Ansichten beschreibt.

   `Viewname`
  :  (One for each view) - View Definition.

       Map
         :  Map Function for the view.

Reduce (optional)

Reduce-Funktion für die Ansicht.

Indizes (optional)

Ein Objekt, das Suchindizes beschreibt.

Indexname: (Eine für jeden Index)- Indexdefinition.
Analysefunktion: Objekt, das den zu verwendenden Analysator beschreibt, oder ein Objekt mit den folgenden Feldern:

Name

Name der Analysefunktion. Gültige Werte sind standard, email, keyword, simple, whitespace, classic und perfield.

Stoppwörter (optional)

Ein Array von Stoppwörtern. Stoppwörter dürfen nicht indexiert werden. Wenn dieses Array angegeben ist, überschreibt es die Standardliste der Stoppwörter. Die Standardliste der Stoppwörter hängt von der Analysefunktion ab. Die standardmäßige Analysefunktion enthält die folgende Liste mit Stoppwörtern: 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 und with.

Standard (für die Analysefunktion pro Feld)

Standardsprache, die verwendet werden soll, wenn für das Feld keine Sprache angegeben ist.

Felder (für die Analysefunktion pro Feld): Ein Objekt, das angibt, welche Sprache für die Analyse der einzelnen Indexfelder verwendet werden soll. Die Feldnamen in dem Objekt entsprechen den Feldnamen im Index, d. h. dem ersten Parameter der Indexfunktion. Die Werte der Felder geben die zu verwendenden Sprachen an (z. B. english).
Index: Funktion, die die Indizierung vornimmt.

Filter (optional, nicht zulässig, wenn partitioned für true steht)

Filterfunktionen.

Funktionsname (einer für jede Funktion): Funktionsdefinition.

Validate_doc_update (optional, nicht zulässig, wenn partitioned auf true gesetzt ist)

Validierungsfunktion für Aktualisierungen.

Das Feld `options.partitioned`

Dieses Feld legt fest, ob der erstellte Index ein partitionierter oder globaler Index ist.

Dieses Feld enthält die folgenden Werte:

Werte für das Feld options.partitioned
Wert	Beschreibung	Anmerkungen
`true`	Partitionierten Index erstellen.	Kann nur in einer partitionierten Datenbank verwendet werden.
`false`	Globalen Index erstellen.	Kann in jeder Datenbank verwendet werden.

Der Standardwert für partitioned richtet sich nach der Einstellung 'Partitioniert' für die Datenbank:

Einstellungen für Partitionierung
Partitionierte Datenbank?	Standardwert für `partitioned`	Zulässige Werte
Ja	`true`	`true`, `false`
Nein	`false`	`false`

Entwurfsdokument kopieren

Sie können die neueste Version eines Entwurfsdokuments in ein neues Dokument kopieren, indem Sie das Ausgangsdokument und das Zieldokument angeben. Die Kopie wird unter Verwendung der Anforderungsmethode COPY angefordert.

COPY is a nonstandard HTTP command.

Im folgenden Beispiel wird angefordert, dass IBM Cloudant das Entwurfsdokuments allusers in das neue Entwurfsdokument copyOfAllusers kopiert und es wird eine Antwort generiert, die die ID und die Überarbeitung des neuen Dokuments enthält.

Beim Kopieren eines Entwurfsdokuments werden die Ansichtsindizes nicht automatisch wiederhergestellt. Analog zu anderen Ansichten werden diese Indizes erneut erstellt, wenn Sie zum ersten Mal auf die neue Ansicht zugreifen.

Der folgende Beispielbefehl kopiert das Entwurfsdokument unter Verwendung von HTTP:

COPY $SERVICE_URL/$DATABASE/_design/$DDOC HTTP/1.1
Content-Type: application/json
Destination: _design/$COPY_OF_DDOC

Sehen Sie sich den folgenden Beispielbefehl zum Kopieren eines Entwurfsdokuments an:

Die IBM Cloudant SDKs unterstützen derzeit nicht die HTTP COPY Methode.

curl "$SERVICE_URL/users/_design/allusers" \
	-X COPY \
	-H "Content-Type: application/json" \
	-H "Destination: _design/copyOfAllusers"

Beispielantwort für die Kopieranforderung:

{
  "ok": true,
  "id": "_design/copyOfAllusers",
  "rev": "1-9c65296036141e575d32ba9c034dd3ee"
}

Struktur des Kopierbefehls

Methode: COPY /$DATABASE/_design/$DDOC
Anforderung: Keine.
Antwort: JSON-Code, der das neue Dokument und die Revision beschreibt.
Zulässige Rollen: _design

Abfrageargumente

Argument

rev

Beschreibung: Überarbeitung, aus der kopiert werden soll.
Optionale: Ja.
Typ: Zeichenfolge.

HTTP-Header

Überschrift

Destination

Beschreibung: Zieldokument (und optionale Überarbeitung)
Optionale: Anzahl

Das als Quelle verwendete Entwurfsdokument wird in der Anforderungszeile angegeben. Im HTTP-Header Destination der Anforderung wird das Zieldokument angegeben.

Aus einer bestimmten Revision kopieren

Wenn Sie aus einer bestimmten Version kopieren möchten, fügen Sie das Argument rev zur Abfragezeichenfolge hinzu.

Das neue Entwurfsdokument wird unter Verwendung der angegebenen Revision des Quellendokuments erstellt.

Der folgende Beispielbefehl kopiert eine bestimmte Revision des Entwurfsdokuments unter Verwendung von HTTP:

COPY $SERVICE_URL/$DATABASE/_design/$DDOC?rev=$REV HTTP/1.1
Content-Type: application/json
Destination: _design/$COPY_OF_DDOC

Der folgende Beispielbefehl kopiert eine bestimmte Revision des Entwurfsdokuments unter Verwendung der Befehlszeile:

curl "$SERVICE_URL/users/_design/allusers?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5" \
	-X COPY \
	-H "Content-Type: application/json" \
	-H "Destination: _design/copyOfAllusers"

In vorhandenes Entwurfsdokument kopieren

Geben Sie zum Überschreiben bzw. Kopieren in ein vorhandenes Dokument die aktuelle Revisionszeichenfolge für das Zieldokument im Parameter rev als HTTP-Headerzeichenfolge für Destination an.

Der folgende Beispielbefehl überschreibt eine vorhandene Kopie des Entwurfsdokuments unter Verwendung von HTTP:

COPY $SERVICE_URL/$DATABASE/_design/$DDOC
Content-Type: application/json
Destination: _design/$COPY_OF_DDOC?rev=$REV

Der folgende Beispielbefehl überschreibt eine vorhandene Kopie des Entwurfsdokuments unter Verwendung der Befehlszeile:

curl "$SERVICE_URL/users/_design/allusers" \
	-X COPY \
	-H "Content-Type: application/json" \
	-H "Destination: _design/copyOfAllusers?rev=1-9c65296036141e575d32ba9c034dd3ee"

Der Rückgabewert enthält die ID und die neue Revision des kopierten Dokuments.

Beispielantwort für das Überschreiben einer vorhandenen Kopie des Entwurfsdokuments:

{
  "id" : "_design/copyOfAllusers",
  "rev" : "2-55b6a1b251902a2c249b667dab1c6692"
}

Entwurfsdokument löschen

Sie können ein vorhandenes Entwurfsdokument löschen. Beim Löschen eines Entwurfsdokuments werden auch alle zugeordneten Ansichtsindizes gelöscht und der von diesen Indizes belegte Plattenspeicherplatz wird freigegeben.

Zum Löschen eines Entwurfsdokuments müssen Sie die aktuelle Revision des Entwurfsdokuments im Abfrageargument rev angeben.

Der folgende Beispielbefehl löscht ein Entwurfsdokument unter Verwendung von HTTP:

DELETE $SERVICE_URL/$DATABASE/_design/$DDOC?rev=$REV HTTP/1.1

Sehen Sie sich die folgenden Beispiele zum Löschen eines Entwurfsdokuments an:

curl "$SERVICE_URL/users/_design/allusers?rev=2-21314508552eceb0e3012429d04575da" -X DELETE

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.delete_design_document(
  db='users',
  ddoc='allusers',
  rev='2-21314508552eceb0e3012429d04575da'
).get_result()

print(response)

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.DeleteDesignDocumentOptions;
import com.ibm.cloud.cloudant.v1.model.DocumentResult;

Cloudant service = Cloudant.newInstance();

DeleteDesignDocumentOptions designDocumentOptions =
    new DeleteDesignDocumentOptions.Builder()
        .db("users")
        .ddoc("allusers")
        .rev("2-21314508552eceb0e3012429d04575da")
        .build();

DocumentResult response =
    service.deleteDesignDocument(designDocumentOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.deleteDesignDocument({
  db: 'users',
  ddoc: 'allusers',
  rev: '2-21314508552eceb0e3012429d04575da'
}).then(response => {
  console.log(response.result);
});

deleteDesignDocumentOptions := service.NewDeleteDesignDocumentOptions(
  "users",
  "allusers",
)
deleteDesignDocumentOptions.SetRev("2-21314508552eceb0e3012429d04575da")

documentResult, response, err := service.DeleteDesignDocument(deleteDesignDocumentOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(documentResult, "", "  ")
fmt.Println(string(b))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Beispielantwort mit ID und Revision des gelöschten Dokuments:

{
  "id": "_design/allusers",
  "ok": true,
  "rev": "3-7a05370bff53186cb5d403f861aca154"
}

Struktur des Löschbefehls

Methode: DELETE /db/_design/$DDOC
Anforderung: Keine.
Antwort: JSON-Code des gelöschten Entwurfsdokuments.
Zulässige Rollen: _design

Abfrageargumente

Argument

rev

Beschreibung: Aktuelle Revision des Dokuments zur Validierung.
Optionale: Ja, wenn If-Match Kopfzeile vorhanden.
Typ: Zeichenfolge.

HTTP-Header

Überschrift

If-Match

Beschreibung: Aktuelle Revision des Dokuments zur Validierung.
Optionale: Ja, wenn rev Abfrageargument vorhanden ist.

Ansichten

Ein wichtiger Verwendungszweck von Entwurfsdokumenten ist die Erstellung von Ansichten. Weitere Informationen zum Erstellen von Ansichten finden Sie unter Ansichten (MapReduce).

Indizes

Alle Abfragen werden auf vordefinierte Indizes angewendet, die in Entwurfsdokumenten definiert sind. Diese Indizes sind in der folgenden Liste angegeben:

Wenn Sie zum Beispiel ein Entwurfsdokument erstellen möchten, das für Suchvorgänge verwendet wird, stellen Sie sicher, dass die beiden folgenden Bedingungen eingehalten werden:

Das Dokument wurde als Entwurfsdokument definiert, d. h. _id beginnt mit dem Präfix _design/.
In dem Dokument wurde ein Suchindex erstellt, indem das Dokument mit einem entsprechenden Feld aktualisiert wurde, oder indem ein neues Dokument erstellt wurde, das den Suchindex enthält.

Sobald das Entwurfsdokument mit Suchindex vorhanden ist und der Index erstellt wurde, können Sie den Index in Suchabfragen verwenden.

Allgemeine Anmerkungen zu Funktionen in Entwurfsdokumenten

Funktionen in Entwurfsdokumenten werden auf mehreren Knoten für jedes Dokument ausgeführt, d. h. sie werden möglicherweise mehrmals ausgeführt. Um Inkonsistenzen zu vermeiden, müssen sie idempotent sein, das heißt, sie müssen sich identisch verhalten, wenn sie mehrmals oder auf verschiedenen Knoten ausgeführt werden. Insbesondere dürfen keine Funktionen verwendet werden, die Zufallszahlen generieren oder die aktuelle Uhrzeit zurückgeben.

Filterfunktionen

Entwurfsdokumente, für die options.partitioned auf true gesetzt ist, können kein Feld filters enthalten.

Filterfunktionen sind Entwurfsdokumente, die den Feed mit Änderungen filtern. Diese Funktionen wenden Tests auf jedes Objekt an, das im Feed mit Änderungen entalten ist.

Wenn Tests der Filterfunktion fehlschlagen, wird das betreffende Objekt aus dem Feed 'entfernt' (herausgefiltert). Wenn die Funktion nach der Anwendung auf eine Änderung das Ergebnis true zurückgibt, verbleibt die Änderung im Feed. Mit anderen Worten: Filterfunktionen entfernen bzw. ignorieren Änderungen, die nicht überwacht werden sollen.

Filterfunktionen können auch zum Ändern einer Replikationstask verwendet werden.

Für Filterfunktionen sind zwei Argumente erforderlich: doc und req.

Das Argument doc gibt das Dokument an, das von der Filterfunktion getestet werden soll.

Das Argument req enthält weitere Informationen zu der Anforderung. Mit diesem Argument können Sie dynamischere Filterfunktionen erstellen, die auf mehreren Faktoren (z. B. Abfrageparametern oder Benutzerkontext) basieren.

Sie können zum Beispiel Aspekte für die Testvorgänge in Filterfunktionen steuern, indem Sie dynamische Werte angeben, die als Teil der HTTP-Anforderung bereitgestellt werden: In vielen Anwendungsfällen für Filterfunktionen wird jedoch nur der Parameter doc verwendet.

Beispiel eines Entwurfsdokuments, das eine Filterfunktion enthält:

{
	"_id":"_design/example_design_doc",
	"filters": {
		"example_filter": "function (doc, req) { ... }"
	}
}

Beispiel für eine Filterfunktion:

function(doc, req){
	// we need only `mail` documents
	if (doc.type != 'mail'){
		return false;
	}
	// we're interested only in `new` ones
	if (doc.status != 'new'){
		return false;
	}
	return true; // passed!
}

Ändert Feedfilterfunktionen

Fügen Sie zum Anwenden einer Filterfunktion auf den Feed mit Änderungen den Parameter filter in die Abfrage _changes ein, um den Namen des Filters anzugeben, der verwendet werden soll.

Siehe das folgende Beispiel einer Filterfunktion, die auf eine _changes Abfrage unter Verwendung von HTTP angewendet wird:

POST $SERVICE_URL/$DATABASE/_changes?filter=$DDOC/$FILTER_FUNCTION HTTP/1.1

Im Folgenden finden Sie Beispiele für eine Filterfunktion, die auf eine _changes-Abfrage angewendet wird:

curl -X POST "$SERVICE_URL/orders/_changes?filter=example_design_doc/example_filter" -H "Content-Type: application/json" -d '{}'

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_changes(
  db='orders',
  filter='example_design_doc/example_filter'
).get_result()

print(response)

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.ChangesResult;
import com.ibm.cloud.cloudant.v1.model.PostChangesOptions;

Cloudant service = Cloudant.newInstance();

PostChangesOptions changesOptions = new PostChangesOptions.Builder()
    .db("orders")
    .filter("example_design_doc/example_filter")
    .build();

ChangesResult response =
    service.postChanges(changesOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.postChanges({
  db: 'orders',
  filter: 'example_design_doc/example_filter'
}).then(response => {
  console.log(response.result);
});

postChangesOptions := service.NewPostChangesOptions(
  "$DATABASE",
)
postChangesOptions.SetFilter("example_design_doc/example_filter")

changesResult, response, err := service.PostChanges(postChangesOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(changesResult, "", "  ")
fmt.Println(string(b))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Filterfunktion `req` Argument

Das Argument req ermöglicht den Zugriff auf Aspekte der HTTP-Anforderung mithilfe der Eigenschaft query.

Im folgenden Beispiel wird ein Argument req unter Verwendung von HTTP angegeben:

GET $SERVICE_URL/$DATABASE/_changes?filter=$DDOC/$FILTER_FUNCTION&status=new HTTP/1.1

Sehen Sie sich das folgende Beispiel für die Angabe eines Arguments req an:

Die IBM Cloudant SDKs unterstützen derzeit keine status Option für _changes Anfragen.

curl "$SERVICE_URL/$DATABASE/_changes?filter=$DDOC/$FILTER_FUNCTION&status=new"

Beispiel für einen Filter, in dem ein Argument req verwendet wird:

function(doc, req){
	// we need only `mail` documents
	if (doc.type != 'mail'){
		return false;
	}
	// we're interested only in `new` ones
	if (doc.status != req.query.status){
		return false;
	}
	return true; // passed!
}

Vordefinierte Filterfunktionen

Mehrere vordefinierte Filterfunktionen sind verfügbar:

_design: Akzeptiert nur Änderungen an Entwurfsdokumenten
_doc_ids: Akzeptiert nur Änderungen für Dokumente, deren ID im Parameter doc_ids oder im bereitgestellten JSON-Dokument angegeben ist.
_selector: Akzeptiert nur Änderungen für Dokumente, die mit einem angegebenen Selektor übereinstimmen, der mit der gleichen Selektorsyntax wie im Abschnitt "Anfrage" beschrieben definiert ist, die für _find verwendet wird.
_view: Mit dieser Funktion können Sie eine vorhandene Zuordnungsfunktion als Filter verwenden.

Filter `_design`

Der Filter _design akzeptiert nur Änderungen für Entwurfsdokumente innerhalb der angeforderten Datenbank.

Für diesen Filter sind keine Argumente erforderlich.

Es werden Änderugen für alle Entwurfsdokumente in der Datenbank aufgelistet.

Beispiel für die Anwendung des Filters _design über HTTP:

POST /$DATABASE/_changes?filter=_design HTTP/1.1

Sehen Sie sich die folgenden Beispielanwendungen des Filters _design an:

curl -X POST "$SERVICE_URL/orders/_changes?filter=_design" -H "Content-Type: application/json" -d '{}'

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_changes(
  db='orders',
  filter='_design'
).get_result()

print(response)

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.ChangesResult;
import com.ibm.cloud.cloudant.v1.model.PostChangesOptions;

Cloudant service = Cloudant.newInstance();

PostChangesOptions changesOptions = new PostChangesOptions.Builder()
    .db("orders")
    .filter("_design")
    .build();

ChangesResult response =
    service.postChanges(changesOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.postChanges({
  db: 'orders',
  filter: '_design'
}).then(response => {
  console.log(response.result);
});

postChangesOptions := service.NewPostChangesOptions(
  "$DATABASE",
)
postChangesOptions.SetFilter("_design")

changesResult, response, err := service.PostChanges(postChangesOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(changesResult, "", "  ")
fmt.Println(string(b))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Beispielantwort (gekürzt) nach dem Anwenden des Filters _design:

{
  ...
  "results":[
    {
      "changes":[
        {
          "rev":"10-304...4b2"
        }
      ],
      "id":"_design/ingredients",
      "seq":"8-g1A...gEo"
    },
    {
      "changes":[
        {
          "rev":"123-6f7...817"
        }
      ],
      "deleted":true,
      "id":"_design/cookbook",
      "seq":"9-g1A...4BL"
    },
    ...
  ]
}

Filter `_doc_ids`

Der Filter _doc-ids akzeptiert nur Änderungen für Dokumente mit angegebenen IDs. Die Dokument-IDs werden in einem Parameter doc_ids angegeben oder in einem JSON-Dokument, das als Teil der ursprünglichen Anforderung bereitgestellt wird.

Beispiel für die Anwendung des Filters _doc_ids über HTTP:

POST $SERVICE_URL/$DATABASE/_changes?filter=_doc_ids HTTP/1.1

Sehen Sie sich die folgenden Beispielanwendungen des Filters _doc_ids an:

curl -X POST "$SERVICE_URL/orders/_changes?filter=_doc_ids" -H "Content-Type: application/json" -d '{"doc_ids": ["ExampleID"]}'

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_changes(
  db='orders',
  filter='_doc_ids',
  doc_ids=['ExampleID']
).get_result()

print(response)

import java.util.Arrays;

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.ChangesResult;
import com.ibm.cloud.cloudant.v1.model.PostChangesOptions;

Cloudant service = Cloudant.newInstance();

PostChangesOptions changesOptions = new PostChangesOptions.Builder()
    .db("orders")
    .filter("_doc_ids")
    .docIds(Arrays.asList("ExampleID"))
    .build();

ChangesResult response =
    service.postChanges(changesOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.postChanges({
  db: 'orders',
  filter: '_doc_ids',
  docIds: ['ExampleID']
}).then(response => {
  console.log(response.result);
});

postChangesOptions := service.NewPostChangesOptions(
  "$DATABASE",
)
postChangesOptions.SetFilter("_doc_ids")
postChangesOptions.SetDocIds([]string{"ExampleID"})

changesResult, response, err := service.PostChanges(postChangesOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(changesResult, "", "  ")
fmt.Println(string(b))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Im folgenden JSON-Beispieldokument werden Dokument-IDs aufgelistet, die beim Filtern abgeglichen werden sollen:

{
  "doc_ids": [
    "ExampleID"
  ]
}

Beispielantwort (gekürzt) nach dem Anwenden des Filters für Dokument-IDs (_docs_ids):

{
  "last_seq":"5-g1A...o5i",
  "pending":0,
  "results":[
    {
      "changes":[
        {
          "rev":"13-bcb...29e"
        }
      ],
      "id":"ExampleID",
      "seq":"5-g1A...HaA"
    }
  ]
}

Filter `_selector`

Der _selector akzeptiert nur Änderungen für Dokumente, die einem bestimmten Selektor entsprechen, der mit der gleichen Selektorsyntax definiert wird wie für _find verwendet wird.

Weitere Beispiele für die Verwendung dieses Filters finden Sie in den Informationen zur Selektorsyntax.

Beispiel für die Anwendung des Filters _selector über HTTP:

POST $SERVICE_URL/$DATABASE/_changes?filter=_selector HTTP/1.1

Sehen Sie sich die folgenden Beispielanwendungen des Filters _selector an:

curl -X POST "$SERVICE_URL/orders/_changes?filter=_selector" -H "Content-Type: application/json" -d '{"selector": {"_id": { "$regex": "^_design/"}}}'

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_changes(
  db='orders',
  filter='_selector',
  selector={'_id': { '$regex': '^_design/'}}
).get_result()

print(response)

import java.util.HashMap;
import java.util.Map;

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.ChangesResult;
import com.ibm.cloud.cloudant.v1.model.PostChangesOptions;

Cloudant service = Cloudant.newInstance();

Map<String, Object> selector = new HashMap<String, Object>();
selector.put("_id", new HashMap<>().put("$regex", "^_design/"));

PostChangesOptions changesOptions = new PostChangesOptions.Builder()
    .db("orders")
    .filter("_selector")
    .selector(selector)
    .build();

ChangesResult response =
    service.postChanges(changesOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.postChanges({
    db: 'animaldb',
    filter: '_selector',
    selector: {"_id": { "$regex": "^_design/"}},
  }).then(response => {
    console.log(response.result);
  });

postChangesOptions := service.NewPostChangesOptions(
  "$DATABASE",
)
postChangesOptions.SetFilter("_selector")
postChangesOptions.SetSelector(map[string]interface{}{
  "_id": map[string]string{ "$regex": "^_design/"}})

changesResult, response, err := service.PostChanges(postChangesOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(changesResult, "", "  ")
fmt.Println(string(b))

Das vorherige Go-Beispiel erfordert den folgenden Importblock:

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

Das folgende JSON-Beispieldokument enthält den Selektorausdruck, der beim Filtern verwendet werden soll:

{
  "selector":{
    "_id":{
      "$regex":"^_design/"
    }
  }
}

Beispielantwort (gekürzt) nach dem Filtern mithilfe eines Selektors:

{
  "last_seq":"11-g1A...OaA",
  "pending":0,
  "results":[
    {
      "changes":[
        {
          "rev":"10-304...4b2"
        }
      ],
      "id":"_design/ingredients",
      "seq":"8-g1A...gEo"
    },
    {
      "changes":[
        {
          "rev":"123-6f7...817"
        }
      ],
      "deleted":true,
      "id":"_design/cookbook",
      "seq":"9-g1A...4BL"
    },
    {
      "changes":[
        {
          "rev":"6-5b8...8f3"
        }
      ],
      "deleted":true,
      "id":"_design/meta",
      "seq":"11-g1A...Hbg"
    }
  ]
}

Filter `_view`

Der Filter _view ermöglicht die Verwendung einer vorhandenen Map-Funktion als Filter.

Die Map-Funktion kann Ausgabedaten als Ergebnis der Verarbeitung eines bestimmten Dokuments zurückgeben. Wenn diese Situation eintritt, prüft der Filter das zulässige Dokument und fügt es in die Liste der von Ihnen geänderten Dokumente ein.

Beispiel für die Anwendung des Filters _view über HTTP:

POST $SERVICE_URL/$DATABASE/_changes?filter=_view&view=$DDOC/$VIEW_NAME HTTP/1.1

Sehen Sie sich die folgenden Beispielanwendungen des Filters _view an:

curl -X POST "$SERVICE_URL/animaldb/_changes?filter=_view&view=views101/latin_name" -H "Content-Type: application/json" -d '{}'

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.post_changes(
  db='animaldb',
  filter='_view',
  view='views101/latin_name'
).get_result()

print(response)

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.ChangesResult;
import com.ibm.cloud.cloudant.v1.model.PostChangesOptions;

Cloudant service = Cloudant.newInstance();

PostChangesOptions changesOptions = new PostChangesOptions.Builder()
    .db("animaldb")
    .filter("_vew")
    .view("views101/latin_name")
    .build();

ChangesResult response =
    service.postChanges(changesOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.postChanges({
  db: 'animaldb',
  filter: '_view',
  view: 'views101/latin_name'
}).then(response => {
  console.log(response.result);
});

postChangesOptions := service.NewPostChangesOptions(
  "animaldb",
)
postChangesOptions.SetFilter("_view")
postChangesOptions.SetView("views101/latin_name")

changesResult, _, err := service.PostChanges(postChangesOptions)
if err != nil {
fmt.Println(err)
}

b, _ := json.MarshalIndent(changesResult, "", "  ")
fmt.Println(string(b))

Beispielantwort (gekürzt) nach dem Filtern unter Verwendung einer Map-Funktion:

{
  "last_seq": "5-g1A...o5i",
  "results": [
    {
      "changes": [
        {
          "rev": "13-bcb...29e"
        }
      ],
      "id": "ExampleID",
      "seq":  "5-g1A...HaA"
    }
  ]
}

Prüfprozesse für Aktualisierungen

Entwurfsdokumente, für die options.partitioned auf true gesetzt ist, können kein Feld validate_doc_update enthalten.

Prüfprozesse für Aktualisierungen ermitteln, ob ein Dokument auf Platte geschrieben werden muss, wenn versucht wird, Einfügungen oder Aktualisierungen auszuführen. Für diese Prüfungen ist keine Abfrage erforderlich, da sie im Rahmen dieses Prozesses implizit durchgeführt werden. Wenn eine Änderung abgelehnt wird, gibt der Prüfprozess für Aktualisierungen als Antwort einen entsprechenden Fehler zurück.

Für Prüfprozesse für Aktualisierungen sind die folgenden vier Argumente erforderlich:

Argumente für den Prüfprozess für Aktualisierungen
Argument	Zweck
`newDoc`	Gibt die Version des in der Anforderung übergebenen Dokuments an.
`oldDoc`	Gibt die Version des aktuell in der Datenbank vorhandenen Dokuments an oder `null`, wenn keine Version vorhanden ist.
`secObj`	Das Sicherheitsobjekt für die Datenbank.
`userCtx`	Kontext zu dem derzeit authentifizierten Benutzer (z. B. `name` und `roles`).

Prüfprozesse für Aktualisierungen werden nicht angewendet, wenn ein Entwurfsdokument durch einen Benutzer mit Administratorberechtigung aktualisiert wird. Auf diese Weise wird sichergestellt, dass Administratoren sich nicht irrtümlich selbst aussperren können.

Beispiel für ein Entwurfsdokument mit einem Prüfprozess für Aktualisierungen:

{
	"_id": "_design/validator_example",
	"validate_doc_update": "function(newDoc, oldDoc, userCtx, secObj) { ... }"
}

Beispiel für einen Prüfprozess für Aktualisierungen:

function(newDoc, oldDoc, userCtx, secObj) {
	if (newDoc.address === undefined) {
		throw({forbidden: 'Document must have an address.'});
	}
}

Beispielantwort von einem Prüfprozess für Aktualisierungen:

{
	"error": "forbidden",
	"reason": "Document must have an address."
}

Informationen zu einem Entwurfsdokument abrufen

Die beiden Endpunkte _info und _search_info liefern zusätzliche Informationen über Entwurfsdokumente.

Endpunkt `_info`

Der Endpunkt _info gibt Informationen zu einem bestimmten Entwurfsdokument zurück (einschließlich Ansichtsindex, Größe des Ansichtsindexes und Status des Entwurfsdokuments sowie zugehörigen Informationen zum Ansichtsindex).

Methode: GET /db/_design/$DDOC/_info
Anforderung: Keine
Antwort: JSON-Code mit Informationen zum Entwurfsdokument.
Zulässige Rollen: _reader

Beispiel für das Abrufen von Informationen zum Entwurfsdokument recipesdd aus der Datenbank recipes über HTTP:

GET /recipes/_design/recipesdd/_info HTTP/1.1

Sehen Sie sich die folgenden Beispiele zum Abrufen von Informationen zum recipesdd-Entwurfsdokument aus der recipes-Datenbank an:

curl "$SERVICE_URL/recipes/_design/recipesdd/_info"

getDesignDocumentInformationOptions := service.NewGetDesignDocumentInformationOptions(
  "recipes",
  "recipesdd",
)

designDocumentInformation, response, err := service.GetDesignDocumentInformation(getDesignDocumentInformationOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(designDocumentInformation, "", "  ")
fmt.Println(string(b))

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.get_design_document_information(
  db='recipes',
  ddoc='recipesdd'
).get_result()

print(response)

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.DesignDocumentInformation;
import com.ibm.cloud.cloudant.v1.model.GetDesignDocumentInformationOptions;

Cloudant service = Cloudant.newInstance();

GetDesignDocumentInformationOptions informationOptions =
    new GetDesignDocumentInformationOptions.Builder()
        .db("recipes")
        .ddoc("recipesdd")
        .build();

DesignDocumentInformation response =
    service.getDesignDocumentInformation(informationOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.getDesignDocumentInformation({
  db: 'recipes',
  ddoc: 'recipesdd'
}).then(response => {
  console.log(response.result);
});

Die JSON-Antwort enthält die folgenden einzelnen Felder:

name

Name oder ID des Entwurfsdokuments.

view_index

Ansichtsindex

compact_running: Gibt an, ob eine Komprimierungsroutine für die Ansicht ausgeführt wird.
disk_size: Größe der Ansicht, wie sie auf der Festplatte gespeichert ist, in Bytes.
language: Die zum Definieren von Ansichten verwendete Sprache.
purge_seq: Die verwendete Löschreihenfolge.
signature: MD5-Signatur der Ansichten für das Entwurfsdokument.
update_seq: Aktualisierungsreihenfolge der zugehörigen Datenbank, die indexiert wurde.
updater_running: Gibt an, ob die Ansicht momentan aktualisiert wird.
waiting_clients: Anzahl der Clients, die auf Ansichten aus diesem Entwurfsdokument warten.
waiting_commit: Gibt an, ob in der zugrunde liegende Datenbank Festschreibungen zur Verarbeitung anstehen.

Beispielantwort im JSON-Format:

{
	"name" : "recipesdd",
	"view_index": {
		"compact_running": false,
		"updater_running": false,
		"language": "javascript",
		"purge_seq": 10,
		"waiting_commit": false,
		"waiting_clients": 0,
		"signature": "fc65594ee76087a3b8c726caf5b40687",
		"update_seq": 375031,
		"disk_size": 16491
	}
}

Endpunkt `_search_info`

Der Endpunkt _search_info gibt Informationen zu einem angegebenen Suchvorgang zurück, der in einem bestimmten Entwurfsdokument definiert ist.

Methode: GET /db/_design/$DDOC/_search_info/yourSearch
Anforderung: Keine
Antwort: JSON-Code mit Informationen zum angegebenen Suchvorgang.
Zulässige Rollen*: _reader

Beispiel für das Abrufen von Informationen zum Suchvorgang description, der im Entwurfsdokument app definiert wird, das in der Datenbank foundbite gespeichert ist, unter Verwendung von HTTP:

GET /foundbite/_design/app/_search_info/description HTTP/1.1

Sehen Sie sich die folgenden Beispiele für das Abrufen von Informationen zum description-Suchindex an, der im Entwurfsdokument app definiert ist, das in der foundbite-Datenbank gespeichert ist:

curl "$SERVICE_URL/foundbite/_design/app/_search_info/description"

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.get_search_info(
  db='foundbite',
  ddoc='app',
  index='description'
).get_result()

print(response)

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("foundbite")
        .ddoc("app")
        .index("description")
        .build();

SearchInfoResult response =
    service.getSearchInfo(infoOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.getSearchInfo({
  db: 'foundbite',
  ddoc: 'app',
  index: 'description'
}).then(response => {
  console.log(response.result);
});

getSearchInfoOptions := service.NewGetSearchInfoOptions(
  "foundbite",
  "app",
  "description",
)

searchInfoResult, response, err := service.GetSearchInfo(getSearchInfoOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(searchInfoResult, "", "  ")
fmt.Println(string(b))

Die JSON-Struktur enthält die folgenden einzelnen Felder:

name: Name oder ID der Suche innerhalb des Entwurfsdokuments.
search_index: Der Suchindex
pending_seq: Die Folgenummer der Änderungen in der Datenbank, die den Lucene-Index erreicht haben (sowohl im Hauptspeicher als auch auf der Platte).
doc_del_count: Anzahl der gelöschten Dokumente im Index.
doc_count: Anzahl der Dokumente im Index.
disk_size: Die Größe des Indexes auf der Festplatte in Bytes.
committed_seq: Die laufende Nummer der Änderungen in der Datenbank, die in den Lucene-Index auf der Festplatte übertragen wurden.

Beispielantwort im JSON-Format:

{
  "name":"_design/app/description",
  "search_index":{
    "pending_seq":63,
    "doc_del_count":3,
    "doc_count":10,
    "disk_size":9244,
    "committed_seq":63
  }
}

Funktionsweise von Entwurfsdokumenten

Entwurfsdokument erstellen oder aktualisieren

Das Feld options.partitioned

Entwurfsdokument kopieren

Struktur des Kopierbefehls

Aus einer bestimmten Revision kopieren

In vorhandenes Entwurfsdokument kopieren

Entwurfsdokument löschen

Struktur des Löschbefehls

Ansichten

Indizes

Allgemeine Anmerkungen zu Funktionen in Entwurfsdokumenten

Filterfunktionen

Ändert Feedfilterfunktionen

Filterfunktion req Argument

Vordefinierte Filterfunktionen

Filter _design

Filter _doc_ids

Filter _selector

Filter _view

Prüfprozesse für Aktualisierungen

Informationen zu einem Entwurfsdokument abrufen

Endpunkt _info

Endpunkt _search_info

Das Feld `options.partitioned`

Filterfunktion `req` Argument

Filter `_design`

Filter `_doc_ids`

Filter `_selector`

Filter `_view`

Endpunkt `_info`

Endpunkt `_search_info`