IBM Cloud Docs
Utilisation d'IBM Cloudant Query

Utilisation d'IBM Cloudant Query

IBM® Cloudant® for IBM Cloud® Query est une syntaxe de requête JSON déclarative pour les bases de données IBM Cloudant. Vous pouvez utiliser un type d'index json ou text avec IBM Cloudant.

Dans les cas suivants, vous pouvez spécifier le mode de création de l'index en faisant en sorte qu'il soit de type json :

  • Vous savez exactement quelles données rechercher.
  • Vous souhaitez limiter les exigences en matière de stockage et de traitement au minimum nécessaire.

Toutefois, pour une souplesse maximale lorsque vous recherchez des données, vous créez généralement un index de type text. Les index de type text possèdent un mécanisme simple d'indexation automatique de toutes les zones des documents.

Bien que les index de type text soient plus souples, leur création peut prendre plus de temps et requérir davantage de ressources de stockage que les index de type json.

Création d'un index

Vous pouvez créer un index avec l'un des types suivants :

  • "type": "json"
  • "type": "text"

Création d'un index type=json

Pour créer un index JSON dans la base de données $DATABASE, envoyez une demande POST à /$DATABASE/_index avec un objet JSON décrivant l'index dans le corps de demande. La zone type de l'objet JSON doit avoir pour valeur json. Un index JSON peut être partitionné ou global ; cette option est définie avec la zone partitioned.

Voici un exemple d'utilisation de HTTP pour demander un index de type JSON :

POST /$DATABASE/_index HTTP/1.1
Content-Type: application/json

Voici un exemple d'objet JSON qui crée un index partitionné nommé foo-partitioned-index pour la zone appelée foo :

{
    "index": {
        "fields": ["foo"]
    },
    "name" : "foo-partitioned-index",
    "type" : "json",
    "partitioned": true
}

Voici un exemple d'objet JSON qui crée un index global nommé bar-global-index pour la zone appelée bar :

{
    "index": {
        "fields": ["bar"]
    },
    "name" : "bar-global-index",
    "type" : "json",
    "partitioned": false
}

Voici un exemple de JSON renvoyé confirmant que l'index a été créé :

{
    "result": "created"
}
Format du corps de la demande
Zone Description
index fields : tableau JSON de noms de zone utilisant la syntaxe de tri. Les zones imbriquées sont également autorisées, par exemple person.name.
ddoc (facultatif) Nom du document de conception dans lequel l'index est créé. Par défaut, chaque index est créé dans son propre document de conception. Les index peuvent être regroupés dans des documents de conception pour une meilleure efficacité. Toutefois, la modification d'un index dans un document de conception invalide tous les autres index figurant dans ce document.
type (facultatif) json ou text. json par défaut.
name (facultatif) Nom de l'index. Si aucun nom n'est indiqué, un nom est généré automatiquement.
partitioned (facultatif, valeur booléenne) Détermine si cet index est partitionné. Pour plus d'informations, voir la section intitulée La zone partitioned.

La zone partitioned

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

Valeurs des champs cloisonnés
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 :

Valeur partitionnée par défaut
La base de données est-elle partitionnée ? Valeur partitioned par défaut Valeurs admises
Oui true true, false
Non false false

It's important to reiterate that the default partitioned value is true pour les index créés dans une base de données partitionnée. Cette valeur par défaut signifie que l'index ne peut pas être utilisé pour répondre aux requêtes globales.

Codes retour
Code Description
200 L'index a été créé ou existe dans la base de données .
400 Demande incorrecte : le format du corps de demande n'est pas le format spécifié.

Création d'un index type=text

Lorsque vous créez un index de texte unique, il est recommandé d'utiliser les valeurs par défaut, mais certains attributs d'index utiles peuvent être modifiés.

Un index text peut être partitionné ou global ; cette option est définie avec la zone partitioned.

Pour les index de recherche en texte intégral, type doit avoir pour valeur text.

Les attributs name et ddoc permettent de regrouper des index dans des documents de conception. Utilisez-les pour faire référence à des groupes d'index à l'aide d'une valeur de chaîne personnalisée. Si aucune valeur n'est fournie pour ces zones, celles-ci sont remplies automatiquement avec une valeur de hachage.

Si vous créez plusieurs index de texte dans une base de données avec la même valeur ddoc, vous devez connaître au moins la valeur ddoc et la valeur name. La création de plusieurs index avec la même valeur ddoc permet de placer ces index dans le même document de conception. En général, vous devez placer chaque index de texte dans son propre document de conception.

