Fonctionnement des documents de conception

IBM® Cloudant® for IBM Cloud® lit des zones et des valeurs spécifiques figurant dans des documents de conception en tant que fonctions. Les documents de conception sont utilisés pour générer des index et valider des mises à jour.

Chaque document de conception définit des index partitionnés ou globaux qui sont contrôlés par la zone options.partitioned. Un index partitionné autorise uniquement les requêtes sur une partition de données unique dans une base de données partitionnée. Un index global autorise l'interrogation de toutes les données d'une base de données, avec le même temps d'attente et le même débit que sur un index partitionné.

Création ou mise à jour d'un document de conception

Méthode: PUT /$DATABASE/_design/$DDOC
Demande: Fichier JSON contenant les informations du cahier des charges.
Réponse: Statut JSON.
Rôles autorisés: _admin

Pour créer un document de conception, transférez-le dans la base de données spécifiée.

Dans ces exemples, $VARIABLES peut faire référence à des documents standard ou de conception. Pour les distinguer, les documents standard ont un _id indiqué par $DOCUMENT_ID, tandis que les documents de conception ont un _id indiqué par $DDOC.

Un ID de document de conception n'inclut jamais de clé de partitionnement, quel que soit le type de partitionnement de la base de données. La clé de partitionnement n'est pas incluse car les index qui sont inclus dans un document de conception s'appliquent à toutes les partitions dans une base de données partitionnée.

Si un document de conception est mis à jour, IBM Cloudant supprime les index de la version précédente et recrée entièrement l'index. Si vous devez changer un document de conception pour une base de données plus grande, reportez-vous au guide de gestion des documents de conception.

La structure d'un document de conception inclut les éléments suivants :

_id

ID du document de conception. Cet ID est toujours préfixé avec _design et n'inclut jamais de clé de partitionnement, quel que soit le type de partitionnement de base de données.

_rev

Révision du document de conception.

Options

Contient des options pour ce document de conception.

Partitionné (facultatif, booléen): Indique si ce document de conception décrit des index partitionnés ou globaux. Pour plus d'informations, voir La zone options.partitioned.

Vues (facultatif)

Un objet décrivant les vues MapReduce.

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

Réduction (facultatif)

Réduisez la fonction de la vue.

Index (facultatif)

Un objet décrivant les index de recherche.

Nom d'index

(Un pour chaque index)- Définition de l'index.

Analyseur: Objet décrivant l'analyseur à utiliser ou objet comportant les champs suivants :

Nom

Nom de l'analyseur. Les valeurs valides sont standard, email, keyword, simple, whitespace, classic et perfield.

Mots vides (facultatif)

Un tableau de mots vides. Les mots vides sont des mots qui ne doivent pas être indexés. Si ce tableau est spécifié, il remplace la liste de mots vides par défaut. La liste de mots vides par défaut dépend de l'analyseur. L'analyseur standard inclut la liste suivante de mots vides : 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 et with.

