IBM Cloud Docs
Cómo trabajar con IBM Cloudant Query

Cómo trabajar con IBM Cloudant Query

IBM® Cloudant® for IBM Cloud® Query es una sintaxis de consulta de JSON declarativa para bases de datos de IBM Cloudant. Puede utilizar un tipo de índice json o text con IBM Cloudant.

En los casos siguientes, puede especificar cómo se crea el índice haciéndolo del tipo json:

  • Sabe exactamente qué datos desea buscar.
  • Desea mantener los requisitos de almacenamiento y proceso en un valor mínimo.

Sin embargo, para obtener la máxima flexibilidad al buscar datos, normalmente se crea un índice de tipo text. Los índices de tipo text tienen un mecanismo simple para indexar automáticamente todos los campos en los documentos.

Aunque son más flexibles, los índices de tipo text pueden tardar más en crearse y pueden requerir más recursos de almacenamiento que los índices json.

Creación de un índice

Puede crear un índice con uno de los tipos siguientes:

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

Creación de un índice type=json

Para crear un índice JSON en la base de datos $DATABASE, ejecute una solicitud POST a /$DATABASE/_index con un objeto JSON que describa el índice en el cuerpo de la solicitud. El campo type del objeto JSON debe establecerse en json. Un índice JSON puede ser particionado o global; esta opción se establece mediante el campo partitioned.

Consulte el ejemplo siguiente que utiliza HTTP para solicitar un índice de tipo JSON:

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

Consulte el ejemplo siguiente de un objeto JSON que crea un índice particionado llamado foo-partitioned-index para el campo llamado foo:

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

Consulte el ejemplo siguiente de un objeto JSON que crea un índice global llamado bar-global-index para el campo denominado bar:

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

Consulte el ejemplo siguiente de JSON devuelto, donde se confirma que se ha creado el índice:

{
    "result": "created"
}
Formato del cuerpo de la solicitud
Campo Descripción
index campos - Una matriz JSON de nombres de campo que utiliza la sintaxis de clasificación. También se permiten campos anidados, por ejemplo, person.name.
ddoc (opcional) Nombre del documento de diseño en el que se crea el índice. De forma predeterminada, cada índice se crea en su propio documento de diseño. Los índices se pueden agrupar en documentos de diseño para mejorar su eficiencia. Sin embargo, un cambio en un índice en un documento de diseño invalida todos los demás índices del mismo documento.
type (opcional) Puede ser json o text. El valor predeterminado es json.
name (opcional) Nombre del índice. Si no se especifica ningún nombre, se genera un automáticamente.
partitioned (opcional, booleano) Determina si este índice está particionado. Para obtener más información, consulte el campo partitioned.

El campo partitioned

Este campo establece si el índice creado es un índice particionado o global.

Valores de campo particionados
Valor Descripción Notas
true Crear el índice como particionado. Solo se puede utilizar en una base de datos particionada.
false Crear el índice como global. Se puede utilizar en cualquier base de datos.

El valor predeterminado sigue el valor de partitioned para la base de datos:

Valor particionado por defecto
¿La base de datos está particionada? Valor predeterminado de partitioned Valores permitidos
Sí true true, false
No false false

Es importante reiterar que el valor partitioned por defecto es true para índices creados en una base de datos particionada. Este valor predeterminado significa que el índice no se puede utilizar para satisfacer consultas globales.

Códigos de retorno
Código Descripción
200 El índice se ha creado correctamente o ya existía en la base de datos.
400 Solicitud errónea: el cuerpo de la solicitud no tiene el formato especificado.

Creación de un índice type=text

Cuando cree un índice de texto único, se recomienda utilizar los valores predeterminados, pero algunos atributos de índice útiles se pueden modificar.

Un índice de tipo text puede ser particionado o global; esta opción se establece utilizando el campo partitioned.

Para los índices de texto completo (FTI), el valor type se debe establecer en text.

Los atributos name y ddoc son para agrupar índices en documentos de diseño. Utilice los atributos para hacer referencia a los grupos de índice utilizando un valor de serie personalizado. Si no se proporcionan valores para estos campos, se rellenan automáticamente con un valor hash.

