Utilisation des vues

Utilisez des vues pour rechercher dans une base de données un contenu qui correspond à des critères spécifiques. Les critères sont spécifiés dans la définition de vue.

Les critères peuvent également être fournis en tant qu'arguments lorsque vous utilisez la vue.

Interrogation d'une vue

Pour interroger une vue, soumettez une demande GET au format suivant :

Méthode
Exécutez une requête de partition à l'aide de la commande suivante : GET $SERVICE_URL/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_view/$VIEW_NAME. Vous pouvez également lancer une requête globale à l'aide de la commande suivante : GET $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME.
Demande
Aucun
Réponse
JSON des documents renvoyés par le vue.
Rôles autorisés
_reader

La demande exécute :

  • L' $VIEW_NAME spécifiée, issue du document de conception $DDOC dans la base de données $DATABASE, dont les résultats sont limités à ceux correspondant aux critères spécifiés $PARTITION_KEY données partition.
  • L' $VIEW_NAME spécifiée, issue du document de conception $DDOC dans la base de données « $DATABASE ».

Les exemples présentés dans ce document utilisent des requêtes de partition ou des requêtes globales selon l'objectif. Sauf indication contraire, la modification du chemin pour imbriquer ou retirer le nom de partition est possible pour tous les types de requête de vue.

Arguments de requête et de corps JSON

Les requêtes globales peuvent utiliser tous les arguments de requête et de corps JSON. Les requêtes de partition ne peuvent utiliser que le sous-ensemble indiqué dans le tableau.

Sous-ensemble d'arguments de requête et de corps JSON disponibles pour les requêtes partitionnées
Argument Description Facultatif Type Valeur par défaut Valeurs prises en charge Requête de partition
conflicts Indiquer s'il faut inclure une liste des révisions en conflit dans la propriété _conflicts du document retourné. Ignoré si include_docs n'a pas la valeur true. Oui Booléen Faux Oui
descending Renvoie les documents dans l'ordre descending by key. Oui Booléen Faux Oui
end_key Arrêt du renvoi des enregistrements lorsque la clé spécifiée est atteinte. Oui Chaîne ou tableau JSON Oui
end_key_docid Arrêt du renvoi des enregistrements lorsque l'ID de document spécifié est atteint. Oui Chaîne Oui
group Indiquez si les résultats réduits doivent être regroupés par clé. Valable uniquement si une fonction de réduction est définie dans la vue. Si la vue émet des clés sous forme de tableau JSON, il est possible de réduire davantage les groupes en fonction du nombre d'éléments du tableau à l'aide du paramètre group_level Oui Booléen Faux Oui
group_level Indiquer le niveau de groupe à utiliser. Ceci ne s'applique que si la vue utilise des clés qui sont des tableaux JSON. Implique que le groupe est true. Le niveau de groupe regroupe les résultats réduits en fonction du nombre spécifié d'éléments du tableau. Si cette option n'est pas définie, les résultats sont regroupés en fonction de la clé du tableau entier, ce qui renvoie une valeur réduite pour chaque clé complète. Oui Numérique Oui
include_docs Inclusion du contenu complet des documents dans la réponse. Oui Booléen Faux Oui
inclusive_end Inclure les lignes avec le end_keyspécifié. Oui Booléen Oui Oui
key Renvoi uniquement des documents correspondant à la clé spécifiée. Les clés sont des valeurs JSON et doivent être codées sous forme d'URL. Oui Matrice JSON Oui
keys Indiquer que seuls les documents correspondant à l'une des clés spécifiées seront retournés. Représentation sous forme de chaîne d'un tableau JSON de clés correspondant au type de clé émis par la fonction de visualisation. Oui Chaîne ou tableau JSON Oui
limit Limitation du nombre de documents renvoyés au nombre spécifié. Oui Numérique Oui
reduce Utilisation de la fonction reduce. Oui Booléen Oui Oui
skip Permet d'ignorer ce nombre de lignes depuis le début. Oui Numérique 0 Oui
stable Indiquer s'il faut utiliser la même réplique de l'index pour chaque requête. La valeur par défaut false contacte toutes les répliques et renvoie le résultat du premier répondeur, le plus rapide. Le réglage sur « true », lorsqu’il est utilisé avec « update=false », peut améliorer la cohérence, mais au prix d’une latence accrue et d’un débit réduit si la réplique sélectionnée n’est pas la plus rapide parmi celles disponibles.