Valeur par défaut (pour l'analyseur de zone par zone)

Langue par défaut à utiliser si aucune langue n'est spécifiée pour la zone.

Champs (pour l'analyseur de champ par champ): Objet qui spécifie la langue à utiliser pour analyser chaque zone de l'index. Les noms de zone dans l'objet correspondent aux noms de zone dans l'index, c'est-à-dire le premier paramètre de la fonction d'index. Les valeurs des zones sont les langues à utiliser, par exemple english.
Index: Fonction chargée de l'indexation.

Filtres (facultatifs, non autorisés lorsque partitioned est défini sur true``)

Fonctions de filtrage.

Nom de la fonction (un pour chaque fonction): Définition de fonction.

Validate_doc_update (facultatif, non autorisé lorsque partitioned est true)

Mettre à jour la fonction de validation.

La zone `options.partitioned`

Cette zone indique si l'index créé est un index partitionné ou un index global.

Cette zone inclut les valeurs suivantes :

Valeurs du champ options.partitioned
Valeur	Description	Remarques
`true`	Création d'un index partitionné.	Peut être utilisée uniquement dans une base de données partitionnée.
`false`	Création d'un index global.	Peut être utilisée dans toutes les bases de données.

La valeur par défaut dépend du paramètre partitioned pour la base de données :

Paramètres de la partition
Base de données partitionnée ?	Valeur `partitioned` par défaut	Valeurs admises
Oui	`true`	`true`, `false`
Non	`false`	`false`

Copie d'un document de conception

Vous pouvez copier la version la plus récente d'un document de conception dans un nouveau document en spécifiant le document de base et le document cible. La copie est demandée avec la méthode de demande COPY.

COPY Il s'agit d'une commande non standard d' HTTP.

L'exemple suivant demande que IBM Cloudant copie le document de conception allusers dans le nouveau document de conception copyOfAllusers et produise une réponse qui inclut l'ID et la révision du nouveau document.

La copie d'un document de conception ne reconstruit pas automatiquement les index de vue. A l'instar des autres vues, ces vues sont recréées lorsque vous accédez à la nouvelle vue pour la première fois.

Voici un exemple de commande permettant de copier un document de conception via HTTP :

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

Voir l'exemple de commande suivant pour copier un document de conception :

Les SDK d' IBM Cloudant ne prennent actuellement pas en charge la méthode COPY de l' HTTP.

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

Voici un exemple de réponse à la demande de copie :

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

Structure de la commande copy

Méthode: COPY /$DATABASE/_design/$DDOC
Demande: Aucun
Réponse: JSON décrivant le nouveau document et la révision.
Rôles autorisés: _design

Arguments de requête

Argument

rev

Description: Révision à partir de la copie.
Facultatif: Oui.
Type: Chaîne.

En-têtes HTTP

En-tête

Destination

Description: Document de destination (et révision facultative)
Facultatif: Non.

Le document de conception source est spécifié sur la ligne de demande alors que l'en-tête HTTP Destination de la demande spécifie le document cible.

Copie à partir d'une révision spécifique

Pour effectuer la copie à partir d'une révision spécifique, ajoutez l'argument rev à la chaîne de requête.

Le nouveau document de conception est créé à l'aide de la révision du document source spécifiée.

Voici un exemple de commande permettant de copier une révision spécifique du document de conception via HTTP :

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

Voici un exemple de commande permettant de copier une révision spécifique du document de conception via la ligne de commande :

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

Copie dans un document de conception existant

Pour remplacer un document existant ou effectuer une copie dans un document existant, spécifiez la chaîne de révision en cours pour le document cible à l'aide du paramètre rev spécifié dans la chaîne d'en-tête HTTP Destination.

Voici un exemple de commande permettant de remplacer une copie existante du document de conception via HTTP :

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

Voici un exemple de commande permettant de remplacer une copie existante du document de conception via la ligne de commande :

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

La valeur renvoyée est l'ID et la nouvelle révision du document copié.

Voici un exemple de réponse à la demande de remplacement d'une copie existante du document de conception :

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

Suppression d'un document de conception

Vous pouvez supprimer un document de conception existant. La suppression d'un document de conception supprime également tous les index de vue associés et récupère l'espace correspondant aux index en question sur le disque.

Pour supprimer un document de conception, vous devez spécifier la révision en cours du document de conception à l'aide de l'argument de requête rev.

Voici un exemple de commande permettant de supprimer un document de conception via HTTP :

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

Voir les exemples suivants pour supprimer un document de conception:

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

L'exemple précédent de Go requiert le bloc d'importation suivant :

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

Voici un exemple de réponse contenant l'ID et la révision du document supprimé :

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

Structure de la commande delete

Méthode: DELETE /db/_design/$DDOC
Demande: Aucun
Réponse: JSON du document de conception supprimé.
Rôles autorisés: _design

Arguments de requête

Argument

rev

Description: Révision actuelle du document pour validation.
Facultatif: Oui, si l'en-tête « If-Match » existe.
Type: Chaîne.

En-têtes HTTP

En-tête

If-Match

Description: Révision actuelle du document pour validation.
Facultatif: Oui, si l'argument de requête « rev » est présent.

Vues

L'une des utilisations essentielles des documents de conception concerne la création de vues. Pour plus d'informations sur la création de vues, voir Vues (MapReduce).

Index

Toutes les requêtes agissent sur des index prédéfinis qui sont définis dans des documents de conception. Ces index sont les suivants :

Par exemple, pour créer un document de conception utilisé pour la recherche, veillez à ce que les deux conditions suivantes soient remplies :

Vous avez défini le document en tant que document de conception lorsque vous avez démarré l'élément _id avec _design/.
Vous avez créé un index de recherche dans le document, soit en mettant à jour ce dernier avec le champ approprié, soit en créant un nouveau document comprenant cet index de recherche.

Dès que le document de conception comportant l'index de recherche existe et que l'index est généré, vous pouvez l'utiliser pour effectuer des requêtes.

Remarques générales sur les fonctions dans les documents de conception

Les fonctions dans les documents de conception sont exécutées sur plusieurs noeuds pour chaque document et peuvent l'être plusieurs fois. Pour éviter toute incohérence, elles doivent être idempotentes, c'est-à-dire qu'elles doivent se comporter de manière identique lorsqu'elles sont exécutées plusieurs fois ou sur différents nœuds. En particulier, vous ne devez pas utiliser de fonctions qui génèrent des nombres aléatoires ou qui renvoient l'heure en cours.

Fonctions de filtrage

Les documents de conception dans lesquels options.partitioned a pour valeur true ne peuvent pas contenir de zone filters.

Les fonctions de filtrage sont des documents de conception qui filtrent le flux de modifications. Elles appliquent des tests à chaque objet inclus dans le flux de modifications.

Si l'un des tests de fonction échoue, l'objet est "retiré" du flux ou "filtré". Si la fonction renvoie le résultat true lorsqu'elle est appliquée à une modification, la modification reste dans le flux. En d'autres termes, les fonctions de filtrage "retirent" ou "ignorent" les modifications que vous ne voulez pas surveiller.

Les fonctions de filtrage peuvent aussi être utilisées pour modifier une tâche de réplication.

Les fonctions de filtrage requièrent deux arguments: doc et req.

L'argument doc représente le document testé pour le filtrage.

L'argument req inclut des informations supplémentaires sur la demande. Avec cet argument, vous pouvez créer des fonctions de filtrage plus dynamiques car elles s'appuient sur plusieurs facteurs, tels que les paramètres de requête ou le contexte utilisateur.

Par exemple, vous pouvez contrôler certains aspects des tests d'une fonction de filtrage à l'aide de valeurs dynamiques fournies dans le cadre de la demande HTTP. Cependant, dans de nombreux cas d'utilisation des fonctions de filtrage, seul le paramètre doc est utilisé.

Voici un exemple de document de conception qui inclut une fonction de filtrage :

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

Reportez-vous à l'exemple de fonction de filtrage suivant :

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!
}

Modifie les fonctions de filtre de flux

Pour appliquer une fonction de filtrage au flux de modifications, incluez le paramètre filter dans la requête _changes en indiquant le nom du filtre à utiliser.

Voici un exemple de fonction de filtrage appliquée à une requête « _changes » à l'aide de HTTP:

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

Voir les exemples suivants d'une fonction de filtre appliquée à une requête_changes :

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

L'exemple précédent de Go requiert le bloc d'importation suivant :

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

Argument `req` de la fonction de filtrage

L'argument req vous donne accès aux divers aspects de la demande HTTP avec la propriété query.

Voici un exemple de spécification de l'argument req via HTTP :

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

Voir l'exemple suivant de fourniture d'un argument req :

Les SDK d' IBM Cloudant ne prennent actuellement pas en charge l'option « status » pour les requêtes de type « _changes ».

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

Voici un exemple de filtre avec l'argument req :

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!
}

