Uso de vistas

Utilice vistas para buscar contenido dentro de una base de datos que coincida con criterios específicos. Los criterios se especifican en la definición de vista.

Los criterios también se pueden proporcionar como argumentos cuando se utiliza la vista.

Consulta de una vista

Para consultar una vista, envíe una solicitud GET con el formato siguiente:

Método
Emita una consulta de partición utilizando el mandato GET $SERVICE_URL/$DATABASE/_partition/$PARTITION_KEY/_design/$DDOC/_view/$VIEW_NAME. O bien, emita consulta global utilizando el mandato GET $SERVICE_URL/$DATABASE/_design/$DDOC/_view/$VIEW_NAME.
Solicitud
Ninguna
Respuesta
JSON de los documentos que devuelve la vista.
Roles permitidos
_reader

La solicitud puede ejecutar:

  • El documento de diseño « $VIEW_NAME » indicado, procedente del documento de diseño « $DDOC » indicado dentro de la base de datos $DATABASE, que se limita a los resultados dentro del $PARTITION_KEY datos partición.
  • El documento de diseño « $VIEW_NAME » indicado, procedente del documento de diseño « $DDOC » indicado en la base de datos « $DATABASE ».

Los ejemplos de este documento varían entre la partición y las consultas globales con fines ilustrativos. A menos que se indique lo contrario, modificar la vía de acceso para incorporar o eliminar el nombre de partición funciona para cualquier tipo de consulta de vista.

Argumentos de consulta y de cuerpo JSON

Las consultas globales pueden utilizar todos los argumentos de consulta y de cuerpo JSON. Las consultas de partición solo pueden utilizar el subconjunto que se indica en la tabla.

Subconjunto de argumentos de consulta y del cuerpo JSON disponibles para consultas particionadas
Argumento Descripción Opcional Tipo Valor predeterminado Valores soportados Consulta de partición
conflicts Especifique si desea incluir una lista de revisiones en conflicto en la _conflicts propiedad del documento devuelto. Se ignora si include_docs no está establecido en true. Sí Boolean No Sí
descending Devolver los documentos en orden descending by key. Sí Boolean No Sí
end_key Dejar de devolver registros cuando se llega a la clave especificada. Sí Serie o matriz JSON Sí
end_key_docid Dejar de devolver registros cuando se llega al ID de documento especificado. Sí Serie Sí
group Especifique si desea agrupar los resultados reducidos por clave. Válido sólo si se define una función de reducción en la vista. Si la vista emite claves en formato de array JSON, es posible reducir aún más los grupos en función del número de elementos del array con el parámetro group_level. Sí Boolean No Sí
group_level Especifique el nivel de grupo que se utilizará. Solo es aplicable si la vista utiliza claves que son matrices JSON. Implica que el grupo es true. El nivel de grupo agrupa los resultados reducidos por el número especificado de elementos de la matriz. Si no se establece, los resultados se agrupan por la clave completa del array, devolviendo un valor reducido por cada clave completa. Sí Numérico Sí
include_docs Incluir el contenido completo de los documentos en la respuesta. Sí Boolean No Sí
inclusive_end Incluya las filas con el end_key especificado. Sí Boolean Sí Sí
key Devolver solo los documentos que coincidan con la clave especificada. Las claves son valores JSON y deben estar codificadas por URL. Sí Matriz JSON Sí
keys Especifique que sólo se devuelvan los documentos que coincidan con alguna de las claves especificadas. Representación en cadena de una matriz JSON de claves que coinciden con el tipo de clave que emite la función de vista. Sí Serie o matriz JSON Sí
limit Limitar el número de documentos devueltos al recuento especificado. Sí Numérico Sí
reduce Utilizar la función reduce. Sí Boolean Sí Sí
skip Omitir este número de filas desde el inicio. Sí Numérico 0 Sí
stable Especifique si desea utilizar la misma réplica del índice en cada solicitud. El valor por defecto false contacta con todas las réplicas y devuelve el resultado de la primera, la más rápida en responder. Si se configura en « true » y se utiliza junto con « update=false », podría mejorar la coherencia, aunque a costa de una mayor latencia y un menor rendimiento si la réplica seleccionada no es la más rápida de las disponibles.

Nota: En general, no se aconseja ni se recomienda establecer este parámetro en « true » cuando se utiliza « update=true ».

 Sí Boolean No No
stale

Nota: stale está en desuso. Utiliza en su lugar stable y update.

Especifica si se deben utilizar los resultados de una vista obsoleta sin que ello provoque una reconstrucción de todas las vistas del documento de diseño que la engloba.

  • ok es equivalente a stable=true&update=false.
  • update_after es equivalente a stable=true&update=lazy.
 Sí Serie No No