Remarque: en règle générale, il est déconseillé de définir ce paramètre sur « true » lorsque vous utilisez update=true.

 Oui Booléen Faux Non
stale

Note: stale est obsolète. Utilisez plutôt stable et update.

Indiquez s'il faut utiliser les résultats d'une vue obsolète sans déclencher une reconstruction de toutes les vues du document de conception correspondant.

  • ok équivaut à stable=true&update=false.
  • update_after équivaut à stable=true&update=lazy.
 Oui Chaîne Faux Non
start_key Renvoi des enregistrements à partir de la clé spécifiée. Oui Chaîne ou tableau JSON Oui
start_key_docid Renvoi des enregistrements à partir de l'ID de document spécifié. Oui Chaîne Oui
update

Indiquez si la vue en question doit être mise à jour avant de répondre à l'utilisateur

  • true- Renvoyer les résultats après la mise à jour de la vue
    *- false- Renvoyer les résultats sans mettre à jour la vue
  • lazy- Renvoyer les résultats de la vue sans attendre la mise à jour, mais en les mettant à jour immédiatement après la demande.
 Oui Chaîne Oui Oui

L'utilisation d'include_docs=true peut avoir une incidence sur les performances.

Découvrez l'exemple d'utilisation de la commande HTTP pour récupérer la liste des 10 premiers documents, avec leur contenu intégral, à partir d'une partition d'une base de données, en appliquant une vue créée par l'utilisateur.

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

Voir l'exemple d'utilisation de HTTP pour extraire une liste des 10 premiers documents d'une base de données, en appliquant une vue créée par l'utilisateur.

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

Consultez l'exemple suivant pour récupérer la liste des 10 premiers documents, ainsi que leur contenu intégral, à partir de la partition « small-appliances » d'une base de données, en appliquant la vue « byApplianceProdId » créée par l'utilisateur.

Les bibliothèques clientes utilisent la méthode POST plutôt que GET , car elles ont le même comportement.

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

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

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

Tous les exemples de Go nécessitent l'initialisation de l'objet service. Pour plus d'informations, reportez-vous à la documentation de l'API Section Authentification pour avoir des exemples.

Voir l'exemple pour extraire une liste des 10 premiers documents d'une base de données, en appliquant la vue getVerifiedEmails créée par l'utilisateur.

Les bibliothèques clientes utilisent la méthode POST plutôt que GET , car elles ont le même comportement.

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

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

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

Tous les exemples de Go nécessitent l'initialisation de l'objet service. Pour plus d'informations, reportez-vous à la documentation de l'API Section Authentification pour avoir des exemples.

Voici un exemple de réponse à la demande :

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

Index

Lorsqu'une vue est définie dans un document de conception, un index correspondant est également créé, en fonction des informations définies dans la vue. Utilisez des index pour rechercher des documents en fonction de critères autres que leur zone _id. Par exemple, vous pouvez procéder à la sélection en fonction d'une zone, d'une combinaison de zones ou d'une valeur calculée en utilisant le contenu du document. L'index est rempli dès que le document de conception est créé. Dans les bases de données de grande taille, ce processus peut prendre un certain temps.

Si l'un des événements suivants se produit, le contenu de l'index est mis à jour de manière incrémentielle et automatique :

  • Un nouveau document est ajouté à la base de données.
  • Un document existant est supprimé de la base de données.
  • Un document existant dans la base de données est mis à jour.