Fonctions de filtrage prédéfinies

Un certain nombre de fonctions de filtrage prédéfinies sont disponibles :

_design: Accepte uniquement les modifications apportées aux documents de conception.
_doc_ids: Accepte uniquement les modifications pour les documents dont l'ID est spécifié dans le paramètre doc_ids ou le document JSON fourni.
_selector: N'accepte que les modifications apportées aux documents correspondant à un sélecteur spécifié, défini à l'aide de la même syntaxe de sélecteur que celle décrite dans la section « Requête », qui est utilisée pour _find.
_view: Avec cette fonction, vous pouvez utiliser une fonction de mappe existante comme filtre.

Le filtre `_design`

Le filtre _design accepte les modifications uniquement pour les documents de conception qui se trouvent dans la base de données demandée.

Le filtre ne requiert pas d'argument.

Les modifications sont répertoriées pour tous les documents de conception se trouvant dans la base de données.

Voici un exemple d'application du filtre _design via HTTP :

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

Voir les exemples d'application du filtre _design suivants :

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

L'exemple précédent de Go requiert le bloc d'importation suivant :

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

Voici un exemple de réponse (abrégée) suite à l'application du filtre _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"
    },
    ...
  ]
}

Le filtre `_doc_ids`

Le filtre _doc-ids accepte uniquement les modifications pour les documents associés aux ID spécifiés. Les ID sont spécifiés dans un paramètre doc_ids ou dans un document JSON fourni dans le cadre de la demande originale.