Si crea varios índices de texto en una base de datos con el mismo valor ddoc, debe conocer al menos el valor ddoc y el valor name. Si se crean varios índices con el mismo valor ddoc, se colocan en el mismo documento de diseño. En general, debe poner cada índice de texto en su propio documento de diseño.

Para más información, consulte más información sobre text índices.

Consulte el ejemplo siguiente de un documento JSON que solicita la creación de un índice particionado:

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

Consulte el ejemplo siguiente de documento JSON que solicita la creación de un índice global:

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

Consulte el ejemplo siguiente de un documento JSON que solicita la creación de un índice particionado más complejo:

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

El campo index

El campo index contiene valores específicos de los índices de texto.

Para indexar todos los campos de todos los documentos automáticamente, utilice la sintaxis simple:

"index": {}

El proceso de indexación recorre todos los campos de todos los documentos de la base de datos.

En la base de datos de demostración de las películas de ejemplo, puede ver un ejemplo de índice de texto que contiene todos los campos y todos los documentos de una base de datos.

Tenga cuidado cuando indexe todos los campos de todos los documentos para grandes conjuntos de datos, ya que es una actividad que puede consumir gran cantidad de recursos.

Consulte el ejemplo siguiente de un documento JSON que solicita la creación de un índice de todos los campos en todos los documentos:

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

El campo default_field

El valor default_field especifica cómo se puede utilizar el operador $text con el índice.

El campo default_field incluye dos claves:

Claves de campo Default_field
Clave Descripción
enabled Habilitar o inhabilitar el campo default_field index. El valor predeterminado es true.

La clave analyzer de default_field especifica cómo el índice analiza el texto. Más adelante, el índice se puede consultar utilizando el operador $text. Para obtener más información, consulte la documentación de búsqueda para ver los analizadores alternativos. Puede elegir un analizador alternativo cuando los documentos estén indexados en idiomas que no sean el inglés o cuando tenga otros requisitos especiales para el analizador, como por ejemplo direcciones de correo electrónico coincidentes.

Si no se especifica el campo default_field o se especifica con un objeto vacío, el valor predeterminado es true y se utiliza el analizador standard.

La matriz fields

La matriz fields incluye una lista de campos que se deben indexar para cada documento. Si sabe que un índice solo consulta campos específicos, se puede utilizar este campo para limitar el tamaño del índice. Cada campo también debe especificar un tipo que indexar. Los tipos aceptados se muestran en la lista siguiente:

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

El campo index_array_lengths

Los índices de texto de IBM Cloudant Query tienen una propiedad llamada index_array_lengths. Si la propiedad no se establece de forma explícita, el valor predeterminado es true.

Si el campo se estable en true, el índice requiere trabajo adicional. Este trabajo contiene una exploración de cada documento para cualquier matriz y se debe crear un campo que contenga la longitud de cada matriz encontrada.

Es posible que prefiera establecer el campo index_array_lengths en false en las siguientes situaciones:

  • No es necesario que conozca la longitud de una matriz.
  • No se utiliza el operador $size.
  • Los documentos de la base de datos son complejos o no están completamente bajo su control. Como resultado, es difícil estimar el impacto del proceso adicional necesario para determinar y almacenar las longitudes de las matrices.

El operador $size requiere que se establezca el campo index_array_lengths en true. De lo contrario, el operador no funciona.

Consulte el siguiente documento JSON de ejemplo con valores sugeridos para optimizar el rendimiento en sistemas de producción:

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

El campo partitioned

Este campo determina si el índice creado es un índice particionado o global.

Valores de campo particionados
Valor Descripción Notas
true Crear el índice como particionado. Solo se puede utilizar en una base de datos particionada.
false Crear el índice como global. Se puede utilizar en cualquier base de datos.

El valor predeterminado sigue el valor de partitioned para la base de datos:

Configuración particionada de la base de datos
¿La base de datos está particionada? Valor predeterminado de partitioned Valores permitidos
Sí true true, false
No false false