Cambios en una base de datos distribuida

Las bases de datos de {{site.data.keyword.cloudant_short_notm}} son distribuidas. Tienen características de fragmentación y tolerancia a errores. Estas características significan que las respuestas que proporciona la solicitud _changes pueden ser diferentes del comportamiento que espera.

En particular, si solicita una lista de cambios _since un identificador de secuencia, obtendrá la información solicitada en la respuesta. Pero es posible que también obtenga los cambios realizados antes del cambio indicado por el identificador de secuencia. La razón por la que se incluyen estos cambios adicionales, junto con las implicaciones para las aplicaciones, se explica en la Guía de réplica.

Cualquier aplicación que utilice la solicitud _changes debe poder procesar una lista de cambios correctamente, tal como se muestra en la siguiente lista:

• Otro orden para los cambios que se muestran en la respuesta, en comparación con una solicitud anterior para la misma información.
• Cambios que se producen antes del cambio especificado por el identificador de secuencia.

El argumento feed

El argumento feed cambia la forma en que {{site.data.keyword.cloudant_short_notm}} envía la respuesta. De forma predeterminada, _changes informa de todos los cambios, y, a continuación, se cierra la conexión. Este comportamiento es el mismo que utilizar el argumento feed=normal.

Si establece feed=longpoll, las solicitudes enviadas al servidor permanecen abiertas hasta que se notifican los cambios. Esta opción ayuda cuando se supervisan cambios continuamente.

Si establece feed=continuous, se notificarán los cambios nuevos a medida que se produzcan. Esta opción significa que la conexión de base de datos permanece abierta durante un tiempo. La respuesta puede finalizar en cualquier momento y los clientes deben volver a conectarse si desean seguir recibiendo cambios.

Cada línea de la respuesta continua está vacía o es un objeto JSON que representa un único cambio. La opción garantiza que se cumplan las siguientes directrices:

• El formato de las entradas del informe refleja la naturaleza continua de los cambios.
• Se mantiene la validez de la salida JSON.

Consulte las siguientes respuestas de ejemplo (abreviadas) de un canal de información de cambios continuos:

{
	"seq": "1-g1A...qyw",
	"id": "2documentation22d01513-c30f-417b-8c27-56b3c0de12ac",
	"changes": [
		{
			"rev": "1-967a00dff5e02add41819138abb3284d"
		}
	]
},
{
	"seq": "2-g1A...ssQ",
	"id": "1documentation22d01513-c30f-417b-8c27-56b3c0de12ac",
	"changes": [
		{
			"rev": "1-967a00dff5e02add41819138abb3284d"
		}
	]
},
{
	"seq": "3-g1A...qyy",
	"id": "1documentation22d01513-c30f-417b-8c27-56b3c0de12ac",
	"changes": [
		{
			"rev": "2-eec205a9d413992850a6e32678485900"
		}
	],
	"deleted": true
},
{
	"seq": "4-g1A...qyz",
	"id": "2documentation22d01513-c30f-417b-8c27-56b3c0de12ac",
	"changes": [
		{
			"rev": "2-eec205a9d413992850a6e32678485900"
		}
	],
	"deleted": true
}

El argumento filter

El argumento filter designa una función de filtro predefinida que aplicar al canal de información de cambios. Además, hay varios filtros integrados disponibles:

_design

El filtro « _design » solo admite cambios en los documentos de diseño.

_doc_ids

Este filtro solo admite modificaciones en los documentos cuyo ID se especifique en el parámetro « doc_ids ».

_selector

Devuelve los cambios correspondientes a los documentos que coinciden con el parámetro « selector » del cuerpo de la solicitud. La sintaxis del selector es la misma que la sintaxis que se utiliza para _find. Si quieres utilizar un filtro de selección, debes utilizar el feed de cambios de POST (ya que no es posible incluir el cuerpo del documento en una solicitud GET). Utiliza el método de filtrado « _selector » en lugar del método « _view », ya que es más rápido y fácil de usar.

Para obtener más información, consulte la documentación de API.

_view

Habilita el uso de una función de correlación existente como filtro.

El argumento since

Utilice el argumento since para obtener una lista de los cambios que se han producido después de un identificador de secuencia especificado. Si el identificador since es 0 (el valor predeterminado) o se omite, la solicitud devuelve todos los cambios. Si el identificador since es now, la solicitud solicita los cambios realizados después de la hora actual.

La naturaleza distribuida de {{site.data.keyword.cloudant_short_notm}} puede afectar a los resultados que se obtienen en una respuesta. Por ejemplo, si solicita una lista de cambios dos veces utilizando el mismo identificador de secuencia since ambas veces, es posible que el orden de cambios en la lista resultante no sea el mismo.

También es posible que vea algunos resultados que parecen ser de antes del parámetro since. El motivo es que puede obtener resultados de una réplica distinta de un fragmento (una réplica de fragmento).

Las réplicas de fragmento se replican de forma automática y continua entre sí y, finalmente, tienen los mismos datos. Sin embargo, en cualquier momento, una réplica de fragmento podría diferir de otra réplica de fragmento porque la réplica entre ellos aún no está completa.