start_key Devolver registros, empezando por la clave especificada. Sí Serie o matriz JSON Sí
start_key_docid Devolver registros, empezando por el ID de documento especificado. Sí Serie Sí
update

Especifique si la vista en cuestión debe actualizarse o no antes de responder al usuario.

  • true- Devuelve los resultados después de que se actualice la vista
  • false- Devuelve los resultados sin actualizar la vista
  • lazy- Devuelve los resultados de la vista sin esperar a que se actualice, pero los actualiza inmediatamente después de la solicitud.
 Sí Serie Sí Sí

El uso de include_docs=true puede afectar al rendimiento.

Consulta el ejemplo de uso de HTTP para recuperar una lista de los 10 primeros documentos que incluyan el contenido completo de los documentos de una partición de una base de datos, aplicando una vista creada por el usuario.

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

Consulte el ejemplo de uso de HTTP para recuperar una lista de los 10 primeros documentos de una base de datos, aplicando una vista creada por el usuario.

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

Consulta el ejemplo para recuperar una lista de los primeros 10 documentos, incluyendo su contenido completo, de la partición « small-appliances » de una base de datos, aplicando la vista « byApplianceProdId » creada por el usuario.

Las bibliotecas de cliente utilizan el método POST en lugar de GET , ya que ambos tienen el mismo comportamiento.

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

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

Todos los ejemplos de Go requieren que se inicialice el objeto service. Para obtener más información, consulte los ejemplos de la Sección de autenticación de la documentación de la API.

Consulte el ejemplo para recuperar una lista de los 10 primeros documentos de una base de datos, aplicando la vista de getVerifiedEmails creada por el usuario.

Las bibliotecas de cliente utilizan el método POST en lugar de GET , ya que ambos tienen el mismo comportamiento.

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

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

Todos los ejemplos de Go requieren que se inicialice el objeto service. Para obtener más información, consulte los ejemplos de la Sección de autenticación de la documentación de la API.

Consulte la siguiente respuesta de ejemplo a la solicitud:

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

Índices

Cuando se define una vista en un documento de diseño, también se crea un índice correspondiente, en función de la información definida en la vista. Utilice índices para localizar documentos por criterios que no sean su campo _id. Por ejemplo, puede seleccionar por un campo o por combinación de campos, o bien por un valor que se calcula utilizando el contenido del documento. El índice se cumplimenta en cuanto se crea el documento de diseño. En bases de datos grandes, este proceso puede tardar un poco.

Si se produce uno de los siguientes eventos, el contenido del índice se actualiza de forma incremental y automática:

  • Se añade un nuevo documento a la base de datos.
  • Se suprime un documento existente de la base de datos.
  • Se actualiza un documento existente en la base de datos.

Los índices de vista se reconstruyen por completo cuando cambia la definición de la vista o cuando cambia otra definición de la vista en el mismo documento de diseño. La reconstrucción garantiza que los cambios en las definiciones de vista se reflejen en los índices de la vista. Para asegurarse de que se produce la reconstrucción, se crea una 'huella dactilar' de la definición de vista siempre que se actualice el documento de diseño. Si la huella dactilar cambia, los índices de vista se reconstruyen.

Las reconstrucciones de índice de vista se producen cuando cambia cualquier vista de todas las vistas definidas en el documento de diseño. Por ejemplo, si tiene un documento de diseño con tres vistas y actualiza el documento de diseño, se reconstruyen los tres índices de vista del documento de diseño. Si desea cambiar un documento de diseño para una base de datos más grande, consulte la Guía de gestión de documentos de diseño.

Si la base de datos se ha actualizado recientemente, es posible que los resultados se retrasen cuando se accede a la vista. El retraso se ve afectado por el número de cambios en la base de datos y si el índice de la vista no está actualizado porque se ha modificado el contenido de la base de datos.

Estos retrasos no se pueden eliminar. En el caso de bases de datos recién creadas, puede reducir los retrasos mediante la creación de una definición de vista en el documento de diseño en la base de datos antes de insertar o actualizar documentos. La creación de la definición de vista en el documento de diseño provoca actualizaciones incrementales en el índice cuando se insertan los documentos.

Si la velocidad de respuesta es más importante que tener datos actualizados, una alternativa consiste en permitir que los usuarios accedan a una versión antigua del índice de vista. Para permitir el acceso a una versión antigua del índice de vista, utilice el parámetro de serie de consulta update cuando realice una consulta de la vista.

