Présentation

Les vues peuvent être des structures de données secondaires dans IBM® Cloudant® for IBM Cloud®, stockant des paires clé/valeur dérivées des attributs du document. Ils peuvent être utilisés pour interroger et agréger des projections de documents.

Ils servent deux objectifs principaux :

• Indexation (projection): Utiliser des vues uniquement cartographiques pour projeter les documents dans de nouveaux espaces clés. Cela permet d'effectuer des recherches et des tris efficaces sur la base de champs autres que l'identifiant du document (par exemple, le courriel, l'horodatage ou la catégorie).
• Agrégation et analyse: Utilisez les vues MapReduce pour émettre et agréger des données sur les documents, par exemple en comptant les documents par type, en additionnant des valeurs ou en calculant des moyennes.

Fonctionnement des vues

Les vues sont définies dans les documents de conception et consistent en

• Une fonction de carte ( JavaScript ): Exécutée sur chaque document pour déterminer les attributs qui forment la clé et la valeur de la vue. Une fonction map peut émettre zéro, une ou plusieurs lignes par document.
• Une fonction de réduction facultative : Elle permet d'agréger les valeurs émises et d'effectuer des opérations telles que le comptage, la sommation ou le calcul de la moyenne.

Une fois construites, les vues sont automatiquement maintenues et mises à jour par IBM Cloudant au fur et à mesure que les documents changent.

Pour les bases de données partitionnées, les vues peuvent fonctionner sur une seule partition lorsque options.partitioned est défini sur true dans le document de conception.

Quand utiliser les vues

Les vues sont idéales pour :

• Des recherches et des requêtes efficaces sur des attributs de documents autres que l'identifiant (par exemple, recherche de documents par courriel du client ou par statut de la commande).
• Index de couverture: Les requêtes qui peuvent être satisfaites en utilisant uniquement les données clé/valeur de la vue, évitant ainsi la nécessité d'extraire des documents complets.
• Sommaires agrégés: Générer des totaux, des moyennes ou des comptages groupés par clés (par exemple, les ventes par année/mois/jour).
• Index partiels: Ils ne comprennent qu'un sous-ensemble de documents (par exemple, une liste des seules commandes de commerce électronique achevées).

Quand ne pas utiliser les vues

Éviter les vues pour :

• Requêtes ad hoc- utilisez plutôt Cloudant Search.
• Recherches en texte libre ou avec caractères génériques: utilisez plutôt Cloudant Search.

Une vue simple

La forme la plus simple d'une vue est une fonction de mappe. La fonction de mappe génère des données de sortie représentant une analyse (un mappage) des documents qui sont stockés dans la base de données.

Par exemple, vous pouvez rechercher l'utilisateur ayant effectué l'enregistrement en ligne et avoir un courrier électronique vérifié à contacter. Vous pouvez trouver ces informations en inspectant chaque document et en recherchant une zone dans le document appelé " email_vérifié " et en obtenant la valeur " email ". Si ce champ est présent et contient la valeur « true », cela signifie que l'utilisateur a terminé son inscription et que vous pouvez le contacter par e-mail. Si la zone n'est pas présente ou a une valeur autre que true, l'utilisateur n'a pas effectué l'enregistrement.

L'utilisation de la fonction emit dans une fonction de vue facilite la génération d'une liste en réponse à l'exécution d'une requête à l'aide de la vue. La liste se compose de paires de clés et de valeurs, où la clé permet d'identifier le document spécifique et la valeur fournit les détails précis dont vous avez besoin. La liste inclut également des métadonnées telles que le nombre de paires key:value renvoyées.

Le document _id est inclus automatiquement dans chaque enregistrement de résultat de paire key:value. Le document _id est inclus pour faciliter le travail du client avec les résultats obtenus.

Voici un exemple de vue simple avec une fonction de mappe :

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

Voici un exemple de données illustrant une vue simple :

[
    {
        "_id":"abc123",
        "name": "Bob Smith",
        "email": "bob.smith@aol.com",
        "email_verified": true,
        "joined": "2019-01-24T10:42:59.000Z"
    },
    {
        "_id":"abc125",
        "name": "Amelie Smith",
        "email": "amelie.smith@aol.com",
        "email_verified": true,
        "joined": "2020-04-24T10:42:59.000Z"
    }
]

Voici un exemple de réponse à l'exécution d'une requête de vue simple :

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

Exemples de fonction de mappe

La définition d'une vue dans un document de conception crée également un index basé sur les informations clés. La production et l'utilisation de l'index augmentent considérablement la vitesse d'accès et de recherche ou de sélection de documents dans la vue.

Les sections suivantes décrivent l'indexation avec des clés simples et complexes et réduisent les fonctions.

Vos fonctions d'indexation fonctionnent dans un environnement à contraintes de mémoire où le document fait partie de la mémoire utilisée dans l'environnement. La pile et le document de votre code doivent s'insérer dans cette mémoire. Nous limitons les documents à une taille maximale de 64 Mo.

function(doc) {
  if (doc.name) {
    emit("name", doc.name);
  }
}

function(doc) {
  if (doc.friends) {
    for (friend in doc.friends) {
      emit(doc._id, { "_id": friend });
    }
  }
}

Utilisation de la valeur

Le deuxième paramètre de la fonction emit d'une définition de MapReduce est la "valeur", qui est stockée avec la clé dans l'index résultant. La valeur a deux usages :

1. Pour les vues de sélection uniquement, la valeur peut être utilisée pour stocker un sous-ensemble du document afin d'éviter d'avoir à utiliser ?include_docs=true au moment de la requête. Cela peut permettre d'améliorer les performances au moment de l'interrogation, au détriment d'un index plus volumineux.
2. Pour les vues qui utilisent un réducteur, la valeur contiendra généralement une seule quantité numérique, un petit objet avec des clés fixes et des valeurs numériques, ou un court tableau de nombres. Les données numériques sont additionnées (avec le réducteur _sum) ou produisent des données statistiques avec le réducteur _stats.

Quelques exemples :

// create a view to allow selection of orders by year/month/day,
// where a subset of the document is projected into the view's value.
function(doc) {
  if (doc.type === 'order') {
    const minidoc = {
      customer_id: doc.customer_id,
      date: doc.date,
      status: doc.status
    }
    emit([doc.year, doc.month, doc.day], minidoc)
  }
}
// create a view, designed for the _sum reducer which contains
// one row per order, in year/month/day order where the value
// is the order's total in USD. This can be summed at query-time
// with optional grouping by year, year/month or year/month/day.
function(doc) {
  emit([doc.year, doc.month, doc.day], doc.order_total_usd)
}
// create a view, designed for the _sum reducer which contains
// one row per order, in year/month/day order where the value
// contains three numeric quantities (order total, tax and shipping)
// which will be summed at query-time with optional grouping by year,
// year/month or year/month/day.
function(doc) {
  const value = {
    total: doc.order_total_usd,
    tax: doc.tax_usd,
    shipping: doc.shipping_usd
  }
  emit([doc.year, doc.month, doc.day], value)
}
// create a view, designed for the _sum reducer which contains
// one row per order, with customer_id as the key. The numeric
// quantities are in array (order total and tax)  which will be
// summed at query-time with optional grouping by customer_id
function(doc) {
  emit(doc.customer_id, [doc.order_total_usd, doc.tax_usd])
}

Ne mettez pas de clés à forte cardinalité dans la valeur d'une vue, comme order_id ou customer_id car cela entraînera une expansion de la valeur réduite d'une vue plutôt qu'une réduction. De telles requêtes peuvent dépasser le temps imparti ou être rejetées par le IBM Cloudant service. Pour les réducteurs numériques, les données à cardinalité élevée sont généralement un composant de la "clé" d'une vue, la "valeur" étant réservée aux données numériques.

Fonctions de réduction

Les documents de conception dans lesquels options.partitioned a pour valeur true ne peuvent pas contenir de fonctions de réduction JavaScript personnalisées. Seules les réductions intégrées sont autorisées.

{
    "views": {
        "getVerifiedEmails": {
            "map": "function(user) { if(user.email_verified === true) { emit(user.email); } }"
        }
    }
}

{
    "views": {
        "teamCount": {
            "map": "function(doc) { if (doc.email_verified === true) { emit(doc.team, doc.name); } }",
            "reduce": "_count"
        }
    }
}

{"rows":[
{"key":null,"value":10010}
]}

{"rows":[
{"key":"blue","value":1409},
{"key":"green","value":1439},
{"key":"indigo","value":1425},
{"key":"orange","value":1432},
{"key":"red","value":1414},
{"key":"violet","value":1443},
{"key":"yellow","value":1448}
]}

{"total_rows":10010,"offset":4273,"rows":[
{"id":"783173e102613c78d02a2b3304001642","key":"orange","value":"Bethel Lusk"},
{"id":"783173e102613c78d02a2b3304001b40","key":"orange","value":"Ethyl Dionne"},
{"id":"783173e102613c78d02a2b3304009c66","key":"orange","value":"Fredda Hendrix"},
{"id":"783173e102613c78d02a2b330401800d","key":"orange","value":"Bibi Page"},
{"id":"783173e102613c78d02a2b3304018ae7","key":"orange","value":"Marylou Lavender-Milton"}
]}

{
    "views": {
        "productPrices": {
            "map": "function(doc) {  emit(doc.type, { price: doc.price, tax: doc.tax }); }",
            "reduce": "_sum"
        }
    }
}

{"rows":[
    {"key":null,"value":{"price":144.97, "tax":7.32}}
]}

{"rows":[
    {"key":"kitchen","value":{"price":14.99,"tax":1.14}},
    {"key":"garden","value":{"price":129.98,"tax":6.18}}
]}

{
    "views": {
        "salesByDate": {
            "map": "function(doc) { emit(doc.date, [doc.price, doc.tax]); }",
            "reduce": "_stats"
        }
    }
}

{"rows":[
    {"key":"2025-01-01","value":[
        {"sum":14.99,"count":1,"min":14.99,"max":14.99,"sumsqr":224.7001},
        {"sum":1.14,"count":1,"min":1.14,"max":1.14,"sumsqr":1.2995}
    ]},
    {"key":"2025-01-02","value":[
        {"sum":129.98,"count":2,"min":29.99,"max":99.99,"sumsqr":10897.4002},
        {"sum":6.18,"count":2,"min":1.62,"max":4.56,"sumsqr":23.418}
    ]}
]}

{
  "views": {
    "estimateIpCount": {
      "map": "function (doc) {\n  emit(doc.ip, 1);\n}",
      "reduce": "_approx_count_distinct"
    }
  }
}

{"rows":[
{"key":null,"value":100528}
]}

{
    "views": {
        "bestScores": {
            "map": "function(doc) { emit(doc.user_id, doc.score); }",
            "reduce": "_top_3"
        }
    }
}

{"rows":[
  {"key":null,"value":[99,98,97]}
]}

{"rows":[
  {"key":"user082","value":[99,98,97]},
  {"key":"user291","value":[85,72,42]},
  {"key":"user452","value":[55,51,30]}
]}

{
    "views": {
        "latestReading": {
            "map": "function(doc) { emit([doc.deviceid, doc.timestamp], doc); }",
            "reduce": "_last"
        }
    }
}

{"rows":[
{"key":["A00"],"value":{"_id":"93117567370d41d091b8dd160a3adf3f","_rev":"1-bc05e93e592d5a5a18e240240b581a55","deviceid":"A00","reading":13.8986,"timestamp":"2025-03-26T04:44:08.917Z","status":"red"}},
{"key":["A01"],"value":{"_id":"c9f53ac9e4a8444487ed0eaa11dc1c78","_rev":"1-1fcf121c73db03e49bac4c1981518b19","deviceid":"A01","reading":59.8453,"timestamp":"2025-04-01T01:52:34.254Z","status":"green"}},
{"key":["A02"],"value":{"_id":"577b7108a8a1458f9a17194ed1da398a","_rev":"1-71d345a773ab31f35ceb998f3c107c41","deviceid":"A02","reading":2.6208,"timestamp":"2025-03-31T00:22:17.175Z","status":"green"}},
{"key":["A03"],"value":{"_id":"150839b1d363427496a4f4e2917b8b1d","_rev":"1-860a2ed5f1f48aa642495dfb21dff3ce","deviceid":"A03","reading":55.8677,"timestamp":"2025-03-22T10:15:57.890Z","status":"red"}},
{"key":["A04"],"value":{"_id":"d3317bdc1f7b4466ae6bf7a30ca9e328","_rev":"1-a58762532f6980ca5b06a8d01d113814","deviceid":"A04","reading":44.1822,"timestamp":"2025-03-23T10:56:10.639Z","status":"green"}},
{"key":["A05"],"value":{"_id":"946754d3762f44e297ca20d13bbceb5e","_rev":"1-41fa2bb3ef8782c90b28ee44628abeab","deviceid":"A05","reading":13.2874,"timestamp":"2025-03-27T13:59:04.723Z","status":"blue"}},
{"key":["A06"],"value":{"_id":"bbcd8a5c0ae948baae713a9fcb5262d5","_rev":"1-66883211ee20a0772374672aa175dc50","deviceid":"A06","reading":7.9525,"timestamp":"2025-04-01T15:13:04.305Z","status":"blue"}},
{"key":["A07"],"value":{"_id":"a600caccdb82400698b158ecebfaa6f2","_rev":"1-68975a8d7133a13c6cc8ae34d28ea1c6","deviceid":"A07","reading":89.4818,"timestamp":"2025-03-07T02:12:59.934Z","status":"blue"}},
{"key":["A08"],"value":{"_id":"be20bae911db4da685f891fd01e07d3a","_rev":"1-d69b559627cf01e80fe85ea2f54d2f4b","deviceid":"A08","reading":97.6739,"timestamp":"2025-03-29T13:46:31.689Z","status":"green"}},
{"key":["A09"],"value":{"_id":"96526e80f2ff48e89e9e42aa47abae24","_rev":"1-85e56901f7113d7d6ff8ba573c535eb3","deviceid":"A09","reading":26.1597,"timestamp":"2025-03-18T03:22:19.848Z","status":"blue"}}
]}

Fonctions de réduction personnalisées

La plupart des clients estiment que les réducteurs intégrés sont suffisants pour effectuer des agrégations sur les paires key-value de vue émises à partir de leurs fonctions de mappe. Toutefois, dans certains cas inhabituels, une fonction de réduction JavaScript peut être fournie à la place du nom de l'un des réducteurs intégrés.

Les fonctions de réduction personnalisées sont beaucoup plus lentes et plus difficiles à maintenir que les réducteurs intégrés. Il convient donc de vérifier si un cas d'utilisation peut être satisfait avec un réducteur intégré avant d'en écrire un personnalisé.

Les fonctions de réduction reçoivent trois arguments dans l'ordre suivant :

• keys
• values
• rereduce

Si une vue possède une fonction de réduction JavaScript personnalisée, celle-ci est utilisée pour générer des résultats agrégés pour la vue. Une fonction de réduction reçoit un ensemble de valeurs intermédiaires et les combine pour obtenir une valeur unique. Une fonction de réduction doit accepter en entrée les résultats émis par sa fonction de mappe correspondante, ainsi que les résultats renvoyés par la fonction de réduction elle-même. Ce dernier cas est appelé "rereduce".

L'exemple ci-dessous décrit les fonctions de réduction.

Voici un exemple de fonction de réduction personnalisée :

function (keys, values, rereduce) {
  return sum(values);
}

Les fonctions de réduction doivent traiter deux cas :

1. Lorsque rereduce a pour valeur false :

   • keys est un tableau dont les éléments sont des tableaux au format [key, id], où key est une clé qui est émise par la fonction de mappe, id identifie le document à partir duquel la clé a été générée et values est un tableau des valeurs qui sont émises pour les éléments respectifs dans keys, par exemple : reduce([ [key1,id1], [key2,id2], [key3,id3] ], [value1,value2,value3], false).

2. Lorsque rereduce a pour valeur true :

   • keys est null.
   • values est un tableau des valeurs renvoyées par les appels précédents de la fonction de réduction, par exemple : reduce(null, [intermediate1,intermediate2,intermediate3], true).

Les fonctions de réduction doivent renvoyer une valeur unique, qui convient pour la zone value de la vue finale et en tant que membre du tableau values qui est transmis à la fonction de réduction.

Souvent, des fonctions de réduction peuvent être écrites pour traiter les appels rereduce sans code supplémentaire, comme la fonction d'addition dans l'exemple précédent. Dans ce cas, l'argument rereduce peut être ignoré.

En alimentant la fonction reduce avec les résultats des fonctions reduce, MapReduce peut diviser l'analyse d'ensembles de données volumineux en tâches parallèles discrètes pouvant être exécutées beaucoup plus rapidement.

Lorsque vous utilisez la fonction de réduction intégrée, si l'entrée n'est pas valide, l'erreur builtin_reduce_error est renvoyée. Des informations plus détaillées sur l'échec figurent dans la zone reason. Les données originales qui ont causé l'erreur sont renvoyées dans la zone caused_by.

Voici un exemple de réponse :

{
    "rows": [
        {
            "key": null,
            "value": {
                "error": "builtin_reduce_error",
                "reason": "The _sum function requires that map values be numbers, arrays of numbers, or objects. Objects can't be mixed with other data structures. Objects can be arbitrarily nested, if the values for all fields are themselves numbers, arrays of numbers, or objects.",
                "caused_by": [
                    {
                        "a": 1
                    },
                    {
                        "a": 2
                    },
                    {
                        "a": 3
                    },
                    {
                        "a": 4
                    }
                ]
            }
        }
    ]
}

Restrictions des fonctions de mappe et de réduction

Les restrictions des fonctions de mappe et de réduction sont décrites ici.

Stockage de la définition de vue

Chaque vue est une fonction JavaScript. Les vues sont stockées dans des documents de conception. Donc, pour stocker une vue, IBM Cloudant stocke simplement la définition de fonction dans un document de conception. Un document de conception peut être créé ou mis à jour à l'instar de n'importe quel autre document.

Pour enregistrer la définition d'une vue, PUT le contenu de la définition de la vue dans un document _design.

Dans l'exemple suivant, la vue getVerifiedEmails est définie en tant que fonction de mappe et est disponible dans la zone views du document de conception.

Utilisez la méthode PUT pour ajouter une vue dans un document de conception :

PUT $SERVICE_URL/$DATABASE/_design/$DDOC HTTP/1.1
Content-Type: application/json

L'exemple suivant ajoute une nouvelle getVerifiedEmails fonction de vue nommée au allusers document de conception avec la définition de la vue :

{
    "views": {
        "getVerifiedEmails": {
            "map": "function(user) { if(user.email_verified === true){ emit(doc.email, {name: user.name, email_verified: user.email_verified, joined: user.joined}) }}  "
        }
    }
}

Voir les exemples de demande :

curl -X PUT "$SERVICE_URL/users/_design/allusers" --data '{
  "views": {
    "getVerifiedEmails": {
      "map": "function(user) { if(user.email_verified === true){ emit(doc.email, {name: user.name, email_verified: user.email_verified, joined: user.joined}) }}"
    }
  }
}'

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.DesignDocument;
import com.ibm.cloud.cloudant.v1.model.DesignDocumentViewsMapReduce;
import com.ibm.cloud.cloudant.v1.model.DocumentResult;
import com.ibm.cloud.cloudant.v1.model.PutDesignDocumentOptions;
import java.util.Collections;
Cloudant service = Cloudant.newInstance();
DesignDocumentViewsMapReduce emailViewMapReduce =
    new DesignDocumentViewsMapReduce.Builder()
        .map("function(user) { if(user.email_verified === true){ emit(doc.email,{name: user.name, email_verified: user.email_verified, joined: user.joined}) }")
        .build();