Pour plus d'informations, consultez la rubrique Plus d'informations sur les text index.

Voici un exemple de document JSON qui demande une création d'index partitionné :

{
    "index": {
        "fields": [
            {
                "name": "Movie_name",
                "type": "string"
            }
        ]
    },
    "name": "Movie_name-text",
    "type": "text",
    "partitioned": true
}

Voici un exemple de document JSON qui demande la création d'un index global :

{
    "index": {
        "fields": [
            {
                "name": "Movie_name",
                "type": "string"
            }
        ]
    },
    "name": "Movie_name-text",
    "type": "text",
    "partitioned": false
}

Voici un exemple de document JSON qui demande la création d'un index partitionné plus complexe :

{
    "type": "text",
    "name": "my-index",
    "ddoc": "my-index-design-doc",
    "index": {
        "default_field": {
            "enabled": true,
            "analyzer": "german"
        },
        "selector": {},
        "fields": [
            {"name": "married", "type": "boolean"},
            {"name": "lastname", "type": "string"},
            {"name": "year-of-birth", "type": "number"}
        ]
    },
    "partitioned": true
}

La zone index

La zone index contient des paramètres propres aux index de texte.

Pour indexer toutes les zones dans tous les documents automatiquement, utilisez la syntaxe simple :

"index": {}

Le processus d'indexation examine toutes les zones de tous les documents qui se trouvent dans la base de données.

Dans la base de données de démonstration des films d'exemple, vous pouvez voir un exemple d'index de texte qui contient tous les champs et tous les documents d'une base de données.

Soyez attentif lorsque vous indexez toutes les zones dans tous les documents pour des ensembles de données volumineux car cette activité peut consommer un nombre élevé de ressources.

Voici un exemple de document JSON qui demande la création d'un index de toutes les zones de tous les documents :

{
	"type": "text",
	"index": { }
}

La zone default_field

La valeur de default_field indique comment l'opérateur $text peut être utilisé avec l'index.

La zone default_field inclut deux clés :

Clé de champ Default_field
Clé Description
enabled Active ou désactive l'index default_field index. La valeur par défaut est true.

La clé analyzer dans la zone default_field spécifie la façon dont l'index analyse le texte. Par la suite, l'index peut être interrogé à l'aide de l'opérateur $text. Pour plus d'informations, voir la documentation relative à la recherche afin de découvrir les autres analyseurs. Vous pouvez choisir un autre analyseur lorsque les documents sont indexés dans des langues autres que l'anglais ou lorsque vous avez des exigences spéciales pour l'analyseur, par exemple la mise en correspondance des adresses électroniques.

Si la zone default_field n'est pas spécifiée ou si un objet vide est indiqué, elle prend la valeur par défaut true et l'analyseur standard est utilisé.

Le tableau fields

Le tableau fields inclut la liste des zones à indexer pour chaque document. Si vous savez qu'un index interroge uniquement des zones spécifiques, cette zone peut être utilisée pour limiter la taille de l'index. Chaque zone doit également spécifier un type à indexer. Les types admis sont les suivants :

  • "boolean"
  • "string"
  • "number"

La zone index_array_lengths

Les index de texte IBM Cloudant Query possèdent une propriété nommée index_array_lengths. Si celle-ci n'est pas définie explicitement, la valeur par défaut est true.

Si la zone a pour valeur true, l'index requiert l'exécution d'une tâche supplémentaire. Cette tâche consiste à examiner chaque document dans tous les tableaux et à créer une zone contenant la longueur de chaque tableau trouvé.

Si vous préférez, vous pouvez associer la zone index_array_lengths à la valeur false dans les situations suivantes :

  • Il n'est pas nécessaire de connaître la longueur d'un tableau.
  • Vous n'utilisez pas l'opérateur $size.
  • Les documents qui se trouvent dans votre base de données sont complexes ou ne sont pas entièrement sous votre contrôle. Par conséquent, il est difficile d'estimer l'impact du traitement supplémentaire requis pour déterminer et stocker les longueurs de tableau.

L'opérateur $size nécessite que le champ index_array_lengths ait la valeur true Sinon, il ne peut pas fonctionner.

Voici un exemple de document JSON contenant les paramètres suggérés pour optimiser les performances sur les systèmes de production :

{
	"default_field": {
		"enabled": false
	},
	"index_array_lengths": false
}

La zone partitioned

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

Valeurs des champs cloisonnés
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 partitionnés pour la base de données
La base de données est-elle partitionnée ? Valeur partitioned par défaut Valeurs admises
Oui true true, false
Non false false