Si desea guardar versiones de índice antiguas sin incurrir en el uso del procesador de indexación, puede detener la creación de todos los índices con el valor "autoupdate": {"indexes": false}. O bien puede detener la actualización automática de las vistas mediante la adición de una de las opciones siguientes a un documento de diseño. Puede detener la indexación de todos los tipos de índice con el valor "autoupdate": false.

Consulte los ejemplos siguientes:

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

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

Mantenimiento de vistas actualizadas

De forma predeterminada, todos los resultados de índice reflejan el estado actual de la base de datos. IBM Cloudant crea sus índices de forma automática y asíncrona en segundo plano. Esta práctica suele significar que el índice está totalmente actualizado cuando se consulta. Si no, por defecto, IBM Cloudant aplica las actualizaciones restantes en el momento de la consulta.

IBM Cloudant proporciona algunos parámetros, que se describen a continuación para alterar este comportamiento. No recomendamos su uso ya que sus efectos secundarios suelen ser mayores que sus beneficios.

Parámetros

La opción update indica si está preparado para aceptar los resultados de la vista sin esperar a que se actualice la vista. El valor predeterminado es true, lo que significa que la vista se actualiza antes de que se devuelvan los resultados. El valor lazy significa que los resultados se devuelven antes de que se actualice la vista, pero luego la vista se debe actualizar de todos modos.

Aunque IBM Cloudant se esfuerza por mantener los índices actualizados en segundo plano, no hay garantía alguna sobre el grado de desactualización de la vista cuando se consulta mediante update=false o update=lazy.

La opción stable indica si prefiere obtener resultados de un único conjunto coherente de fragmentos. El valor « false » significa que se consultan todas las réplicas de fragmentos disponibles y IBM Cloudant utiliza el más rápido respuesta. En cambio, fijar stable=true fuerza a la base de datos a utilizar sólo una réplica del índice.

El uso de stable=true puede provocar una latencia elevada, ya que consulta sólo una de las copias del índice, aunque las otras copias responderían responderían más rápido.

Combinación de parámetros

Si se especifica stable=false y update=false, se observa una mayor inconsistencia entre los resultados, incluso para la misma consulta y sin cambios en la base de datos. No recomendamos esta combinación a menos que esté seguro de que su sistema puede tolerar este comportamiento.

Clasificación de las filas devueltas

Los datos que devuelve una consulta de vista están en forma de matriz. Cada elemento del array se ordena mediante UTF-8. La clasificación se aplica a la clave definida en la función de vista.

El orden básico de la salida se muestra en la tabla siguiente:

Orden de las filas devueltas
Valor Orden
null Primero
false
true
Números
Texto (minúsculas)
Texto (mayúsculas)
Matrices (según los valores de cada elemento, utilizando el orden de esta tabla)
Objetos (según los valores de las claves, en orden de claves utilizando el orden de esta tabla) Último

Puede invertir el orden de la información de vista que de devuelve estableciendo el valor de consulta descending en true.

Cuando emite una solicitud de vista que especifica el parámetro keys, los resultados se devuelven en el mismo orden que la matriz keys proporcionada.

Consulte el ejemplo de uso de HTTP para solicitar los registros en orden de clasificación inverso:

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

Consulte el ejemplo de solicitud de los registros en orden de clasificación inverso.

Las bibliotecas de cliente utilizan el método POST en lugar de GET porque tienen un comportamiento similar.

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

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

Todos los ejemplos de Go requieren que se inicialice el objeto service. Para obtener más información, consulte los ejemplos de la Sección de autenticación de la documentación de la API.

Consulte la respuesta de ejemplo de solicitud de los registros en orden de clasificación inverso:

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

Especificación de claves de inicio y finalización

Los argumentos de consulta start_key y end_key se pueden utilizar para especificar el rango de valores que se devuelven al consultar la vista.

La dirección de clasificación siempre se aplica en primer lugar. A continuación, se aplica el filtrado utilizando los argumentos de consulta start_key y end_key. Es posible que ninguna fila coincida con su rango de claves si los planes de ordenación y filtrado no tienen sentido cuando se combinan.

Consulte el ejemplo de uso de HTTP para realizar una consulta global que incluya los argumentos de consulta start_key y end_key:

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

Consulte el ejemplo de una consulta global que incluya los argumentos de consulta start_key y end_key.

Las bibliotecas de cliente utilizan el método POST en lugar de GET , ya que ambos tienen el mismo comportamiento.

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

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

Todos los ejemplos de Go requieren que se inicialice el objeto service. Para obtener más información, consulte los ejemplos de la Sección de autenticación de la documentación de la API.

Por ejemplo, si tienes una base de datos que devuelve un resultado al utilizar un « start_key » de alpha y un end_key de beta, obtendrá un error 400 (solicitud incorrecta) con un orden inverso. El motivo es que las entradas de la vista se invierten antes de aplicar el filtro de claves.