DesignDocument designDocument = new DesignDocument();
designDocument.setViews(
        Collections.singletonMap("getVerifiedEmails", emailViewMapReduce));
PutDesignDocumentOptions designDocumentOptions =
    new PutDesignDocumentOptions.Builder()
        .db("users")
        .designDocument(designDocument)
        .ddoc("allusers")
        .build();
DocumentResult response =
    service.putDesignDocument(designDocumentOptions).execute()
        .getResult();
System.out.println(response);

import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
const emailViewMapReduce: CloudantV1.DesignDocumentViewsMapReduce = {
  map: 'function(user) { if(user.email_verified === true){ emit(doc.email, {name: user.name, email_verified: user.email_verified, joined: user.joined}) }}'
}
const designDocument: CloudantV1.DesignDocument = {
  views: {'getVerifiedEmails': emailViewMapReduce}
}
service.putDesignDocument({
  db: 'users',
  designDocument: designDocument,
  ddoc: 'allusers'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
email_view_map_reduce = DesignDocumentViewsMapReduce(
  map='function(user) { if(user.email_verified === true){ emit(doc.email, {name: user.name, email_verified: user.email_verified, joined: user.joined}) }}'
)
design_document = DesignDocument(
  views={'getVerifiedEmails': email_view_map_reduce}
)
response = service.put_design_document(
  db='users',
  design_document=design_document,
  ddoc='allusers'
).get_result()
print(response)

emailViewMapReduce, err := service.NewDesignDocumentViewsMapReduce(
  "function(user) { if(user.email_verified === true){ emit(doc.email, {name: user.name, email_verified: user.email_verified, joined: user.joined}) }}",
)
if err != nil {
  panic(err)
}
designDocument := &cloudantv1.DesignDocument{
  Views: map[string]cloudantv1.DesignDocumentViewsMapReduce{
    "getVerifiedEmails": *emailViewMapReduce,
  },
}
putDesignDocumentOptions := service.NewPutDesignDocumentOptions(
  "users",
  "allusers",
  designDocument,
)
documentResult, _, err := service.PutDesignDocument(putDesignDocumentOptions)
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"
)

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.