Les index de vue sont régénérés entièrement lorsque la définition de vue change ou lorsqu'une autre définition de vue dans le même document de conception change. La régénération garantit l'application des modifications apportées aux définitions de vue dans les index de vue. Pour garantir la régénération, une "empreinte digitale" de la définition de vue est créée à chaque fois que le document de conception est mis à jour. Si l'empreinte digitale change, les index de vue sont régénérés.

Des régénérations d'index de vue ont lieu lorsque vous changez l'une des vues définies dans le document de conception. Par exemple, si vous disposez d'un document de conception comportant trois vues et mettez à jour le document de conception, les trois index de vue se trouvant dans le document de conception sont régénérés. Si vous voulez changer le document de conception d'une base de données de plus grande taille, reportez-vous au guide de gestion des documents de conception.

Si la base de données a été mise à jour récemment, les résultats peuvent être différés lors de l'accès à la vue. Ce report dépend du nombre de modifications apportées à la base de données et du fait que l'index de vue est à jour ou non car le contenu de la base de données a été modifié.

Il n'est pas possible d'éliminer ces reports. Pour les bases de données nouvellement créées, vous pouvez les réduire en créant la définition de vue dans le document de conception dans votre base de données avant d'insérer ou de mettre à jour des documents. La création de la définition de vue dans le document de conception entraîne des mises à jour incrémentielles de l'index lorsque les documents sont insérés.

S'il est plus important d'obtenir une réponse rapide plutôt que des données à jour, vous pouvez autoriser les utilisateurs à accéder à une ancienne version de l'index de vue. Pour autoriser l'accès à une ancienne version de l'index de vue, utilisez le paramètre de chaîne de requête update lorsque vous effectuez une requête de vue.

Si vous voulez sauvegarder des anciennes versions d'index sans utiliser le processus d'indexation, vous pouvez arrêter la génération de tous les index en définissant "autoupdate": {"indexes": false}. Ou bien, vous pouvez arrêter la mise à jour automatique des vues en ajoutant l'une des options ci-après à un document de conception. Vous pouvez arrêter l'indexation de tous les types d'index en définissant "autoupdate": false.

Voir cet exemple :

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

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

Affichage de l'ancienneté

Par défaut, tous les résultats d'index reflètent l'état en cours de la base de données. IBM Cloudant génère ses index automatiquement et de manière asynchrone en arrière-plan. Cette pratique signifie généralement que l'index est entièrement à jour lorsque vous effectuez une requête. Si ce n'est pas le cas pas, par défaut, IBM Cloudant applique les les mises à jour restantes au moment de la requête.

IBM Cloudant fournit quelques paramètres, décrits ci-dessous pour modifier ce comportement. Nous recommandons de ne pas les utiliser car les effets secondaires l'emportent généralement sur les avantages.

Paramètres

L'option update indique si vous êtes prêt ou non à accepter des résultats de vue sans attendre que la vue ne soit mise à jour. La valeur par défaut est true et signifie que la vue est mise à jour avant le renvoi des résultats. La valeur lazy signifie que les résultats sont renvoyés avant la mise à jour de la vue, mais que la vue devra de toute façon être mise à jour.

Bien que IBM Cloudant s'efforce de mettre à jour les index en arrière-plan, il n'existe aucune garantie quant au degré de désactualisation de la vue lorsqu'elle est interrogée via update=false ou update=lazy.

L'option stable indique si vous préférez ou non obtenir des résultats depuis un ensemble cohérent unique de fragments. La valeur « false » signifie que toutes les répliques de shard disponibles sont interrogées et IBM Cloudant utilise la réponse la plus rapide la plus rapide. En revanche, la mise en place d'un stable=true oblige la base de données à n'utiliser qu'une seule réplique de l'index index.

L'utilisation de stable=true peut entraîner une latence élevée car elle ne consulte qu'une seule copie de l'index, même si les autres copies auraient pu le faire seulement une des copies de l'index, même si les autres copies répondraient répondraient plus rapidement.

Combinaison de paramètres