Consulte el ejemplo que utiliza HTTP para ilustrar por qué invertir el orden de start_key y end_key podría dar lugar a un error de análisis de la consulta:

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

Consulte el ejemplo que ilustra el motivo por el que invertir el orden de start_key y end_key puede causar un error 400.

Las bibliotecas de cliente utilizan el método POST en lugar de GET , ya que ambos tienen el mismo comportamiento.

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

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

Todos los ejemplos de Go requieren que se inicialice el objeto service. Para obtener más información, consulte los ejemplos de la Sección de autenticación de la documentación de la API.

El end_key de beta se ve antes que el start_key de alpha, lo que da como resultado un error de análisis de consulta.

La solución es invertir no solo el orden de clasificación, sino también los valores de parámetro start_key y end_key.

El ejemplo siguiente muestra el filtrado correcto y la inversión del orden de salida, utilizando el argumento de consulta descending e invirtiendo los argumentos de consulta start_key y end_key.

Consulte el ejemplo que utiliza HTTP para aplicar el filtrado y la clasificación correctos a una consulta global:

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

Consulte el ejemplo para aplicar el filtrado y la clasificación correctos a una consulta global.

Las bibliotecas de cliente utilizan el método POST en lugar de GET , ya que ambos tienen el mismo comportamiento.

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

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

Todos los ejemplos de Go requieren que se inicialice el objeto service. Para obtener más información, consulte los ejemplos de la Sección de autenticación de la documentación de la API.

Consulta de una vista mediante una lista de claves

También puede ejecutar una consulta especificando una lista de claves que utilizar.

La solicitud de información de una base de datos de este modo utiliza el valor $VIEW_NAME especificado del documento de diseño $DDOC especificado. Al igual que el parámetro keys para el método GET, puede utilizar el método POST para especificar las claves que se utilizarán para recuperar los resultados de la vista. En todos los demás aspectos, el método POST es el mismo que la solicitud de API GET. En concreto, puede utilizar cualquiera de sus parámetros de consulta en la serie de consulta o en el cuerpo JSON.

Consulte la solicitud HTTP de ejemplo que devuelve todos los usuarios, donde la clave para la vista coincide con amelie.smith@aol.com o 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"
  ]
}

Véase el ejemplo de una consulta global que devuelve todos los usuarios (en la que la clave de la vista coincide con amelie.smith@aol.com o 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))

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

Todos los ejemplos de Go requieren que se inicialice el objeto service. Para obtener más información, consulte los ejemplos de la Sección de autenticación de la documentación de la API.

La respuesta contiene la información de vista estándar, pero solo los documentos en los que coinciden las claves.

Consulte la respuesta de ejemplo después de ejecutar una consulta utilizando una lista de claves:

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

Paginación

Utilice la paginación basada en teclas para las vistas. Para obtener detalles específicos y ejemplos, consulte el tema de la documentación de la API Paging on view queries.

Captación de varios documentos

En la siguiente sección se explica cómo realizar una solicitud « POST » para obtener varios documentos de una base de datos.

Para una aplicación cliente, esta técnica resulta más eficiente que utilizar varias solicitudes de API GET.

Sin embargo, include_docs=true puede requerir un tiempo de proceso adicional si se compara con el acceso a la vista por sí mismo.

El motivo es que si se utiliza include_docs=true en una consulta de vista, se deben recuperar todos los documentos del resultado para construir la respuesta para la aplicación cliente. De hecho, se ejecuta una serie completa de solicitudes GET de documento, cada una de las cuales compite por recursos con otras solicitudes de la aplicación.

Una forma de mitigar este efecto es mediante la recuperación de los resultados directamente del archivo de índice de vista. Omita include_docs=true para recuperar resultados directamente desde el archivo de índice de vista. En su lugar, en la función de correlación en un documento de diseño, emita los campos necesarios como valor para el índice de vista.

Por ejemplo, en la función de correlación, puede utilizar la siguiente especificación de diseño:

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

Consulte la solicitud de ejemplo que utiliza HTTP para obtener el contenido completo de los documentos que coinciden con las claves listadas dentro de una partición:

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

Consulte la solicitud de ejemplo para obtener el contenido completo de los documentos que coinciden con las claves listadas en la partición 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))

El ejemplo Go anterior requiere el siguiente bloque de importación:

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

Todos los ejemplos de Go requieren que se inicialice el objeto service. Para obtener más información, consulte los ejemplos de la Sección de autenticación de la documentación de la API.

Consulte la respuesta de ejemplo (abreviada), que devuelve el documento completo para cada dispositivo que coincida con una clave proporcionada:

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