Cuando solicita una lista de cambios, normalmente se utilizan las mismas réplicas para responder. Pero si el nodo que contiene la réplica de fragmento no está disponible, el sistema sustituye una réplica de fragmento correspondiente que se retiene en otro nodo. Para asegurarse de que ve todos los cambios aplicables, se utiliza el punto de comprobación más reciente entre las réplicas. El uso del punto de comprobación realmente lo que hace es "retroceder" la lista de cambios al punto más reciente en el tiempo en que se confirmó que las réplicas del fragmento estaban de acuerdo entre sí. Esta "retroceso" significa que puede ver los cambios que han tenido lugar "antes" del identificador de secuencia since que ha especificado.

La aplicación debe poder manejar un cambio que se notifica más de una vez si realiza una solicitud _changes varias veces.

Para obtener más información sobre el comportamiento de la respuesta _changes, consulte la guía de réplica.

Respuestas de la solicitud _changes

La respuesta de una solicitud _changes es un objeto JSON que contiene una lista de los cambios realizados en los documentos de la base de datos. En la tabla siguiente se describe el significado de cada campo:

Consulte la siguiente respuesta de ejemplo (abreviada) a una solicitud _changes:

{
	"results": [
		{
			"seq": "1-g1A...sIg",
			"id": "foo",
			"changes": [
				{
					"rev": "1-967...84d"
				}
			]
		}
	],
	"last_seq": "1-g1A...sIg",
	"pending": 0
}

Notas importantes sobre _changes

• Los resultados que devuelve _changes están parcialmente ordenados. Es decir, es posible que el orden no se conserve para varias llamadas. Puedes obtener una lista actualizada accediendo a _changes e incluyendo el valor « last_seq ». La lista resultante proporciona el punto de partida para las siguientes listas _changes que utilizan el argumento de consulta since.
• Aunque las copias de fragmentos del mismo rango contienen los mismos datos, su historial de _changes suele ser exclusivo. Esta diferencia es el resultado del modo en que se han aplicado las escrituras en el fragmento. Por ejemplo, es posible que se hayan aplicado en un orden diferente. Para asegurarse de que se notifican todos los cambios para la secuencia especificada, es posible que sea necesario volver atrás en el historial del fragmento para encontrar un punto de partida adecuado. Luego se notifican los cambios desde este punto de partida. Este "retroceso" puede dar lugar a la aparición de actualizaciones duplicadas o actualizaciones que sean aparentemente anteriores al valor since.
• Los cambios (_changes) que notifica un fragmento se presentan siempre en orden. Pero es posible que parezca que el orden entre todos los fragmentos sea diferente. Para obtener más información, consulta « Ejemplo de un feed de cambios ».
• Los valores de secuencia son exclusivos para un fragmento, pero pueden variar entre fragmentos. Esta variación significa que, si tiene valores de secuencia de diferentes fragmentos, no puede suponer que el mismo valor de secuencia hace referencia al mismo documento dentro de los distintos fragmentos.

Utilización de POST para obtener cambios

En lugar de GET, también puede utilizar POST para consultar el canal de información de cambios. La única diferencia, si está utilizando POST y los filtros docs_ids o selector, es que se pueden incluir las partes "doc_ids" : [...] o "selector": {...} en el cuerpo de la solicitud. Se espera que todos los demás parámetros estén en la serie de consulta, igual que cuando se utiliza GET.

Consulte el ejemplo siguiente que utiliza HTTP para ejecutar POST sobre el punto final _changes:

POST /$DATABASE/_changes?filter=_selector HTTP/1.1
Host: $ACCOUNT.cloudant.com
Content-Type: application/json

Consulte el ejemplo siguiente en POST para el punto final _changes:

curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X POST "$SERVICE_URL/orders/_changes" -H "Content-Type: application/json"'

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.ChangesResult;
import com.ibm.cloud.cloudant.v1.model.PostChangesOptions;
Cloudant service = Cloudant.newInstance();
PostChangesOptions changesOptions = new PostChangesOptions.Builder()
    .db("orders")
    .build();
ChangesResult response =
    service.postChanges(changesOptions).execute()
        .getResult();
System.out.println(response);

import { CloudantV1 } from '@ibm-cloud/cloudant';
const service = CloudantV1.newInstance({});
service.postChanges({
  db: 'orders'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1
service = CloudantV1.new_instance()
response = service.post_changes(
  db='orders'
).get_result()
print(response)

postChangesOptions := service.NewPostChangesOptions(
  "orders",
)
changesResult, response, err := service.PostChanges(postChangesOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(changesResult, "", "  ")
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.

Si ejecuta POST sobre el punto final _changes, verá un ejemplo similar al objeto JSON siguiente:

{"results":[
{"seq":"1-g1AAAA...","id":"0007741142412418284","changes":[{"rev":"1-9d0c2676941ec3a3b3cc2f08fe9a51e0"}]},
{"seq":"2-g1AAAA...","id":"_design/applianceId","changes":[{"rev":"1-b1f67a8b672c1324680d6d7dc1e1fd3c"}]},
...
],
"last_seq":"18-g1AAAA...","pending":0}

Paginación

Utilice el parámetro since como un marcador para paginar la fuente de cambios. Para obtener detalles específicos y ejemplos, consulte el tema de la documentación de la API Paging the changes feed.