Si vous spécifiez stable=false et update=false, vous constaterez une plus grande incohérence entre les résultats, même pour la même requête et sans modification de la base de données. Nous vous déconseillons cette combinaison, sauf si vous êtes sûr que votre système peut tolérer ce comportement que vous soyez sûr que votre système peut tolérer ce comportement.

Tri des lignes renvoyées

Les données renvoyées par une requête de vue sont présentées sous forme de tableau. Chaque élément du tableau est trié à l'aide d'un UTF-8. Le tri est appliqué à la clé définie dans la fonction de vue.

L'ordre de base de la sortie est présenté dans le tableau suivant :

Ordre des lignes renvoyées
Valeur Commande
null Premier
false
true
Nombres
Texte (en minuscules)
Texte (en majuscules)
Tableaux (en fonction des valeurs de chaque élément, avec l'ordre indiqué dans ce tableau)
Objets (en fonction des valeurs des clés, dans l'ordre de clé avec l'ordre indiqué dans ce tableau) Dernier

Vous pouvez inverser l'ordre des informations de vue renvoyées en définissant descending pour la valeur de requête true.

Lorsque vous émettez une demande de vue qui spécifie le paramètre keys, les résultats sont renvoyés dans le même ordre que celui indiqué dans le tableau keys.

Voir l'exemple d'utilisation de HTTP pour demander les enregistrements dans l'ordre de tri inverse :

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

Voir l'exemple de demande des enregistrements dans l'ordre de tri inverse.

Les bibliothèques client utilisent la méthode POST au lieu de GET car elles ont un comportement similaire.

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

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

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

Tous les exemples de Go nécessitent l'initialisation de l'objet service. Pour plus d'informations, reportez-vous à la documentation de l'API Section Authentification pour avoir des exemples.

Voir l'exemple de réponse pour demander les enregistrements dans l'ordre de tri inverse :

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

Spécification des clés de début et de fin

Les arguments de requête start_key et end_key peuvent être utilisés pour spécifier la plage de valeurs renvoyées lors de l'interrogation de la vue.

Le sens du tri est toujours appliqué en premier. Ensuite, le filtrage est appliqué à l'aide des arguments de requête start_key et end_key. Il est possible qu'aucune ligne ne corresponde à votre gamme de clés si les plans de tri et de filtrage n'ont pas de sens lorsqu'ils sont combinés.

Voir l'exemple d'utilisation de HTTP pour effectuer une requête globale incluant start_key et des arguments de requête end_key :

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

Voir l'exemple d'une requête globale qui inclut des arguments de requête start_key et end_key.

Les bibliothèques clientes utilisent la méthode POST plutôt que GET , car elles ont le même comportement.

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

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

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

Tous les exemples de Go nécessitent l'initialisation de l'objet service. Pour plus d'informations, reportez-vous à la documentation de l'API Section Authentification pour avoir des exemples.

Par exemple, si vous disposez d'une base de données qui renvoie un résultat lorsque vous utilisez l' start_key e alpha et end_key de beta, vous obtenez une erreur 400 (requête incorrecte) avec un ordre inversé. En effet, les entrées dans la vue sont inversées avant l'application du filtre de clé.

Voir l'exemple qui utilise le protocole HTTP pour illustrer les raisons de l'inversion de l'ordre de start_key et end_key pourrait générer une erreur d'analyse de la requête :

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

Reportez-vous à l'exemple illustrant pourquoi l'inversion de l'ordre de start_key et de end_key peut provoquer une erreur 400.

Les bibliothèques clientes utilisent la méthode POST plutôt que GET , car elles ont le même comportement.

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

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

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

Tous les exemples de Go nécessitent l'initialisation de l'objet service. Pour plus d'informations, reportez-vous à la documentation de l'API Section Authentification pour avoir des exemples.

end_key de beta est visible avant start_key de alpha, ce qui entraîne une erreur d'analyse de requête.

La solution consiste à inverser non seulement l'ordre de tri, mais également les valeurs des paramètres start_key et end_key.

L'exemple suivant montre le filtrage correct et l'inversion de l'ordre de sortie, à l'aide de l'argument de requête descending et en inversant les arguments de requête start_key et end_key.

Voici un exemple qui utilise HTTP pour appliquer un filtrage et un tri corrects à une requête globale :

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

Voir l'exemple pour appliquer un filtrage et un tri corrects à une requête globale.

Les bibliothèques clientes utilisent la méthode POST plutôt que GET , car elles ont le même comportement.

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

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

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

Tous les exemples de Go nécessitent l'initialisation de l'objet service. Pour plus d'informations, reportez-vous à la documentation de l'API Section Authentification pour avoir des exemples.

Interrogation d'une vue à l'aide d'une liste de clés

Vous pouvez également exécuter une requête en fournissant une liste de clés à utiliser.

Le fait de demander des informations à partir d'une base de données utilise le $VIEW_NAME spécifié à partir du document de conception $DDOC spécifié. Comme pour le paramètre keys pour la méthode GET, vous pouvez utiliser la méthode POST pour spécifier les clés à utiliser afin d'extraire les résultats de vue. Pour tous les autres aspects, la méthode POST est identique à la demande d'API GET. En particulier, vous pouvez utiliser l'un quelconque de ses paramètres de requête dans la chaîne de requête ou le corps JSON.

Voir l'exemple de requête HTTP qui renvoie tous les utilisateurs, où la clé de la vue correspond à amelie.smith@aol.com ou bob.smith@aol.com:

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

Voici un exemple de requête globale qui renvoie tous les utilisateurs (pour lesquels la clé de la vue correspond soit à amelie.smith@aol.com, soit à bob.smith@aol.com):

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

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

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

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

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

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

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

Tous les exemples de Go nécessitent l'initialisation de l'objet service. Pour plus d'informations, reportez-vous à la documentation de l'API Section Authentification pour avoir des exemples.

La réponse contient les informations de la vue standard, mais uniquement les documents pour lesquels les clés correspondent.

Voici un exemple de réponse suite à l'exécution d'une requête avec une liste de clés :

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

Pagination

Utiliser la pagination par clé pour les vues. Pour plus de détails et d'exemples, voir la rubrique de la documentation de l'API intitulée Pagination sur les requêtes de vues.

Extraction de plusieurs documents

La section suivante traite d'une requête « POST » portant sur plusieurs documents issus d'une base de données.

Pour une application client, cette technique est plus efficace que l'utilisation de plusieurs demandes d'API GET.

Toutefois, include_docs=true peut nécessiter un temps de traitement supplémentaire pour accéder à la vue.

En effet, si vous utilisez include_docs=true dans une requête de vue, tous les documents résultants doivent être extraits afin de construire la réponse pour l'application client. Ainsi, une série entière de demandes GET de document sont exécutées, chacune entrant en compétition pour l'utilisation des ressources avec les autres demandes d'application.

Pour atténuer ces effets, vous pouvez extraire les résultats directement depuis le fichier d'index de vue. Omettez include_docs=true pour extraire les résultats directement depuis le fichier d'index de vue. A la place, dans la fonction de mappe d'un document de conception, émettez les zones requises comme valeur pour l'index de vue.

Par exemple, dans votre fonction de mappe, vous pouvez utiliser la spécification de conception suivante :

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

Voir l'exemple de demande qui utilise le protocole HTTP pour obtenir le contenu complet des documents qui correspondent aux clés répertoriées dans une partition :

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

Voir l'exemple de demande pour obtenir le contenu complet des documents qui correspondent aux clés répertoriées dans la partition products :

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

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

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

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

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

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

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

Tous les exemples de Go nécessitent l'initialisation de l'objet service. Pour plus d'informations, reportez-vous à la documentation de l'API Section Authentification pour avoir des exemples.

Voir l'exemple de réponse (abrégée), renvoyant le document complet pour chaque dispositif qui correspond à une clé fournie :

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