Voici un exemple d'application du filtre _doc_ids via HTTP :

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

Voir les exemples d'application du filtre _doc_ids suivants :

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

L'exemple précédent de Go requiert le bloc d'importation suivant :

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

Voici un exemple de document JSON qui répertorie les ID de document à mettre en correspondance au cours du filtrage :

{
  "doc_ids": [
    "ExampleID"
  ]
}

Voici un exemple de réponse (abrégée) suite au filtrage avec _docs_ids :

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

Le filtre `_selector`

Le filtre « _selector » n'accepte que les modifications apportées aux documents correspondant à un sélecteur spécifié, défini à l'aide de la même syntaxe de sélecteur que celle utilisée pour _find.

Pour d'autres exemples illustrant l'utilisation de ce filtre, voir les informations relatives à la syntaxe de sélecteur.

Voici un exemple d'application du filtre _selector via HTTP :

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

Voir les exemples d'application du filtre _selector suivants :

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

L'exemple précédent de Go requiert le bloc d'importation suivant :

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

Voici un exemple de document JSON qui inclut l'expression de sélecteur à utiliser au cours du filtrage :

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

Voici un exemple de réponse (abrégée) suite au filtrage à l'aide d'un sélecteur :

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

Le filtre `_view`

Avec le filtre _view, vous pouvez utiliser une fonction de mappe existante comme filtre.

La fonction de mappe peut émettre une sortie comme résultat du traitement d'un document spécifique. Dans ce cas, le filtre prend en compte le document autorisé et l'inclut dans la liste des documents que vous avez modifiés.

Voici un exemple d'application du filtre _view via HTTP :

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

Voir les exemples d'application du filtre _view suivants :

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

Voici un exemple de réponse (abrégée) suite au filtrage à l'aide d'une fonction de mappe :

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

Valideurs de mises à jour

Les documents de conception dans lesquels options.partitioned a pour valeur true ne peuvent pas contenir de zone validate_doc_update.

Les valideurs de mises à jour déterminent si un document peut être écrit sur le disque lorsque des insertions et des mises à jour sont tentées. Ils ne nécessitent pas de requête car ils s'exécutent implicitement au cours de ce processus. Si une modification est rejetée, le valideur de mises à jour répond avec une erreur personnalisée.

Les valideurs de mises à jour requièrent quatre arguments :

Arguments pour la valideur de mises à jour
Argument	Objectif
`newDoc`	Version du document transmise dans la demande.
`oldDoc`	Version du document actuellement dans la base de données ou valeur `null` s'il n'en existe pas.
`secObj`	L' objet de sécurité de la base de données.
`userCtx`	Contexte concernant l'utilisateur authentifié, par exemple son nom et ses rôles (`name` et `roles`).

Les valideurs de mises à jour ne s'appliquent pas lorsqu'un document de conception est mis à jour par un administrateur. Cette pratique empêche les administrateurs de se verrouiller accidentellement.

Voici un exemple de document de conception avec un valideur de mises à jour :

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

Voici un exemple de valideur de mises à jour :

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

Voici un exemple de réponse d'un valideur de mises à jour :

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

Extraction d'informations sur un document de conception

Deux noeuds finaux fournissent des informations supplémentaires sur les documents de conception : _info et _search_info.

Le noeud final `_info`

Le noeud final _info renvoie des informations sur un document de conception spécifique, notamment l'index de vue, la taille de l'index de vue et le statut du document de conception ainsi que des informations sur les index de vus associés.

Méthode: GET /db/_design/$DDOC/_info
Demande: Aucun
Réponse: JSON contenant les informations de document de conception.
Rôles autorisés: _reader

Voici un exemple d'extraction d'informations sur le document de conception recipesdd depuis la base de données recipes via HTTP :

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

Reportez-vous aux exemples suivants pour extraire des informations sur le document de conception recipesdd à partir de la base de donnéesrecipes :

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

La réponse JSON inclut les zones individuelles suivantes :

name

Nom ou ID du document de conception.

view_index

Afficher l'index

compact_running: Indique si une routine de compression s'exécute sur la vue.
disk_size: Taille en octets de la vue telle qu'elle est stockée sur le disque.
language: Langage utilisée pour définir les vues.
purge_seq: Séquence de purge qui a été traitée.
signature: Signature MD5 des vues du document de conception.
update_seq: Séquence de mise à jour de la base de données correspondante qui a été indexée.
updater_running: Indique si la vue est en cours de mise à jour.
waiting_clients: Nombre de clients en attente de vues à partir de ce document de conception.
waiting_commit: Indique si la base de données sous-jacente possède des validations en attente qui doivent être en cours de traitement.

Voici un exemple de réponse au format JSON :

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

Le noeud final `_search_info`

Le noeud final _search_info renvoie des informations sur une recherche spécifiée qui est définie dans un document de conception spécifique.

Méthode: GET /db/_design/$DDOC/_search_info/yourSearch
Demande: Aucun
Réponse: JSON contenant des informations sur la recherche spécifiée.
Rôles autorisés *: _reader

Voici un exemple d'obtention d'informations sur la recherche description, qui est définie dans le document de conception app stocké dans la base de données foundbite via HTTP :

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

Reportez-vous aux exemples suivants pour obtenir des informations sur l'index de recherche description, qui est défini dans le document de conception app stocké dans la base de donnéesfoundbite :

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

La structure JSON inclut les zones individuelles suivantes :

name: Nom ou ID de la recherche dans le document de conception.
search_index: Index de recherche
pending_seq: Numéro de séquence des modifications dans la base de données qui a atteint l'index Lucene, dans la mémoire et sur le disque.
doc_del_count: Nombre de documents supprimés dans l'index.
doc_count: Nombre de documents dans l'index.
disk_size: Taille de l'index sur le disque, en octets.
committed_seq: Numéro de séquence des modifications dans la base de données qui ont été validées avec l'index Lucene sur le disque.

Voici un exemple de réponse au format JSON :

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

Fonctionnement des documents de conception

Fonctionnement des documents de conception

Création ou mise à jour d'un document de conception

La zone options.partitioned

Copie d'un document de conception

Structure de la commande copy

Copie à partir d'une révision spécifique

Copie dans un document de conception existant

Suppression d'un document de conception

Structure de la commande delete

Vues

Index

Remarques générales sur les fonctions dans les documents de conception

Fonctions de filtrage

Modifie les fonctions de filtre de flux

Argument req de la fonction de filtrage

Fonctions de filtrage prédéfinies

Le filtre _design

Le filtre _doc_ids

Le filtre _selector

Le filtre _view

Valideurs de mises à jour

Extraction d'informations sur un document de conception

Le noeud final _info

Le noeud final _search_info

La zone `options.partitioned`

Argument `req` de la fonction de filtrage

Le filtre `_design`

Le filtre `_doc_ids`

Le filtre `_selector`

Le filtre `_view`

Le noeud final `_info`

Le noeud final `_search_info`